UNIVIP

Part 06 — Capability Document

On this page

Maturity: Draft · Profiles: all · Schema: univip.capabilities.v0.2 (../schemas/capabilities.schema.json)

6.1 Purpose

The capability document is the contract between one device and its clients. A client MUST read it before offering any control and MUST offer only what it declares. A gateway MUST declare exactly the subset the underlying aircraft and API allow, never the superset the specification permits.

It is sent as the first payload after hello/welcome on the session channel and served at GET /univip/v1/devices/{device_id}/capabilities. A device MUST resend it on the session channel whenever it changes (for example when a payload is attached or the operator enables Profile N).

6.2 Structure

{
  "schema": "univip.capabilities.v0.2",
  "device": { "...identity (Part 05)..." },
  "profiles": ["S", "C"],
  "schemas": ["univip.envelope.v0.2", "univip.capabilities.v0.2", "univip.telemetry.v0.2", "univip.event.v0.2",
              "univip.command.v0.2", "univip.command_status.v0.2", "univip.lease.v0.2"],
  "transports": {
    "rest": { "device_hosted": false, "session_proxy": true },
    "realtime": ["WSS"],
    "media": ["WEBRTC"]
  },
  "telemetry": { "rate_hz": { "min": 1, "max": 10, "default": 2 }, "applied_rate_hz": 5,
                 "fields": ["position", "motion", "power", "link", "vehicle", "payloads", "health"] },
  "events": { "topics": ["vehicle.operation.started", "..."] },
  "media": { "streams": [ { "...Part 09 stream descriptor..." } ], "webrtc": { "ice": "FULL" } },
  "payloads": [ { "...§6.4..." } ],
  "vehicle": { "...§6.5, Profile N only..." },
  "geospatial": { "supported": false },
  "extensions": []
}

6.3 Top-level members

Member Required Description
device yes Identity block, Part 05 §5.1
profiles yes Claimed profiles, subset of S, C, N. C requires S; N requires S.
schemas yes Exact schema identifiers the device emits or accepts, including univip.envelope.v<MAJOR>.<MINOR> and univip.capabilities.v<MAJOR>.<MINOR>
transports.rest.device_hosted yes true if the device serves /univip/v1 itself; base_url then REQUIRED
transports.rest.session_proxy if not device-hosted true if the device answers request envelopes (Part 05 §5.5.1). REQUIRED and true when device_hosted is false.
transports.rest.insecure optional true when base_url is plaintext http://, permitted only on an isolated local link (Part 13 §13.2)
transports.realtime yes Non-empty subset of WSS, MQTT5
transports.media yes Subset of WEBRTC, RTSP, SRT; non-empty whenever a profile is claimed
telemetry.rate_hz yes min, max, default supported publication rates
telemetry.applied_rate_hz yes (session channel) The rate the device applies for the session that receives this document, after clamping (Part 05 §5.4.2). Omitted when served over REST.
telemetry.fields yes Top-level telemetry objects the device populates
events.topics yes Every topic the device can emit (standard and vendor)
media.streams yes (may be empty only if profiles is empty) Stream descriptors, Part 09
media.webrtc.ice SHOULD FULL (gathers host, server-reflexive and relay candidates as configured) or LITE (host candidates only, Part 09 §9.3)
payloads Profile C Payload capability blocks
vehicle Profile N Vehicle control block
geospatial optional supported and the list of geospatial fields emitted, Part 12
extensions optional Reverse-DNS identifiers of vendor or future standard extensions

An optional member set to null means the same as an absent member (Part 01 §1.4).

6.4 Payload capability block

{
  "payload_id": "cam-1",
  "type": "CAMERA",
  "name": "Wide + zoom EO",
  "lease_required": true,
  "lease": { "max_ttl_s": 900, "heartbeat_interval_s": 10 },
  "gimbal": {
    "axes": ["PITCH", "YAW"],
    "frames": ["BODY", "EARTH"],
    "limits_deg": { "pitch": { "min": -120, "max": 30 }, "yaw": { "min": -180, "max": 180 } },
    "max_rate_degps": { "pitch": 90, "yaw": 90 },
    "continuous_move": true
  },
  "zoom": { "min_ratio": 1.0, "max_ratio": 56.0, "optical_max_ratio": 7.0, "continuous": true },
  "focus": { "modes": ["AUTO", "MANUAL", "ONE_SHOT"] },
  "imaging": { "parameters": ["EXPOSURE_MODE", "EV_COMPENSATION", "WHITE_BALANCE", "IR_CUT_FILTER"] },
  "thermal": null,
  "recording": { "supported": true, "local_storage": true },
  "snapshot": { "supported": true },
  "spotlight": null
}
Member Rule
type CAMERA, THERMAL, DUAL_EO_IR, MULTISPECTRAL, LIDAR, RANGEFINDER, SPOTLIGHT, SPEAKER, OTHER
lease_required If true, camera.* commands for this payload need a camera lease (Part 11 §11.3).
lease REQUIRED when lease_required is true: max_ttl_s and heartbeat_interval_s of camera leases for this payload, so that a client can plan heartbeats before acquiring one.
gimbal null if the payload is fixed. axes subset of ROLL, PITCH, YAW. frames lists the frames accepted in camera.gimbal.set_orientation.
zoom null if fixed focal length. optical_max_ratio marks where digital zoom begins.
thermal For thermal payloads: { "palettes": ["WHITE_HOT", "BLACK_HOT", "IRONBOW", ...], "gain_modes": ["HIGH", "LOW", "AUTO"], "radiometric": true }
imaging.parameters Subset of the standard parameter list in Part 10 §10.6

6.5 Vehicle control block (Profile N)

{
  "enabled": true,
  "domain": "AIR",
  "commands": ["vehicle.hold", "vehicle.return_home", "vehicle.cancel", "vehicle.goto", "vehicle.move_relative"],
  "limits": {
    "max_altitude_agl_m": 120,
    "max_altitude_msl_m": null,
    "max_distance_from_home_m": 2000,
    "max_ground_speed_mps": 15,
    "max_depth_m": null,
    "min_altitude_above_seabed_m": null,
    "altitude_agl_basis": "HOME_ELEVATION",
    "geofence": { "type": "Polygon", "coordinates": [[[77.59, 12.97], [77.60, 12.97], [77.60, 12.98], [77.59, 12.98], [77.59, 12.97]]] }
  },
  "lease": { "max_ttl_s": 300, "heartbeat_interval_s": 5, "preemptable_by": ["PILOT", "OPERATOR_POLICY"] },
  "missions": { "formats": ["univip.mission.v0.2"], "max_waypoints": 99 },
  "operator_authority": { "pilot_present_required": true, "pilot_override": "ALWAYS" }
}
Member Rule
enabled Operator-controlled switch. When false the device MUST reject every vehicle.* command with FLIGHT_CONTROL_DISABLED even though it claims Profile N.
domain AIR, UNDERWATER, SURFACE, GROUND, MULTI; MUST equal device.domain.
commands Exact supported subset of the Part 11 command list. vehicle.hold, vehicle.return_home and vehicle.cancel are REQUIRED for any Profile N claim. Domain-specific commands (vehicle.takeoff, vehicle.land, vehicle.dive_to, vehicle.surface) MUST NOT be listed for a domain they do not apply to.
limits Limits the device enforces. null means not limited by the device (regulatory limits still apply to the operator). geofence is a GeoJSON Polygon or MultiPolygon in WGS84. max_depth_m and min_altitude_above_seabed_m apply to the UNDERWATER domain. altitude_agl_basis states how max_altitude_agl_m is evaluated: TERRAIN_MODEL, RANGEFINDER, or HOME_ELEVATION (height above the home point's ground, assuming flat terrain); it is REQUIRED when max_altitude_agl_m is set.
lease Lease parameters, Part 11 §11.3
operator_authority Declares how pilot authority is enforced. pilot_override MUST be ALWAYS.

6.6 Change notification

When the capability document changes, the device MUST publish event vehicle.device.capabilities_changed and resend the capabilities envelope. Clients SHOULD re-evaluate offered controls.

Generated from spec/06-capabilities.md.