MAVLINKHUD
Download App MAVLink HUD for Android

MISSION_REQUEST_PARTIAL_LIST

ID: 37
Unsupported

Summary

Request a partial list of mission items from the system.

Status

Unsupported

Directionality

  • TX (Transmit): None
  • RX (Receive): None

Description

ArduPilot does not implement this message. It relies on the standard MISSION_REQUEST_LIST and individual MISSION_REQUEST messages to download missions.

Theoretical Use Cases

Efficiently downloading a small range of waypoints from a large mission.

MISSION_WRITE_PARTIAL_LIST

ID: 38
Supported (RX Only)

Summary

Initiate a partial write transaction for mission items.

Status

Supported (RX Only)

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles - Receives partial upload request.

Reception (RX)

Handled by GCS_MAVLINK::handle_mission_write_partial_list.

Source: libraries/GCS_MAVLink/GCS_Common.cpp

Protocol Logic

Allows the GCS to update a specific range of waypoints (e.g., changing points 10-15 of a 100-point mission) without re-uploading the entire list.

  1. GCS sends MISSION_WRITE_PARTIAL_LIST.
  2. Vehicle responds with MISSION_REQUEST for the first item in the range.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • start_index: Start index.
  • end_index: End index.

Practical Use Cases

  1. In-Flight Mission Update:
    • Scenario: Pilot wants to move a few waypoints mid-mission.
    • Action: GCS uploads only the modified points using this message, saving bandwidth.

Key Codebase Locations

  • libraries/GCS_MAVLink/GCS_Common.cpp:4513: Handler.

MISSION_ITEM

ID: 39
Legacy / Supported

Summary

The MISSION_ITEM message is the legacy mechanism for uploading and downloading autonomous mission waypoints using floating-point coordinates. While fully supported for backward compatibility, it is largely superseded by MISSION_ITEM_INT (73), which uses integer coordinates to avoid precision loss over long distances. ArduPilot unifies both formats internally to high-precision integer representation.

Status

Legacy / Supported (Superseded by ID 73)

Directionality

  • TX (Transmit): All Vehicles (Downloading mission to GCS)
  • RX (Receive): All Vehicles (Uploading mission from GCS)

Reception (RX)

Reception is handled by GCS_MAVLINK::handle_mission_item in libraries/GCS_MAVLink/GCS_Common.cpp:915.

Conversion Logic

Upon receiving a MISSION_ITEM packet, ArduPilot immediately converts it to the integer format using AP_Mission::convert_MISSION_ITEM_to_MISSION_ITEM_INT in libraries/AP_Mission/AP_Mission.cpp:1498. This ensures that the mission is stored with the highest possible fidelity in the vehicle's EEPROM/Flash.

Transmission (TX)

During a mission download, ArduPilot will send MISSION_ITEM messages if the GCS requested them via a MISSION_REQUEST (40).

  • Logic: The MissionItemProtocol state machine retrieves the command from AP_Mission, converts it to float-scale, and sends the packet.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • seq: Sequence.
  • frame: The coordinate system of the waypoint (MAV_FRAME).
  • command: The scheduled action for the waypoint (MAV_CMD).
  • current: false:0, true:1.
  • autocontinue: autocontinue to next wp.
  • param1: PARAM1, see MAV_CMD enum.
  • param2: PARAM2, see MAV_CMD enum.
  • param3: PARAM3, see MAV_CMD enum.
  • param4: PARAM4, see MAV_CMD enum.
  • x: PARAM5 / local: x position in meters * 1e4, global: latitude in degrees * 10^7.
  • y: PARAM6 / local: y position in meters * 1e4, global: longitude in degrees * 10^7.
  • z: PARAM7 / local: z position: altitude in meters (relative or absolute, depending on frame).

Practical Use Cases

  1. Legacy Script Support:
    • Scenario: A researcher has a legacy DroneKit script that defines waypoints using floats.
    • Action: ArduPilot accepts the MISSION_ITEM messages and transparently converts them for the internal flight controller.
  2. Simple GCS Implementation:
    • Scenario: A developer is building a minimal GCS and finds float math easier to implement than 1E7 integer scaling.
    • Action: The developer uses MISSION_ITEM to send simple waypoint coordinates.

Key Codebase Locations

MISSION_REQUEST

ID: 40
Supported (RX Only)

Summary

Request the information of a mission item.

Status

Supported (RX Only)

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles - Receives request for item.

Reception (RX)

Handled by GCS_MAVLINK::handle_mission_request.

Source: libraries/GCS_MAVLink/GCS_Common.cpp

Protocol Logic

This message is deprecated in favor of MISSION_REQUEST_INT (51) but is still supported for backward compatibility.

  • ArduPilot converts it internally to a MISSION_REQUEST_INT and processes it.
  • A warning is sent to the GCS: "got MISSION_REQUEST; use MISSION_REQUEST_INT!".

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • seq: Sequence number of the mission item.

Practical Use Cases

  1. Legacy GCS Support:
    • Scenario: Connecting an old version of Mission Planner.
    • Action: It uses this message to download waypoints.

Key Codebase Locations

  • libraries/GCS_MAVLink/GCS_Common.cpp:4529: Handler.

MISSION_SET_CURRENT

ID: 41
Supported

Summary

The MISSION_SET_CURRENT message allows a Ground Control Station (GCS) to manually override the vehicle's progress through an autonomous mission. It can be used to jump ahead to a specific waypoint, restart the mission from the beginning, or skip a section of the flight path.

Status

Supported

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles (Manually sets mission index)

Reception (RX)

Reception is handled by GCS_MAVLINK::handle_mission_set_current in libraries/GCS_MAVLink/GCS_Common.cpp:710.

Processing Logic

  1. Index Update: It calls AP_Mission::set_current_cmd(index).
  2. Execution Jump:
    • If the mission is active, it calls advance_current_nav_cmd(index), which forces the flight controller to stop its current navigation goal and immediately track toward the new waypoint.
    • If the mission is stopped/disarmed, it primes the mission engine to resume from that index upon the next mission start.
  3. Special Markers: It supports jumping to the MAV_CMD_DO_LAND_START marker, which is commonly used during abort procedures to find the start of the landing sequence.
  4. Confirmation: ArduPilot immediately responds with a MISSION_CURRENT (42) message echoing the new index.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • seq: Sequence.

Practical Use Cases

  1. Waypoint Skipping:
    • Scenario: A pilot is flying a survey mission and notices a localized cloud over waypoint 5.
    • Action: The pilot uses the "Set Current Waypoint" feature in the GCS to jump to waypoint 6, skipping the obscured area.
  2. Mission Restart:
    • Scenario: A battery fail-safe triggered an early return. After swapping batteries, the pilot wants to start the mission from waypoint 1 again.
    • Action: The GCS sends MISSION_SET_CURRENT with index 0.
  3. Emergency Landing Search:
    • Scenario: A fixed-wing plane needs to land immediately due to high winds.
    • Action: The GCS triggers a jump to the "Land Start" index, allowing the plane to follow its pre-planned landing approach.

Key Codebase Locations

MISSION_CURRENT

ID: 42
Supported

Summary

The MISSION_CURRENT message is the vehicle's report of its current progress through the active mission. It specifies the sequence number (index) of the waypoint or command the vehicle is currently executing.

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Reports current mission index)
  • RX (Receive): None (Ignored)

Transmission (TX)

Transmission logic is in GCS_MAVLINK::send_mission_current within libraries/GCS_MAVLink/GCS_Common.cpp:678.

Data Sourcing

  • Source: The index is retrieved from the AP_Mission library via get_current_nav_index().
  • Trigger:
    1. Periodic: Sent as part of the MSG_CURRENT_WAYPOINT stream (typically 1Hz).
    2. Event-Driven: Sent immediately after a MISSION_SET_CURRENT (41) command is processed.
    3. Autonomous: Sent whenever the mission engine automatically advances to the next item in the list.

Data Fields

  • seq: Sequence.

Practical Use Cases

  1. Mission Progress Visualization:
    • Scenario: A pilot is watching the drone fly a complex path on a ground station.
    • Action: The GCS highlights the "active" waypoint on the map based on the index received in MISSION_CURRENT.
  2. Autonomous Event Triggers:
    • Scenario: A photographer wants to be notified when the drone reaches waypoint 10 to start a manual video sequence.
    • Action: An app listens for MISSION_CURRENT and triggers a sound alert on the pilot's phone when seq == 10.

Key Codebase Locations

MISSION_REQUEST_LIST

ID: 43
Supported

Summary

The MISSION_REQUEST_LIST message is the standard way for a Ground Control Station (GCS) to initiate a mission download. Upon receiving this request, ArduPilot determines the number of stored mission items and responds with a MISSION_COUNT (44) message.

Status

Supported

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles (Triggers mission download handshake)

Reception (RX)

Reception is handled by GCS_MAVLINK::handle_mission_request_list in libraries/GCS_MAVLink/GCS_Common.cpp:607.

Processing Logic

  1. Protocol Identification: The message is routed to the appropriate MissionItemProtocol handler (e.g., Waypoints, Rally points, or Fences).
  2. Count Retrieval: ArduPilot queries the AP_Mission library for the total number of items currently stored in the requested list.
  3. Response: It immediately sends a MISSION_COUNT (44) packet back to the requester.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.

Practical Use Cases

  1. Post-Connect Synchronization:
    • Scenario: A pilot connects a tablet to a drone that was previously flown.
    • Action: The tablet sends MISSION_REQUEST_LIST to see if there is an active mission still stored on the vehicle.
  2. Mission Verification:
    • Scenario: After uploading a new route, the GCS wants to double-check the onboard state.
    • Action: The GCS requests the list to begin a verification download.

Key Codebase Locations

MISSION_COUNT

ID: 44
Supported

Summary

The MISSION_COUNT message is a critical handshake packet used at the beginning of both mission uploads and downloads. It defines how many items are about to be transferred, allowing the receiver to allocate memory and prepare for the sequence of individual waypoint messages.

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Starting a download)
  • RX (Receive): All Vehicles (Starting an upload)

Transmission (TX)

ArduPilot sends MISSION_COUNT in response to a MISSION_REQUEST_LIST (43). This tells the GCS exactly how many waypoints are currently stored in the vehicle's memory.

Reception (RX)

Reception is handled by GCS_MAVLINK::handle_mission_count in libraries/GCS_MAVLink/GCS_Common.cpp:741.

Processing Logic

  1. Preparation: The autopilot receives this message from a GCS wanting to upload a new mission.
  2. Clearance: ArduPilot calls truncate() on the internal mission storage. This effectively clears existing items of that type to make room for the new list.
  3. Resource Allocation: The mission protocol state machine is initialized to expect the specified number of items.
  4. Handshake Continuation: ArduPilot responds by sending the first MISSION_REQUEST (40) for index 0.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • count: Number of mission items in the sequence.

Practical Use Cases

  1. Uploading a Route:
    • Scenario: A user draws a 10-point circle on a map in Mission Planner and clicks "Write WPs".
    • Action: Mission Planner sends MISSION_COUNT with value 10. ArduPilot clears its mission memory and begins requesting the 10 points.
  2. Telemetry Resumption:
    • Scenario: A link was temporarily lost during a mission download.
    • Action: The GCS re-sends the count request to re-verify the list size before continuing.

Key Codebase Locations

MISSION_CLEAR_ALL

ID: 45
Supported

Summary

The MISSION_CLEAR_ALL message allows a Ground Control Station (GCS) to wipe a specific set of autonomous instructions from the vehicle's memory. This is typically used to reset the drone to a clean state before uploading a new mission or to ensure no old geofence boundaries remain active.

Status

Supported

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles (Clears stored mission/fence/rally items)

Reception (RX)

Reception is handled by GCS_MAVLINK::handle_mission_clear_all in libraries/GCS_MAVLink/GCS_Common.cpp:763.

Processing Logic

  1. Target Selection: The message contains a mission_type field. ArduPilot uses this to determine whether to clear the Main Mission, the Geo-Fence, or the Rally points.
  2. Safety First: Before clearing, ArduPilot cancels any active mission upload sessions to prevent the system from entering an inconsistent state.
  3. Scoped Wipe: Only the requested list is cleared. The rest of the vehicle's configuration (parameters, calibration data) remains untouched in the EEPROM.
  4. Acknowledgement: ArduPilot responds with a MISSION_ACK (47) message. If successful, it returns MAV_MISSION_ACCEPTED.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • mission_type: Mission type (MAV_MISSION_TYPE).

Practical Use Cases

  1. New Mission Prep:
    • Scenario: A user finishes a survey at Site A and drives to Site B.
    • Action: The GCS sends MISSION_CLEAR_ALL to remove the Site A waypoints before the user starts drawing a new flight plan.
  2. Fence Removal:
    • Scenario: A pilot is flying in a restricted area with a temporary geofence. After the restriction is lifted, they want to fly freely.
    • Action: The GCS clears the fence type, allowing the drone to fly past the previous boundaries.
  3. Automation Cleanup:
    • Scenario: A custom script is used to generate dynamic missions.
    • Action: At the end of each flight, the script clears the mission to ensure the drone doesn't accidentally restart the same route on the next takeoff.

Key Codebase Locations

MISSION_ITEM_REACHED

ID: 46
Supported

Summary

The MISSION_ITEM_REACHED message is an event-driven notification sent by the autopilot to the Ground Control Station (GCS). It announces that a specific mission item (waypoint, takeoff, landing, or action) has been successfully completed. This is the primary signal used by GCS software to update progress bars and provide audio feedback to the pilot (e.g., "Waypoint 5 reached").

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Reports completion events)
  • RX (Receive): None (Ignored)

Transmission (TX)

The transmission logic is in GCS::send_mission_item_reached_message within libraries/GCS_MAVLink/GCS_Common.cpp:2717.

Trigger Logic

This message is not sent periodically. Instead, it is triggered by the mission engine:

  1. Verification: The AP_Mission library calls a vehicle-specific verify_command() function (e.g., in ArduCopter/mode_auto.cpp) at high frequency (10Hz+).
  2. Completion: When the vehicle determines it has fulfilled the criteria for the current item (e.g., it is within the waypoint radius and has finished any required loiter time), verify_command returns true.
  3. Dispatch: Upon completion, the autopilot immediately broadcasts MISSION_ITEM_REACHED with the index of the finished item.

Scope

  • Navigation Commands: Sent for waypoints, land, takeoff, and return-to-launch.
  • DO Commands: Sent for non-movement actions (e.g., MAV_CMD_DO_SET_SERVO), which typically complete instantly upon execution.

Data Fields

  • seq: Sequence.

Practical Use Cases

  1. GCS Audio Alerts:
    • Scenario: A pilot is flying a survey mission and isn't looking at the screen.
    • Action: Mission Planner receives the message and uses Text-to-Speech to announce "Waypoint 10 reached. Returning home."
  2. Automated Data Logging:
    • Scenario: A researcher wants to log exactly when a drone entered a specific study area.
    • Action: An external script listens for MISSION_ITEM_REACHED. When the index matches the boundary waypoint, it saves a timestamp and GPS coordinate.
  3. Companion Computer Actions:
    • Scenario: A drone is delivering a package.
    • Action: When the companion computer sees the "Land" waypoint index reached, it triggers the gripper mechanism to release the payload.

Key Codebase Locations

MISSION_ACK

ID: 47
Supported

Summary

The MISSION_ACK message is the terminal handshake packet in the MAVLink mission protocol. It signals the final result of a multi-message operation, such as uploading a new waypoint list or clearing the mission memory. Ground Control Stations (GCS) use this message to determine if a "Write" operation was successful or if an error occurred (e.g., the drone's memory is full).

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Confirming result to GCS)
  • RX (Receive): None (Received but ignored by ArduPilot)

Transmission (TX)

The transmission logic is centered in MissionItemProtocol::send_mission_ack within libraries/GCS_MAVLink/MissionItemProtocol.cpp:334.

Response Types

ArduPilot uses the type field to communicate specific results:

  • MAV_MISSION_ACCEPTED (0): The operation was successful (e.g., all waypoints received and saved).
  • MAV_MISSION_ERROR (1): A generic failure occurred.
  • MAV_MISSION_UNSUPPORTED (3): The requested mission type or command is not supported.
  • MAV_MISSION_NO_SPACE (4): The vehicle has run out of EEPROM/Flash storage for mission items.
  • MAV_MISSION_INVALID (5): One or more parameters in the uploaded mission items are invalid (e.g., unrealistic coordinates).
  • MAV_MISSION_INVALID_SEQUENCE (13): Items were received out of order during an upload.

Reception (RX)

ArduPilot receives MISSION_ACK from the GCS after providing a mission for download.

  • Handling: The message is decoded in GCS_Common.cpp:4566, but it is marked as "not used" and discarded. ArduPilot considers its job done once the last mission item is sent and does not require verification from the GCS.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • type: Mission result (MAV_MISSION_RESULT).
  • mission_type: Mission type (MAV_MISSION_TYPE).

Practical Use Cases

  1. Ensuring Reliable Uploads:
    • Scenario: A user uploads 50 waypoints over a weak telemetry link.
    • Action: The GCS waits for the final MISSION_ACK with type=0 before showing the "Upload Complete" dialog. If it receives an error, it prompts the user to "Retry".
  2. Storage Capacity Warnings:
    • Scenario: A developer attempts to upload a 2000-point mission to an older flight controller.
    • Action: ArduPilot sends a MISSION_ACK with MAV_MISSION_NO_SPACE, allowing the GCS to explain why the full mission wasn't saved.
  3. Protocol Verification:
    • Scenario: A companion computer clears the onboard fence.
    • Action: The computer listens for the ACK to verify the fence has indeed been deactivated before proceeding with a flight.

Key Codebase Locations

MISSION_REQUEST_INT

ID: 51
Supported (RX Only)

Summary

Request the information of a mission item with the sequence number seq.

Status

Supported (RX Only)

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles - Receives request for a mission item.

Reception (RX)

Handled by GCS_MAVLINK::handle_mission_request_int.

Source: libraries/GCS_MAVLink/GCS_Common.cpp

Protocol Logic

  1. GCS sends MISSION_REQUEST_INT with a sequence number.
  2. ArduPilot retrieves the waypoint from storage.
  3. ArduPilot responds with MISSION_ITEM_INT.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • seq: Sequence number of the mission item to fetch.
  • mission_type: Mission type (Mission, Fence, Rally).

Practical Use Cases

  1. Downloading Mission:
    • Scenario: User clicks "Read" in Mission Planner.
    • Action: Mission Planner iterates through all waypoints, sending a MISSION_REQUEST_INT for each one to download the plan from the drone.

Key Codebase Locations

  • libraries/GCS_MAVLink/GCS_Common.cpp:629: Handler.

SAFETY_SET_ALLOWED_AREA

ID: 54
Unsupported

Summary

Set a safety zone (volume) for the vehicle.

Status

Unsupported

Directionality

  • TX (Transmit): None
  • RX (Receive): None

Description

ArduPilot does not implement this message. It uses the AC_Fence library and the Fence Protocol (items with MAV_CMD_NAV_FENCE_...) for geofencing.

Theoretical Use Cases

Defining a safety box.

SAFETY_ALLOWED_AREA

ID: 55
Unsupported

Summary

Read out the safety zone the MAV currently assumes.

Status

Unsupported

Directionality

  • TX (Transmit): None
  • RX (Receive): None

Description

ArduPilot does not implement this message.

Theoretical Use Cases

Reading geofence boundaries.

MISSION_ITEM_INT

ID: 73
Supported / Recommended

Summary

The MISSION_ITEM_INT message is the modern standard for transmitting mission waypoints in MAVLink. It uses integer values for Latitude and Longitude (scaled by 1E7) to ensure high spatial precision, even on global scales. This is ArduPilot's preferred message for all mission planning activities.

Status

Supported / Recommended

Directionality

  • TX (Transmit): All Vehicles (Downloading mission to GCS)
  • RX (Receive): All Vehicles (Uploading mission from GCS)

Reception (RX)

Reception is handled by GCS_MAVLINK::handle_mission_item in libraries/GCS_MAVLink/GCS_Common.cpp:915.

Internal Storage

  • Direct Mapping: Since ArduPilot uses integer coordinates internally, MISSION_ITEM_INT messages are decoded directly into the internal mission representation without the precision loss associated with float conversions.
  • Storage: Items are stored in the vehicle's non-volatile memory via the AP_Mission library.

Transmission (TX)

During a mission download, modern Ground Control Stations (like Mission Planner or QGroundControl) will request items using MISSION_REQUEST_INT (51). ArduPilot responds with MISSION_ITEM_INT packets.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • seq: Sequence.
  • frame: The coordinate system of the waypoint (MAV_FRAME).
  • command: The scheduled action for the waypoint (MAV_CMD).
  • current: false:0, true:1.
  • autocontinue: autocontinue to next wp.
  • param1: PARAM1, see MAV_CMD enum.
  • param2: PARAM2, see MAV_CMD enum.
  • param3: PARAM3, see MAV_CMD enum.
  • param4: PARAM4, see MAV_CMD enum.
  • x: PARAM5 / local: x position in meters * 1e4, global: latitude in degrees * 10^7.
  • y: PARAM6 / local: y position in meters * 1e4, global: longitude in degrees * 10^7.
  • z: PARAM7 / local: z position: altitude in meters (relative or absolute, depending on frame).
  • mission_type: Mission type (MAV_MISSION_TYPE).

Practical Use Cases

  1. Professional Mission Planning:
    • Scenario: A surveyor is planning an automated grid for a 1cm/pixel orthomosaic map.
    • Action: The GCS uses MISSION_ITEM_INT to ensure the waypoint coordinates are accurate to within 1.1cm on the Earth's surface.
  2. Long Range Navigation:
    • Scenario: A fixed-wing drone is flying a 50km out-and-back mission.
    • Action: Integer coordinates prevent the "coordinate drift" that can occur in floating-point systems when coordinates have many digits before the decimal point.

Key Codebase Locations

TERRAIN_REQUEST

ID: 133
Supported

Summary

The TERRAIN_REQUEST message is part of the ArduPilot Terrain Protocol. It is sent by the vehicle to the Ground Control Station (GCS) to request digital elevation data (DEM) for a specific geographic area. The GCS responds by sending TERRAIN_DATA (134) messages containing the requested grid blocks.

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Requests map data)
  • RX (Receive): None (Ignored)

Transmission (TX)

The transmission logic is in AP_Terrain::request_missing within libraries/AP_Terrain/TerrainGCS.cpp:72.

Protocol Logic

  1. Grid Management: The AP_Terrain library divides the world into 4x4 grids of terrain heights.
  2. Bitmap Check: It maintains a bitmap of which grids it has loaded. If the vehicle is flying towards an area where data is missing (and not on the SD card), it initiates a request.
  3. Masking: The mask field tells the GCS exactly which 4x4 blocks within a larger tile are missing, optimizing bandwidth.

Data Fields

  • lat: Latitude of grid (deg * 1E7).
  • lon: Longitude of grid (deg * 1E7).
  • grid_spacing: Grid spacing (in meters).
  • mask: Bitmask of requested 4x4 blocks within the 8x7 grid.

Practical Use Cases

  1. Terrain Following:
    • Scenario: A plane is flying a low-altitude mission over a mountain.
    • Action: As the plane approaches the mountain, AP_Terrain detects it is missing elevation data for the upcoming coordinates. It sends TERRAIN_REQUEST to the GCS. The GCS replies with the data, allowing the plane to climb autonomously to maintain safe ground clearance.

Key Codebase Locations

TERRAIN_DATA

ID: 134
RX Only

Summary

The TERRAIN_DATA message carries a 4x4 grid of terrain height measurements. It is sent by the Ground Control Station (GCS) to the vehicle in response to a TERRAIN_REQUEST.

Status

RX Only

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles (Updates terrain database)

Reception (RX)

Reception is handled by AP_Terrain::handle_terrain_data within libraries/AP_Terrain/TerrainGCS.cpp:264.

Core Logic

  1. Validation: It verifies that the incoming packet corresponds to a pending request in the internal grid cache.
  2. Population: It maps the 4x4 data block into the larger 8x7 internal grid structure.
  3. Persistence: Once a grid is fully populated or sufficiently updated, it is marked as GRID_CACHE_DIRTY, triggering a write to the SD card database.

Data Fields

  • lat: Latitude of grid (deg * 1E7).
  • lon: Longitude of grid (deg * 1E7).
  • grid_spacing: Grid spacing (in meters).
  • gridbit: Index of the 4x4 block within the larger grid.
  • data: Array of 16 int16_t values representing terrain height in meters.

Practical Use Cases

  1. Offline Terrain Following:
    • Scenario: A user uploads a mission with TERRAIN_FRAME waypoints but the drone is not yet flying.
    • Action: The GCS proactively pushes TERRAIN_DATA for the mission area to the drone. The drone stores this on its SD card. During flight, even if telemetry is lost, the drone has the data needed to fly safely close to the ground.

Key Codebase Locations

TERRAIN_CHECK

ID: 135
Supported

Summary

The TERRAIN_CHECK message is a query used by the Ground Control Station (GCS) to verify if the vehicle has terrain data available for a specific location. This is often done during mission planning or pre-flight checks to ensure the drone can safely perform terrain-following operations.

Status

Supported

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles (Queries terrain database)

Reception (RX)

Reception is handled by AP_Terrain::handle_terrain_check within libraries/AP_Terrain/TerrainGCS.cpp:251.

Core Logic

  1. Query: The GCS provides a latitude (lat) and longitude (lon).
  2. Lookup: ArduPilot checks its internal AP_Terrain database (both RAM cache and SD card).
  3. Response: It immediately sends back a TERRAIN_REPORT (136) message containing the terrain height at that location and the status of pending/loaded grid blocks.

Data Fields

  • lat: Latitude (deg * 1E7).
  • lon: Longitude (deg * 1E7).

Practical Use Cases

  1. Pre-Arming Safety:
    • Scenario: A user uploads a mission that requires terrain following.
    • Action: The GCS sends TERRAIN_CHECK for each waypoint. If the drone replies with TERRAIN_REPORT indicating missing data, the GCS warns the user or initiates a data upload.

Key Codebase Locations

TERRAIN_REPORT

ID: 136
Supported

Summary

The TERRAIN_REPORT message is sent by the vehicle to the Ground Control Station (GCS) to provide the terrain elevation at a specific coordinate. It is typically sent in response to a TERRAIN_CHECK (135) request or as part of the vehicle's periodic status stream to indicate terrain database health (loaded/pending blocks).

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Reports terrain data)
  • RX (Receive): None (Ignored)

Transmission (TX)

The transmission logic is in AP_Terrain::send_terrain_report within libraries/AP_Terrain/TerrainGCS.cpp:221.

Protocol Logic

  1. Height Lookup: It queries the internal terrain database for the elevation at the requested lat/lon.
  2. Statistics: It calculates the number of pending (requested but not received) and loaded (valid) 4x4 grid blocks in the cache.
  3. Current Height: It includes the vehicle's current height above terrain (current_height) if available.

Data Fields

  • lat: Latitude (deg * 1E7).
  • lon: Longitude (deg * 1E7).
  • spacing: Grid spacing in meters (0 if no data available).
  • terrain_height: Terrain height in meters AMSL.
  • current_height: Current vehicle height above terrain in meters.
  • pending: Number of 4x4 terrain blocks waiting to be loaded/received.
  • loaded: Number of 4x4 terrain blocks currently in memory.

Practical Use Cases

  1. Database Visualization:
    • Scenario: A pilot is preparing for a terrain-following mission.
    • Action: The GCS displays the loaded count. As the GCS pushes TERRAIN_DATA to the drone, this number increases, confirming the map is being saved to the SD card.
  2. Look-Ahead Safety:
    • Scenario: The drone is flying towards a hill.
    • Action: The GCS (or onboard script) sends a TERRAIN_CHECK for a coordinate 500m ahead. The returned TERRAIN_REPORT shows the hill's altitude, allowing the system to verify clearance.

Key Codebase Locations

FENCE_POINT

ID: 160
Legacy / Deprecated

Summary

The FENCE_POINT message is part of the legacy Geofence protocol. It is used to upload a fence vertex to the vehicle or to return a fence vertex to the GCS in response to a FENCE_FETCH_POINT request.

Status

Legacy / Deprecated

Directionality

  • TX (Transmit): All Vehicles (Response to FENCE_FETCH_POINT)
  • RX (Receive): All Vehicles (Set fence point)

Description

ArduPilot deprecated this protocol in version 4.6. Newer systems use the Mission Protocol (with type MAV_MISSION_TYPE_FENCE) to manage complex geofences including polygons, circles, and exclusion zones.

However, ArduPilot still supports this message for backward compatibility if AC_POLYFENCE_FENCE_POINT_PROTOCOL_SUPPORT is enabled. It allows uploading a single inclusion polygon and a return point.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • idx: Point index (0 is return point, 1-N are polygon vertices).
  • count: Total number of points (must be >= 5 for a valid fence).
  • lat: Latitude of point (degrees).
  • lng: Longitude of point (degrees).

Practical Use Cases

  1. Legacy GCS:
    • Scenario: An older version of Mission Planner uploads a fence.
    • Action: It iterates through the vertices, sending FENCE_POINT messages with incrementing idx.

Key Codebase Locations

FENCE_FETCH_POINT

ID: 161
Legacy / Deprecated

Summary

The FENCE_FETCH_POINT message is used by a Ground Control Station (GCS) to request a specific fence vertex from the vehicle. The vehicle responds with a FENCE_POINT (160) message.

Status

Legacy / Deprecated

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles (Requests a fence point)

Description

ArduPilot deprecated this protocol in version 4.6. Receiving it triggers a send_received_message_deprecation_warning before processing.

If AC_POLYFENCE_FENCE_POINT_PROTOCOL_SUPPORT is enabled:

  1. ArduPilot decodes the idx (index).
  2. It retrieves the corresponding vertex (Return point for 0, Polygon vertices for 1+).
  3. It sends back a FENCE_POINT message.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • idx: Point index to fetch.

Key Codebase Locations

FENCE_STATUS

ID: 162
Supported

Summary

The FENCE_STATUS message reports the current status of the vehicle's geofence, including whether a breach has occurred, the type of breach (altitude, boundary), and any active mitigation actions.

Status

Supported

Directionality

  • TX (Transmit): All Vehicles (Reports fence status)
  • RX (Receive): None (Ignored)

Transmission (TX)

Transmission is handled by GCS_MAVLINK::send_fence_status within libraries/GCS_MAVLink/GCS_Fence.cpp:66.

Logic

  1. Check: If the fence is disabled, no message is sent.
  2. Translate Breaches: The internal AC_Fence breach types are mapped to MAVLink enums (FENCE_BREACH_MINALT, FENCE_BREACH_MAXALT, FENCE_BREACH_BOUNDARY).
  3. Mitigation: Checks AC_Avoid to see if velocity limiting (FENCE_MITIGATE_VEL_LIMIT) is active to prevent a breach.

Data Fields

  • breach_status: 0 if currently inside fence, 1 if outside.
  • breach_count: Number of fence breaches since arming.
  • breach_type: Type of last breach (FENCE_BREACH_NONE, MINALT, MAXALT, BOUNDARY).
  • breach_time: Time of last breach (ms since boot).
  • breach_mitigation: Active mitigation action (FENCE_MITIGATE_NONE, VEL_LIMIT).

Practical Use Cases

  1. Pilot Awareness:
    • Scenario: A pilot is flying near a geofence boundary.
    • Action: The GCS displays a warning icon when breach_status becomes 1, alerting the pilot that the vehicle has violated the safety zone.
  2. Safety Auditing:
    • Scenario: Post-flight analysis.
    • Action: Reviewing the log to see where breach_count incremented helps identify if the mission plan was too close to restricted airspace.

Key Codebase Locations

RALLY_POINT

ID: 175
Supported (RX & TX)

Summary

Represents a rally point (safe return location). This message is part of the legacy Rally Point protocol.

Status

Supported (RX & TX)

Directionality

  • TX (Transmit): All Vehicles - Sends a rally point to the GCS (response to fetch).
  • RX (Receive): All Vehicles - Receives a new rally point from the GCS (upload).

Description

This message allows a GCS to read or write rally points on the vehicle. While fully supported, ArduPilot 4.6+ issues a deprecation warning when this protocol is used, preferring the Mission Item protocol (using MAV_CMD_NAV_RALLY_POINT) instead.

Transmission (TX)

Sent in response to RALLY_FETCH_POINT.

Source: libraries/GCS_MAVLink/GCS_Rally.cpp

Reception (RX)

Handled by GCS_MAVLINK::handle_rally_point. Updates the rally point at the specified index in the storage.

Source: libraries/GCS_MAVLink/GCS_Rally.cpp

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • idx: Index of the rally point (0-based).
  • count: Total number of rally points.
  • lat: Latitude (int32, deg * 1E7).
  • lng: Longitude (int32, deg * 1E7).
  • alt: Altitude (int16, meters).
  • break_alt: Break altitude (int16, meters) - Alt to descend to before landing.
  • land_dir: Landing direction (centidegrees).
  • flags: Configuration flags (e.g., Favorable Wind).

Practical Use Cases

  1. Uploading Safe Points:
    • Scenario: Uploading a set of safe landing zones before a mission.
    • Action: GCS sends RALLY_POINT messages to populate the list.

Key Codebase Locations

  • libraries/GCS_MAVLink/GCS_Rally.cpp: Implementation.

RALLY_FETCH_POINT

ID: 176
Supported (RX Only)

Summary

Request to fetch a specific rally point from the vehicle.

Status

Supported (RX Only)

Directionality

  • TX (Transmit): None
  • RX (Receive): All Vehicles - Receives request from GCS.

Reception (RX)

Handled by GCS_MAVLINK::handle_rally_fetch_point. The vehicle responds by sending a RALLY_POINT message for the requested index.

Source: libraries/GCS_MAVLink/GCS_Rally.cpp

Protocol Logic

  1. GCS sends RALLY_FETCH_POINT with idx.
  2. Vehicle retrieves point at idx.
  3. Vehicle replies with RALLY_POINT.

Data Fields

  • target_system: System ID.
  • target_component: Component ID.
  • idx: Index of the rally point to fetch.

Practical Use Cases

  1. Downloading Safe Points:
    • Scenario: GCS connects to a drone and wants to display existing safe zones.
    • Action: GCS iterates through indices, sending RALLY_FETCH_POINT for each.

Key Codebase Locations

  • libraries/GCS_MAVLink/GCS_Rally.cpp:73: handle_rally_fetch_point implementation.

TRAJECTORY_REPRESENTATION_WAYPOINTS

ID: 332
Unsupported

Summary

The TRAJECTORY_REPRESENTATION_WAYPOINTS message is used to describe a trajectory as a series of waypoints. It allows for more complex path planning descriptions than standard mission items, often used in offboard control scenarios.

Status

Unsupported

Directionality

  • TX (Transmit): None
  • RX (Receive): None

Description

ArduPilot does not implement this message.

ArduPilot typically handles trajectories via:

  1. Mission Protocol: Uploading a list of MISSION_ITEM_INT waypoints.
  2. Guided Mode: Sending individual SET_POSITION_TARGET_LOCAL_NED or SET_POSITION_TARGET_GLOBAL_INT commands.

Intended Data Fields (Standard)

  • time_usec: Timestamp.
  • valid_points: Number of valid points (up to 5).
  • pos_x / pos_y / pos_z: Arrays of X, Y, Z positions.
  • vel_x / vel_y / vel_z: Arrays of X, Y, Z velocities.
  • acc_x / acc_y / acc_z: Arrays of X, Y, Z accelerations.
  • pos_yaw: Array of yaw angles.
  • vel_yaw: Array of yaw rates.
  • command: Array of MAV_CMD commands associated with waypoints.

Theoretical Use Cases

  1. Lookahead Planning:
    • Scenario: A companion computer is planning a path through a dynamic environment.
    • Action: It sends a packet of 5 waypoints representing the immediate future trajectory (0s, 1s, 2s, 3s, 4s) to the flight controller. This provides the controller with "intent" data, allowing for smoother feed-forward control than sending a single setpoint at 50Hz.
  2. Swarm Choreography:
    • Scenario: Drones flying in formation.
    • Action: The central computer broadcasts the next 5 seconds of the "dance" to all drones. If the radio link drops for a second, the drones continue on the pre-buffered path without jittering.

TRAJECTORY_REPRESENTATION_BEZIER

ID: 333
Unsupported

Summary

The TRAJECTORY_REPRESENTATION_BEZIER message describes a trajectory using Bezier curves. This allows for extremely smooth path definitions with continuous velocity and acceleration profiles, often used in advanced motion planning.

Status

Unsupported

Directionality

  • TX (Transmit): None
  • RX (Receive): None

Description

ArduPilot does not implement this message.

Internally, ArduPilot uses S-Curve navigation (SCurve) for smooth path generation between waypoints, but it does not currently accept external Bezier curve definitions via MAVLink.

Intended Data Fields (Standard)

  • time_usec: Timestamp.
  • valid_points: Number of valid points.
  • pos_x / pos_y / pos_z: Arrays of control points.
  • delta: Array of time deltas for each segment.
  • pos_yaw: Array of yaw angles.

Theoretical Use Cases

  1. Cinematic Videography:
    • Scenario: Filming a car chase.
    • Action: A director designs a complex, sweeping camera move in 3D software. The software exports the path as a series of Bezier curves, which are uploaded to the drone. The drone executes the curve perfectly, ensuring smooth acceleration that doesn't jerk the gimbal.
  2. Obstacle Avoidance:
    • Scenario: High-speed flight through a forest.
    • Action: A path planner generates a curved tube that avoids trees. Sending Bezier control points allows the drone to follow this curved tube much more accurately than connecting straight line waypoints.