Configuration files (drive, machine, cell)

rt-core reads one compiled configuration. You write it as JSON in rt-core/config/, and rtctl compile turns it into an immutable directory named after its digest. This page lists every field of the machine, drive and cell layers. Robot descriptions have their own page: Robot description files.

Compile a shipped simulation machine and print its digest directory:

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

How the layers fit together is explained in Cells, machines and positioners.

Templates#

rt-core/config/templates/ holds one annotated template per layer: machine.json, drive.json, cell.json and robot.json. Every field has a <field>_doc sibling that states its unit, allowed values and default. The tables below are drawn from those templates and the compiler.

The templates are class definitions, not deployable configs. They show mutually exclusive branches side by side (flat axes and robot-bound axes, for example), and <required> marks a value the example cannot choose. To use one, pick a branch, remove the _doc siblings and fill the values.

Tests in rt-core/tools/rtctl and rt-core/config/cells check the templates against the compiler's readers and compile their simulation branches. None of them touches hardware.

Provenance siblings#

Numeric robot facts and safety exceptions must say where they came from. Add a <field>_source ("cited: …") or <field>_unverified ("unverified: …") string beside the field. Missing provenance is a compile error. Free-text reasons (for example collision_watchdog.reason) must be non-empty.

What compile writes#

rtctl compile --out DIR writes DIR/<configuration_sha256>/:

rt-control loads this directory through --compiled-config or ROSIE_RT_COMPILED_CONFIG.

Three digests#

The compiler produces three SHA-256 digests. Describe reports all three.

Canonical identity text uses sorted keys, one key=value per line, %.17g doubles and decimal integers.

Machine config#

A machine config binds drives, and optionally a robot description, to bus positions, timing, limits, I/O and host policy. The shipped ones are in config/machines/, config/machines/bench/ and config/machines/simulation/.

A machine uses one of two axis forms:

• Flat axes declare their own scaling and limits. Simulation fixtures and bare-motor benches use them.
• Robot-bound axes name a robot_joint in a pinned robot description. They inherit travel, velocity, acceleration, gearing and Home policy from the description, and must not redeclare them.

{
  "schema_version": 1,
  "backend": "simulation",
  "cycle_ns": 1000000,
  "robot": {
    "robot_description": {
      "path": "robot_description/robots/rosie_1400_v3",
      "sha256": "sha256:<identity>",
      "source": "cited: …"
    }
  },
  "axes": [
    { "robot_joint": "J1", "slave_position": 0,
      "limits": { "max_target_lead": 0.02, "following_error": 0.04, "following_error_timeout_ms": 100,
                  "completion_tolerance": 0.0002, "completion_timeout_ms": 500 } }
  ],
  "max_cycle_lateness_ns": 20000000,
  "runtime": { "cpu": 2, "priority": 90 }
}

Top level#

axes[], flat form#

axes[], robot-bound form#

A robot-bound axis must omit limits.min, limits.max, limits.max_velocity, limits.jog_acceleration, max_acceleration and coordinate_evidence_mode. It inherits them:

• travel and maximum velocity from robot.urdf
• trajectory and jog acceleration from config.json → planning.joints.<joint>.acceleration_rad_s2 (required)
• the per-axis drive speed cap, derived from the URDF velocity through the definition's gearing and encoder scale
• Home policy and coordinate evidence mode from the definition

Every joint in the definition needs an axis, unless you list it in robot.absent_joints.

limits#

jog#

The ramp when jog input stops. Also settable per drive; the axis value wins.

brake and brake_override#

Brake fields are taken from the drive config first, then overridden per axis.

brake_override exists for benches whose brake wiring is not yet verified. It disables brake handling on that axis and must say why.

collision_watchdog#

Faults the axis when torque or following error stays above a bound. It detects an impact after it happens; it does not avoid one. Also settable per drive.

Both branches need _source and _unverified siblings. An axis with no watchdog at all compiles with a warning: axis <name>: collision_watchdog missing; disabled.

diagnostics#

This lets rt-core report the state of an external enable, such as an auxiliary contact on the cell's stop chain. It is a diagnostic only. It never gates motion and is not a safety function. See the safety model.

runtime#

The core writes telemetry dumps (a .bin file and its .json index) to telemetry.directory. Convert one with rtctl telemetry dump-to-jsonl.

robot#

Omit machine_planning_calibration and the cell serves the empty calibration document for its model.

control#

The per-cell lease and jog-age ceilings. See Control authority.

bus#

hold leaves unknown slaves in PREOP without outputs. It is meant for test benches; an assembled robot cell must use refuse.

bus_bringup#

io#

Cell I/O through a digital I/O terminal. See Process I/O and sensing.

config/cell-io/simulation.json is a complete simulation machine with an io block, not a terminal descriptor.

Drive config#

A drive config describes one drive or I/O terminal model: its EtherCAT identity, PDO layout, scaling semantics, startup parameters, Home transaction and protective defaults. A machine axis selects one with profile; a robot definition with drive_profile. Names resolve only in config/drives/. The template is config/templates/drive.json.

The PDO semantics RX accepts are cw, target_pos, target_vel, target_torque, mode, tp_func and max_profile_vel. TX semantics include sw, pos, mode_disp, err, manufacturer_err, velocity_actual, following_error, torque, di and the drive's extended diagnostics.

Cell config#

A cell config binds one deployed cell to a machine config and its compiled digest. The template is config/templates/cell.json.

{
  "name": "simulation-cell",
  "nodes": [
    {
      "runtime": "rt-core",
      "rt_core": {
        "machine_config": "rt-core/config/machines/simulation/simulation.json",
        "configuration_sha256": "<64 hex from rtctl compile>",
        "pair_id": "simulation-cell",
        "pair_revision": 1,
        "remote_listen": "127.0.0.1:8443"
      }
    }
  ]
}

The validator in Go package rosieos/rt-core/config/cells recompiles every node's machine config and refuses a mismatched digest, axis count, pair or listener:

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

Cell configs in config/cells/ also carry deployment fields for the deploy tooling. Those fields select and pin a configuration but never enter its digest.

Compile warnings#

Warnings go to stderr, prefixed warning:. The compile still succeeds.

Robot compile refusals#

When a machine pins a robot description, compile refuses with <reason>: <detail>:

Other compile errors print a plain message and exit 1. Nothing is written until the whole configuration is valid.