boxsym-rnd(5)

📦 version 1.0.11, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 boxsym-rnd 🎀 — the boxsym description syntax, explained by your fav Unix bestie

okay so bestie, welcome to boxsym-rnd(5), a page from the sch-rnd manual. this is THE doc for how you write a boxsym file, and honestly? it's giving "weirdly chill file format". let's get into it 💅

✨ NAME ✨

boxsym-rnd — the syntax for a boxsym description. yep, that's the whole vibe of this page 🦋

🌸 DESCRIPTION 🌸

A boxsym file is where you spell out the symbol attributes and the pins (aka terminals) for either:

  • one single box symbol, or
  • a whole set of inhomogenousely slotted box symbols (say that five times fast, I dare you 😭)

Now, when slotted symbols get generated, here's what actually comes out:

  • one symbol file per slot, and it contains only the pins defined for that specific slot (the file name gets suffixed with the slot name), and
  • a monolith symbol (which uses the original file name) with all the pins thrown into one large box.

🧚 Syntax 🧚

The boxsym syntax is a plain text, line based, hierarchical file format, with a syntax similar to tEDAx. Iconic lineage tbh.

  • Leading whitespace in lines is ignored — she does not care about your indentation, do it for you.
  • Empty lines are ignored. So are lines starting with a hashmark (#).
  • The first word of a line is a command.

If the command is begin, then everything after it — up until the matching end line — gets read as a nested level of hierarchy. And yes, the syntax allows "begin in begin", meaning nesting to any depth. Go off. The second word of begin and end is the type of the nested subtree.

Commands issued outside of any begin-end blocks are said to be made in global scope. ✨

💜 Refdes 💜

There can be only one refdes line, and it lives in global scope. The argument is a single word: the refdes attribute.

If no refdes is specified? No stress — the default refdes is used. 🫶

🎀 Attributes 🎀

Attributes are symbol attributes. Here's the tea on scope:

  • Attributes specified in the global scope will be present in every symbol generated from the file.
  • Attributes specified for a slot will be present in that slot's symbol and in the monolith symbol.

An attribute is defined in the following form:

attr key value

Key is a single word. value is anything up to the end of the line. This definition creates the attribute and places a dyntext+floater text object that prints the value of the attribute.

  • If the command is attr_both, the text object is created to print key=value.
  • If the command is attr_invis, the attribute is still created, but no text object is made. Sneaky. Invisible. Lowkey iconic.

🌈 Other global settings 🌈

A line starting with text_size_mult followed by a decimal number (greater than zero, bestie, don't test her) changes the text pixel length allocation factor.

Increasing the values will allocate more pixels to each text in length. Note: text height is not affected. Length only. Periodt.

🦋 Defining pins 🦋

Pins are defined using a pin subtree: begin pin pinname, then lines defining pin properties, then end pin.

Pinname should be the textual, human readable name of the pin (it's also used as an input for the optional devmap) — not the physical pin number, okurrr?

For example:

begin pin Vcc
     num 14
     loc top
end pin
begin pin B
     num 2:5:10:13
     loc left
     dir in
     invcirc
     funcmap
end pin

Within the pin block, the num line specifies the physical footprint pin number. For a pin participating in a slot, this should be a colon separated list of pin number per slot.

The mandatory loc line specifies the location of the pin — the side of the box on which it should be placed — one of: left, right, top or bottom. (Mandatory!! do not forget her 😭)

  • If a dir line is present, extra "pin direction" graphics is drawn for the pin inside of the box. Values are in or out.
  • If invcirc is present, the pin will have a small circle near the box to indicate the pin is inverted. Cute lil bubble 🫧.
  • If label is present, its value (anything written after label) is printed within the box next to the pin, instead of the pin name.
  • If funcmap is present, the label is replaced with a dyntext that prints the abstract attribute funcmap/name. This is useful for symbols that are going to use a funcmap (alternate pin function mapping). The funcmap file is normally also referenced from the component, setting the funcmap attribute to the funcmap file name.

🌸 Arranging pins 🌸

By default, pins are listed per side (loc), tightly packed, in order of appearance in the file, from the start of the side. Bestie behaviour: organized, no gaps.

You can change that using pinalign lines in global or slot scope. For example:

pinalign left center

will arrange left side pins on the center (vertically). Slay. ✨

👑 Defining a single box symbol 👑

The simplest form of box symbols emits a single file that has a single large box with all the pins. The boxsym definition for such symbols contains the constructs described above, and no begin slot subtrees. Simple. Elegant. No drama.

💅 Defining inhomogenous slot symbol 💅

In a multi-box, inhomogenous slot symbol, there are different symbols representing different sections of the component.

The typical example is an MCU which is split up into a couple of boxes: a few boxes per port groups, and another few per peripheral types. Each box represents a slot that appears only once in the MCU.

Another typical example is logic ICs, e.g. 7400 implemented in two different slot symbols:

  1. one for power (Vcc and gnd), which presents once in the component, and
  2. one for a 3 pin gate — the same box used 4 times for 4 different slots.

An inhomogenous slot symbol does not have any pin in global scope, but defines one or more begin slot slotname subtrees for all the different types of slots.

And here's the key thing: if the same slot appears multiple times in the component, it needs to be defined only once — and you assign multiple pin numbers in the pin definitions. Efficiency queen 👑.

🔥 EXAMPLE 🔥

🍓 Single box LDO 🍓

refdes U??
attr_invis sym-source       sch-rnd default symbol lib
attr_invis sym-copyright    (C) 2022 Tibor 'Igor2' Palinkas
attr_invis sym-license-dist GPLv2+
attr_invis sym-license-use  Public Domain

pinalign bottom center
pinalign left center
pinalign right center

shape box
shape_fill yes
begin pin in
     num 1
     loc left
end pin

begin pin gnd
     num 2
     loc bottom
end pin

begin pin out
     num 3
     loc right
end pin

🧁 Inhomogenous slot 7400 🧁

refdes U??

pinalign right center
pinalign bottom center
pinalign top center
attr device 7400

begin slot power
     shape box
     shape_fill yes
     begin pin Vcc
          num 14
          loc top
     end pin
     begin pin gnd
          num 7
          loc bottom
     end pin
     pinalign top center
     pinalign bottom center
end slot

begin slot logic
     attr device 7400
     attr_both slot 1

     begin pin A
          num 1:4:9:12
          loc left
          dir in
     end pin

     begin pin B
          num 2:5:10:13
          loc left
          dir in
     end pin

     begin pin Z
          num 3:6:8:11
          loc right
          dir out
          invcirc
     end pin

     pinalign left center
     pinalign right center
end slot

⭐ SEE ALSO ⭐

okay that's the whole page bestie, you're officially a boxsym girlie now 💖 anyway this lil drop was brought to you by the sch-rnd manual, dated 2022-03-28 — so if you're reading this from the future, hi, you're cute, and the syntax is still right there waiting for you. no cap. bye!! 🌈🎀🦋

📦 where this page comes from