Dense trajectory daemon

joint_trajectory_daemon stores immutable .rdt programs and plays them on the robot through rt-control. It has two planes that never overlap:

• Data plane: TCP, on 127.0.0.1:8797 by default. Upload, validate, preload and status. Nothing on this socket can start motion.
• Control plane: NATS, on the cell's robot command subject. A controller acquires the daemon's leader lease, then sends play with the exact plan identity. stop is always accepted.

The daemon uses rt_core as its only backend. Retired backends and options exit with backend_retired or option_retired.

Quick start#

The dev stack runs the daemon against the simulated core like this:

joint_trajectory_daemon --backend rt_core \
  --config "$ROSIE_LOCAL_RT_BUILD/daemon-rt-core.json" \
  --dense-ingest-listen 127.0.0.1:8797 \
  --plan-store-dir "$ROSIE_LOCAL_RT_BUILD/dense-plans" \
  --nats-url nats://127.0.0.1:14222 \
  --robot-cell dev-cell \
  --robot-command-subject robot/v4/robot.dev-cell.command \
  --status-publish-subject robot/v4/robot.dev-cell.status

Build it with make -C motion-server/joint-trajectory/v1 all. The binary goes to rt-core/build/dense (make ... print-bin-dir prints the path).

Then upload a program from Python. The weld planner package has a client for the TCP framing:

from weldplan.dense_joint_trajectory import upload, request

blob = open("hold.rdt", "rb").read()
print(upload("127.0.0.1", 8797, blob))
# {'ok': True, 'kind': 'upload', 'trajectory_digest': 'sha256:…',
#  'segment_count': 1, 'total_sample_count': 3, 'total_duration_s': 0.02}
print(request("127.0.0.1", 8797, "status"))

To play it, a NATS client acquires the leader lease, preloads over TCP, and sends play. The sequence is in Play a program.

Command line#

Settings come from the JSON config file first. Command-line flags override it.

--joint-target and --rtcore-status-subject are retired and exit with option_retired. Exit code 2 means a configuration or usage error.

Config file#

The canonical, annotated copy is motion-server/joint-trajectory/v1/config/joint_trajectory_daemon.config.json. Every REPLACE_… value must be replaced with the cell's approved binding before the daemon will start.

{
  "schema": "robot.v4.joint-trajectory-daemon.config.v1",
  "ingest": { "listen": "127.0.0.1:8797" },
  "status": { "publish_hz": 20.0 },
  "leader": { "ttl_min_ms": 500, "ttl_max_ms": 2000 },
  "backend": "rt_core",
  "rt_core": {
    "socket": "/run/rosie-rt-core/control.sock",
    "controller": "motion-server",
    "pair_id": "REPLACE_WITH_APPROVED_PAIR",
    "pair_revision": 1,
    "machine_sha256": "REPLACE_WITH_APPROVED_MACHINE_SHA256",
    "deployment_sha256": "REPLACE_WITH_APPROVED_DEPLOYMENT_SHA256",
    "configuration_sha256": "REPLACE_WITH_APPROVED_CONFIGURATION_SHA256",
    "expected_backend": "simulation",
    "home_policy": "home",
    "status_subject": "motion-server.status",
    "control_timeout_ms": 10000
  }
}

Integers must be positive and strings non-empty. A missing file that was asked for, a wrong schema or a malformed value is a startup error; the daemon never falls back to compiled defaults.

On leader_acquire the daemon also checks that rt-control implements describe, acquire, renew, enable, arm, home, restore_anchor, recovery_status, prepare_program, start_program, status, subscribe_events, stop and release, and that Describe lists exactly nine axes J1…J9 in rad. A six-axis cell is refused with native_axis_map_invalid.

TCP ingest#

One request and one response per connection, then the daemon closes it. Each exchange must finish within 240 s.

frame   = [u64 BE payload_size][payload]            payload_size ≤ 64 MiB
payload = [u32 BE json_len][control JSON][optional binary body]

The response uses the same framing, with a JSON body and no binary part. A rejection is:

{"ok": false, "reason": "block_sha256_mismatch", "segment_index": 0, "detail": "stored sha256:… computed sha256:…"}

segment_index is present only when one segment is at fault.

upload#

Validates the binary body as a .rdt and stores it. Upload never causes motion.

{"kind": "upload"}

{"ok": true, "kind": "upload", "trajectory_digest": "sha256:…", "segment_count": 1, "total_sample_count": 3, "total_duration_s": 0.02}

Refusals: any .rdt validation reason (the daemon reports a wrong schema as schema_mismatch), and store_write_failed.

validate#

The same checks as upload, without storing. Answers "kind": "validate".

preload#

Stages a stored blob by reference and prepares it on rt-control (prepare_program). It needs the leader lease to be held, because preparation happens under the daemon's rt-control grant.

{
  "kind": "preload",
  "trajectory_digest": "sha256:…",
  "plan_id": "demo:1",
  "program_id": "demo",
  "program_digest": "sha256:…",
  "manifest_revision": 1,
  "plan_revision": 1
}

The daemon re-verifies the stored bytes in full, so a blob corrupted on disk fails here rather than at play.

{"ok": true, "kind": "preload", "trajectory_digest": "sha256:…", "total_sample_count": 3}

A refused native_limit_exceeded leaves any previously prepared program in place. Other native refusals stop the executor and release the grant.

status#

{"kind": "status"}

Returns the status document.

NATS control plane#

Commands are JSON messages on --robot-command-subject. Send them as NATS requests: the daemon replies on the message's reply subject. It ignores messages with a different robot, a missing envelope field or a command it does not own.

Every command carries this envelope:

Replies have this shape:

{"schema": "robot.v4.command-reply.v1", "command": "play", "command_id": "c-42", "ok": false, "reason": "fresh_exact_leader_lease_required"}

Leader lease#

The daemon mints the lease itself. A client never supplies an epoch or lease ID to leader_acquire.

{"schema": "robot.v4.robot-command.v1", "command": "leader_acquire", "robot": "dev-cell",
 "command_id": "c-1", "sender_id": "offline-programming:bench-1",
 "controller_boot_id": "boot-7f3a", "ttl_ms": 1000}

{"schema": "robot.v4.command-reply.v1", "command": "leader_acquire", "command_id": "c-1", "ok": true,
 "lease_id": "motion-server-…-0000000000000001", "leader_fence_epoch": 1, "expires_in_ms": 1000}

ttl_ms is clamped to leader.ttl_min_ms…leader.ttl_max_ms. Renew well inside the TTL. If the lease expires, the executor aborts any playback with leader_lease_expired, then stops and releases its rt-control grant. Note the field names: lease commands use lease_id, motion commands use leader_lease_id.

Lease refusals: leader_identity_invalid, ttl_ms_required, client_fence_not_accepted (an acquire that carried a lease ID or epoch), lease_not_held.

Play a program#

1. leader_acquire on NATS. Keep renewing.
2. upload the blob over TCP, then preload it with its identity.
3. play on NATS:

{
  "schema": "robot.v4.robot-command.v1", "command": "play", "robot": "dev-cell",
  "command_id": "c-3", "sender_id": "offline-programming:bench-1",
  "controller_boot_id": "boot-7f3a",
  "leader_lease_id": "motion-server-…-0000000000000001", "leader_fence_epoch": 1,
  "motion_intent_seq": 1,
  "plan_id": "demo:1", "program_id": "demo", "program_digest": "sha256:…",
  "trajectory_digest": "sha256:…", "manifest_revision": 1, "plan_revision": 1
}

A play the daemon accepts runs these phases, reported in commissioning_phase:

1. preparation: status and the prepared identity are read back from rt-control.
2. home or restore_anchor: only for axes whose Home is not valid, as home_policy says. Refused with native_home_unavailable if an axis has no native Home.
3. enable_arm: recovery status must show no faults, then enable and arm.
4. readiness: waits until every program axis reports ready.
5. start: start_program with the full identity.

The reply comes when start_program has been accepted, or when a phase fails. Progress is then visible in the status document.

Other commands#

Fenced commands are refused with fresh_exact_leader_lease_required, ordered_motion_intent_sequence_required, stale_motion_intent_sequence or exact_staged_plan_identity_required before the executor sees them. play, leader_acquire and leader_release run on a queue; when 256 are already waiting, a new one is refused with command_queue_full.

Status document#

The TCP status reply, the --status-publish-subject stream and the rt_core.status_subject stream carry the same document.

{
  "ok": true, "kind": "status",
  "schema": "robot.v4.dense-joint-trajectory.v1",
  "store_dir": "/srv/rosie/dense-plans",
  "staged": {"trajectory_digest": "sha256:…", "plan_id": "demo:1", "total_sample_count": 3},
  "executor": {
    "state": "playing", "backend": "rt_core", "native_state": "owned",
    "execution_state": "executing", "commissioning_phase": "",
    "execution_generation": 4, "native_sequence": 118,
    "segment_index": 0, "sample_index": 1, "t_s": 0.01,
    "detail": "", "consumer_action": "", "native_result": null,
    "program_identity": {"plan_id": "demo:1", "…": "…"},
    "authority_fresh": true, "leader_fresh": true
  },
  "last_error": null
}

--status-publish-subject carries this whole document at status.publish_hz. rt_core.status_subject carries only the executor object, every 200 ms.

The executor document also carries compatibility fields from an earlier backend: armed, torch_on, feedback_age_ms, tracking_error_rad, tracking_error_axis, transient, and the authority and feedback objects. The rt_core executor does not fill them; they keep their defaults (armed is false, feedback_age_ms is -1). Read native_state, execution_state and rt-control's own status instead.

consumer_action#

After an abort the daemon stops the grant, releases it, and waits for two consecutive, newer status samples that show no grant, the axes disarmed and disabled, and unchanged positions before it reports inactive.

Refusal codes#

Beyond the ingest and lease reasons above, abort_reason and play replies can carry:

rt-control's own reasons pass through unchanged. See Error codes.

Related pages#

• Motion paths and planning
• Dense trajectory (.rdt) format
• NATS subjects and streams
• Control authority