PUT/physical/sites/:idadmin
Enrol a site, or replace its key: the key the site signs its batches and its command receipts with. Needs the project in LW_PHYSICAL_COMMAND_TENANTS.
Body
site_key | the site's key as ed25519:<64 lowercase hex> or p256:<66 lowercase hex, compressed>, from the site's operator tooling |
GET/physical/sitesmember
The project's enrolled sites: id, key, the last command sequence number issued and the last batch sequence number accepted.
POST/physical/commandsadmin
Issue one command to a site, only for a twin inside its solved band: the twin must be calibrated, every value inside the band, and the twin's forecasts proven (at least 20 scored, 80% inside their 90% interval). The command is a setpoint or a trajectory chunk (an action chunk of a learned policy), signed by the core's command signer with the twin's certificate; the site decides on its own policy and answers with a signed receipt. The mode is shadow by default. Mode actuate is signed only when the project is in LW_PHYSICAL_COMMAND_TENANTS and a stored approval, signed by an enrolled approver key, covers the site, the system class, the actuator and the kind through the command's expiry and has not been revoked; otherwise 403 actuation_not_approved. The site decides again on its own stage and approvals. Needs a configured signer (503 otherwise).
Body
site | an enrolled site id |
twin | a twin loop id |
band_key | the band coefficient the setpoint, or the joint position of a trajectory (radian), is, mean.<name> or scale.<name> |
effort_band_key | trajectory only: the band coefficient that bounds joint effort (newton metre); required when the steps carry tau |
target | {actuator_id, scope} |
setpoint | {quantity, unit, value}; exactly one of setpoint and trajectory |
trajectory | {chunk_index, dof, step_ms, steps: [{q, tau?, xyz?}], start: {q, dq, ddq}, limits: {q_min, q_max, dq_max, ddq_max, dddq_max, tau_max?, xyz_min?, xyz_max?}}; every step must lie inside the band (409 outside_solved_band) and q_min and q_max are clipped to it |
policy_sha256 | the site's operator policy hash, 64 hex |
model_sha256 | the model's hash, 64 hex |
birth_record_sha256 | optional, 64 hex |
envelope | setpoint only: {min?, max?, max_rate_per_s}, clipped to the band; the site applies its own stricter envelope |
ttl_s | 1..300; default 60 |
mode | shadow (the default) or actuate |
system_class | the class of system the actuator belongs to, a lowercase name; required for actuate |
PUT/physical/approvers/:idadmin
Enrol an approver key, or replace it: the hardware-held key whose signature makes an actuation approval valid. Needs the project in LW_PHYSICAL_COMMAND_TENANTS.
Body
key | the approver's key as ed25519:<64 lowercase hex> |
GET/physical/approversmember
The project's enrolled approver keys.
POST/physical/approvalsadmin
Store an actuation approval: the request body is its canonical JSON text byte for byte (format actuation-approval, version 1). Verified against an enrolled approver key, for this project and an enrolled site, not yet ended; valid for at most 31 days. The same record twice is accepted once; a different record with the same id is a 409. Codes: malformed, not_canonical, unsupported_format, approval_too_long, unknown_approver, bad_signature, wrong_tenant, approval_expired, approval_conflict.
GET/physical/approvalsmember
The project's approvals with their site, class, actuators, kinds, validity and status (active, pending, expired or revoked).
POST/physical/approvals/:id/revocationadmin
Revoke an approval. Core stops issuing under it at once; the site's own copy is removed at the site by its operator, and a receipt that reports an execution under a revoked approval is recorded with an alert.
GET/physical/commandsmember
Commands issued, newest first, each with what the site decided (decision, code, ledger position) once its receipt is in.
Query
site | one site |
limit | 1..200; default 50 |
POST/physical/receiptsmember
A site's receipt for a command, as its canonical JSON text (the request body, byte for byte). Verified against the key registered for the site and recorded; a replay of the same receipt is accepted once, a different receipt with the same sequence number is a 409. A receipt is recorded with an alert when it contradicts what core issued: executed_in_shadow_mode, execution_unapproved, execution_under_revoked_approval, mode_differs or command_hash_differs.
GET/physical/kindsmember
The physical interface: every measurement kind with its family, unit, range, whether it is measured or inferred, and the twin variable it validates; the derived signals; the purpose domains and the usual kinds of system; the integrations (robot_middleware, industrial_server, motion_bus, message_broker, vehicle_bus, register_device) with the systems and purposes they serve, the kinds and units they carry, their attestation ceiling (soft), that they are observe only and shadow only, and what has and has not been run; the capabilities (measure, plan, gate, actuate). Stateless; it reaches no site.
POST/physical/purposes/checksmember
Check a description of what a system is for: its purpose domains, the quantities it measures, the actions it can take, its safe operating limits and its twin. Answers every issue with a code; an action without a limit, a limit in the wrong unit, an unknown kind and a request to act are errors. Stores nothing and acts on nothing.
Body
v | the number 1 |
name | string |
purpose | [compute|processing|physics|motion|measurement|environment|energy|fluid_thermal|structure] |
system | optional kind of system |
quantities | [{kind, unit?, axes?, rate_hz?, uncertainty_sd?}] |
integrations | optional [integration id]: checked against the systems and purposes it serves and the kinds it carries |
actions | [{action: setpoint|trajectory|mode|model_update|calibration_update, quantity, unit, min?, max?}] |
limits | [{quantity, unit, min, max, max_rate_per_s?}] |
twin | {id?, variables: [string]} |
POST/physical/measurements/admissionsmember
Decide what one typed measurement may be used for against a twin's solved band: inform always; validate and recalibrate only inside the band, only at or above the attestation floor, and recalibrate only when the sensor measured it rather than inferred it. Outside the band, or with no band, it validates nothing. Stateless.
Body
measurement | {v: 1, kind, value, unit, uncertainty_sd?, attestation: soft|device|se|tee|dice|tpm, modality?: direct|inferred, placement?: environment|device} |
band | the twin's band, {mean.<variable>: [min, max]}, or null |
floor | lowest attestation level accepted; default soft |
GET/physical/measurements/statsadmin
What the admissions route has been asked since this core started, for this project: per key label, requests, accepted, informs-only (could not validate), refused with the code, and by kind with the units seen, and when one was last seen. Counts only, kept in memory, emptied by a restart (since says from when).
POST/physical/signalsmember
Compute a derived signal (tilt_angle, vibration_rms, angular_speed, field_strength, dew_point, mechanical_power, pressure_height_change) from verified measurements, only inside the regime it is valid in; its attestation is the lowest of its inputs. Stateless.
Body
signal | name |
inputs | [{kind, value, unit, attestation}] |
reference | reference pressure in pascals, for pressure_height_change |