Part 11 — Vehicle Control, Control Leases and SafetyLink to the section Part 11 — Vehicle Control, Control Leases and Safety#

Maturity: Draft · Profiles: N (leases §11.3 also apply to Profile C camera leases) · Schemas: univip.command.v0.2, univip.command_status.v0.2, univip.lease.v0.2

Safety statement. UNIVIP is an integration protocol, not a vehicle-control system. Nothing in this Part authorizes an implementation to bypass the vehicle's certified or approved controller (flight controller, dive controller, autopilot), its failsafes, the operator's authority or applicable regulation. A device MUST pass every accepted vehicle.* command through the same safety checks the manufacturer applies to its own remote controller, and a pilot action MUST always take precedence over any UNIVIP command.

11.1 Scope of Profile NLink to the section 11.1 Scope of Profile N#

Profile N standardizes a deliberately small set of tasking commands, domain-neutral where possible. It does not standardize stick-level manual control, launch and recovery sequencing beyond take-off/land and dive/surface, or any effector. Commands marked (AIR) or (UNDERWATER) are only valid for devices declaring that domain (or MULTI).

The device MUST list the exact supported subset in capabilities.vehicle.commands.

11.2 Preconditions enforced by the deviceLink to the section 11.2 Preconditions enforced by the device#

Before accepting any vehicle.* command the device MUST verify, and MUST reject with the stated reason if any fails:

A limit that the device cannot evaluate when the command arrives (for example max_distance_from_home_m while the home position is unknown, or an AGL limit without the data its basis needs) MUST cause rejection with OUT_OF_LIMITS; limits fail closed.

Altitude limits are evaluated on the target altitude converted to the limit's reference. max_altitude_agl_m is evaluated with the basis the device declares in limits.altitude_agl_basis: with HOME_ELEVATION the device takes AGL as height above the home point's ground (so a target in altitude_rel_m is compared directly), and it MUST NOT claim TERRAIN_MODEL without terrain data for the area. An altitude_rel_m target is checked against max_altitude_agl_m on that basis and against max_altitude_msl_m after adding the home altitude.

Acceptance after these checks still does not guarantee completion; the vehicle controller may abort for reasons that arise later, which MUST be reported as FAILED with a reason and, where applicable, an event (vehicle.navigation.returning_home, vehicle.operation.emergency).

11.3 Control leasesLink to the section 11.3 Control leases#

A lease is a time-limited, scoped grant of control authority to one client.

11.3.1 AcquireLink to the section 11.3.1 Acquire#

POST /univip/v1/devices/{device_id}/leases

{ "schema": "univip.lease.v0.2", "scope": "vehicle", "requested_ttl_s": 120,
  "purpose": "Operator J. Doe repositioning for incident 4471", "client_id": "vms-site-7", "operator_user": "jdoe" }

Response 201:

{ "schema": "univip.lease.v0.2", "lease_id": "lease-7f3a", "scope": "vehicle", "state": "ACTIVE",
  "granted_at": "...", "expires_at": "...", "heartbeat_interval_s": 5, "client_id": "vms-site-7",
  "pilot_acknowledged": true }

Scopes: vehicle, camera:<payload_id>, camera:*.

Rules:

• At most one ACTIVE lease with scope vehicle exists at any time. Camera leases MAY coexist per payload.
• ttl MUST NOT exceed capabilities.vehicle.lease.max_ttl_s for vehicle leases or the payload's lease.max_ttl_s for camera leases (RECOMMENDED defaults 300 s for vehicles, 900 s for cameras); a longer requested_ttl_s is granted at the maximum.
• A device MAY require pilot acknowledgment before granting a vehicle lease (operator_authority.pilot_present_required). Until acknowledged the lease is returned with state: PENDING and the device publishes vehicle.control.lease_granted only on acknowledgment.
• purpose, client_id and operator_user are REQUIRED for vehicle leases and are written to the audit record. client_id MUST be the caller's own (lease-scope otherwise).
• Because a lease names its operator (Part 13 §13.7), lease envelopes go only to the holder's sessions and GET /leases shows a caller only its own leases (administrators see all). Other clients learn of control changes from the vehicle.control.lease_* events, which carry no operator_user.

11.3.2 Heartbeat and extensionLink to the section 11.3.2 Heartbeat and extension#

The client MUST send PATCH /leases/{lease_id} with { "heartbeat": true } at least every heartbeat_interval_s. A device MUST transition the lease to EXPIRED after three missed heartbeats or at expires_at, whichever is first, and on expiry of a vehicle lease MUST cancel any client-issued movement in progress and transition the aircraft to hold (or the manufacturer's equivalent safe state). Extension is { "extend_s": 60 } subject to max_ttl_s from the time of the request.

11.3.3 Release, revoke, preemptLink to the section 11.3.3 Release, revoke, preempt#

• Client releases with DELETE /leases/{lease_id} → RELEASED.
• Operator or pilot revokes from the controller or dock → REVOKED; device publishes vehicle.control.lease_released with reason: REVOKED.
• A pilot taking manual control → vehicle.control.pilot_override (state: ACTIVE); the lease MAY remain ACTIVE but every vehicle.* command is rejected with PILOT_OVERRIDE until the pilot releases, at which point the event clears. A device MAY instead revoke the lease.
• A higher-priority client (per operator policy) preempting → PREEMPTED.

11.3.4 Lease stateLink to the section 11.3.4 Lease state#

stateDiagram-v2
    accTitle: A lease grants temporary control
    accDescr: A lease becomes active immediately or waits for required pilot acknowledgment. An active lease ends when released, expired, revoked or preempted. Expiry of a vehicle lease cancels client movement and holds the vehicle or uses the manufacturer's equivalent safe state.
    [*] --> PENDING: Pilot acknowledgment required
    [*] --> ACTIVE: Granted immediately
    PENDING --> ACTIVE: Pilot acknowledges
    ACTIVE --> RELEASED: Client releases
    ACTIVE --> EXPIRED: Time limit or missed heartbeats
    ACTIVE --> REVOKED: Operator revokes
    ACTIVE --> PREEMPTED: Higher priority client

Camera leases and vehicle leases have separate scopes. Expiry of a vehicle lease stops client-issued movement and puts the vehicle into hold or the manufacturer's equivalent safe state; a camera lease does not grant vehicle authority.

The current lease state is in telemetry vehicle.control and available at GET /leases/{lease_id}. Lease state changes are also published as lease envelopes on the session channel.

11.4 Command lifecycle specifics for aircraftLink to the section 11.4 Command lifecycle specifics for aircraft#

• Only one client-issued movement command (goto, move_relative, set_heading, return_home, land, takeoff, mission) is active at a time. A new one SUPERSEDEDs the previous.
• EXECUTING status MUST include progress where meaningful: { "distance_remaining_m", "eta_s" }.
• vehicle.hold and vehicle.cancel MUST attempt a stop whenever a lease is valid, regardless of other client activity, and a supported stop MUST be dispatched within 1 s. A controller refusal or an operation that cannot be stopped (for example dock launch preparation) MUST be reported explicitly; it MUST NOT be described as successful cancellation or holding. The original movement remains active if the stop request is rejected (Part 10 §10.1). On the ground (IDLE, PREDEPLOY, RECOVERED, DOCKED) a hold completes at once only when no launch preparation or other movement is pending.
• Loss of every UNIVIP session with the lease-holding client starts the expiry clock of §11.3.2 as if heartbeats had stopped at that moment: unless a session with that client is restored first, the lease expires three heartbeat intervals later. While no session exists, REST heartbeats do not reset this clock, because the device could no longer deliver status or failsafe notices to the client. Restoring a session stops it.

11.5 Mission format univip.mission.v0.2Link to the section 11.5 Mission format univip.mission.v0.2#

{
  "schema": "univip.mission.v0.2",
  "mission_id": "m-2026-10-15-01",
  "name": "Perimeter north",
  "altitude_reference": "REL",
  "default_ground_speed_mps": 8,
  "finish_action": "RETURN_HOME",
  "waypoints": [
    { "latitude_deg": 12.9716, "longitude_deg": 77.5946, "altitude_m": 60, "hold_s": 5,
      "heading_deg": 45, "gimbal": { "frame": "EARTH", "pitch_deg": -60, "yaw_deg": 45 },
      "actions": [ { "type": "camera.recording.start", "payload_id": "cam-1" } ] }
  ]
}

altitude_reference is MSL, AGL, REL or DEPTH and applies to every altitude_m (with DEPTH, altitude_m is depth below surface, positive downward). finish_action is RETURN_HOME, HOVER or LAND. Waypoint actions are camera.* commands executed on arrival. Devices MUST reject missions exceeding max_waypoints, leaving the geofence or exceeding limits at upload time with OUT_OF_LIMITS or GEOFENCE and a message naming the offending waypoint.

11.6 Failsafe interactionLink to the section 11.6 Failsafe interaction#

Device failsafes (low battery RTH, link-loss RTH, geofence action) always take precedence. When a failsafe interrupts a client command the device MUST publish FAILED with reason SAFETY and the corresponding event (vehicle.navigation.returning_home with reason, vehicle.geofence.breach, vehicle.link.lost with failsafe_action). A client MUST surface these to the user immediately.

11.7 AuditLink to the section 11.7 Audit#

For every vehicle lease and every vehicle.* command the device (or gateway) MUST record and retain for at least 90 days, and make available to the operator: timestamp, client_id, operator_user, lease_id, command_id, type, params, every status transition with reason, and the aircraft position at acceptance and at completion/failure. Clients MUST keep the equivalent record on their side. The audit record format is univip.audit.v0.2 (informative in v0.2; see Part 14 for the test).

11.8 Regulatory note (Informative)Link to the section 11.8 Regulatory note (Informative)#

Remote tasking of a vehicle from a VMS may be constrained by national rules on remote-pilot responsibility, visual line of sight, geo-awareness, waterway and port authority rules, and operational authorization. Profile N provides the technical means to honor those constraints (operator enablement, leases, limits, audit). It does not itself make any operation lawful.