​
do_set_home

PX4 capability domain: do-control. PX4 mapping: MAV_CMD_DO_SET_HOME. Sets the home position to either to the current position or a specified position. The home position is the default position that the system will return to and land on. The position is set automatically by the system during the takeoff (and may also be set using this command). Note: the current home position may be emitted in a HOME_POSITION message on request (using MAV_CMD_REQUEST_MESSAGE with param1=242).

​
Request Params

​
vendor
string
必填
Fixed value px4
​
device_id
string
必填
Target PX4 device ID
​
command_type
string
必填
Fixed value do_set_home
​
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.use_current
number
Meaning: Use Current, enum MAV_BOOL; maps to MAVLink parameter 1 in the PX4 frame.
​
payload.roll
number
Meaning: Roll, units deg; maps to MAVLink parameter 2 in the PX4 frame.
​
payload.pitch
number
Meaning: Pitch, units deg; maps to MAVLink parameter 3 in the PX4 frame.
​
payload.yaw
number
Meaning: Yaw, units deg; maps to MAVLink parameter 4 in the PX4 frame.
​
payload.latitude
number
Meaning: Latitude; maps to MAVLink parameter 5 in the PX4 frame.
​
payload.longitude
number
Meaning: Longitude; maps to MAVLink parameter 6 in the PX4 frame.
​
payload.altitude
number
Meaning: Altitude, units m; maps to MAVLink parameter 7 in the PX4 frame.

​
PX4 Frame Mapping

  • MAVLink command: MAV_CMD_DO_SET_HOME
  • Command ID: 179
  • Default transport: COMMAND_INT
  • Source XML: common.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\":\"do_set_home\",\"payload\":{\"use_current\":0,\"roll\":0,\"pitch\":0,\"yaw\":0,\"latitude\":473566000,\"longitude\":85432100,\"altitude\":30.0},\"idempotency_key\":\"req-do_set_home-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"
}