Cartesian motion server

robot-v4-cartesiand turns a stream of UDP intent packets into Cartesian jog on the robot. It resolves each Cartesian twist into joint velocities with a damped Jacobian, applies joint-limit and singularity scaling, and streams the result on the rt-control jog lane. NATS carries its leader lease and its lifecycle commands: arm, disarm, Home and stop.

The same binary has a second, motion-free mode, --resolve-only, which OLP runs as a subprocess to turn a twist or a displacement into joint velocities or waypoints.

rt_core is the only backend. The retired selections exit with backend_retired.

Run it#

Every binding is required. The server refuses to start without the control and jog sockets, the pair binding, six axis IDs, a URDF with its SHA-256, a UDP listen address, a NATS URL, a robot command subject and --trusted-lan-leader-authority.

robot-v4-cartesiand --backend rt_core \
  --rt-control-socket /run/rosie-rt-core/control.sock \
  --rt-jog-socket /run/rosie-rt-core/jog.sock \
  --rt-pair-id "$ROSIE_RT_PAIR_ID" --rt-pair-revision "$ROSIE_RT_PAIR_REVISION" \
  --rt-configuration-sha256 "$ROSIE_RT_CONFIGURATION_SHA256" \
  --rt-axis-ids J1,J2,J3,J4,J5,J6 \
  --rt-urdf robot_description/robots/rosie_1400_v3/robot.urdf \
  --rt-urdf-sha256 "$URDF_SHA256" \
  --udp-listen 127.0.0.1:9000 \
  --nats-url nats://127.0.0.1:14222 \
  --robot-cell cell-a \
  --robot-command-subject robot/v4/robot.cell-a.command \
  --nats-status-subject robot/v4/motion-server.cell-a.status \
  --trusted-lan-leader-authority

Build it with make -C motion-server/v1 all. The binary goes to $(ROSIE_HOME)/motion-server/v1/bin; set BIN_DIR to change it. On an installed host, motion-server/v1/start-motion-server.sh supplies the --rt-* bindings from the ROSIE_RT_* environment variables (ROSIE_RT_CONTROL_SOCKET, ROSIE_RT_JOG_SOCKET, ROSIE_RT_PAIR_ID, ROSIE_RT_PAIR_REVISION, ROSIE_RT_CONFIGURATION_SHA256, ROSIE_RT_AXIS_IDS, ROSIE_RT_URDF, ROSIE_RT_URDF_SHA256), and MOTION_SERVER_BINARY names the binary.

On startup the server acquires rt-control with its pair binding and renews the grant every 100 ms. It enables and arms only when a controller asks. Home never arms. On shutdown it ends the jog, stops and releases.

Command line#

Bindings#

Network and status#

A subject must name the concrete motion-server peer: robot/v4/motion-server.<peer>.… or robot/v4/robot.<peer>.…. --nats-arm-subject, --nats-go-home-subject, --nats-io-subject and --rtcore-target are retired and exit with backend_retired.

Offline modes#

UDP intent packet#

One datagram per intent, big-endian throughout. Version 2 adds the leader lease, and motion on the rt_core backend needs it.

A version 1 packet is exactly 70 + tool_id_len bytes. A version 2 packet is exactly 79 + tool_id_len + lease_id_len bytes. The maximum is 173 bytes. Anything else, or any non-finite float, is rejected.

Scaling#

Each linear axis maps to axes[i] × speed_scale × 0.2 m/s and each angular axis to axes[i] × speed_scale × π rad/s. The command is slew-limited at 0.75 m/s² linear and 540°/s² angular, resolved into six joint velocities, and scaled as one vector so no joint exceeds 100 rpm and the Jacobian's singularity gate. The rt_core backend then scales the whole vector again to Describe's per-axis velocity caps. One common scale is applied, so the direction of a Cartesian jog never bends.

Each jog output's deadline is at most 250 ms after the packet arrived, shortened by the time it waited in the socket queue.

Frames#

What halts the jog#

The server reads every waiting datagram (up to 64 per loop) and acts only on the newest. It halts, which ends the jog and runs Stop, when any packet in the batch:

• fails to decode, or has the deadman released
• is a neutral hold (a TOOL or JOINT packet with every axis within 0.02 of zero)
• is a disarm
• arrived without a kernel receive timestamp, or waited in the socket queue for 250 ms or more

It also halts when a packet's lease ID, fence epoch or sender does not match the current leader, or its sequence does not increase (leader_fence_or_sequence_rejected). After a halt, fresh input cannot resume motion. The controller must arm again.

NATS commands#

Commands arrive on --robot-command-subject as robot.v4.robot-command.v1 JSON. The server ignores messages for another robot and commands it does not own.

{
  "schema": "robot.v4.robot-command.v1",
  "command": "arm",
  "robot": "cell-a",
  "command_id": "c-17",
  "sender_id": "steamdeck:deck-1",
  "controller_boot_id": "boot-5c1e",
  "leader_lease_id": "…",
  "leader_fence_epoch": 3,
  "armed": true
}

Replies use robot.v4.command-reply.v1:

{"schema": "robot.v4.command-reply.v1", "component": "motion-server", "command": "arm", "command_id": "c-17", "accepted": true, "duplicate": false, "state": "completed"}

A reply that the command was queued is not proof it was applied. Read latest_processed_cold_command_id, latest_processed_cold_accepted and latest_processed_cold_result in the status document.

Leader lease#

The server grants one leader lease at a time. It is process-local and empty after every restart. A new grant is revoke-first: motion stops before the new fence epoch exists.

ttl_ms is clamped to 500–2000 ms. The grant shows in the status document: leader_id, leader_lease_id, leader_fence_epoch, leader_expires_in_ms and leader_lease_fresh. latest_leader_request_id and latest_leader_result report the outcome of your request, for example acquired, renewed, released, rejected or expired.

Lease commands spell the fence fence_epoch. Motion commands and UDP packets spell it leader_fence_epoch.

Robot commands#

A command that needs the lease and arrives without a matching one halts the server with rt_core_command_unowned, which stops any motion in progress. Any other command halts with rt_core_command_unavailable_or_unowned.

Status document#

Written to --status-output and published on --nats-status-subject. The schema name is robot_v4_motion_server_cartesian_live_status_v1.

Resolve-only protocol#

robot-v4-cartesiand --resolve-only /path/to/RosieOS rosie_1400_v3

The server loads REPO_ROOT/robot_description/robots/<MODEL>/robot.urdf once, then answers one JSON line on stdout for each JSON line on stdin. MODEL is rosie_1400_v3 or rosie_1420_v1. No sockets are opened and no grant is taken. Exit code 2 means a bad invocation, an unavailable model or a request line over 16,384 bytes; end of input exits 0.

{"model": "rosie_1400_v3", "frame": "base",
 "twist": [0.05, 0, 0, 0, 0, 0], "fraction": 0.5, "input_age_ns": 250000000,
 "pose": [0, -0.4, 0.8, 0, 0.6, 0], "lower": [-3.14, -1.9, -1.57, -3.14, -3.37, -2.09],
 "upper": [3.14, 1.9, 1.53, 3.14, 1.3, 3.14]}

{"accepted": true, "reason": "", "velocities": [0.0, 0.07, -0.05, 0.0, -0.02, 0.0],
 "joint_limit_scale": 1, "singularity_scale": 1, "waypoints": []}

For a twist, velocities are J1–J6 in rad/s. For a move, waypoints are J1–J6 positions in rad at 1 mm or 0.25° spacing along the straight line.

Refusal and halt reasons#

rt-control's own reasons pass through in refusal and typed_refusal. See Error codes.

Related pages#

• Motion paths and planning
• NATS subjects and streams
• Control authority
• Ports, sockets and environment