Structure notation

How we write down the structure of the robot as text. Duckbot uses this notation in its structure document. Robot-specific definitions live under robots/<robot>/; paths such as parts/ and sensors.json below are relative to that robot directory.

Draft. We are still working on this spec.

1. Parts#

• The robot is made of re-usable parts. Each part type is specified once, in the parts/ folder.
• A cell holds the exact name of a part file, e.g. servo, foot, head_box, box_body, so the table can be matched to parts/<name>.json.
• A servo and its holder are one unit: servo (parts/servo.json, marked "servo_holder": true). They are never written separately. The servo model inside it (sts3215) is referenced from that file and never appears in the table.
• Every servo has a numerical ID so it can be referenced, written in the cell as servo <ID>, e.g. servo 5. IDs are unique and numbered in reading order: top to bottom, and left to right within a row.
• The height of a servo cell shows its orientation, as seen from the front:
• a servo standing vertically, facing us, is two bars (text lines) tall, with its label on the lower line;
• a servo lying horizontally is one bar tall.

│     servo 5     │   ← horizontal
├────────⊙────────┤
│                 │
│     servo 9     │   ← vertical, facing us

• Sensors are written inside the cell of the part they are mounted on, as { sensor_name }. The name matches an entry in sensors.json.

│           { imu_body }          │
│             box_body            │

2. The table#

The structure is a Unicode box-drawing table, wrapped in a code block so it renders in a monospace font.

• Each row is one level of the hierarchy, read from top (head) to bottom (feet).
• Columns are left to right as we see the robot from the front. "Left" always means our left, looking at the robot.
• Each cell holds one object only. Links between objects are never cells.
• A cell spans the full width when it is a single object in the middle (head, body).
• Physically separate objects in the same row get a gap between their cells, e.g. the two legs:

│     servo 9     │   │     servo 10    │

3. Links#

Links are drawn only on the borders between cells.

Rigid link#

The two cells share a border. A rigid link is marked on that border with one of three symbols:

Left, right, up and down can be seen in the table itself. Only front and behind cannot, which is why every rigid link carries one of these symbols.

│     servo 5     │
├────────⊙────────┤
│                 │
│     servo 9     │

Servo 5 is fixed to the front of servo 9.

No symbol on a shared border means the two cells are not connected.

Joint#

Two objects connected by a joint are separated. The upper cell narrows into a stem that plugs into the lower cell:

│                 │
│     servo 11    │
└──────┐   ┌──────┘
       ↓   ↓
       ○   ○
┌──────┘   └──────┐
│      foot       │

The joint type is written on the separator (the stem).

Arrows are only used on joint stems, never for a rigid link. They show which object moves: they point from the servo that drives the joint toward the circles. The object on the other side of the circles is the one that swings. In the example, servo 11 drives the joint and the foot swings.

Sideways joint (draft)#

Two objects side by side in the same row can also be joined by a joint. The driving servo's border narrows into a short sideways stem; the arrow points from it toward the circle, and the object on the other side of the circle moves:

                    ┌─────────────┐
┌─────────────┐     │             │
│   servo 5   │ ○←──┤   servo 6   │
└─────────────┘     └─────────────┘

Servo 6 drives the joint and servo 5 moves. One circle: the rotator points forward (back–forward axis), so servo 5 tilts to the left and right.

4. Joint types#

The joint type is shown by where the circles sit on the stem, as seen from the front:

Swings back and forward (e.g. a foot):

│                 │
│     servo 11    │
└──────┐   ┌──────┘
       ↓   ↓
       ○   ○
┌──────┘   └──────┐
│      foot       │

Rotor points down, the servo below turns parallel to the ground:

│     servo 3     │
└──────┐   ┌──────┘
       ↓ ○ ↓
┌──────┘   └──────┐
│                 │
│     servo 6     │

5. Open points#

• Sideways joint: the symbol for a left–right axis on a sideways stem.