rt-control HTTP API

rt-control is the only public way to command a RosieOS cell. It serves HTTP/1.1 and JSON over a Unix socket on the cell host, and optionally over mutual TLS for remote clients. Every client uses it: the offline programming server, the motion servers, the pendant, rtctl and your own code. Behind it, rt-control talks to the real-time core over a private IPC channel, which is internal and not part of this API.

This page is generated from the contract file rt-core/protocol/application-v1.schema.json (contract_version 2) and the adapter code. It lists all 33 capabilities, every request and response field, and the reason codes each operation can return. The full catalogue of 153 reason codes is on Error codes and fault states.

Quick start#

Read the description and status, then take and release authority, from a shell on the cell host (or on a machine running the simulated core). The socket path is the installed default.

SOCK=/run/rosie-rt-core/control.sock
rt() { curl -sS --unix-socket "$SOCK" "http://localhost$1" "${@:2}"; }

# 1. Who is this cell? Check the backend, identity and axis order.
rt /v1/describe | jq '.data | {backend, machine_sha256, cycle_ns, axes: [.axes[] | {id, position_unit, min_position, max_position}]}'

# 2. What is it doing now?
rt /v1/status | jq '{armed: .data.core.armed, homed: .data.core.home_valid_mask, faults: .data.core.safety_fault_mask}'

# 3. Take authority, then give it back. Use the pair ID and revision rt-control was started with.
D=$(rt /v1/describe)
GRANT=$(rt /v1/control -H 'Content-Type: application/json' -d "$(jq -n --argjson d "$D" '{
  schema: "rosie.rt-control.request.v1", operation: "acquire", controller: "curl-demo",
  binding: {pair_id: "cell-a", revision: 1,
            configuration_sha256: $d.data.configuration_sha256, machine_sha256: $d.data.machine_sha256}}')")
echo "$GRANT" | jq '.data | {session, generation, lease_ms}'
rt /v1/control -d "$(echo "$GRANT" | jq '{schema: "rosie.rt-control.request.v1", operation: "release",
  session: .data.session, generation: .data.generation}')" | jq '.data.session == ""'

The default lease is 500 ms, and a shell cannot renew it between steps. For anything beyond this round trip, use a client that renews in the background: the Go SDK or the C++ client. rtctl wraps the same calls for one-off commands; see rtctl.

Operations at a glance#

Each capability has a state. implemented means the interface exists and is tested in software; it is not a hardware qualification. interim is the current reset API, test_only is for fixtures, and unimplemented returns capability_unimplemented. Describe returns this list at run time.

Connecting#

rt-control's own flags set these paths: --socket (default /run/rosie-rt-core/control.sock; jog.sock is created beside it) and --remote-listen. Use localhost as the HTTP host name on the Unix socket. Keep connections alive: the listener's idle timeout is control_idle_timeout_ns from Describe (90 s).

Request envelope#

Every JSON command is a POST /v1/control whose body is one Request object. schema and operation are always required. After acquire, every command also carries the session and generation of the current grant (the fence). Fields an operation does not use can be omitted. The server decodes strictly: unknown fields, duplicate fields and trailing data are refused.

session and generation come from the embedded Fence, so they sit at the top level of the object.

• Large uploads. For a large prepare_trajectory, send schema, operation, session and a non-zero generation before points, within the first 16384 bytes. rt-control admits the fence and reserves the upload slot before it reads the rest.
• Size caps. 16384 bytes for ordinary commands, 222516384 bytes for prepare_trajectory and 39298580 bytes for a .rdt upload to /v1/program. Larger bodies get HTTP 413 body_too_large.
• Units. Positions are in each axis's position_unit (rad or m), velocities per second, times in ns. Host times use the cell's CLOCK_MONOTONIC.

Idempotent retries#

Add request_id (1..64 printable ASCII bytes) to make a JSON command safe to retry. The current session remembers its last 256 outcomes. Resending the same decoded payload with the same ID joins the in-flight request or replays its final reply. Changing the payload under the same ID returns request_id_conflict. Release and lease expiry drop the cache, and so does an adapter restart.

Keep one ID for one logical attempt. Use a fresh ID for every renewal and after you correct a refused request. /v1/program uploads have no deduplication. After an ambiguous Start, inspect handle state and incarnations before you try new motion. The Go and C++ clients add a random request_id to every command.

Responses and errors#

Ordinary replies are one Response object with schema: rosie.rt-control.response.v1. data holds the operation's result type; sequence and handle are top-level fields. Fields that are zero or empty are omitted.

error is usually one catalogue label. It can also be an open diagnostic: JSON decoder errors, I/O and context errors, native receipts such as RTCore rejected operation 0x124: reason 2, or two causes joined with a newline. Some labels carry detail after a colon, for example native_limit_exceeded: segment=<index> sample=<index> axis=<id>. Match on the leading label. Treat anything you do not recognise, and any transport failure, as an unknown outcome: stop producing motion, issue an authenticated stop if you can, and reconcile Status before you acquire again.

Common reasons#

These sets apply in addition to each operation's own table. The operation sections say which sets apply.

Envelope reasons (every POST /v1/control)#

Authority reasons (every fenced call)#

Native reasons (calls the core admits)#

Cell I/O reasons (calls that can carry outputs)#

Observation#

Reads need no lease. On the remote listener they still need a valid client certificate.

describe#

Returns the native description (backend, protocol version, digests, cycle period, axis order, units and limits), the contract version and digest, every capability with its state, the prepared program if there is one, and the compiled robot description and drive identities.

Call it first. Check backend, machine_sha256, the axis order and capabilities_digest against what your client was built for before you acquire authority. max_grant_lease_ns and max_jog_input_age_ns are the cell's timing ceilings.

Request#

No parameters.

Response#

data is a Description.

Example#

GET /v1/describe HTTP/1.1
Host: localhost

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "describe",
  "data": {
    "backend": "simulation",
    "schema": "…",
    "protocol_major": 1,
    "protocol_minor": 10,
    "configuration_sha256": "c2b097096fef301cad3b9c3e594f32266c625feaccba02be3410ed08df2b63ea",
    "machine_sha256": "4f1d9a7c2e6b8d0f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f",
    "deployment_sha256": "…",
    "max_trajectory_points": 250000,
    "resident_plans": 3,
    "cycle_ns": 1000000,
    "interpolation": "…",
    "stop": "…",
    "axes": [
      {
        "index": 0,
        "id": "J1",
        "position_unit": "rad",
        "min_position": -2.96,
        "max_position": 2.96,
        "max_velocity": 1.5,
        "…": "…"
      }
    ],
    "bus": {},
    "max_grant_lease_ns": 500000000,
    "max_jog_input_age_ns": 250000000,
    "contract_version": 2,
    "capabilities_digest": "d63b2aee7bbcb7e4f11eca7148ce9ffda0e5d8db421f165d20918ccb4f119158",
    "capabilities": [
      {
        "name": "acquire",
        "state": "implemented",
        "transport": "POST /v1/control"
      },
      "…"
    ],
    "control_idle_timeout_ns": 90000000000,
    "robot": null,
    "drives": []
  }
}

Axis values in the example are illustrative. Read the real limits from your cell.

Reason codes#

No operation-specific reason codes. Unknown diagnostics mean the request failed.

Client libraries. Go: Client.Describe. C++: describe().

status#

Every successful snapshot belongs to one daemon incarnation: daemon_incarnation equals core.daemon_incarnation. time_ns is the native publication time, not an adapter estimate. Check validity flags and timestamps before you treat a logical position as valid.

execution.state reports the program lifecycle: prepared, executing, completed, faulted, cancelled, discarded or released (empty before any observation). A faulted program carries native_execution_failed in execution.error.

Request#

No parameters.

Response#

data is a ProcessStatus.

Example#

GET /v1/status HTTP/1.1
Host: localhost

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "status",
  "data": {
    "daemon_incarnation": "3b9d…",
    "adapter_incarnation": "a41c…",
    "grant": {},
    "jog": {},
    "jog_ingress": {},
    "core": {
      "armed": 0,
      "axis_enable_mask": 0,
      "home_valid_mask": 511,
      "safety_fault_mask": 0,
      "…": "…"
    },
    "motion": {
      "mode": 0,
      "state": 0,
      "done": false,
      "…": "…"
    },
    "execution": {
      "state": "",
      "generation": 0,
      "handles": [],
      "…": "…"
    },
    "time_ns": 81234567890123,
    "axes": [
      {
        "logical_position": 0,
        "logical_valid": true,
        "readiness": "not_enabled",
        "…": "…"
      }
    ],
    "generations": {},
    "plan_cursor": {},
    "buffer_health": {},
    "adapter": {}
  }
}

Reason codes#

Client libraries. Go: Client.Status. C++: status().

jog_clock#

Returns domain (CLOCK_MONOTONIC), the clock incarnation, mapping_generation and now_host_ns. Pass incarnation to begin_jog as clock_incarnation; every jog time you send uses this clock, in ns.

Request#

No parameters.

Response#

data is a LocalJogClock.

Example#

GET /v1/jog/clock HTTP/1.1
Host: localhost

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "jog_clock",
  "data": {
    "domain": "CLOCK_MONOTONIC",
    "incarnation": "0f3c9a…",
    "mapping_generation": 1,
    "now_host_ns": 81234567890123
  }
}

Reason codes#

Client libraries. Go: Client.JogClock. C++: jog_clock().

jog_status#

On the local socket this returns the native JogObservation. Its fields keep their native, case-sensitive names (Open, JogGeneration, InputDeadlineHostNs, StateReason …). The reasons are the numeric native jog reasons.

On the mutual-TLS listener the same path is the WebSocket upgrade for remote jog. See Remote access.

Request#

No parameters.

Response#

data is a JogObservation.

Example#

GET /v1/jog HTTP/1.1
Host: localhost

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "jog_status",
  "data": {
    "Open": 1,
    "JogGeneration": 4,
    "AxisMask": 1,
    "InputDeadlineHostNs": 81234817890123,
    "StateReason": 0,
    "…": "…"
  }
}

Reason codes#

Client libraries. Go: Client.JogStatus. C++: jog_status().

jog_ingress#

Counts every refused jog input across jog.sock datagrams, WebSocket frames and internal updates. refused_by_reason is indexed by native jog reason 0..14. The counters reset only when rt-control restarts.

Local datagrams get no reply, so this endpoint is how a local jog producer sees its refusals.

Request#

No parameters.

Response#

data is a JogIngressObservation.

Example#

GET /v1/jog/ingress HTTP/1.1
Host: localhost

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "jog_ingress",
  "data": {
    "source_sequence": 120,
    "reason": 0,
    "now_host_ns": 81234567890123,
    "refused": 2,
    "refused_by_reason": [
      0,
      0,
      0,
      0,
      2,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0
    ],
    "latest_refusal": {
      "source_sequence": 7,
      "reason": 4,
      "now_host_ns": 81230000000000
    }
  }
}

Reason codes#

No operation-specific reason codes. Unknown diagnostics mean the request failed.

Client libraries. Go: Client.JogIngress. C++: jog_ingress().

subscribe_events#

/v1/events returns one EventBatch inside the normal response envelope. /v1/events/stream is Server-Sent Events: each message has id (the sequence), event (the type) and data (one Event as JSON, with no envelope). after is the last sequence you handled; omit it to start from 0.

The ring keeps 256 events and a batch holds at most 64. The full model, including loss handling, is in Events and telemetry.

Request#

Response#

data is a EventBatch.

Example#

GET /v1/events?after=41 HTTP/1.1
Host: localhost

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "subscribe_events",
  "data": {
    "events": [
      {
        "sequence": 42,
        "time_ns": 81234567890123,
        "type": "grant_acquired",
        "daemon_incarnation": "3b9d…",
        "adapter_incarnation": "a41c…",
        "grant": {
          "…": "…"
        }
      }
    ],
    "next_sequence": 42,
    "latest_sequence": 42,
    "adapter_incarnation": "a41c…"
  }
}

Reason codes#

Client libraries. Go: Client.Events, Client.StreamEvents. C++: events(), events_stream().

telemetry#

Returns application/octet-stream: one 312-byte TelemetryBatchHeaderV1 followed by record_count 5392-byte CycleCaptureRecordV2 records. It is never JSON. /v1/telemetry returns one batch (gzip if you send Accept-Encoding: gzip). /v1/telemetry/stream writes one complete batch per flush, about every 20 ms, including empty batches.

Errors come back as a JSON Response. The binary layout and decoders are in Events and telemetry.

The contract describes it as: “Full-rate binary cycle records; observation needs no session or authority.”

Request#

Response#

The body is binary: a TelemetryBatch.

Example#

GET /v1/telemetry?after=0 HTTP/1.1
Host: localhost
Accept-Encoding: gzip

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Encoding: gzip
Cache-Control: no-store

<312-byte header><record_count × 5392-byte records>

Reason codes#

Client libraries. Go: Client.TelemetryBatches, Client.TelemetryStream. C++: telemetry(), telemetry_stream().

resource#

Serves the files of the compiled robot description (robot_description_manifest.json, robot.urdf, meshes, machine_planning_calibration.json …) listed in Describe robot.resources. The path component is the lowercase SHA-256 of the exact bytes.

The reply is the raw bytes with Content-Type, Content-Length and a quoted-digest ETag. rt-control never looks anything up in a repository at request time: only the loaded compiled resource set is served. Remote clients need the mutual-TLS listener, like every remote call.

The contract describes it as: “Read one bounded content-addressed compiled resource without a lease; remote mutual TLS required.”

Request#

Response#

The body is the resource itself. ResourceInfo (from Describe) describes it.

Example#

GET /v1/resources/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 HTTP/1.1
Host: localhost

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 48213
ETag: "9f86d081…"
X-Content-Type-Options: nosniff

<robot name="…">…

Reason codes#

Client libraries. Go: Client.Resource. C++: none.

Authority#

One controller at a time. See Control authority for the model behind these four calls.

acquire#

Only one controller holds authority at a time. acquire checks your binding against the pair and digests rt-control was started with. When you supply machine_sha256 it must match exactly and there is no fallback; without it, configuration_sha256 must match. On success you get a fresh 64-hex session, a generation one higher than the last, and the effective lease_ms.

The effective lease is min(requested_lease_ms, cell ceiling). Omit requested_lease_ms (or send 0) for the 500 ms default, still capped by the cell. Renew before it runs out. Local socket permissions or the remote TLS identity authenticate the connection; controller is only a label.

Request#

The contract's semantically required fields: schema, operation, controller, binding.

Response#

data is a Grant.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "acquire",
  "controller": "my-app",
  "binding": {
    "pair_id": "cell-a",
    "revision": 1,
    "configuration_sha256": "c2b097096fef301cad3b9c3e594f32266c625feaccba02be3410ed08df2b63ea",
    "machine_sha256": "4f1d9a7c2e6b8d0f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f"
  },
  "requested_lease_ms": 500
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "acquire",
  "data": {
    "stopping": false,
    "deadline_host_ns": 81234567890123,
    "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
    "generation": 3,
    "controller": "my-app",
    "binding": {
      "pair_id": "cell-a",
      "revision": 1,
      "configuration_sha256": "c2b097096fef301cad3b9c3e594f32266c625feaccba02be3410ed08df2b63ea",
      "machine_sha256": "4f1d9a7c2e6b8d0f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f"
    },
    "lease_ms": 500
  }
}

Reason codes#

Also the common envelope reasons.

Client libraries. Go: Client.Acquire, Client.AcquireLease. C++: acquire().

renew#

Renew keeps the session alive. The deadline moves to now plus the effective lease_ms, which never changes after Acquire. Renew at most every third of the lease, on its own connection, and use a fresh request_id each time: a reused ID replays the old receipt.

An older non-zero generation of the same live session may renew and learns the current fence from the reply, but it cannot move the robot. While a Stop is in flight, renew returns stopping: true: the lease is kept alive, and no motion permission is granted.

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

data is a Grant.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "renew",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "request_id": "5f0c2a9e6b1d4c3a8e7f0b2d4c6a8e1f"
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "renew",
  "data": {
    "stopping": false,
    "deadline_host_ns": 81234567890123,
    "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
    "generation": 3,
    "controller": "my-app",
    "binding": {
      "pair_id": "cell-a",
      "revision": 1,
      "configuration_sha256": "c2b097096fef301cad3b9c3e594f32266c625feaccba02be3410ed08df2b63ea",
      "machine_sha256": "4f1d9a7c2e6b8d0f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f"
    },
    "lease_ms": 500
  }
}

Reason codes#

Also the common envelope and authority reasons.

Client libraries. Go: Client.Renew, Client.StartRenewal. C++: renew(), start_renewal().

release#

Release runs the same inhibiting sequence as Stop and then clears the session: the returned Grant has an empty session. Stop your renewal loop first. The Go and C++ clients do that for you and never replay a Release automatically after a transport failure.

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

data is a Grant.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "release",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "release",
  "data": {
    "stopping": false,
    "deadline_host_ns": 81234567890123,
    "session": "",
    "generation": 4,
    "controller": "my-app",
    "binding": {
      "pair_id": "cell-a",
      "revision": 1,
      "configuration_sha256": "c2b097096fef301cad3b9c3e594f32266c625feaccba02be3410ed08df2b63ea",
      "machine_sha256": "4f1d9a7c2e6b8d0f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f"
    },
    "lease_ms": 500
  }
}

Reason codes#

Also the common envelope and authority reasons.

Client libraries. Go: Client.Release. C++: release().

stop#

Stop cancels execution, uploads, handles and jog at once, inhibits the drive outputs and increments the generation. It does not wait for a ramp. If the session is still valid you get it back with the new generation, and you need a fresh Enable and Arm before moving again.

A session that has expired or been revoked can still send Stop to inhibit, but it cannot regain motion permission. Concurrent Stop and Release calls join one cancellation. A Stop receipt does not prove the robot is at standstill.

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

data is a Grant.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "stop",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "stop",
  "data": {
    "stopping": false,
    "deadline_host_ns": 81234567890123,
    "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
    "generation": 4,
    "controller": "my-app",
    "binding": {
      "pair_id": "cell-a",
      "revision": 1,
      "configuration_sha256": "c2b097096fef301cad3b9c3e594f32266c625feaccba02be3410ed08df2b63ea",
      "machine_sha256": "4f1d9a7c2e6b8d0f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f"
    },
    "lease_ms": 500
  }
}

Reason codes#

Also the common envelope and authority reasons.

Client libraries. Go: Client.Stop. C++: stop().

Machine control#

Every call here needs the current session and generation.

enable#

Sends a native enable for axis_mask and waits for the native result. The receipt only confirms admission. Poll Status until each axis reports the expected enable bit and readiness. Enable and Arm on their own do not establish Home or permit a Start.

Request#

The contract's semantically required fields: schema, operation, session, generation, axis_mask.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "enable",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 511
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "enable",
  "sequence": 17
}

Reason codes#

Only the common envelope, authority and native reasons.

Client libraries. Go: Client.Enable. C++: enable().

arm#

Sends a native arm and waits for its result. Observe core.armed == 1 in Status. A successful Arm does not mean every axis is ready: the motion start gate is still checked at every Start and jog.

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "arm",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "arm",
  "sequence": 18
}

Reason codes#

Only the common envelope, authority and native reasons.

Client libraries. Go: Client.Arm. C++: arm().

home#

Runs native Home (commissioning) on axis_mask and waits up to 60 s for the result. Home leaves the selected axes disabled: observe the new home_epoch, an idle commissioning_phase and every selected bit in home_valid_mask, then Enable and Arm again. If Home fails, rt-control issues a Stop.

When ROSIE_RT_ANCHOR_DIR is set in rt-control's environment, a successful Home also saves one anchor file per selected axis, for later use by restore_anchor. Losing the HTTP reply does not cancel Home; Stop, lease expiry or transport loss do.

Request#

The contract's semantically required fields: schema, operation, session, generation, axis_mask.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "home",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 511
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "home",
  "sequence": 19
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.Home. C++: home().

halt#

Halt requests a controlled deceleration using the active trajectory's acceleration, or the jog acceleration when no trajectory bound is declared. It retires the active trajectory handle and jog generation, but keeps the grant, Enable and Arm. A new Start must begin at the held target; jogging needs a new begin_jog.

Halt does not replace Stop. Stop, faults and lease expiry always inhibit immediately. The receipt confirms admission, not a completed hold. A native refusal also carries native_result.

The contract describes it as: “Controlled deceleration to enabled hold using the active trajectory acceleration, or jog acceleration when no trajectory bound is declared. Retires active motion; preserves authority and Arm. Stop and faults always inhibit immediately.”

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "halt",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "halt",
  "sequence": 20
}

Reason codes#

Also the common envelope and authority reasons.

Client libraries. Go: Client.Command with Operation "halt". C++: command() with operation halt.

restore_anchor#

An alternative to Home after a restart. The machine must be disarmed, disabled and not commissioning. For every selected axis, the saved anchor's pair, revision, coordinate identity, drive identity and absolute source must match current evidence, and the core checks them again independently. Set ROSIE_RT_ANCHOR_DIR to the same directory for rt-control (write) and the core (read).

On success the reply carries the restore receipt in sequence and a RecoveryStatus read after it, with the selected bits set in home_valid_mask. Restoring never enables or arms.

Request#

The contract's semantically required fields: schema, operation, session, generation, axis_mask.

Response#

sequence holds the native command sequence and data is a RecoveryStatus.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "restore_anchor",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 511
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "restore_anchor",
  "sequence": 21,
  "data": {
    "home_valid_mask": 511,
    "faults": [],
    "reset_sequence": 0,
    "reason": "",
    "outcomes": []
  }
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.RestoreAnchor. C++: restore_anchor().

reset_fault#

reset_fault is labelled interim. It needs an inhibited, idle machine: not armed, no active jog, no commissioning, no native Home and no executing program. It submits one native fault reset for axis_mask (0 means every configured axis) and reports the correlated result: sequence, native_result and a RecoveryStatus whose reset_sequence matches.

A submitted reset retires your session, even when the core refuses it. Acquire again afterwards. Any persistent condition refuses the whole reset (fault_persists); there is no partial clear. Reset never starts motion and never grants Home. See fault recovery.

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

sequence holds the native command sequence and data is a RecoveryStatus. native_result carries the native CommandResult of the reset.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "reset_fault",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 0
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "reset_fault",
  "sequence": 22,
  "native_result": {
    "Sequence": 22,
    "Handle": 0,
    "Generation": 5,
    "Operation": 260,
    "Result": 0,
    "Reason": 0,
    "AxisMask": 511
  },
  "data": {
    "home_valid_mask": 511,
    "faults": [],
    "reset_sequence": 22,
    "reason": "",
    "outcomes": []
  }
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.ResetFault. C++: reset_fault().

recovery_status#

Requires the same inhibited, idle machine as reset_fault, but clears nothing and keeps the session. Each faults[] entry names the fault bit, the affected axes and its recovery class.

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

data is a RecoveryStatus.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "recovery_status",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "recovery_status",
  "data": {
    "home_valid_mask": 511,
    "faults": [
      {
        "bit": 5,
        "name": "following_error",
        "axis_mask": 4,
        "recovery": "reset_after_condition_clears",
        "outcome": "persists",
        "rehome_axis_mask": 0
      }
    ],
    "reset_sequence": 0,
    "reason": "fault_persists",
    "outcomes": []
  }
}

Reason codes#

Also the common envelope and authority reasons.

Client libraries. Go: Client.Command with Operation "recovery_status". C++: recovery_status().

io_arm#

Cell I/O outputs are only driven after an explicit io_arm under a fresh grant, with valid OFF readback observed after the last Stop. Stop commands every output OFF. Torch-class outputs are refused everywhere: see Process I/O and sensing.

The receipt confirms native permission only. It does not establish physical feedback.

The contract describes it as: “Native cell I/O permission; torch remains unqualified.”

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "io_arm",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "io_arm",
  "sequence": 23
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.IOArm. C++: io_arm().

io_disarm#

Clears output permission and intent in the native cycle.

The contract describes it as: “Native cell I/O permission; torch remains unqualified.”

Request#

The contract's semantically required fields: schema, operation, session, generation.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "io_disarm",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "io_disarm",
  "sequence": 24
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.IODisarm. C++: io_disarm().

mark_telemetry#

Adds a diagnostic mark. An accepted mark publishes one telemetry_mark event carrying the label, the native sequence and the grant generation. It does not take the motion lock, so it works during a long Home. A receipt does not mean anything was written to disk.

Request#

The contract's semantically required fields: schema, operation, session, generation, label.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "mark_telemetry",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "label": "before weld 3"
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "mark_telemetry",
  "sequence": 25
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.Command with Operation "mark_telemetry". C++: command() with operation mark_telemetry.

Jog#

Jogging uses its own lane with its own generation and input deadlines. The JSON calls open and close a jog session; the velocity updates themselves are binary frames.

begin_jog#

Reserves native jog mode for axis_mask. Get clock_incarnation from GET /v1/jog/clock. source_origin_host_ns is when your input was captured and deadline_host_ns is when it must stop applying, both in that host clock. The deadline is never extended by admission or renewal.

The reply's handle is the new jog generation. Send velocities with update_jog, then close with end_jog. Jog velocities are joint-space, in each axis's logical unit per second.

Request#

The contract's semantically required fields: schema, operation, session, generation, axis_mask, source_origin_host_ns, deadline_host_ns, clock_incarnation.

Response#

handle holds the result. handle is the jog generation.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "begin_jog",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 1,
  "source_origin_host_ns": 81234567890123,
  "deadline_host_ns": 81234667890123,
  "clock_incarnation": "0f3c9a…"
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "begin_jog",
  "handle": 4
}

Reason codes#

Also the common envelope and authority reasons.

Other native jog refusals return the diagnostic RTCore rejected jog (reason N) with native_jog_result set; see native jog reasons.

Client libraries. Go: Client.NewJogSession, Client.PrepareJogSession, Client.BeginJog. C++: RtJogProducer, begin_jog().

update_jog#

Updates are 224-byte little-endian local_jog_update frames. Local producers send them as Unix datagrams to jog.sock, next to control.sock. Remote producers send them as binary WebSocket frames on /v1/jog over mutual TLS (see Remote access). Build frames with the SDK (BuildJogFrame, RtJogProducer) rather than by hand.

Each frame carries the session, grant generation, jog generation, a strictly increasing non-zero source_sequence, its own origin and deadline, an axis mask and a finite velocity vector. deadline_host_ns − origin_host_ns may not exceed the cell's max_jog_input_age_ns (250 ms on LAN). Only the newest valid frame in a burst is applied, and a refused frame never extends the previous input's deadline. Local datagrams get no reply: read refusals from GET /v1/jog/ingress.

Request#

A 224-byte little-endian local_jog_update frame, defined in protocol/control.json. Reserved bytes are zero.

Response#

No reply on jog.sock. On WSS, only refusals are answered, as {"type":"rejected","seq":N,"reason":"…"}.

Reason codes#

A frame refused by the native lane is answered on WSS as jog_native_rejected_<n>, where n is the native jog reason. On jog.sock, every refusal is only counted in /v1/jog/ingress.

Client libraries. Go: JogSession.Update / UpdateAt, RemoteJogSession.Update. C++: RtJogProducer::update, RtJogRemoteProducer::update.

end_jog#

Revokes input for jog_generation before waiting for the native receipt, then the core ramps the jog to a stop. The reply's handle echoes the generation. end_jog does not release authority: call release separately. Ending during the expiry ramp can return a native closed refusal.

Request#

The contract's semantically required fields: schema, operation, session, generation, jog_generation.

Response#

handle holds the result. handle echoes the ended jog generation.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "end_jog",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "jog_generation": 4
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "end_jog",
  "handle": 4
}

Reason codes#

Also the common envelope and authority reasons.

Native jog refusals return RTCore rejected jog (reason N) with native_jog_result.

Client libraries. Go: JogSession.End, Client.EndJog. C++: RtJogProducer::end, end_jog().

jog#

Labelled test_only: it is kept for test fixtures. Applications use begin_jog, update_jog and end_jog instead.

The contract describes it as: “Legacy velocity jog is test-only for oracle ports and fixtures. Consumers use begin_jog/update_jog/end_jog; update_jog uses jog.sock or WSS /v1/jog.”

Request#

The contract's semantically required fields: schema, operation, session, generation, axis_mask, velocity, timeout_ms.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "jog",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 1,
  "velocity": [
    0.01,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ],
  "timeout_ms": 100
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "jog",
  "sequence": 26
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.Jog. C++: jog().

Trajectories#

A low-level point-list path, used by tests and short moves. Programs from the planner use Programs.

prepare_trajectory#

Stages 2..250000 Point records for axis_mask and returns a handle in the prepared state. Nothing moves until start_trajectory. The first point's time_ns is 0 and times strictly increase; positions and optional velocities are in Describe axis order and logical rad or m units. Native limits and continuity are enforced at Prepare, and again at Start.

For a large body, put schema, operation, session and a non-zero generation before points, within the first 16384 bytes, so rt-control can check the fence before reading the rest. Do not use a key-sorting JSON encoder. One JSON upload is admitted at a time across all listeners, and the whole body is capped at 222516384 bytes. This is the low-level path for tests and short moves; production programs use prepare_program.

Request#

The contract's semantically required fields: schema, operation, session, generation, axis_mask, points.

Response#

handle is the new handle and data is its HandleRecord.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "prepare_trajectory",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "axis_mask": 1,
  "points": [
    {
      "time_ns": 0,
      "position": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    {
      "time_ns": 1000000000,
      "position": [
        0.05,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  ]
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "prepare_trajectory",
  "handle": 7,
  "data": {
    "handle": 7,
    "state": "prepared",
    "generation": 3,
    "execution_generation": 0,
    "native_sequence": 0,
    "identity": {}
  }
}

Reason codes#

Also the common envelope, authority, native and cell I/O reasons.

A native invalid_trajectory refusal (reason 6) retires every prepared handle and the prepared program.

Client libraries. Go: Client.PrepareTrajectory. C++: prepare_trajectory().

start_trajectory#

Starts handle if it is still prepared and belongs to this grant. The full motion start gate is evaluated in the core: lease, Arm, bus, faults, configuration, Home, limits, CSP mode, enable and a first point continuous with the held position.

A definite not_ready or mode_conflict refusal restores the prepared plan so you can retry. Any uncertain outcome retires the handle: prepare again rather than replay. Completion is observed in Status and events, never inferred from the receipt.

Request#

The contract's semantically required fields: schema, operation, session, generation, handle.

Response#

sequence holds the native command sequence and data is a HandleRecord.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "start_trajectory",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "handle": 7
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "start_trajectory",
  "sequence": 27,
  "data": {
    "handle": 7,
    "state": "started",
    "generation": 3,
    "execution_generation": 1,
    "native_sequence": 27,
    "identity": {}
  }
}

Reason codes#

Also the common envelope, authority and native reasons.

Client libraries. Go: Client.StartTrajectory. C++: start_trajectory().

discard_trajectory#

Discards a prepared handle. Discarding an already discarded handle is a no-op. A started handle cannot be discarded: you get handle_active; use Halt or Stop instead.

Request#

The contract's semantically required fields: schema, operation, session, generation, handle.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "discard_trajectory",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "handle": 7
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "discard_trajectory",
  "sequence": 28
}

Reason codes#

Also the common envelope, authority and native reasons.

When native cleanup fails, the error reads discard preparation <handle>: <cause>.

Client libraries. Go: Client.DiscardTrajectory. C++: discard_trajectory().

Programs#

The production path for planned weld programs: upload a verified .rdt, then start it by identity.

prepare_program#

The body is the raw .rdt bytes (see the .rdt format); authority travels in headers. rt-control decodes and validates the whole file (format, digests, time grid, continuity, native position, velocity and declared acceleration limits, axis mapping and process markers) before staging it. It replaces any previously prepared program.

The reply's Program carries the full Identity. Echo it unchanged to start_program. prepare_program has no request_id deduplication: never replay an uncertain upload; inspect Describe or Status, or Stop, first. One binary upload is admitted at a time, and the body is capped at 39298580 bytes.

Request#

Body: Binary .rdt blob.

Required: X-Control-Session, X-Control-Generation.

Response#

data is a Program.

Example#

POST /v1/program HTTP/1.1
Host: localhost
Content-Type: application/octet-stream
X-Control-Session: 8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e
X-Control-Generation: 3
Content-Length: 1530412

<.rdt bytes>

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "prepare_program",
  "data": {
    "process_markers": [],
    "identity": {
      "plan_id": "weld-demo:1a2b3c4d5e6f",
      "program_id": "weld-demo",
      "program_digest": "sha256:…",
      "trajectory_digest": "sha256:…",
      "source_digest": "sha256:…",
      "normalised_digest": "sha256:…",
      "manifest_revision": 1,
      "plan_revision": 1
    },
    "requires_process_io": false,
    "segments": 3,
    "samples": 10002,
    "normalised_samples": 10000,
    "axis_mask": 511
  }
}

Reason codes#

Also the common authority and native reasons.

The dense format reasons are defined with the .rdt format. Every one of them is a catalogue label.

Client libraries. Go: Client.PrepareProgram. C++: prepare_program().

start_program#

identity must equal the prepared program's Identity field for field. The same start gate as start_trajectory applies. Record sequence; completion appears in Status as execution.state: completed for the next execution.generation, or faulted with native_execution_failed.

To retry a lost receipt, resend the same request with the same request_id. A new ID is a new command.

Request#

The contract's semantically required fields: schema, operation, session, generation, identity.

Response#

sequence holds the native command sequence. There is no data.

Example#

POST /v1/control HTTP/1.1
Host: localhost
Content-Type: application/json

{
  "schema": "rosie.rt-control.request.v1",
  "operation": "start_program",
  "session": "8c2f4e1a9b7d3c5e0f6a2b4c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b2c4d6e",
  "generation": 3,
  "request_id": "9b2e41c07d5f4a3e8c6b1d0f2a4e6c8b",
  "identity": {
    "plan_id": "weld-demo:1a2b3c4d5e6f",
    "program_id": "weld-demo",
    "program_digest": "sha256:…",
    "trajectory_digest": "sha256:…",
    "source_digest": "sha256:…",
    "normalised_digest": "sha256:…",
    "manifest_revision": 1,
    "plan_revision": 1
  }
}

{
  "schema": "rosie.rt-control.response.v1",
  "operation": "start_program",
  "sequence": 29
}

Reason codes#

Also the common envelope, authority, native and cell I/O reasons.

Client libraries. Go: Client.StartProgram. C++: start_program().

Reserved operations#

Named in the contract so clients can detect them, but they perform no operation.

abort#

Advertised as unimplemented, with transport none. Sending operation: "abort" performs nothing and returns capability_unimplemented with the CapabilityInfo in data. Use stop or halt.

Request#

The standard envelope with operation set to the operation name. No other fields.

Response#

Always refused; see below.

Reason codes#

readiness#

Advertised as unimplemented. Returns capability_unimplemented. Read per-axis readiness from GET /v1/status instead.

Request#

The standard envelope with operation set to the operation name. No other fields.

Response#

Always refused; see below.

Reason codes#

Types#

Every type in the contract, generated from types in the schema. Required is the codec designation; which fields an operation needs is in its request table. JSON integers are exact uint64 values: parse them without converting to floating point. Fields of native receipts (CommandResult, JogObservation, GrantObservation) keep their case-sensitive native names.

Authority#

Fence#

Binding#

Grant#

GrantObservation#

Requests and responses#

Request#

Response#

RawResponse#

CommandResult#

CapabilityInfo#