Part 10 — Camera and Payload ControlLink to the section Part 10 — Camera and Payload Control#

Maturity: Draft · Profiles: C · Schemas: univip.command.v0.2, univip.command_status.v0.2

10.1 Command model (shared with Part 11)Link to the section 10.1 Command model (shared with Part 11)#

Cancellation MUST NOT be reported as CANCELLED when the underlying adapter refuses or cannot confirm the stop. DELETE /commands/{command_id} then returns 409 command-not-cancellable with a rejection reason and leaves the original command active. A rejected vehicle.cancel similarly leaves the original movement active. Failure to stop after lease loss is reported as FAILED, with the reason and an explicit indication that stopping was not confirmed; the lease still ends. Dock launch preparation is one example of an operation whose cancellation may be unavailable.

A command is submitted with POST /univip/v1/devices/{device_id}/commands:

{
  "schema": "univip.command.v0.2",
  "command_id": "01J9ZC5R2M8K4T1V7W9X3Y5Z0A",
  "type": "camera.gimbal.set_orientation",
  "issued_at": "2026-10-15T10:33:00.000Z",
  "expires_at": "2026-10-15T10:33:05.000Z",
  "lease_id": "lease-7f3a",
  "payload_id": "cam-1",
  "params": { "frame": "EARTH", "pitch_deg": -45, "yaw_deg": 90 }
}

The synchronous response (HTTP 202 or 200) is:

{ "schema": "univip.command_status.v0.2", "command_id": "...", "type": "...", "state": "ACCEPTED", "timestamp": "..." }

or, with HTTP 422, state: "REJECTED", reason and message. A command refused for a lease, limit, state or safety reason is always a 422 rejection, never a 403 (403 means only a missing scope, Part 05 §5.5). ACCEPTED means the device will attempt the command; it never means completion.

Where the vehicle or payload controller acknowledges commands (for example MAVLink COMMAND_ACK), the synchronous answer reflects that acknowledgment: the device dispatches the command and waits for it, up to 10 s, before answering. A refusal by the controller is answered REJECTED with the mapped reason (Annex A); an acknowledgment that reports failure is answered ACCEPTED and followed at once by FAILED; no acknowledgment within the wait is answered ACCEPTED, and the outcome follows as status messages. Subsequent states arrive as command_status envelopes on the session channel and via GET /commands/{command_id}:

flowchart TB
    accTitle: Accepted is the start, not the outcome
    accDescr: An accepted command may be queued and then execute. Later status messages report completion, failure, cancellation or supersession. A rejected command is refused before entering this lifecycle.
    A["ACCEPTED: the device will try"] --> Q["QUEUED"]
    Q --> E["EXECUTING"]
    E --> C["COMPLETED"]
    Q --> F["FAILED"]
    E --> F
    Q --> X["CANCELLED"]
    E --> X
    Q --> S["SUPERSEDED"]
    E --> S

Read ACCEPTED as an acknowledgment, then follow command_status for the outcome. Cancellation can follow a client request or lease loss; a newer command on the same axis or target can supersede the earlier one.

Standard rejection and failure reasons: UNSUPPORTED_COMMAND, INVALID_PARAMETERS, NO_LEASE, LEASE_SCOPE, LEASE_EXPIRED, OUT_OF_LIMITS, PAYLOAD_UNAVAILABLE, BUSY, FLIGHT_STATE, PILOT_OVERRIDE, GEOFENCE, SAFETY, FLIGHT_CONTROL_DISABLED, LINK_LOST, EXPIRED, INTERNAL.

expires_at is RECOMMENDED for all commands and REQUIRED for continuous moves. It bounds the start of execution, not its completion: the device MUST NOT start a command after its expiry (reason EXPIRED), and a command already executing at expires_at continues, except that a continuous move stops.

10.2 Separation from vehicle controlLink to the section 10.2 Separation from vehicle control#

Every camera.* command MUST be executable without moving the vehicle. If a payload's pointing is coupled to the aircraft (for example a fixed forward camera where "pan" would require yawing the aircraft), the device MUST NOT advertise the gimbal axis and MUST NOT translate a camera.* command into aircraft motion. A client MAY offer the user an explicit vehicle.* alternative under Profile N permissions.

10.3 Gimbal commandsLink to the section 10.3 Gimbal commands#

Gimbal frames: in EARTH, yaw_deg is the true azimuth of the optical axis ([0, 360) or (−180, 180]), and pitch_deg and roll_deg are relative to the local horizontal plane (pitch_deg negative looking down). In BODY, yaw_deg is relative to the vehicle's forward axis (positive to the right), and pitch_deg and roll_deg are still relative to the local horizontal, as a stabilized gimbal holds them; they are not relative to the vehicle's own pitch and roll. (MAVLink's "vehicle frame" is this BODY frame; ST 0601's sensor-relative angles are relative to the full platform attitude, see Annex A.3.)

10.4 Zoom and focusLink to the section 10.4 Zoom and focus#

10.5 Recording, snapshot, modeLink to the section 10.5 Recording, snapshot, mode#

10.6 ImagingLink to the section 10.6 Imaging#

camera.imaging.set with params.settings as an object of standard parameter names:

Thermal payloads additionally accept camera.thermal.set with palette, gain_mode, isotherm ({ "enabled", "min_c", "max_c" }), spot_meter ({ "x_pct", "y_pct" }).

10.7 Other payloadsLink to the section 10.7 Other payloads#

10.8 Leases for camera controlLink to the section 10.8 Leases for camera control#

If a payload declares lease_required: true, camera.* and payload.* commands for it MUST carry a valid lease with scope camera:<payload_id> or camera:*. Lease mechanics are in Part 11 §11.3. A device MAY allow multiple concurrent camera leases on different payloads. Pilot gimbal input MUST take precedence and MUST generate vehicle.control.pilot_override scoped to the camera lease.

10.9 Capability-gated behaviorLink to the section 10.9 Capability-gated behavior#

A client MUST NOT send a command type, axis, frame, parameter or value outside the ranges advertised in the capability document. A device MUST reject such commands with UNSUPPORTED_COMMAND, INVALID_PARAMETERS or OUT_OF_LIMITS, never silently clamp, except for continuous-move rates which it MAY clamp and report in the EXECUTING status result.applied.