rtctl command reference

rtctl is the operator CLI for rt-core. It compiles and validates machine configurations, launches the core, checks a cell host, and sends single requests to rt-control for inspection and administration.

cd rt-core
make control                                   # builds build/rtctl
build/rtctl describe --socket /run/rosie-rt-core/control.sock
build/rtctl status --json | head -c 400; echo

rtctl builds and runs on Linux only. There is no rosie command in this repository; READMEs that mention rosie … or ./rosie.sh … refer to an internal tool.

Commands at a glance#

Every command rejects positional arguments it does not expect.

Exit codes#

validate returns the daemon's own exit status.

Where rtctl finds rt-core#

Configuration and host commands need the rt-core root, the directory that holds config/drives/. rtctl looks beside its own executable first (<root>/build/rtctl or <root>/bin/rtctl), then walks up from the working directory to a directory containing both config/drives/ and go.mod. If neither works it prints cannot locate rt-core root and exits 1 (3 for hostcheck).

Configuration commands#

compile#

Validates a machine config and writes the compiled configuration. It never contacts drives.

build/rtctl compile --config config/machines/simulation/simulation-program.json --out build/config
# /…/build/config/<configuration_sha256>

It prints the compiled directory on stdout and any warning: lines on stderr. The files it writes and the three digests are described in Configuration files.

validate#

Compiles, then runs the daemon with --validate-config, so the daemon checks its own private format without starting a runtime session.

build/rtctl validate --backend simulation --config config/machines/simulation/simulation-program.json
# daemon exit status: 0

run#

Compiles, then replaces itself (exec) with the selected daemon and the compiled argument list. This is how you start the core by hand in simulation.

build/rtctl run --backend simulation \
  --config config/machines/simulation/simulation-program.json \
  --out "$TMPDIR/config" --socket "$TMPDIR/ipc.sock"

Two guards keep simulation away from hardware:

• --backend live requires the machine config itself to say "backend": "live".
• In an installed package (where <root>/bin/rtctl exists), run accepts only --backend live and runs <root>/bin/rosie-rt-core. It never resolves a simulation request to the hardware binary.

On WSL, keep sockets on a Linux tmpfs such as /dev/shm; they cannot bind on /mnt/c.

control-env#

Compiles a live machine config for installed systemd units and prints the environment file they read. host/generate-control-env.sh calls it during host installation.

rtctl control-env --config machine.json --pair-id cell-a --pair-revision 1 \
  --out /tmp/staging --installed-out /etc/rosie-rt-core/compiled

It prints these variables on stdout:

ROSIE_RT_PAIR_ID=cell-a
ROSIE_RT_PAIR_REVISION=1
ROSIE_RT_CONFIGURATION_SHA256=<64 hex>
ROSIE_RT_CORE_ARGS="<compiled argv>"
ROSIE_RT_COMPILED_CONFIG=/etc/rosie-rt-core/compiled/<64 hex>

It refuses an argument list containing characters that would be unsafe unquoted in an environment file.

Host commands#

hostcheck#

Read-only inspection of a cell host's real-time prerequisites. It never measures cycle latency, so passing it does not qualify timing: it always reports timing_qualification as not_applicable.

sudo rtctl hostcheck --config /etc/rosie-rt-core/machine.json
# pass rt_cpu: observed="2" expected="configured nonnegative runtime.cpu (or deployed --rt-cpu)"
# …

It checks, among others: the RT CPU; kernel version and build; PREEMPT_RT (/sys/kernel/realtime or PREEMPT_RT in uname -v); the loaded IgH ec_master version (1.6.9); /dev/EtherCAT0 permissions for the device group; the RT CPU in isolated and nohz_full; the CPU frequency governor (performance); EtherCAT NIC IRQ affinity; clock source, timer slack and resolution; service users, groups and directories.

Each line is <status> <id>: observed="…" expected="…", with status pass, fail or not_applicable.

The --expected-release manifest has schema and a services map for exactly rosie-rt-core, rosie-rt-control and rosie-rt-natspublisher. Each entry gives template_sha256, unit_files[] (path, sha256), argv, executable_sha256, environment_files and environment. No tool in the repository generates it; the cell owner supplies it.

inventory#

Compiles a live machine config, then reads the EtherCAT bus and compares each slave with what the configuration expects. It only issues read commands (ethercat slaves and SDO upload).

sudo rtctl inventory --config /etc/rosie-rt-core/machine.json

Each axis reports match, mismatch or unreadable. A configured I/O terminal is reported too.

recover-encoder#

A maintenance procedure that clears an absolute-encoder alarm on a supported servo drive. It talks to the drive with the ethercat tool while the EtherCAT master is idle.

sudo systemctl stop rosie-rt-control rosie-rt-core
sudo rtctl recover-encoder --backend ethercat --slave 3

It refuses to write unless master 0 is idle (stop the daemon first), the slave is identified as a supported drive, is in PREOP and is disabled, and shows the specific encoder alarm it can clear. It refuses on any unexpected alarm between steps. It never starts the daemon or Home.

Control commands#

These send one request to rt-control through the Go SDK and print the result as indented JSON (compact with --json). describe and status print the description or status document itself; the other commands print the response envelope (schema, operation, sequence, handle, data, error).

Common flags#

Observation#

build/rtctl events --after 0 --follow --socket "$TMPDIR/control.sock"

resources fetch#

Downloads the cell's robot description files, verified by digest.

sha=$(build/rtctl describe --json | jq -r '.robot.resources[0].sha256')
build/rtctl resources fetch "$sha" --out ./cell-model
# ./cell-model/resources.json

It writes every resource as DIR/<sha256> and then the manifest DIR/resources.json, last, so an incomplete set never looks complete. It never overwrites an existing file. A digest the cell does not list is refused with resource_unknown.

Authority and machine control#

"Fence" means --session and --generation. The axis mask is a bit per axis, 0 to 0xffffffff.

# Take authority, then stop and give it back. Each call is one request.
build/rtctl acquire --pair-id readme --pair-revision 1 --configuration-sha256 "$digest"
build/rtctl stop    --session "$session" --generation "$generation"
build/rtctl release --session "$session" --generation "$generation"

Because rtctl does not renew, commands after acquire that need a live lease are usually refused with an authority reason once the lease lapses. See authority reasons.

Trajectories and programs#

rtctl commands bypass the weld planner's verifier: the core admits them against joint limits, velocity and continuity only. And because the lease lapses between commands, a prepared trajectory or program usually cannot be started from a second rtctl call. Drive motion from an SDK client instead.

Telemetry#

telemetry dump-to-jsonl#

Converts a raw telemetry dump written by the core (runtime.telemetry.directory) into JSON Lines, one record per cycle.

build/rtctl telemetry dump-to-jsonl /dev/shm/rt-core/telemetry/<dump>.bin > cycles.jsonl

Each line has the cycle time t_ns, seq, cycle, work_ns, cycle-level state (armed, grant and jog generations, safety_fault_mask, execution_fault_reasons, I/O words) and an ax array per axis (position p and target tp in counts, statusword sw, error codes, velocity and following error in counts, readiness and diagnostic fields). Values are in drive counts and ns, not rad. Keep the .bin file with its .json index.

Usage: rtctl telemetry dump-to-jsonl <file>. Exit 2 on wrong arguments.

Related pages#

• rt-control HTTP API: what each control command sends
• Configuration files
• Install rt-core on a cell host
• Your first motion: why the SDK, not rtctl, moves the robot
• Ports, sockets and environment variables