Offline programming HTTP API

The offline programming (OLP) server is the backend of the OLP web app and of the Steam Deck v5 pendant. It serves CAD import, seam authoring and weld planning, a local simulator, and machine control: Home, Arm, joint and Cartesian jog, joint and Cartesian moves, Load, Play and Stop on a selected cell, through rt-control.

All routes are under /api/offline-programming/v1 on 127.0.0.1:8794 by default (serve --listen). The server has no authentication. It is meant to be reached from the same host, by the UI's dev proxy or by a pendant's local process. Don't expose it on a network.

Quick start#

This selects the local simulated cell that the dev stack provides, homes it, arms it, jogs J1 for a moment, and stops.

OLP=http://127.0.0.1:8794/api/offline-programming/v1

# 1. Pick a cell. The dev stack lists "local-simulation" first.
curl -s $OLP/targets
curl -s -X POST $OLP/targets/select -d '{"cell_id":"local-simulation","model_id":"rosie_1400_v3"}'

# 2. Every mutating dense-execution call carries the selection it was made against.
STATUS=$(curl -s $OLP/dense-execution/status)
GEN=$(echo "$STATUS" | jq -r .target.selection_generation)
CELL=$(echo "$STATUS" | jq -r .target.cell_id)
FENCE=(-H "X-RT-Target-Generation: $GEN" -H "X-RT-Target-Cell: $CELL")

# 3. Home, then arm. Arm acquires the rt-control lease.
curl -s -X POST $OLP/dense-execution/home "${FENCE[@]}"
curl -s -X POST $OLP/dense-execution/arm "${FENCE[@]}" -d '{"armed":true}'

# 4. Jog J1 at 10 % for one hold. A real client repeats "update" every 50 ms.
TARGET=$(curl -s $OLP/dense-execution/capabilities | jq -r .cell)
SESSION=$(curl -s $OLP/dense-execution/status | jq -r .session.id)
REV=$(curl -s $OLP/dense-execution/jog/state | jq -r .revision)
JOG="{\"target_id\":\"$TARGET\",\"session_id\":\"$SESSION\",\"revision\":$REV,\"axis\":0,\"direction\":1,\"fraction\":0.1}"
curl -s -X POST $OLP/dense-execution/jog/begin "${FENCE[@]}" -d "$JOG"
curl -s -X POST $OLP/dense-execution/jog/end -d "$JOG"

# 5. Stop always works and needs no fence. It also releases the lease.
curl -s -X POST $OLP/dense-execution/stop

While OLP holds the lease, send a heartbeat at least every 5 s, or OLP stops the machine with ui_heartbeat_lost.

Conventions#

• Request and response bodies are JSON unless a route says otherwise. Unknown request fields are ignored; trailing data after the JSON value is refused.
• Units are in the field names: _rad, _deg, _mm, _m, _s, _ms, _ns. Where a name has no unit, the table says.
• Request body limits: 64 KiB for dense-execution routes, 12 MiB for /cadquery/topology and /seam, 24 MiB for /weld-plan.
• Responses are gzip-compressed when the client accepts it.

Errors#

Two error shapes are in use.

Machine-control routes (/dense-execution/*, /targets/select):

{"error": "home_required", "detail": "home_required: establish the current joint position reference in Home before loading the program"}

error is a stable code. A refusal from rt-control keeps rt-control's reason as the code. A limit refusal can add limit_violation: {kind, segment, sample, axis, value, limit, unit}.

Authoring and service routes:

{"ok": false, "code": "seam_worker_unavailable", "error": "the seam worker is unavailable, so no plan request can be packed"}

Target fencing#

When the server runs with a cell catalogue (OFFLINE_PROGRAMMING_CELLS), every POST under /dense-execution/ must name the selection it was issued against:

If another client has selected a different cell since, the request is refused with 409 target_changed and nothing is sent to the robot.

These routes are exempt, so they always work: /stop, /pause, /heartbeat, /target, /cells, /jog/stop, /jog/end, and /arm with {"armed": false}. /cartesian/stop and /cartesian/halt are not exempt.

Without a catalogue (a single target from --rt-core-config), there is no selection and no fencing.

Routes at a glance#

Service#

{"ok": true, "schema": "offline-programming.server-status.v1", "mode": "offline_preview",
 "network_required": false, "connected": false, "connected_targets": 0,
 "local_simulator": { … }, "local_ready": true, "execution_enabled": false,
 "target_planning": false, "teleop_enabled": false,
 "program_catalog": {"available": false, "owner": "motion-server"}}

execution_enabled and connected_targets describe the legacy connected-execution path, not dense execution.

{"robots": [{"model_id": "rosie_1400_v3", "robot_description_sha256": "sha256:…",
   "frames": {"base": "world", "tool": "tool0", "work": "positioner_table_a_top",
              "work_world_m": [0, -0.622, 0.1], "arm_base_world_m": [ … ]},
   "axes": {"driven": ["J1", "J2", "J3", "J4", "J5", "J6", "J7"], "held": {"J8": 0, "J9": 0}},
   "reset_pose": { … }}],
 "problems": []}

problems names each description that failed to load. A 500 with robot_store_unreadable means the description directory itself could not be read.

Returns {"urdf": "<xml>", "identity": …}. A failure returns 400 {"error": "…"}. If the description is neither local, cached nor advertised by the selected cell: adopt the matching robot description before recording.

Authoring and planning#

The worker operations are extract_topology, build_seam, build_sequence and tessellate. Error codes are the same set as the seam worker's, below.

The body names the operation: {"operation": "detect_joints", …}. Operations: detect_joints, check_torch_fits, plan_torch_path, sample_seam_frames, build_plan_request. The response header X-Offline-Seam-Part identifies the part the answer is about.

See the weld program format for the operations' payloads.

Plan a program#

The server always asks the planner for weld and connecting trajectory optimisation, verification and a dense trajectory.

{"result": { … }, "weldplan_sha256": "…", "program_digest": "sha256:…",
 "dense": {"trajectory_digest": "sha256:…", "plan_id": "bracket_fillet:3f1c0a9d2b7e", … },
 "dense_blob_base64": "…"}

Returns the container bytes as an attachment named <program_id>.weldplan, with its hash in X-Weldplan-SHA256.

Cells and targets#

A cell is a commissioned machine in the server's catalogue. Selecting one creates the controller for it and bumps the selection generation used for target fencing. Selection grants no authority; Arm or Load does. See Connect to a cell for the catalogue file.

{"targets": [{"cell_id": "local-simulation", "label": "Local simulation", "role": "LOCAL SIMULATION",
   "models": ["rosie_1400_v3"], "requested_mode": "simulation",
   "backend": "simulation", "simulation": true, "host": "localhost"}],
 "selected": null}

A cell that cannot be used has backend: "unreachable" and a reason, for example cell_configuration_missing, cell_mode_mismatch or cell_unreachable.

Returns {"selected": {cell_id, model_id}, "target": {…view…}}. Refusals, all 409: cell_switch_busy, cell_switch_while_playing, cell_model_mismatch, cell_id_unknown, cell_mode_mismatch (the cell's backend is not the requested mode), cell_previous_stop_failed, cell_backend_unavailable, cell_configuration_mismatch, cell_description_invalid, cell_backend_mismatch, cell_unreachable. Without a catalogue: 503 cell_catalogue_unavailable.

POST /dense-execution/cells only accepts a cell that matches a commissioned server-side binding (otherwise cell_not_commissioned or cell_binding_pinned). DELETE /dense-execution/cells/{id} always refuses with cell_commissioning_required, or dense_cell_active for the selected cell: commissioned cells are removed from the catalogue file, not from the UI.

Machine control#

Every route below answers 503 dense_target_unavailable when no cell is selected. Every mutating route except the exempt ones needs the fencing headers.

Observe#

{"backend": "rt_core", "available": true, "cell": "local-dev", "controller_id": "offline-programming:server-3f9a1c",
 "daemon_reachable": true, "rt_core": {"description": { … }, "address_host": ""},
 "active_cell": "local-simulation", "cells": [ … ]}

cell is the cell's pair ID. Joint and Cartesian jog and moves send it as target_id. rt_core.description is rt-control's Describe. reason explains an unreachable controller, for example rt_core_identity_mismatch.

{
  "backend": "rt_core", "available": true,
  "target": {"selection_generation": "4", "cell_id": "local-simulation", "model_id": "rosie_1400_v3",
             "label": "Local simulation", "backend": "simulation", "simulation": true, "host": "localhost"},
  "session": {"id": "ds-9b1e4f07a2c3", "kind": "trajectory", "state": "loaded", "dry_run": true,
              "trajectory_digest": "sha256:…", "plan_id": "bracket_fillet:3f1c0a9d2b7e",
              "lease": {"held": true, "expires_in_ms": 0},
              "heartbeat_age_ms": 820, "heartbeat_deadline_ms": 5000,
              "stop_reason": "", "last_error": ""},
  "armed": true,
  "robot_cell": {"configured": true, "valid": true, "model_id": "rosie_1400_v3",
                 "robot_description_sha256": "sha256:…", "machine_planning_calibration_sha256": "sha256:…",
                 "machine_planning_calibration_present": false, "error": ""},
  "rt_core": {"inhibited": false, "stop_uncertain": false, "recovery_action": "",
              "refusal": "", "refusal_kind": "", "reason": "", "status": { … }, "events": [ … ], "description": { … }},
  "round_trip_ns": 180000, "link_lease_ns": 500000000
}

Returns {daemon_incarnation, configuration_sha256, cycle_period_ns, axis_count, stride, seconds, first_sequence, last_sequence, head_estimate, fetched_records, fetch_ms, records: [...]}. One second of 1 kHz telemetry is about 4.9 MB from the cell before thinning. Errors: 400 telemetry_window_invalid, 503 telemetry_unavailable, 409 telemetry_identity_changed.

Home#

Returns the status body. If an axis has a latched reference fault whose recovery is a reset, Home resets it first. Other latched faults refuse with rt_core_fault. Errors: 400 home_axes_invalid, 409 capability_unimplemented, and rt-control reasons.

Arm and disarm#

{"ok": true, "accepted": true, "status": { … }}

If a latched execution fault can be cleared by a reset (recovery class reset_clears or reset_after_condition_clears), Arm resets it first, then re-acquires and arms, so one Arm recovers the machine. Faults that need a re-Home or a restart are left to their refusal. Errors: 400 dense_arm_invalid, 409 rt_core_arm_refused, 409 rt_core_arm_timeout, and rt-control reasons such as control_already_owned or not_ready.

Heartbeat#

{"session_id": "ds-9b1e4f07a2c3"}

{"ok": true, "deadline_ms": 5000, "age_ms": 1004}

age_ms is how long the previous beat had stood. If no beat arrives for 5 s, OLP stops the machine with ui_heartbeat_lost, except while an accepted Cartesian move is finishing. Errors: 400 dense_session_required, 409 dense_session_mismatch.

Load, Play, Stop#

{
  "trajectory_digest": "sha256:…",
  "plan_id": "bracket_fillet:3f1c0a9d2b7e",
  "program_id": "bracket_fillet",
  "program_digest": "sha256:…",
  "manifest_revision": 1,
  "plan_revision": 3,
  "dry_run": true
}

Load runs these checks in order, before any byte reaches the robot:

1. The identity matches the header (dense_identity_mismatch).
2. The plan's robot_cell matches the machine (robot_cell_missing, robot_cell_mismatch, robot_cell_unavailable).
3. Every configured axis has valid Home (home_required).
4. OLP acquires the lease and calls prepare_program. rt-control applies its admission checks.
5. The prepared identity, axis mask and process requirement match (program_identity_or_process_mismatch).

{"ok": true, "session_id": "ds-9b1e4f07a2c3",
 "trajectory": {"trajectory_digest": "sha256:…", "total_sample_count": 4210, "total_duration_s": 42.09, "dt_s": 0.01,
                "segments": [{"index": 0, "kind": "freespace", "source_id": "approach-1", "sample_count": 350, "duration_s": 3.49}]},
 "status": { … },
 "notes": ["the machine's configuration changed since this plan was made (…); the robot description and planning calibration still match, so it loads"]}

Other errors: 400 dense_identity_invalid, 400 dense_trajectory_invalid, 404 dense_blob_not_found, 503 dense_blob_source_unavailable, 409 program_already_executing, and rt-control reasons with an optional limit_violation.

Refused with control_session_stale unless the session is the loaded one and OLP holds the lease. Arm before Play.

{"ok": true, "stopped": true, "attempts": 1, "status": { … }}

note: "nothing_held" means there was nothing to stop. If Stop or Release cannot be confirmed, the answer is an error that still carries stopped, attempts and status, and further motion is blocked (rt_core_inhibited) until a Stop succeeds. A receipt does not prove the robot is standing still; see Software stops.

Joint jog#

Send begin, then update every 50 ms while the operator holds the control, then end. An update may not change axis, direction or fraction; end the hold and begin a new one. Each update lives for the cell's jog input age (250 ms on a LAN cell). If updates stop, the jog ends with jog_input_deadline_expired and the axis ramps to a hold.

{"active": true, "revision": 12, "generation": 3, "sequence": 41, "axis": 0, "reason": "", "cadence_ms": 50,
 "move": {"axis": 0, "state": "done", "reason": "", "revision": 11}}

Errors (409 unless noted): jog_session_stale, jog_mode_conflict (a move, a program or another hold is active), no_grant, jog_not_ready, invalid_axis_mask, 400 jog_invalid_vector, jog_input_deadline_expired, jog_transport_congested, dense_target_unavailable, and native jog reasons.

Joint move#

{"target_id": "local-dev", "session_id": "ds-9b1e4f07a2c3", "revision": 12, "fraction": 0.2,
 "axis": 0, "degrees": 0,
 "axes": [{"axis": 0, "position_rad": 0}, {"axis": 1, "position_rad": 0}, {"axis": 2, "position_rad": 0},
          {"axis": 3, "position_rad": 0}, {"axis": 4, "position_rad": 0}, {"axis": 5, "position_rad": 0}]}

Each joint follows its own trapezoid at fraction × max_velocity × 0.75 and fraction × its jog acceleration (or its described maximum acceleration, if lower). Shorter profiles are stretched so all joints start and finish together. The points are sampled at the core's cycle and sent with prepare_trajectory and start_trajectory. The target must be inside the joint's limits.

{"axis": 0, "state": "done", "reason": "", "revision": 13, "axes": [0, 1, 2, 3, 4, 5]}

Errors: joint_move_invalid, joint_move_limits, joint_move_units, joint_move_description_invalid, joint_move_too_many_points, joint_move_prepare_timeout, joint_move_prepare_busy, joint_move_interrupted, joint_move_completion_timeout, joint_move_feedback_invalid, client_disconnected, plus the joint jog errors. If the HTTP client disconnects, OLP stops the move.

Cartesian jog#

OLP resolves the twist into joint velocities from the measured pose with robot-v4-cartesiand --resolve-only, then scales the whole vector so no joint exceeds fraction × max_velocity × 0.75. The twist sets the direction; the joint ceilings usually set the speed. A step that would leave a joint's limits within one input lifetime is refused with joint_limit.

Errors: 400 cartesian_input_invalid, cartesian_resolver_unavailable, cartesian_resolver_invalid, cartesian_pose_stale, cartesian_axes_invalid, joint_limit, jacobian_gate, ik_no_solution, plus the joint jog errors.

Cartesian move#

The resolver solves IK along the line at 1 mm or 0.25° spacing and checks each waypoint against joint limits and the singularity gate. OLP then times the path with a smooth (quintic) progress clock, so that no joint exceeds fraction × max_velocity × 0.75, reduced further near a singularity, or fraction × its acceleration limit. It sends the result as one trajectory. An accepted move finishes even if the HTTP client disconnects; Stop still cancels it.

Errors: cartesian_input_invalid, cartesian_reach, ik_no_solution, joint_limit, cartesian_pose_stale, cartesian_resolver_invalid, joint_move_too_many_points, plus the joint move errors.

Local simulator#

The server can own a loopback-only rt-core simulator for preview. It requires a loopback --listen address and is on by default (--enable-local-simulator).

Once a machine is selected, preview jog requests are refused with target_changed, so a preview cannot run beside a selected controller.

Program catalog#

GET/POST /programs, GET/PUT /programs/{program_id} and GET /programs/{program_id}/revisions proxy to an external program catalog set with --program-catalog-origin. Without one they answer catalog_unavailable. The OLP app stores projects in the browser (IndexedDB) and does not need the catalog.

Legacy and disabled routes#

• connected-targets, execution-gateway, execution, targets/{profile}/plans and plans/{plan_id} belong to the older connected-execution path over NATS. They stay off unless the server is started with --enable-connected-planning or --enable-connected-execution. Don't use them for new work.
• POST /connect, POST /execute and POST /teleop are retired and answer 403 {"ok": false, "enabled": false}.

Error codes#

Codes specific to machine control, with their usual HTTP status. rt-control reasons such as control_already_owned, not_ready, native_limit_exceeded or mode_conflict pass through with 409; see Error codes.

Related pages#

• Connect to a cell and run a program
• Motion paths and planning
• Program format
• Weld planner HTTP API
• rt-control HTTP API