Body file reference
Generated from packages/body-spec/schema/body.v1.json (https://isaac.tools/schema/body.v1.json), the authority on the structure of robot.isaac.yaml. The semantic rules (one primary board, pins used once, parts in the registry, roles, class requirements) are checked by the validator in @isaac/body-spec; see Your first body file.
One YAML file that describes a robot. Everything else (BOM, wiring, firmware, sim model, calibration profile, ROS export, assembly guide) is generated from it. This schema is the structural authority; the semantic rules in section 4.12 of the build document are enforced by the validator in @isaac/body-spec.
Top level
| field | type | required | description |
|---|---|---|---|
isaac |
1 |
yes | Schema version. Always 1 for this schema. |
robot |
robot |
yes | |
dimensions |
dimensions |
||
boards |
array of board |
yes | |
actuators |
array of actuator |
||
sensors |
array of sensor |
||
power |
power |
||
links |
array of link |
||
joints |
array of joint |
||
drive |
drive |
Shortcut for tracked and diffdrive robots. Expands to wheel links and continuous joints in the sim and ROS export. | |
mounts |
array of mount |
||
buses |
array of bus |
||
parts |
array of part |
||
calibration |
calibration |
Written by the agent's calibration flow. Excluded from the body hash. | |
skills |
skills |
yes |
identifier
Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars.
Type: string. Pattern: ^[a-z][a-z0-9_]{0,31}$.
registryId
Driver registry part id, e.g. esp32-s3-wroom-1 or st7789-1.14.
Type: string. Pattern: ^[a-z0-9]+([.-][a-z0-9]+)*$.
gpio
Type: integer. Range: 0 to 255.
pinMap
Logical pin name to GPIO number on the owning board.
Type: map of gpio.
address
Type: string. Pattern: ^0x[0-9a-fA-F]{40}$.
semver
Type: string. Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$.
vec3
Type: array of number. Items: 3.
vec2
Type: array of number. Items: 2.
origin
| field | type | required | description |
|---|---|---|---|
xyz_in |
vec3 |
||
rpy_deg |
vec3 |
robotClass
Type: companion, tracked, diffdrive, arm, quadruped. Values: companion, tracked, diffdrive, arm, quadruped.
interfaceId
Type: companion/1, mobile/1, arm/1, legged/1. Values: companion/1, mobile/1, arm/1, legged/1.
role
Type: motion, audio_in, audio_out, display, battery, distance_front, distance_left, distance_right, distance_rear, line_left, line_center, line_right, camera_front, encoder, button, touch, temperature, light, battery_voltage, charge_rate, charger. Values: motion, audio_in, audio_out, display, battery, distance_front, distance_left, distance_right, distance_rear, line_left, line_center, line_right, camera_front, encoder, button, touch, temperature, light, battery_voltage, charge_rate, charger.
robot
| field | type | required | description |
|---|---|---|---|
name |
string | yes | |
slug |
string | yes | |
class |
robotClass |
yes | |
version |
semver |
yes | |
creator |
address |
yes | |
summary |
string | yes | |
license |
string | yes | SPDX license id. |
tags |
array of string |
dimensions
| field | type | required | description |
|---|---|---|---|
size_in |
vec3 |
yes | Overall x y z extent in inches. |
weight_oz |
number | ||
size_mm |
vec3 |
Overall x y z extent in millimetres when the design is metric; must agree with size_in. |
board
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
part |
registryId |
yes | Driver registry part id, e.g. esp32-s3-wroom-1 or st7789-1.14. |
role |
primary, secondary, daughterboard |
yes | primary: the board the agent talks to; secondary: an MCU board linked to the primary over a bus; daughterboard: a passive board with no MCU (a USB-C or connector board) joined to another board by a cable. |
transport |
usb-serial, wifi-mqtt, ble |
How the agent reaches this board. Required on the primary board. A secondary board is reached through the primary over a bus with peer set to this board. |
|
pins |
pinMap |
Signals wired directly to this board that belong to no bus, actuator, or sensor (status LEDs, enable lines). Net name to GPIO. | |
active_low |
array of identifier |
Pin names (keys of pins) whose signal is active low: asserted at 0 V. Firmware and the wiring diagram use it. |
|
alternates |
array of registryId |
Registry ids of drop-in module alternates the board also accepts unchanged (same footprint and pin map). | |
pcb |
object | The custom circuit board that carries this board's parts: a parts[] entry (its design file) plus its outline and stack-up. | |
link |
object | Daughterboards: how the board joins its host board. |
actuator
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
part |
registryId |
yes | Motor or servo registry id. |
driver |
registryId |
Driver registry id. Omit for direct drive (a servo on a GPIO, a smart servo on a bus). | |
driver_channel |
string or integer | Channel of the driver this actuator uses, e.g. A or B on a TB6612FNG, 0..15 on a PCA9685. | |
board |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
pins |
pinMap |
Registry pin names of the driver channel (or the actuator itself for direct drive) to GPIOs on board. |
|
bus |
identifier |
Bus id for bus-attached drivers and smart servos. | |
address |
integer | ||
encoder |
object | ||
limits |
object |
sensor
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
part |
registryId |
yes | Driver registry part id, e.g. esp32-s3-wroom-1 or st7789-1.14. |
board |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
bus |
identifier |
Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. | |
address |
integer | ||
pins |
pinMap |
Registry pin names to GPIOs for sensors and peripherals not on a bus, or for the extra pins of a bus device (interrupt, chip select, reset). | |
role |
role |
yes | |
origin |
origin |
Pose of the sensor on the robot's root link, for the sim. | |
link |
identifier |
Link the sensor is attached to. Default is the root link. | |
range_in |
number | Max range for distance sensors, in inches. Default from the registry. | |
active_low |
array of identifier |
Pin names (keys of pins) whose signal is active low: asserted at 0 V. Firmware and the wiring diagram use it. |
|
source |
identifier |
Another reading of a part that is already in the body: the id of a sensor, or battery / charger / regulator. Such an entry has no bus, address or pins of its own and adds nothing to the BOM. |
power
| field | type | required | description |
|---|---|---|---|
battery |
object | ||
charger |
object | ||
regulator |
object | ||
rails |
array of object |
link
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
shape |
box, cylinder, sphere, mesh |
yes | |
size_in |
vec3 |
Box extents x y z in inches. | |
radius_in |
number | Cylinder or sphere radius in inches. | |
length_in |
number | Cylinder length along its axis in inches. | |
axis |
x, y, z |
Cylinder axis. | |
mass_oz |
number | yes | |
mesh |
string | Path to an STL in the body folder, for display. | |
origin |
origin |
Visual and collision shape offset from the link frame. | |
color |
string |
joint
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
type |
fixed, revolute, continuous, prismatic |
yes | |
parent |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
child |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
origin |
origin |
Child frame in the parent frame. | |
axis |
vec3 |
||
actuator |
identifier or null |
||
limits |
object |
drive
Shortcut for tracked and diffdrive robots. Expands to wheel links and continuous joints in the sim and ROS export.
| field | type | required | description |
|---|---|---|---|
kind |
diffdrive, tracked |
yes | |
wheel_radius_in |
number | yes | |
track_width_in |
number | yes | Distance between the left and right wheel or track centers. |
wheel_width_in |
number | ||
left |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
right |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
base |
identifier |
Link the wheels attach to. Default: the root link. | |
axle_xyz_in |
vec3 |
Axle center in the base link frame. Default [0,0,0]. | |
caster |
object |
mount
| field | type | required | description |
|---|---|---|---|
part |
identifier |
yes | Id of a board, actuator, sensor, part, or power item (battery, charger, regulator). |
on |
identifier |
yes | Link or part id it attaches to. |
position |
string | yes | |
fastener |
snap, adhesive, screw, heat-insert, press-fit, zip-tie, tape, velcro, solder, none |
yes | |
hardware |
identifier |
Id of the parts[] hardware entry used (screws, inserts). | |
qty |
integer | ||
notes |
string |
bus
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
kind |
i2c, i2s, uart, spi, onewire, can, pdm |
yes | |
board |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
pins |
pinMap |
yes | Logical pin name to GPIO number on the owning board. |
speed_hz |
integer | ||
baud |
integer | ||
peer |
identifier |
For board-to-board links: the secondary board reached over this bus. | |
peer_pins |
pinMap |
Pins on the peer board. |
part
| field | type | required | description |
|---|---|---|---|
id |
identifier |
yes | Local id: lowercase letter then lowercase letters, digits, underscores. Max 32 chars. |
kind |
printed, cut, hardware, other |
yes | |
file |
string | Path in the body folder: STL for printed, DXF/SVG for cut. | |
material |
string | ||
part |
registryId |
Registry id, required for hardware; resolves to an AliExpress search. | |
qty |
integer | yes | |
notes |
string |
calibration
Written by the agent's calibration flow. Excluded from the body hash.
| field | type | required | description |
|---|---|---|---|
imu |
object | ||
display |
object | ||
motors |
map of object | ||
servos |
map of object |
skills
| field | type | required | description |
|---|---|---|---|
interface |
interfaceId |
yes |