Cells, machines and positioners

A running cell is described by four layers of configuration. Each layer pins the one below it by content hash, so every process can tell whether it is talking to the cell it expects. This page explains the layers, how they compile into one identity, and how the Rosie 1400's two-table positioner fits in.

Four layers#

Each layer has an annotated template in rt-core/config/templates/ (drive.json, robot.json, machine.json, cell.json). Every field there has a _doc sibling giving its unit, allowed values and default. The field-by-field tables are in Configuration files.

Compiling a machine into an identity#

rtctl compile resolves a machine config, the drive configs it names and any robot description it pins. It writes one immutable directory named after the result, the configuration digest:

cd rt-core
build/rtctl compile --config config/machines/simulation/simulation.json --out build/config
# build/config/<configuration_sha256>

The directory holds axes.conf, argv.json (the core's command line), the identity artifacts and resources.json, the robot files that rt-control serves to clients. Machine, deployment and configuration digests are distinct, and Describe reports all three.

The digest travels with the cell:

• rt-control is started with --configuration-sha256 and refuses a core that reports another identity.
• Every acquire must present the same digest in its binding, with the pair id and revision.
• OLP refuses a cell whose deployed digest differs from its catalogue entry, with cell_configuration_mismatch.

Change any layer and the digest changes. You then recompile, and update every pin that referred to the old digest.

Robot-bound limits#

For an axis mapped to a robot joint, the compiler takes travel and maximum velocity from robot.urdf, and acceleration from config.json (planning.joints.<joint>.acceleration_rad_s2). A machine config cannot override those values. The per-axis drive speed cap is derived from the same URDF velocity.

A cell can narrow its limits further with a per-cell machine_planning_calibration.json. That file lives with the cell, not in the repository, and the machine config pins it by path and hash. It can narrow joint limits and apply small, capped kinematic corrections. It can never widen a limit.

Cell config#

The cell config is the deployment pin. Its native binding has these fields:

The validator in rt-core/config/cells recompiles every cell's machine config and refuses the cell if the digest, axis count, pair or listener is wrong, or if the compiler printed warnings:

cd rt-core
go test -count=1 ./config/cells -run TestRepositoryCompatibility

Robot models#

Frames, joint chains and units are covered in Robot description and coordinate frames.

The H-frame positioner#

The Rosie 1400 description models the positioner as three revolute joints. They are driven by the same core as the arm, at the same 1 kHz cycle.

The two tables sit either side of the H-frame. rosie_1400_v3/config.json sets what the planner uses:

• Driven axes: J1 to J7. The planner moves the arm and table A together.
• Held axes: J8 = 0 and J9 = 0. The planner keeps them fixed.
• Work frame: positioner_table_a_top, a surface on positioner_table_a at xyz_m [0, −0.622, 0.1]. Weld geometry is expressed on table A.

Dense programs always carry nine axis columns in the order J1–J6, J7/J8, J9. The header's axis mask is 0x1ff for rosie_1400_v3 and 0x3f for rosie_1420_v1. See Dense trajectory format.

Simulation machines#

rt-core/config/machines/simulation/ holds machine configs for the simulated backend:

Choose the dev-stack machine with DEV_STACK_MACHINE_CONFIG. See Run everything in simulation.