Makes a map of the sheet level terminals of a given hierarchic child sheet and exports a boxsym (in the format of boxsym-rnd) that represents a the child sheet as a symbol usable in a parent sheet. Terminals of the symbol match the terminals of the child sheet.
The following attributes of sheet level terminal objects are interpreted by the plugin:
attr key | mandatory | description |
---|---|---|
name | yes | name of the terminal in the resulting symbol |
boxsym/loc | no | specify which side of the boxsym the terminal should go: left, right, top or bottom |
boxsym/grp | no | arbitrary string for grouping terminals in the resulting symbol |
boxsym/num | no | override automatically generated pin number |
boxsym/prio | no | integer priority value for sorting terminals |
Each terminal is put into one of 4 lists depending on which side of the boxsym the terminal would end up on (left, right, top or bottom). If the input terminal has a boxsym/loc attribute, that specifies the side, otherwise the plugin picks the side the input sheet terminal is closest to on the input sheet:
Once all input terminals are collected into the corresponding per side list, the lists are each sorted. The sorting algorithm uses multiple attributes and properties of input terminals:
The by-grp and by-name sorting is done as normal alphanumeric sorting.
In-group priority sorting: when boxsym/loc is not specified, the normal priority value of a terminal is assigned from 0..1000 depending on the position of the input terminal along the given edge (e.g. for a top side terminal the leftmost x coordinate of the input terminal determines prio). This priority is overridden by the optional user supplied boxsym/prio value, which is not restricted to the 0..1000 range.
When boxsym/loc is specified the default priority is set to 500, regardless of any coordinates of the input terminal. In other words, without boxsym/loc the plugin extracts side and ordering info from input terminal coordinates but with boxsym/loc set input geometry is ignored in all regards.
Note: the actual numeric values are used only for sorting, they are not directly proportional to the final coordinates of the terminals within the symbol, they only affect the order of terminals.
Sorted terminal pinnum is assigned automatically and sequentially per side, from 100, 200, 300 and 400 respectively, unless the pin number is overridden by boxsym/num, which is an arbitrary string, does not need to be a number. When boxsym/num is specified for a terminal, it does not affect the numbering sequence of other terminals; that is if originally a side had terminal pinnums 100, 101, 102 and 103 and the input terminal corresponding to 101 gets a boxsym/num=8, the symbol will have pin numbers 100, 8, 102, 103 on that side.
How to use this in practice:
When the export plugin is invoked from the GUI export dialog (e.g. using the {f e} hotkey), it offers a "Generate symbol!" button that:
This should be done while the hierarchic child sheet is active; the new symbol should be placed on the hierarchic parent sheet.
Note: placing the symbol on the child sheet will cause a compilation error as it will result in infinite recursion of the sheet having itself as a child sheet. The recursion is eventually terminated by the compiler with real long component paths reported in the message log.
The plugin ignores display/omit or display/dnp.