​
request_operator_control

PX4 capability domain: request-system. PX4 mapping: MAV_CMD_REQUEST_OPERATOR_CONTROL. Request exclusive control of a system or special system feature by a GCS. The operator control protocol supports two modes: - In single-owner mode there is a single GCS “owner” that can send state changing operations to the whole system, and this command can be used to request takeover of that ownership role. - In multi-owner mode the flight stack allows multiple GCS to be “owners” and send (most) state changing operations (which GCS those are is implementation-dependent, and not controlled by this protocol). However only one GCS owner can control manual input of the vehicle: this command can be used to request takeover of that ownership role. A controlled system should only accept MAVLink operations that change the state of the vehicle, such as commands and command-like messages, which are sent by its controlling GCS(s) (or from other components in its own system/with the same system id, such as a companion computer). Commands to control the vehicle from other systems should be rejected with MAV_RESULT_NOT_IN_CONTROL (except for this command, which may be acknowledged with MAV_RESULT_ACCEPTED if control is granted). Messages and commands that don’t control or change vehicle movement or functionality, such as telemetry requests, may still be send from (and to) a controlled system. GCS control of the whole system is managed via a single component that we will refer to here as the “system manager component”. This component streams the CONTROL_STATUS message and sets the GCS_CONTROL_STATUS_FLAGS_SYSTEM_MANAGER flag. Other components in the system should monitor for the CONTROL_STATUS message with this flag, and set their controlling GCS(s) to match its published system id(s). A GCS that wants to control the system should also monitor for the same message and flag, and address the MAV_CMD_REQUEST_OPERATOR_CONTROL to its component id. Note that integrators are required to ensure that there is only one system manager component in the system (i.e. one component emitting the message with GCS_CONTROL_STATUS_FLAGS_SYSTEM_MANAGER set). The MAV_CMD_REQUEST_OPERATOR_CONTROL command is sent by a GCS to the system manager component to request or release control of a system, specifying whether subsequent takeover requests from another GCS are automatically granted, or require permission. The command may request control for a single GCS system ID or a range of GCS system IDs: the sender of the command must have a system id that is in the requested range. The system manager component should grant control to the requested GCS(s) if the system does not require takeover permission (or is uncontrolled) and ACK the request with MAV_RESULT_ACCEPTED. The system manager component should then stream CONTROL_STATUS indicating its controlling system(s): all other components in the system (with the same system id) should monitor this message and set their own controlling GCS(s) to match that of the system manager component. If the system manager component cannot grant control because takeover requires permission, the request should be rejected with MAV_RESULT_FAILED. The system manager component should then send this same command to the owning GCS with the lowest system ID that has a heartbeat, in order to notify of the request. That owning GCS must ACK with MAV_RESULT_ACCEPTED, and may choose to release control of the vehicle, or re-request control with the takeover bit set to allow permission. In case it choses to re-request control with takeover bit set to allow permission, the requester GCS will only have 10 seconds to get control, otherwise owning GCS will re-request control with takeover bit set to disallow permission, and requester GCS will need repeat the request if still interested in getting control. Note that the pilots of both GCS should coordinate safe handover offline. While any owning GCS are connected the system should consider itself connected to a GCS, and still owned by all GCS (even those that are not connected). If all owning GCS are disconnected the vehicle should GCS loss failsafe, and broadcast a CONTROL_STATUS indicating that it has no owner(s). In simultaneous-owner scenarios this allows an owner to disconnect and reconnect without the vehicle failsafing, provided at least one owner is connected. Note that in most systems the only controlled component will be the “system manager component”, and that will be the autopilot (although it could be a companion computer). However separate GCS control of a particular component is also permitted, if supported by the component. In this case the GCS will address MAV_CMD_REQUEST_OPERATOR_CONTROL to the specific component it wants to control. The component will then stream CONTROL_STATUS for its controlling GCS (it must not set GCS_CONTROL_STATUS_FLAGS_SYSTEM_MANAGER). The component should fall back to the system GCS (if any) when it is not directly controlled, and may stop emitting CONTROL_STATUS. The flow is otherwise the same as for requesting control over the whole system.

​
Request Params

​
vendor
string
必填
Fixed value px4
​
device_id
string
必填
Target PX4 device ID
​
command_type
string
必填
Fixed value request_operator_control
​
idempotency_key
string
必填
Idempotency key; repeated requests return the same command
​
timeout_seconds
integer
Timeout in seconds, range 0~300
​
payload
object
必填
Typed request payload for this command. Field names are generated from PX4 MAVLink XML labels, but callers do not send raw param1..param7 fields.
​
payload.action
number
Meaning: Action; maps to MAVLink parameter 1 in the PX4 frame.
​
payload.allow_takeover
number
Meaning: Allow takeover; maps to MAVLink parameter 2 in the PX4 frame.
​
payload.request_timeout
number
Meaning: Request timeout, units s; maps to MAVLink parameter 3 in the PX4 frame.
​
payload.gcs_sysid
number
Meaning: GCS Sysid; maps to MAVLink parameter 4 in the PX4 frame.
​
payload.gcs_sysid_upper_range
number
Meaning: GCS Sysid (upper range); maps to MAVLink parameter 5 in the PX4 frame.

​
PX4 Frame Mapping

  • MAVLink command: MAV_CMD_REQUEST_OPERATOR_CONTROL
  • Command ID: 32100
  • Default transport: COMMAND_LONG
  • Source XML: development.xml
  • Completion: COMMAND_ACK
  • Guard: real PX4 downlink is disabled by default; guarded mode requires explicit authorization and a ready transport.

​
Create Response

​
command_id
string
Platform command ID, used for follow-up queries
​
status
string
Acceptance status: ACCEPTED
​
accepted_at
string(datetime)
Command acceptance time (UTC)

​
Query Response

​
command_id
string
Platform command ID
​
status
string
Execution status: ACCEPTED / DELIVERED / SUCCEEDED / FAILED / TIMED_OUT / UNMATCHED_RESPONSE
​
vendor
string
Vendor identifier; fixed value px4
​
device_id
string
Target PX4 device ID
​
command_type
string
PX4 command type
​
response_code
string
Mapped COMMAND_ACK.result value
​
response_message
string
PX4 acknowledgement summary
​
vendor_response
object
Raw PX4 acknowledgement summary, including MAVLink command ID and transport

​
PX4 ACK Mapping

After sending the frame, the PX4 agent waits for COMMAND_ACK and correlates the response by command id. Disabled mode sends no frame and completes with a rejected lifecycle result. 
curl -X POST "/api/v1/open/downlink/commands" \
  -H "Content-Type: application/json" \
  -H "X-Api-Id: YOUR_API_ID" \
  -H "X-Api-Timestamp: YOUR_UNIX_SECONDS" \
  -H "X-Api-Nonce: YOUR_NONCE" \
  -H "X-Api-Signature: YOUR_SIGNATURE" \
  -d "{\"vendor\":\"px4\",\"device_id\":\"px4-real-1\",\"command_type\":\"request_operator_control\",\"payload\":{\"action\":0,\"allow_takeover\":0,\"request_timeout\":0,\"gcs_sysid\":0,\"gcs_sysid_upper_range\":0},\"idempotency_key\":\"req-request_operator_control-001\",\"timeout_seconds\":30}"

curl "/api/v1/open/downlink/commands/8cdb5bf3-8902-c5f7-f9aa-dc7fa0af1de0"

{
  "command_id": "8cdb5bf3-8902-c5f7-f9aa-dc7fa0af1de0",
  "status": "ACCEPTED",
  "accepted_at": "2026-06-15T00:00:00Z"
}