pcb-rnd knowledge pool
How refdes works with subcircuits
| subc_refdes by Tibor 'Igor2' Palinkas on 2017-10-19 | Tags: spec, refdes, subc, subcircuit, element, footprint, name |
Abstract: Details on how the refdes worked with the old element model and how it works with the new subcircuit model.
Imported from the mailing list archives.
The last piece of the subc "refdes text" cleanup is done. The new code fits nicely into the new data model and pcb-rnd's approach: instead of hardwired hacks and side effects that happen to do The Right Thing for one specific case, provide a few, orthogonal features that can be combined to do the same thing, or 100 other things.
Old, pcb-mainline model: "element text"
An element has 3 hardwired text objects that have to contain the refdes, the value and the footprint name. Further limitations:
- all three element text object have to have the same coordinates and font and size
- they can be only on silk, and all three must be on the same silk layer
- special exception from under the element-lock: the only element-part you can move without moving the element is the element text (e.g. the only element part that can change its position compared to other parts of the element without breaking the element up first)
- and the element text can always be moved, you can't locally lock it to the element; so you can't have a special element where the text has a fixed position for whatever reason
- there was exactly 3 of these - no more, no less
- they could contain only what the programmer thought would be useful
- only one of them could be displayed at a time, and which one got displayed was a board-global setting; this global setting also affected some
New, pcb-rnd model: subc
Instead of the bunch of hardwired properties and restrictions of an element text, subcircuits offer a set of orthogonal features that can be used to reproduce the behavior of element texts too, but can also be used more flexibly:
- subcircuits consist of any object on any layer
- these objects can be text, and can be on a silk layer
- a text object can have the DYNTEXT flag, in which case the code does %% substitution on the text; e.g. if the text string contains %a.parent.refdes% , the part between the %% is substituted with the refdes attribute ("a.") of the parent subcircuit ("parent."). In short: it's replaced with the subcircuit's refdes
- there's no limitation on the number of text objects having DYNTEXT flags - you can have one displaying the refdes on silk, another on copper
- there's no limitation on what attribute is displayed; refdes, value and footprint name are not special any more, they are just attributes. You can introduce your own attributes, and you can get them printed in text
- with these, you can have a resistor footprint that prints both the refdes and the value on silk, side by side
- if any object of a subcircuit has the FLOATER flag, it can be moved within the subcircuit (and can be edited without breaking up the subcircuit); the "lock names" and "only names" became "lock floaters" and "only floaters".
How to emulate the old behavior with the new features
To get a subc refdes that behaves the same as an element refdes text, except that it's only a refdes text and not a 3-fold "magic text":
- on a silk layer create a text object that will be part of the subc
- set the text string to %a.parent.refdes% so that it will always display the subcircuit refdes
- edit flags to turn on DYNTEXT and FLOATER ; the first lets pcb-rnd replace %% patterns, the second lets the user grab and move the text
Note: when you convert buffer to subc and it doesn't have a refdes text, the code automatically adds one, so you don't need to do this manually for each new subcircuit you draw.
Attributes
| property name in old element | default/automatic subc attribute name | manual override subc attributes | pre-subc lihata text object role property |
|---|---|---|---|
| desc | footprint | visible_footprint, plugin::footprint | desc |
| name | refdes | (n/a) | name |
| value | value | (n/a) | value |
When the code needs to figure what footprint file was used for a subcircuit (e.g. when deciding if a footprint has changed on a new forward annotation), it will always use the default/automatic "footprint" attribute. The manual override affects only the output of some exporters. Note: the footprint attribute should not be overwritten as it may lead to unpredictable effects on importing a schematics. Overwriting the refdes attribute really does change the refdes.
Old fp format element variants:
Element[* "desc" "name" "value" **] Element(* "desc" "name" "value" **) Element(* "desc" "name" **)
Old (pre subc) lihata format for Elements will have the 3 magic text objects, with a "role" property. The roles are as described in the above table.
The import action:
ElementList(Need, refdes, footprint, value)