PAYLOAD

Summary

The CAMERA_TRIGGER message is defined in MAVLink to notify external systems that a camera shutter has been activated. ArduPilot does not implement this message. Instead, it uses the more modern and detailed CAMERA_FEEDBACK (180) and CAMERA_IMAGE_CAPTURED (263) messages to report camera events.

Status

Unsupported

Directionality

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

Analysis

ArduPilot's camera subsystem (AP_Camera) focuses on providing rich feedback about the exact moment and location of a photo capture, which is essential for photogrammetry. The simple CAMERA_TRIGGER message lacks the precision and metadata (like roll/pitch/yaw and GPS coordinates) required for professional mapping, so it is bypassed in favor of other messages.

• Replacement: Users and GCS developers should listen for CAMERA_FEEDBACK (180) to receive the exact position and attitude data associated with a shutter event.

Data Fields

• time_usec: Timestamp for the image frame in microseconds.
• seq: Image sequence number.

Key Codebase Locations

• libraries/GCS_MAVLink/GCS_Common.cpp: Lacks a handler or sender for ID 112.

Summary

The DATA_TRANSMISSION_HANDSHAKE message is part of the legacy MAVLink Image Transmission Protocol. It is used to initiate a data transfer session (typically for images or other large binary blobs) between a component and a Ground Control Station.

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

This protocol has largely been superseded by:

1. MAVLink FTP (FILE_TRANSFER_PROTOCOL): For transferring logs, parameters, and mission files.
2. RTSP/UDP Streaming: For live video (see VIDEO_STREAM_INFORMATION).
3. CAMERA_IMAGE_CAPTURED: For notifying GCS of new photos, often with HTTP download links.

Data Fields

• type: Type of requested/acknowledged data.
• size: Total data size in bytes.
• width: Width of a matrix or image.
• height: Height of a matrix or image.
• packets: Number of packets being sent.
• payload: Payload size per packet.
• jpg_quality: JPEG quality.

Theoretical Use Cases

1. Low-Bandwidth Image Transfer:
   • Scenario: A satellite-connected drone takes a surveillance photo.
   • Action: Since the link is too slow for RTSP, the drone initiates a handshake to send the image as a series of small, acknowledged MAVLink packets (ENCAPSULATED_DATA), allowing the GCS to reconstruct the image over several minutes.

Summary

The ENCAPSULATED_DATA message carries the actual binary payload (chunks of an image or file) during a transfer initiated by DATA_TRANSMISSION_HANDSHAKE.

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message. It is part of the legacy Image Transmission Protocol.

Data Fields

• seqnr: Sequence number (starting at 0).
• data: Raw data (up to 253 bytes).

Theoretical Use Cases

1. Chunked File Transfer:
   • Scenario: Transmitting a 10KB thumbnail image.
   • Action: The image is split into 40 packets. Each packet is sent as an ENCAPSULATED_DATA message. The receiver uses the seqnr to reassemble the binary blob in the correct order.

Summary

The DIGICAM_CONFIGURE message was historically used to configure onboard camera settings like aperture, shutter speed, and ISO.

Status

Legacy / Unsupported

Directionality

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

Description

ArduPilot does not implement this message directly.

Instead, camera configuration is handled via the Mission Command protocol using MAV_CMD_DO_DIGICAM_CONFIGURE (202).

• Mission Items: Users add DO_DIGICAM_CONFIGURE commands to missions.
• Command Handling: AP_Camera processes these commands to adjust settings on supported camera backends (e.g., MAVLink cameras, Relay triggers).

Data Fields

• target_system: System ID.
• target_component: Component ID.
• mode: Shooting mode (A, S, M, Auto, etc.).
• shutter_speed: Shutter speed (1/value).
• aperture: Aperture (F-stop * 10).
• iso: ISO sensitivity.
• exposure_type: Exposure type.
• command_id: Command Identity.
• engine_cut_off: Main engine cut-off time (seconds/10).
• extra_param: Extra parameter.
• extra_value: Extra value.

Summary

The DIGICAM_CONTROL message is a legacy method for controlling onboard cameras (taking photos, zooming, etc.). It is largely deprecated in favor of the MAV_CMD_DO_DIGICAM_CONTROL command, but ArduPilot still supports receiving this message for backward compatibility.

Status

RX Only

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles (Triggers camera action)

Reception (RX)

Reception is handled by AP_Camera::handle_message within libraries/AP_Camera/AP_Camera.cpp:261.

Protocol Logic

1. Decoding: The message is decoded into a mavlink_digicam_control_t packet.
2. Action: The control() function is called with the unpacked parameters.
3. Triggering: If shot is 1, the camera shutter is triggered via the configured backend (Servo, Relay, or MAVLink).

Data Fields

• target_system: System ID.
• target_component: Component ID.
• session: Session control (e.g. show/hide lens).
• zoom_pos: Zoom's absolute position.
• zoom_step: Zooming step value to offset zoom from the current position.
• focus_lock: Focus Locking, Unlocking or Re-locking.
• shot: Shooting Command (1 to take a picture).
• command_id: Command Identity.
• extra_param: Extra parameter.
• extra_value: Extra value.

Practical Use Cases

1. Legacy GCS Support:
   • Scenario: An older Ground Control Station only supports this message for camera triggering.
   • Action: When the user clicks "Trigger Camera", the GCS sends DIGICAM_CONTROL. ArduPilot receives it and fires the relay to take a picture.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera.cpp:261: Implementation of the handler.

Summary

The MOUNT_CONFIGURE message was historically used to configure the operation mode (retract, neutral, mavlink targeting, rc targeting, gps point) of a gimbal/mount.

Status

Legacy / Unsupported

Directionality

• TX (Transmit): None
• RX (Receive): None (ArduPilot explicitly warns of deprecation if received)

Description

ArduPilot deprecated this message in version 4.5. Receiving it may trigger a send_received_message_deprecation_warning.

Users should instead use the Mission Command:

• MAV_CMD_DO_MOUNT_CONFIGURE (204)

Data Fields

• target_system: System ID.
• target_component: Component ID.
• mount_mode: Mount operation mode (MAV_MOUNT_MODE enum).
• stab_roll: (1 = yes, 0 = no).
• stab_pitch: (1 = yes, 0 = no).
• stab_yaw: (1 = yes, 0 = no).

Summary

The MOUNT_CONTROL message was historically used to control the pitch, roll, and yaw angles of a gimbal/mount.

Status

Legacy / Unsupported

Directionality

• TX (Transmit): None
• RX (Receive): None (ArduPilot explicitly warns of deprecation if received)

Description

ArduPilot deprecated this message in version 4.5. Receiving it may trigger a send_received_message_deprecation_warning.

Users should instead use the Mission Command:

• MAV_CMD_DO_MOUNT_CONTROL (205)

Data Fields

• target_system: System ID.
• target_component: Component ID.
• input_a: Pitch (centi-degrees) or Lat (deg * 1E7) depending on mode.
• input_b: Roll (centi-degrees) or Lon (deg * 1E7) depending on mode.
• input_c: Yaw (centi-degrees) or Alt (cm) depending on mode.
• save_position: Save current position (1 = yes).

Summary

The MOUNT_STATUS message was historically used to report the orientation (Pitch, Roll, Yaw) of a gimbal/mount to the GCS.

Status

Deprecated

Directionality

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

Description

ArduPilot no longer sends this message. It has been superseded by the MAVLink Gimbal Protocol v2.

Instead, ArduPilot sends:

1. MOUNT_ORIENTATION (265): Simplified orientation report.
2. GIMBAL_DEVICE_ATTITUDE_STATUS (285): Detailed status for Gimbal v2.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• pointing_a: Pitch (centi-degrees).
• pointing_b: Roll (centi-degrees).
• pointing_c: Yaw (centi-degrees).

Summary

Legacy camera status message.

Status

Unsupported

Directionality

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

Description

This message is not supported by ArduPilot. Use CAMERA_FEEDBACK (180) or CAMERA_IMAGE_CAPTURED (263) instead.

Theoretical Use Cases

Legacy camera reporting.

Summary

precise location and attitude information for the moment a photo was taken. Crucial for aerial mapping and photogrammetry.

Status

Supported (TX Only)

Directionality

• TX (Transmit): All Vehicles (with Camera enabled) - Sends trigger confirmation.
• RX (Receive): None

Transmission (TX)

ArduPilot sends this message whenever a camera trigger event is successfully logged (either by software command or hardware hot-shoe feedback).

Source: libraries/AP_Camera/AP_Camera_Backend.cpp

Protocol Logic

When a photo is taken, AP_Camera records the vehicle's position (lat, lng, alt) and attitude (roll, pitch, yaw) at that exact timestamp. This data is then streamed to the GCS.

• Hot Shoe: If hardware feedback is enabled, this message corresponds to the exact shutter close time.
• Open Loop: If no feedback, it corresponds to the trigger command time.

Data Fields

• time_usec: Image timestamp (microseconds since boot).
• target_system: System ID.
• cam_idx: Camera ID.
• img_idx: Image index (counter).
• lat: Latitude (deg * 1E7).
• lng: Longitude (deg * 1E7).
• alt_msl: Altitude MSL (meters).
• alt_rel: Relative Altitude (meters).
• roll: Roll (degrees).
• pitch: Pitch (degrees).
• yaw: Yaw (degrees).
• foc_len: Focal length (mm).
• flags: Feedback flags (e.g., CAMERA_FEEDBACK_PHOTO).
• completed_captures: Count of completed captures.

Practical Use Cases

1. Photogrammetry / Mapping:
   • Scenario: A drone flies a survey grid taking photos every 20 meters.
   • Action: The GCS records CAMERA_FEEDBACK messages to a log. Post-flight, this log is used to geotag the images (Write EXIF data) with high precision, allowing for accurate 3D model reconstruction.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera_Backend.cpp:205: Sending implementation.

Summary

Status report from a 3DR Solo Gimbal (or compatible device).

Status

Supported (RX Only)

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles - Receives status from the gimbal.

Reception (RX)

Handled by GCS_MAVLink and passed to AP_Mount.

Source: libraries/AP_Mount/AP_Mount.cpp

Protocol Logic

The AP_Mount library decodes the message to update its internal state of the gimbal's actual angles.

• Note: This is specific to the "Solo Gimbal" protocol, which is distinct from the newer MAVLink Gimbal Protocol v2 (GIMBAL_DEVICE_...).

Data Fields

• target_system: System ID.
• target_component: Component ID.
• delta_time: Time since last update.
• delta_angle_x: Delta angle X.
• delta_angle_y: Delta angle Y.
• delta_angle_z: Delta angle Z.
• delta_velocity_x: Delta velocity X.
• delta_velocity_y: Delta velocity Y.
• delta_velocity_z: Delta velocity Z.
• joint_roll: Joint angle roll.
• joint_el: Joint angle elevation.
• joint_az: Joint angle azimuth.

Practical Use Cases

1. Solo Gimbal Integration:
   • Scenario: Using a legacy 3DR Solo Gimbal.
   • Action: The gimbal reports its joint angles, allowing the autopilot to stabilize it or display its orientation.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount.cpp:996: Handler.

Summary

Control message for the 3DR Solo Gimbal.

Status

Supported (TX Only)

Directionality

• TX (Transmit): All Vehicles (if Solo Gimbal configured) - Sends control demands.
• RX (Receive): None

Transmission (TX)

ArduPilot sends this message to command the gimbal's rate and orientation.

Source: libraries/AP_Mount/SoloGimbal.cpp

Protocol Logic

The AP_Mount_SoloGimbal driver converts user or autopilot demands (e.g., "Look Down") into rate commands for the gimbal motors.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• demand: Demand vector (rate or angle).

Practical Use Cases

1. Gimbal Pointing:
   • Scenario: Pilot uses a slider to tilt the camera.
   • Action: ArduPilot sends GIMBAL_CONTROL commands to the gimbal to execute the movement.

Key Codebase Locations

• libraries/AP_Mount/SoloGimbal.cpp:118: Sending implementation.

Summary

Report torque commands for gimbal.

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

Theoretical Use Cases

Debugging gimbal motor torques.

Summary

Heartbeat from a GoPro camera connected via a Solo Gimbal.

Status

Supported (RX Only)

Directionality

• TX (Transmit): None
• RX (Receive): All Vehicles - Detects GoPro presence.

Reception (RX)

Handled by GCS_MAVLink and used for routing logic.

Source: libraries/GCS_MAVLink/GCS_Common.cpp

Protocol Logic

Used to determine if a GoPro is connected and active on the gimbal link.

Data Fields

• status: Status flags.
• capture_mode: Current capture mode.
• flags: Additional flags.

Practical Use Cases

1. Gimbal Integration:
   • Scenario: User turns on Solo drone.
   • Action: Autopilot receives GOPRO_HEARTBEAT and enables GoPro control widgets in the GCS.

Key Codebase Locations

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

Summary

Request a setting from a GoPro.

Status

Unsupported

Directionality

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

Description

ArduPilot does not process this message. It is likely routed directly between the GCS and the Gimbal/Camera if used.

Theoretical Use Cases

Retrieving camera settings.

Summary

Response to a GoPro setting request.

Status

Unsupported

Directionality

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

Description

ArduPilot does not process this message.

Theoretical Use Cases

Returning camera settings.

Summary

Request to set a GoPro setting.

Status

Unsupported

Directionality

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

Description

ArduPilot does not process this message.

Theoretical Use Cases

Changing camera settings.

Summary

Response to a GoPro set request.

Status

Unsupported

Directionality

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

Description

ArduPilot does not process this message.

Theoretical Use Cases

Confirming camera setting changes.

Summary

The CAMERA_INFORMATION message provides static metadata about an onboard camera to the Ground Control Station (GCS). It includes details like the manufacturer, model, focal length, sensor size, and resolution. This information is critical for survey planning software to calculate the "Ground Sample Distance" (GSD) and footprint of photos without requiring the user to manually enter camera specifications.

Status

Supported

Directionality

• TX (Transmit): All Vehicles (Reports camera capabilities to GCS)
• RX (Receive): Specific Backends (Receives info from external MAVLink cameras)

Transmission (TX)

The transmission logic is centered in libraries/AP_Camera/AP_Camera.cpp:577, which delegates to individual backend implementations.

Data Sourcing

• Metadata: Sourced from the AP_Camera backend (AP_Camera_Backend.cpp:224).
• Information Included:
  • vendor_name / model_name: Identifies the hardware (e.g., "Sony", "Alpha 7").
  • focal_length: The lens focal length in millimeters.
  • sensor_size_h / sensor_size_v: Dimensions of the image sensor in millimeters.
  • resolution_h / resolution_v: Total pixel dimensions of the captured images.
• Trigger: Sent on request (e.g., via MAV_CMD_REQUEST_MESSAGE).

Reception (RX)

ArduPilot handles this message in the MAVLinkCamV2 backend.

• Scenario: A specialized MAVLink-enabled camera (like a Gremsy or SIYI) is connected to the autopilot.
• Action: The camera sends its CAMERA_INFORMATION to the autopilot. ArduPilot's AP_Camera_MAVLinkCamV2 backend parses this data and stores it, allowing the autopilot to proxy the information to the main Ground Control Station.

Data Fields

• time_boot_ms: Timestamp (time since system boot).
• vendor_name: Name of the camera vendor.
• model_name: Name of the camera model.
• firmware_version: Version of the camera firmware, encoded as: (Dev & 0xff) << 24 | (Patch & 0xff) << 16 | (Minor & 0xff) << 8 | (Major & 0xff).
• focal_length: Focal length.
• sensor_size_h: Image sensor size horizontal.
• sensor_size_v: Image sensor size vertical.
• resolution_h: Image resolution in pixels horizontal.
• resolution_v: Image resolution in pixels vertical.
• lens_id: Reserved for a lens ID.
• flags: Bitmap of camera capability flags.
• cam_definition_version: Camera definition version (iteration).
• cam_definition_uri: Camera definition URI (if any, otherwise only basic functions will be available). HTTP- (http://) or MAVLink FTP- (mavlinkftp://) formatted URI.

Practical Use Cases

1. Automatic Survey Setup:
   • Scenario: A user connects a new mapping camera to their drone.
   • Action: Mission Planner receives CAMERA_INFORMATION. It automatically updates the "Survey" grid calculator with the correct sensor size and focal length, ensuring the overlap and altitude calculations are mathematically correct for that specific camera.
2. Remote Identity & Inventory:
   • Scenario: A fleet manager is checking the status of 10 different drones.
   • Action: The management software queries CAMERA_INFORMATION to verify that each drone is equipped with the correct payload for the scheduled mission (e.g., Thermal vs. RGB).
3. Lens Calibration verification:
   • Scenario: A researcher is using a drone for high-precision scientific imaging.
   • Action: By checking the focal_length field, the researcher can verify that the lens hasn't been swapped or adjusted since the last calibration.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera.cpp:577: Common camera message dispatcher.
• libraries/AP_Camera/AP_Camera_Backend.cpp:224: Logic for populating the information packet.
• libraries/GCS_MAVLink/GCS_Common.cpp:6178: Scheduler integration for camera telemetry.

Summary

The CAMERA_SETTINGS message reports the current dynamic state of an onboard camera, specifically its operating mode, zoom level, and focus level. Unlike CAMERA_INFORMATION, which describes static capabilities, CAMERA_SETTINGS provides real-time feedback to the Ground Control Station (GCS). This ensures that the pilot's UI accurately reflects the camera's physical state, especially during slow operations like zooming or focusing.

Status

Supported

Directionality

• TX (Transmit): Camera-enabled vehicles (Reports state to GCS)
• RX (Receive): None (ArduPilot does not parse this message from GCS)

Transmission (TX)

The transmission logic is abstracted through the AP_Camera and AP_Mount libraries, allowing various hardware drivers to report their status using this unified MAVLink message.

Core Logic

The primary entry point is AP_Camera::send_camera_settings in libraries/AP_Camera/AP_Camera.cpp:605. This function iterates through all initialized camera instances and calls their respective backends.

The message routing from GCS_MAVLink is handled in libraries/GCS_MAVLink/GCS_Common.cpp:6179, which delegates to AP_Camera::send_mavlink_message (libraries/AP_Camera/AP_Camera.cpp:452).

Supported Drivers (Backends)

Several advanced gimbal and camera drivers implement this message to provide feedback:

• Siyi (AP_Mount_Siyi):
  • Implemented in libraries/AP_Mount/AP_Mount_Siyi.cpp:1107.
  • Reports zoomLevel calculated from the current zoom multiplier (interpolated against the max zoom of 6x or 30x depending on hardware model).
  • Reports mode_id based on _config_info.record_status (Video vs Image).
• Viewpro (AP_Mount_Viewpro):
  • Implemented in libraries/AP_Mount/AP_Mount_Viewpro.cpp:936.
• Topotek (AP_Mount_Topotek):
  • Implemented in libraries/AP_Mount/AP_Mount_Topotek.cpp:562.
• Xacti (AP_Mount_Xacti):
  • Implemented in libraries/AP_Mount/AP_Mount_Xacti.cpp:390.

Data Fields

• time_boot_ms: Timestamp (time since system boot).
• mode_id: Camera mode (CAMERA_MODE_IMAGE, CAMERA_MODE_VIDEO, CAMERA_MODE_IMAGE_SURVEY).
• zoomLevel: Current zoom level as a percentage of the full range (0.0 to 100.0, NaN if not known).
• focusLevel: Current focus level as a percentage of the full range (0.0 to 100.0, NaN if not known).

Triggering

This message is typically sent in response to:

1. Command Acknowledgement: After receiving MAV_CMD_DO_SET_CAM_ZOOM_FOCUS or MAV_CMD_REQUEST_CAMERA_SETTINGS.
2. State Change: Some drivers may stream this message while the lens is moving (zooming) to provide smooth UI updates.

Practical Use Cases

1. Zoom Slider Feedback:
   • Scenario: A pilot uses a slider on the GCS to request 50% zoom.
   • Action: The physical lens takes 1.5 seconds to move. The gimbal driver sends CAMERA_SETTINGS updates during this movement, allowing the GCS slider to move in sync with the actual lens, confirming the command is being executed.
2. Focus Confirmation:
   • Scenario: The user taps the screen to "Touch Focus".
   • Action: The camera executes the auto-focus routine. When complete, it sends CAMERA_SETTINGS with the new focusLevel, confirming to the user that the image is sharp.
3. Mode Switching Verification:
   • Scenario: The user switches from "Video" to "Photo" mode to take a high-res still.
   • Action: The camera takes a moment to stop recording and switch buffers. CAMERA_SETTINGS updates the mode_id, enabling the "Shutter" button on the GCS only when the camera is actually ready.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera.cpp:605: Main routing logic.
• libraries/AP_Mount/AP_Mount_Siyi.cpp:1107: Example of a driver implementing the message.
• libraries/GCS_MAVLink/GCS_Common.cpp:6179: Message definition and ID mapping.

Summary

The STORAGE_INFORMATION message is designed to report the status, capacity, and usage of onboard storage media (e.g., SD cards, internal flash, SSDs). It supports reporting for multiple storage devices via a storage_id index. This message allows a Ground Control Station to warn the pilot if storage is low or if a drive is failing before starting a mission or recording session.

Status

Unsupported

Directionality

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

Description

ArduPilot currently does not implement this message. While ArduPilot supports MEMINFO for RAM usage and SYS_STATUS for general system health, it does not have a standardized mechanism for reporting detailed file system statistics via this specific MAVLink message.

If implemented in the future, it would likely be used by the AP_Logger or AP_Filesystem libraries to report the status of the microSD card.

Intended Data Fields (Standard)

• time_boot_ms: Timestamp (ms since boot).
• storage_id: ID of the storage device (1-based index).
• storage_count: Total number of storage devices.
• status: Status flags (STORAGE_STATUS enum) indicating if the device is ready, unformatted, or has errors.
• total_capacity: Total size in MiB.
• used_capacity: Used space in MiB.
• available_capacity: Free space in MiB.
• read_speed: Read throughput in MiB/s.
• write_speed: Write throughput in MiB/s.

Theoretical Use Cases

1. Pre-Flight Check:
   • Scenario: A photographer is about to launch a mission.
   • Action: The GCS checks available_capacity. If it's less than 1GB (insufficient for the planned 4K video recording), it prevents arming and prompts the user to format the card.
2. Health Monitoring:
   • Scenario: A microSD card is degrading.
   • Action: The autopilot detects slow write speeds and reports a low write_speed. The GCS warns the user that high-rate logging might be compromised.

Summary

The CAMERA_CAPTURE_STATUS message reports the current status of the image and video capture subsystem. It allows the Ground Control Station (GCS) to know if the camera is currently taking photos (e.g., during a mapping mission) or recording video, along with the current image count and capture interval.

Status

Supported

Directionality

• TX (Transmit): Camera-enabled vehicles (Reports status to GCS)
• RX (Receive): None

Transmission (TX)

The transmission is handled by the AP_Camera library, specifically for cameras controlled directly by the autopilot's internal intervalometer (e.g., Servo, Relay, or basic MAVLink cameras).

Core Logic

The implementation resides in AP_Camera_Backend::send_camera_capture_status within libraries/AP_Camera/AP_Camera_Backend.cpp:346.

It is triggered by AP_Camera::send_mavlink_message in libraries/AP_Camera/AP_Camera.cpp:633.

Data Fields

• time_boot_ms: Timestamp (ms since boot).
• image_status:
  • Calculated from time_interval_settings.num_remaining.
  • 2 ("Interval set but idle") if num_remaining > 0.
  • 0 ("Idle") otherwise.
  • Note: The base implementation does not currently return 1 ("Capture in progress") or 3, limiting its utility to showing intent rather than active exposure.
• video_status: Hardcoded to 0 (Idle) in the base implementation.
• image_interval: The configured interval in seconds, derived from time_interval_settings.time_interval_ms.
• recording_time_ms: Hardcoded to 0.
• available_capacity: Hardcoded to NaN (Not Available).
• image_index: The total number of images captured in this session (image_index).

Limitations

• Advanced Gimbals: While AP_Mount has a virtual method for this message, most complex drivers (Siyi, Viewpro, Topotek) do not currently override it. This means they will not report their internal video recording status or SD card capacity via this message. They typically use CAMERA_SETTINGS (Mode) and CAMERA_INFORMATION instead.
• Video Status: The base AP_Camera implementation assumes it is only controlling a still shutter, so video_status is always 0.

Practical Use Cases

1. Mapping Mission Progress:
   • Scenario: A drone is flying a grid pattern for photogrammetry.
   • Action: The GCS monitors image_index to confirm that the camera is actually incrementing its photo count, ensuring the trigger cable hasn't failed.
2. Intervalometer Confirmation:
   • Scenario: The user commands "Take 1 photo every 2 seconds".
   • Action: The message reports image_interval = 2.0 and image_status = 2, confirming the autopilot has accepted the command and is running the timer.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera_Backend.cpp:346: Default implementation.
• libraries/AP_Camera/AP_Camera.cpp:462: Message handling.

Summary

The CAMERA_IMAGE_CAPTURED message is intended to be emitted every time a camera captures an image. It includes detailed metadata such as the precise UTC timestamp, geolocation (lat/lon/alt), orientation (quaternion), and the file URL. It is effectively a richer, modern replacement for the older CAMERA_FEEDBACK message.

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

Instead, ArduPilot uses the legacy CAMERA_FEEDBACK (180) message to report successful image captures. This usually occurs when the camera's hot-shoe signal triggers the flight controller's feedback pin.

Intended Data Fields (Standard)

• time_boot_ms: Timestamp (ms since boot).
• time_utc: Capture time (us since UNIX epoch).
• camera_id: Deprecated/unused.
• lat, lon, alt: Location where image was taken.
• relative_alt: Altitude above ground.
• q: Quaternion of camera orientation.
• image_index: Zero-based index of this image.
• capture_result: Success (1) or Failure (0).
• file_url: URL of the image (local path or HTTP).

Alternative

For image capture feedback in ArduPilot, refer to CAMERA_FEEDBACK (180).

Theoretical Use Cases

1. Instant Geotagging:
   • Scenario: A companion computer is building a map in real-time.
   • Action: It receives CAMERA_IMAGE_CAPTURED containing the exact pose (q) and location (lat/lon) of the image just taken, allowing it to project the image onto the map without needing to interpolate log data later.
2. File Management:
   • Scenario: A WiFi-connected camera.
   • Action: The message includes file_url, allowing the GCS to immediately download a thumbnail of the image via HTTP.

Summary

The MOUNT_ORIENTATION message is a modern replacement for the older MOUNT_STATUS message. It is designed to report the precise orientation of a gimbal or camera mount in the global frame (Roll/Pitch/Yaw relative to Earth) and the body frame (Yaw relative to vehicle).

Status

Unsupported

Directionality

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

Description

ArduPilot currently does not implement this message.

Instead, ArduPilot uses the legacy MOUNT_STATUS (158) message to report gimbal angles. MOUNT_STATUS provides the pitch, roll, and yaw angles in centi-degrees, typically relative to the body frame (depending on the mode).

Intended Data Fields (Standard)

• time_boot_ms: Timestamp (ms since boot).
• roll: Roll in global frame (deg).
• pitch: Pitch in global frame (deg).
• yaw: Yaw relative to the vehicle (deg).
• yaw_absolute: Yaw in global frame (relative to North) (deg).

Alternative

For gimbal feedback in ArduPilot, refer to MOUNT_STATUS (158).

Theoretical Use Cases

1. Augmented Reality (AR):
   • Scenario: A GCS overlays street names on the live video feed.
   • Action: The GCS uses yaw_absolute and pitch from MOUNT_ORIENTATION to accurately project the 3D map data onto the 2D video plane, independent of the drone's own heading.

Summary

The VIDEO_STREAM_INFORMATION message provides the Ground Control Station (GCS) with the necessary connection details to display a live video feed. This includes the Stream URI (e.g., rtsp://192.168.144.25:8554/main.264), resolution, framerate, and encoding format.

Status

Supported

Directionality

• TX (Transmit): Camera-enabled vehicles (Reports stream config to GCS)
• RX (Receive): None

Transmission (TX)

The transmission logic is unique in ArduPilot: the core C++ engine handles the sending of the message, but the content is typically generated dynamically by a Lua script. This allows users to configure arbitrary IP cameras without modifying the firmware source code.

Core Logic

1. Sending (C++):

   • AP_Camera_Backend::send_video_stream_information in libraries/AP_Camera/AP_Camera_Backend.cpp:263 calls mavlink_msg_video_stream_information_send_struct.
   • It sends the data stored in the _stream_info struct.

2. Populating (Lua):

   • The _stream_info struct is populated by the set_stream_information binding.
   • The official script libraries/AP_Scripting/applets/video-stream-information.lua (Source) reads custom parameters (e.g., VID1_CAMMODEL, VID1_IPADDR) to construct the correct RTSP URI for supported cameras (Siyi, Herelink, Topotek, Viewpro) and pushes this data to the C++ backend.

Data Fields

• stream_id: Stream ID (1-based).
• count: Total number of streams.
• type: Protocol type (e.g., RTSP, RTPUDP, MPEG-TS).
• flags: Status flags (e.g., Thermal, Thermal Range).
• framerate: Frame rate in Hz.
• resolution_h / resolution_v: Resolution in pixels (e.g., 1920x1080).
• bitrate: Bitrate in bits/s.
• rotation: Rotation (0, 90, 180, 270).
• hfov: Horizontal Field of View (deg).
• name: Stream name (e.g., "Video").
• uri: The connection string (e.g., rtsp://192.168.144.25:8554/main.264).
• encoding: Encoding format (H.264, H.265).

Practical Use Cases

1. Siyi/Herelink Integration:
   • Scenario: A user connects a Siyi ZR10 gimbal.
   • Action: The Lua script detects VID1_CAMMODEL = 2 (ZR10) and automatically populates the uri with rtsp://192.168.144.25:8554/main.264. QGroundControl receives this message and automatically starts playing the video feed without manual URL entry.
2. Dual-Stream setups:
   • Scenario: A drone has both a Visible and Thermal camera.
   • Action: The GCS receives two VIDEO_STREAM_INFORMATION messages (or one with count=2) and offers the pilot a dropdown to switch between "RGB" and "Thermal" views.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera_Backend.cpp:263: C++ Sender.
• libraries/AP_Scripting/applets/video-stream-information.lua: Lua Logic for populating data.

Summary

The VIDEO_STREAM_STATUS message is designed to report the real-time health and telemetry of a video stream, such as current bitrate, framerate, and resolution. This differs from VIDEO_STREAM_INFORMATION, which provides static configuration data (like the URI).

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

While ArduPilot supports sending static stream configuration via VIDEO_STREAM_INFORMATION (269), it does not currently monitor or report the real-time performance statistics (bandwidth usage, dropped frames) of the video link.

Intended Data Fields (Standard)

• stream_id: Video Stream ID (1-based).
• flags: Status flags (VIDEO_STREAM_STATUS_FLAGS) indicating if the stream is running, thermal, etc.
• framerate: Frame rate (Hz).
• resolution_h: Horizontal resolution (pix).
• resolution_v: Vertical resolution (pix).
• bitrate: Bit rate (bits/s).
• rotation: Video image rotation (deg).
• hfov: Horizontal Field of View (deg).

Theoretical Use Cases

1. Adaptive Streaming:
   • Scenario: The radio link quality drops.
   • Action: The camera reports a reduced bitrate via VIDEO_STREAM_STATUS. The GCS sees this and automatically downgrades the video player quality to match, preventing buffering or lag.
2. Diagnostics:
   • Scenario: The video feed is black.
   • Action: The GCS checks VIDEO_STREAM_STATUS. If framerate is 0, it knows the camera sensor has failed. If framerate is 30 but the image is black, it might be a lens cap or exposure issue.

Summary

The CAMERA_FOV_STATUS message reports the geospatial projection of the camera's view. Specifically, it provides the 3D coordinates of the camera itself, the 3D coordinates of the "Point of Interest" (where the center of the image hits the ground), and the camera's absolute orientation in quaternion format. This is critical for applications like Augmented Reality (AR) overlays or "Click to Fly" map interfaces.

Status

Supported

Directionality

• TX (Transmit): Camera-enabled vehicles (Reports geospatial view)
• RX (Receive): None

Transmission (TX)

The message is generated by the AP_Camera library, leveraging the AP_Mount library to perform the necessary 3D math (ray-tracing).

Core Logic

The implementation is in AP_Camera_Backend::send_camera_fov_status within libraries/AP_Camera/AP_Camera_Backend.cpp:295.

1. POI Calculation: It calls mount->get_poi() to calculate the intersection of the camera's optical axis with the terrain (or home altitude).
2. Attitude: It combines the gimbal's attitude (relative to the body) with the vehicle's AHRS yaw to produce an Earth-Frame Quaternion (quat_ef).
3. Fallback: If the POI cannot be calculated (e.g., the camera is looking above the horizon), it sends the camera's location but marks the POI coordinates as INT32_MAX.

Data Fields

• time_boot_ms: Timestamp (milliseconds since system boot).
• lat_camera: Latitude of camera (deg * 1E7).
• lon_camera: Longitude of camera (deg * 1E7).
• alt_camera: Altitude of camera (meters * 1000).
• lat_image: Latitude of center of image (deg * 1E7).
• lon_image: Longitude of center of image (deg * 1E7).
• alt_image: Altitude of center of image (meters * 1000).
• q: Quaternion of camera orientation (w, x, y, z).
• hfov: Horizontal field of view (deg).
• vfov: Vertical field of view (deg).

Practical Use Cases

1. Map Projection:
   • Scenario: A user is looking at the 2D map on the GCS.
   • Action: The GCS draws a "View Cone" polygon on the map, showing exactly what the drone's camera can see on the ground.
2. Target Geolocation:
   • Scenario: Search and Rescue. The pilot spots a missing person on the video feed.
   • Action: The GCS reads lat_image / lon_image to instantly provide the GPS coordinates of the person, without needing to be directly overhead.

Key Codebase Locations

• libraries/AP_Camera/AP_Camera_Backend.cpp:295: Implementation of the math and sending logic.

Summary

The CAMERA_TRACKING_IMAGE_STATUS message is designed to report the status of an on-camera object tracking system, specifically using image coordinates (pixel space). It reports the location of the tracked point or rectangle within the video frame.

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

While ArduPilot supports sending tracking commands to a camera (e.g., MAV_CMD_CAMERA_TRACK_POINT), it does not currently have a mechanism to relay the high-frequency status of that tracking (the bounding box location) back to the GCS via this MAVLink message.

Intended Data Fields (Standard)

• tracking_status: Current status (CAMERA_TRACKING_STATUS_FLAGS).
• tracking_mode: Current mode (CAMERA_TRACKING_MODE).
• target_data: Generic data.
• point_x, point_y: Point location in image (0..1).
• radius: Radius of tracked object.
• rec_top_x, rec_top_y: Bounding box top-left.
• rec_bottom_x, rec_bottom_y: Bounding box bottom-right.

Theoretical Use Cases

1. Visual Confirmation:
   • Scenario: A user taps a car on the screen to track it.
   • Action: The camera reports the rec_top_x / rec_bottom_y of the object it has locked onto. The GCS draws a green rectangle around the car, confirming to the user that the "lock" command was successful and the camera is tracking the correct object.
2. Target Loss Warning:
   • Scenario: The tracked object moves behind a tree.
   • Action: The message stops arriving or reports a "Lost" status. The GCS alerts the pilot to manually intervene.

Summary

The CAMERA_TRACKING_GEO_STATUS message is designed to report the status of an on-camera object tracking system, specifically using geospatial coordinates (Latitude/Longitude). Unlike CAMERA_FOV_STATUS, which reports where the center of the image is looking, this message reports the location of the specific object being tracked (e.g., a car or person).

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

While ArduPilot can calculate the camera's center-of-view intersection with the ground (CAMERA_FOV_STATUS), it does not currently support relaying specific object-tracking telemetry from smart cameras back to the GCS via this MAVLink message.

Intended Data Fields (Standard)

• tracking_status: Current status (CAMERA_TRACKING_STATUS_FLAGS).
• tracking_mode: Current mode (CAMERA_TRACKING_MODE).
• lat, lon, alt: Location of the tracked object.
• h_acc, v_acc: Accuracy/Uncertainty of the location.
• vel_n, vel_e, vel_d: Velocity of the tracked object.
• vel_acc: Velocity accuracy.
• dist: Distance to the tracked object.
• hdg: Heading of the tracked object.

Theoretical Use Cases

1. Target Speed Estimation:
   • Scenario: Following a suspect vehicle.
   • Action: The camera uses optical flow and rangefinding to calculate the vehicle's speed (vel_n, vel_e). The GCS displays this speed to the operator.
2. Coordinate Handover:
   • Scenario: A surveillance drone spots a target.
   • Action: It broadcasts CAMERA_TRACKING_GEO_STATUS with the target's lat/lon. A second "interceptor" drone receives this location and automatically navigates to intercept the target.

Summary

The CAMERA_THERMAL_RANGE message reports the temperature statistics from a thermal camera. Specifically, it provides the maximum and minimum temperatures currently detected in the frame, along with the pixel coordinates of those hot/cold spots. This is essential for industrial inspections (e.g., finding hot spots on solar panels) or search and rescue (finding a heat signature in a cold environment).

Status

Supported

Directionality

• TX (Transmit): Thermal Camera-enabled vehicles (Reports temp stats to GCS)
• RX (Receive): None

Transmission (TX)

The message is currently implemented for specific thermal gimbals via the AP_Mount library.

Core Logic

The implementation example can be found in AP_Mount_Siyi::send_camera_thermal_range within libraries/AP_Mount/AP_Mount_Siyi.cpp:1127.

1. Driver Support: Currently supported by the Siyi ZT6 and Siyi ZT30 gimbals.
2. Data Retrieval: The driver requests temperature data from the gimbal (via Siyi SDK) at 5Hz.
3. Timeout: If fresh data hasn't been received in 3 seconds (AP_MOUNT_SIYI_THERM_TIMEOUT_MS), it transmits NaN to indicate invalid data.

Data Fields

• time_boot_ms: Timestamp (milliseconds since system boot).
• stream_id: Video Stream ID (1 for first, 2 for second, etc).
• camera_id: Camera ID (1 for first, 2 for second, etc).
• max: Temperature max (degC).
• max_point_x: Temperature max point x (normalized 0..1).
• max_point_y: Temperature max point y (normalized 0..1).
• min: Temperature min (degC).
• min_point_x: Temperature min point x (normalized 0..1).
• min_point_y: Temperature min point y (normalized 0..1).

Practical Use Cases

1. Solar Inspection:
   • Scenario: A drone scans a solar farm.
   • Action: The GCS monitors the max field. If it spikes above 70°C, it flags the location and highlights the max_point_x/y on the video feed to show the defective cell.
2. Firefighting:
   • Scenario: Mapping a forest fire line.
   • Action: The max temperature confirms active combustion, while min helps calibrate the color palette of the display.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount_Siyi.cpp:1127: Siyi implementation.

Summary

The GIMBAL_MANAGER_INFORMATION message is a cornerstone of the MAVLink Gimbal Protocol v2. It allows the Autopilot (acting as the Gimbal Manager) to advertise its high-level capabilities and configuration to the Ground Control Station (GCS). This includes supported axes, lock/follow modes, and physical angular limits.

Status

Supported

Directionality

• TX (Transmit): Gimbal-enabled vehicles (Reports capabilities to GCS)
• RX (Receive): None

Transmission (TX)

The message is handled by the AP_Mount library, which aggregates the capabilities of the underlying driver.

Core Logic

The implementation is in AP_Mount_Backend::send_gimbal_manager_information within libraries/AP_Mount/AP_Mount_Backend.cpp:242.

It populates the cap_flags bitmask via get_gimbal_manager_capability_flags() (Line 208), which checks the configured MNT_ parameters to see if Roll, Pitch, or Yaw control is enabled (has_roll_control, etc.).

Data Fields

• time_boot_ms: Timestamp (ms since boot).
• cap_flags: Bitmap of capabilities (GIMBAL_MANAGER_CAP_FLAGS).
  • Modes: HAS_RETRACT, HAS_NEUTRAL, HAS_RC_INPUTS.
  • Pointing: CAN_POINT_LOCATION_LOCAL, CAN_POINT_LOCATION_GLOBAL.
  • Axes: HAS_ROLL_AXIS, HAS_PITCH_AXIS, HAS_YAW_AXIS.
  • Behaviors: HAS_ROLL_LOCK/FOLLOW, HAS_PITCH_LOCK/FOLLOW, HAS_YAW_LOCK/FOLLOW.
• gimbal_device_id: Component ID of the gimbal device (usually 1).
• roll_min / roll_max: Physical limits in radians.
• pitch_min / pitch_max: Physical limits in radians.
• yaw_min / yaw_max: Physical limits in radians.

Practical Use Cases

1. UI Configuration:
   • Scenario: A GCS connects to a drone with a 2-axis gimbal (Pitch/Yaw only).
   • Action: The GCS reads this message, sees HAS_ROLL_AXIS is missing, and automatically hides the Roll control slider to declutter the interface.
2. Safety Limits:
   • Scenario: A user tries to command the gimbal to look straight up (+90 deg pitch).
   • Action: The GCS checks pitch_max (e.g., +45 deg) and clamps the command before sending it, preventing mechanical strain or frame collisions.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount_Backend.cpp:242: Implementation of the sender.

Summary

The GIMBAL_MANAGER_STATUS message is a key component of the MAVLink Gimbal Protocol v2. It reports the current status of the gimbal manager, specifically which high-level flags are active (e.g., Lock vs Follow) and, most importantly, which MAVLink component currently has primary control over the gimbal.

Status

Supported

Directionality

• TX (Transmit): Gimbal-enabled vehicles (Reports status to GCS)
• RX (Receive): None

Transmission (TX)

The message is handled by the AP_Mount library to reflect the internal state of the arbitration logic.

Core Logic

The implementation is in AP_Mount_Backend::send_gimbal_manager_status within libraries/AP_Mount/AP_Mount_Backend.cpp:257.

It provides two critical pieces of information:

1. Arbitration: It reports primary_control_sysid and primary_control_compid. This tells all listeners "Who is driving right now?" (e.g., The Mission Planner GCS, a Companion Computer, or the RC Controller).
2. Flags: It reports the active state of the gimbal axes (e.g., GIMBAL_MANAGER_FLAGS_YAW_LOCK vs Follow).

Data Fields

• time_boot_ms: Timestamp (milliseconds since system boot).
• flags: High level gimbal manager flags (bitmap).
• gimbal_device_id: Gimbal device ID.
• primary_control_sysid: Primary control system ID.
• primary_control_compid: Primary control component ID.
• secondary_control_sysid: Secondary control system ID.
• secondary_control_compid: Secondary control component ID.

Practical Use Cases

1. Multi-Operator Handover:
   • Scenario: A pilot is flying via RC ([sysid](/field-manual/advanced-tuning/system-identification-mode.html)=1, compid=1), but a Payload Operator wants to take control via a joystick on a second GCS (sysid=255, compid=190).
   • Action: The GCS sends a MAV_CMD_DO_GIMBAL_MANAGER_CONFIGURE to request control. The Autopilot accepts this and updates GIMBAL_MANAGER_STATUS to show primary_control_sysid=255. The Pilot's UI updates to show "Payload Operator has control".
2. Mode Verification:
   • Scenario: The user switches from "Follow Mode" to "Lock Mode".
   • Action: The GCS monitors flags to verify that GIMBAL_MANAGER_FLAGS_YAW_LOCK becomes active.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount_Backend.cpp:257: Implementation of the sender.

Summary

The GIMBAL_MANAGER_SET_ATTITUDE message is the primary command for controlling a gimbal in the MAVLink Gimbal Protocol v2. It allows a Ground Control Station or Companion Computer to command the gimbal to a specific orientation (using Quaternions) or to a specific rotation rate (using Angular Velocity), while also managing high-level states like Retract and Neutral.

Status

Supported

Directionality

• TX (Transmit): None
• RX (Receive): Autopilot (Controls the gimbal)

Reception (RX)

The message is handled by the AP_Mount library, which translates the MAVLink command into internal driver calls.

Core Logic

The implementation is in AP_Mount::handle_gimbal_manager_set_attitude within libraries/AP_Mount/AP_Mount.cpp:419.

1. Target Selection: Uses gimbal_device_id to select the correct gimbal instance.
2. Mode Overrides:
   • If GIMBAL_MANAGER_FLAGS_RETRACT is set, it calls backend->[set_mode](/field-manual/mavlink-interface/set-mode.html)(MAV_MOUNT_MODE_RETRACT).
   • If GIMBAL_MANAGER_FLAGS_NEUTRAL is set, it calls backend->set_mode(MAV_MOUNT_MODE_NEUTRAL).
3. Mutual Exclusion: It explicitly checks that you are not providing both a Quaternion q AND Angular Velocities angular_velocity_x/y/z simultaneously. If both are valid numbers (not NaN), the command is ignored.
4. Attitude Control:
   • Converts the Quaternion q into Euler angles (Roll, Pitch, Yaw).
   • Calls set_angle_target with the resulting degrees.
   • If GIMBAL_MANAGER_FLAGS_YAW_LOCK is set, the Yaw is interpreted as Earth-Frame (North = 0). Otherwise, it is Body-Frame.
5. Rate Control:
   • Converts angular_velocity_x/y/z (rad/s) into deg/s.
   • Calls set_rate_target.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• flags: High level gimbal manager flags (bitmap).
• gimbal_device_id: Component ID of gimbal device to address.
• q: Quaternion components, w, x, y, z (1 0 0 0 is the null-rotation). Set fields to NaN if only angular velocity should be used.
• angular_velocity_x: X angular velocity (rad/s). NaN if only attitude should be used.
• angular_velocity_y: Y angular velocity (rad/s). NaN if only attitude should be used.
• angular_velocity_z: Z angular velocity (rad/s). NaN if only attitude should be used.

Practical Use Cases

1. Look at Coordinate:
   • Scenario: A companion computer wants the camera to look at a specific GPS location.
   • Action: The companion computer calculates the required Earth-Frame Quaternion to point at the target and sends this message with GIMBAL_MANAGER_FLAGS_YAW_LOCK set.
2. Joystick Control:
   • Scenario: A pilot is manually controlling the gimbal using a joystick knob.
   • Action: The GCS maps the joystick position to an angular velocity (e.g., +0.5 rad/s) and streams this message to smoothly pan the camera.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount.cpp:419: Implementation of the handler.

Summary

The GIMBAL_DEVICE_INFORMATION message provides static configuration data about a specific gimbal device, such as its vendor name, model name, firmware version, and physical angular limits. In the MAVLink Gimbal Protocol v2 architecture, this message is typically emitted by the Gimbal Device (the physical hardware) and consumed by the Gimbal Manager (the Autopilot).

Status

RX Only

Directionality

• TX (Transmit): None (ArduPilot typically does not generate this message).
• RX (Receive): Autopilot (Receives from MAVLink Gimbals like Gremsy).

Reception (RX)

ArduPilot listens for this message to auto-configure its internal gimbal limits.

Core Logic

The handler is implemented in AP_Mount_Gremsy::handle_gimbal_device_information within libraries/AP_Mount/AP_Mount_Gremsy.cpp:181.

1. Discovery: When a MAVLink gimbal connects, ArduPilot requests this message.
2. Configuration: It extracts roll_min, roll_max, pitch_min, pitch_max, etc., and updates the internal AP_Mount parameters.
3. Propagation: These limits are then re-packaged and sent to the GCS via the GIMBAL_MANAGER_INFORMATION message.

Data Fields

• time_boot_ms: Timestamp (milliseconds since system boot).
• vendor_name: Name of the gimbal vendor.
• model_name: Name of the gimbal model.
• custom_name: Custom name of the gimbal given to it by the user.
• firmware_version: Version of the gimbal firmware, encoded as: (Dev & 0xff) << 24 | (Patch & 0xff) << 16 | (Minor & 0xff) << 8 | (Major & 0xff).
• hardware_version: Version of the gimbal hardware, encoded as: (Dev & 0xff) << 24 | (Patch & 0xff) << 16 | (Minor & 0xff) << 8 | (Major & 0xff).
• uid: UID of gimbal device (or 0 if not known).
• cap_flags: Bitmap of gimbal capability flags.
• custom_cap_flags: Bitmap of custom gimbal capability flags.
• roll_min: Minimum hardware roll angle (positive: rolling to the right, negative: rolling to the left).
• roll_max: Maximum hardware roll angle (positive: rolling to the right, negative: rolling to the left).
• pitch_min: Minimum hardware pitch angle (positive: up, negative: down).
• pitch_max: Maximum hardware pitch angle (positive: up, negative: down).
• yaw_min: Minimum hardware yaw angle (positive: to the right, negative: to the left).
• yaw_max: Maximum hardware yaw angle (positive: to the right, negative: to the left).

Practical Use Cases

1. Plug-and-Play Configuration:
   • Scenario: A user swaps a Gremsy T3 for a Gremsy Mio.
   • Action: The Autopilot receives GIMBAL_DEVICE_INFORMATION from the new gimbal, sees different physical limits, and automatically updates its internal safety constraints without user intervention.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount_Gremsy.cpp:181: Implementation of the handler.

Summary

The GIMBAL_DEVICE_SET_ATTITUDE message is the low-level command used by the Gimbal Manager (Autopilot) to control the Gimbal Device (Physical Hardware). It is essentially the "driver-level" equivalent of GIMBAL_MANAGER_SET_ATTITUDE.

Status

Supported

Directionality

• TX (Transmit): Autopilot (Commands the Gimbal Device)
• RX (Receive): None (ArduPilot does not obey this command from GCS; it is the sender)

Transmission (TX)

ArduPilot uses this message to drive MAVLink-capable gimbals, such as those from Gremsy.

Core Logic

The implementation is in AP_Mount_Gremsy::send_gimbal_device_set_attitude within libraries/AP_Mount/AP_Mount_Gremsy.cpp:311.

1. Attitude Control:
   • Converts internal target Euler angles (Roll/Pitch/Yaw) into a Quaternion q.
   • Sets angular_velocity_x/y/z to NaN.
   • Sets flags (e.g., GIMBAL_DEVICE_FLAGS_YAW_LOCK) to indicate if the target is Earth-Frame or Body-Frame.
2. Rate Control:
   • Sets q to {NaN, NaN, NaN, NaN}.
   • Populates angular_velocity_x/y/z with the target rates in rad/s.
3. Retract:
   • Sets flags to GIMBAL_DEVICE_FLAGS_RETRACT.
   • Sets all control values to 0 or NaN.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• flags: Low level gimbal flags (bitmap).
• q: Quaternion components, w, x, y, z (1 0 0 0 is the null-rotation). Set fields to NaN if only angular velocity should be used.
• angular_velocity_x: X angular velocity (rad/s). NaN if only attitude should be used.
• angular_velocity_y: Y angular velocity (rad/s). NaN if only attitude should be used.
• angular_velocity_z: Z angular velocity (rad/s). NaN if only attitude should be used.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount_Gremsy.cpp:311: Implementation of the sender.

Summary

The GIMBAL_DEVICE_ATTITUDE_STATUS message is the primary telemetry packet for the Gimbal Device (physical hardware). It reports the low-level status of the gimbal, including its current orientation (quaternion), angular velocity, and hardware fault flags.

Status

Supported (TX & RX)

Directionality

• TX (Transmit): Autopilot -> GCS (Reports the status of attached gimbals).
• RX (Receive): Gimbal Device -> Autopilot (Reports hardware status to the manager).

Dual Role Implementation

ArduPilot supports this message in two distinct roles, acting as a bridge between the hardware and the GCS.

1. Reception (RX) - Consuming Hardware Data

The implementation is in AP_Mount_Gremsy::handle_gimbal_device_attitude_status within libraries/AP_Mount/AP_Mount_Gremsy.cpp:223.

• ArduPilot listens for this message from connected MAVLink gimbals (e.g., Gremsy).
• It caches the latest attitude quaternion q and failure_flags.
• This data is used to update the internal state of the AP_Mount backend.

2. Transmission (TX) - Reporting to GCS

The implementation is in AP_Mount_Backend::send_gimbal_device_attitude_status within libraries/AP_Mount/AP_Mount_Backend.cpp:175.

• ArduPilot acts as a "Virtual Gimbal Device" towards the GCS.
• It sends this message to the GCS, populated with either:
  • The cached data from the physical MAVLink gimbal (proxying).
  • The calculated attitude of a PWM/Servo gimbal (synthesized).
• This ensures the GCS receives a standard GIMBAL_DEVICE_ATTITUDE_STATUS regardless of the underlying hardware protocol.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• time_boot_ms: Timestamp (milliseconds since system boot).
• flags: Current gimbal device flags (bitmap).
• q: Quaternion components, w, x, y, z (1 0 0 0 is the null-rotation).
• angular_velocity_x: X angular velocity (rad/s).
• angular_velocity_y: Y angular velocity (rad/s).
• angular_velocity_z: Z angular velocity (rad/s).
• failure_flags: Failure flags (bitmap).
• delta_yaw: Yaw angle delta (rad).
• delta_yaw_velocity: Yaw angular velocity delta (rad/s).
• gimbal_device_id: Gimbal device ID.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount_Backend.cpp:175: TX Implementation.
• libraries/AP_Mount/AP_Mount_Gremsy.cpp:223: RX Implementation.

Summary

The AUTOPILOT_STATE_FOR_GIMBAL_DEVICE message provides the vehicle's high-fidelity state estimation (Attitude, Velocity, Yaw Rate) directly to a connected Gimbal Device. This allows "Smart Gimbals" (like the Gremsy T3V3) to fuse the autopilot's robust AHRS solution with their own internal IMU data, resulting in superior horizon holding and drift correction compared to using the gimbal's IMU alone.

Status

Supported

Directionality

• TX (Transmit): Autopilot (Broadcasts state to Gimbal)
• RX (Receive): None (Gimbal Device consumes this)

Transmission (TX)

The message is generated by the core GCS_MAVLINK library, drawing data from the AHRS (Attitude and Heading Reference System).

Core Logic

The implementation is in GCS_MAVLINK::send_autopilot_state_for_gimbal_device within libraries/GCS_MAVLink/GCS_Common.cpp:5989.

It is typically streamed at a high rate (e.g., 50Hz) to the gimbal over a private UART link.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• time_boot_us: Timestamp (microseconds since UNIX epoch or microseconds since system boot).
• q: Quaternion components of autopilot attitude: w, x, y, z (1 0 0 0 is the null-rotation).
• q_estimated_delay_us: Estimated delay of the attitude data.
• vx: X Speed in NED (m/s).
• vy: Y Speed in NED (m/s).
• vz: Z Speed in NED (m/s).
• v_estimated_delay_us: Estimated delay of the speed data.
• feed_forward_angular_velocity_z: Feed forward Z angular velocity (rad/s).
• estimator_status: Bitmap indicating the status of the estimator (AHRS).
• landed_state: The landed state. Is set to MAV_LANDED_STATE_UNDEFINED if landed state is unknown.
• angular_velocity_z: Z component of angular velocity in NED (rad/s).

Practical Use Cases

1. Horizon Drift Correction:
   • Scenario: A drone is flying a long, straight mapping line.
   • Action: The gimbal uses the autopilot's q (which is corrected by GPS/Compass) to correct the slow drift of its own internal MEMS gyros, ensuring the camera remains perfectly level.
2. Cornering Compensation:
   • Scenario: The drone executes a sharp turn.
   • Action: The gimbal uses angular_velocity_z and vx/vy to anticipate the centripetal acceleration, pre-actuating the motors to keep the image stable.

Key Codebase Locations

• libraries/GCS_MAVLink/GCS_Common.cpp:5989: Implementation of the sender.

Summary

The GIMBAL_MANAGER_SET_PITCHYAW message is a high-level command for controlling a gimbal. Unlike GIMBAL_MANAGER_SET_ATTITUDE, which requires a full Quaternion, this message uses simple Euler angles (Pitch/Yaw) or angular rates. It is designed for typical "Point and Shoot" or "Pan/Tilt" operations where Roll control is not required (the gimbal is expected to keep the horizon level).

Status

Supported

Directionality

• TX (Transmit): None
• RX (Receive): Autopilot (Controls the gimbal)

Reception (RX)

The message is handled by the AP_Mount library.

Core Logic

The implementation is in AP_Mount::handle_gimbal_manager_set_pitchyaw within libraries/AP_Mount/AP_Mount.cpp:484.

1. Target Selection: Uses gimbal_device_id to select the gimbal instance.
2. Mode Overrides: Checks GIMBAL_MANAGER_FLAGS_RETRACT and GIMBAL_MANAGER_FLAGS_NEUTRAL.
3. Mutual Exclusion: It enforces that you cannot set both absolute angles (pitch/yaw) AND rates (pitch_rate/yaw_rate) in the same message.
4. Control:
   • Angles: If pitch and yaw are valid (not NaN), it converts them from Radians to Degrees and calls set_angle_target. Roll is hardcoded to 0.
   • Rates: If pitch_rate and yaw_rate are valid, it converts them from Rad/s to Deg/s and calls set_rate_target.
   • Yaw Lock: If GIMBAL_MANAGER_FLAGS_YAW_LOCK is set, Yaw is treated as Earth-Frame (North=0). Otherwise, it is Body-Frame.

Data Fields

• target_system: System ID.
• target_component: Component ID.
• flags: High level gimbal manager flags (bitmap).
• gimbal_device_id: Component ID of gimbal device to address.
• pitch: Pitch angle (rad).
• yaw: Yaw angle (rad).
• pitch_rate: Pitch angular rate (rad/s).
• yaw_rate: Yaw angular rate (rad/s).

Practical Use Cases

1. Object Tracking:
   • Scenario: A companion computer is running vision tracking.
   • Action: The computer calculates the required Pitch and Yaw error to center the target and sends this message with pitch_rate and yaw_rate to close the loop.
2. Simple Pointing:
   • Scenario: A user clicks "Look North" on the map.
   • Action: The GCS sends pitch=0 and yaw=0 (North) with YAW_LOCK set.

Key Codebase Locations

• libraries/AP_Mount/AP_Mount.cpp:484: Implementation of the handler.

Summary

The GIMBAL_MANAGER_SET_MANUAL_CONTROL message provides a mechanism for direct "stick input" control of a gimbal. It accepts normalized values (-1.0 to 1.0) for pitch, yaw, and zoom, mimicking the raw inputs from an RC controller or joystick.

Status

Unsupported

Directionality

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

Description

ArduPilot does not implement this message.

For manual gimbal control via MAVLink, ArduPilot typically uses:

1. GIMBAL_MANAGER_SET_PITCHYAW (287): sending angular rates (rad/s) which can be mapped from joystick axes.
2. RC_CHANNELS_OVERRIDE (70): overriding the specific RC channels mapped to the gimbal functions.

Intended Data Fields (Standard)

• target_system / target_component: Targeted component.
• flags: Bitmap (GIMBAL_MANAGER_FLAGS).
• gimbal_device_id: Component ID of the gimbal.
• pitch: Normalized pitch input (-1..1).
• yaw: Normalized yaw input (-1..1).
• pitch_rate: Normalized pitch rate input (-1..1).
• yaw_rate: Normalized yaw rate input (-1..1).
• zoom: Normalized zoom input (-1..1).

Theoretical Use Cases

1. Standardized Joystick Mapping:
   • Scenario: A GCS wants to support a generic USB gamepad for gimbal control.
   • Action: Instead of needing to know specific RC channel mappings (e.g., "Channel 6 is tilt"), the GCS simply sends GIMBAL_MANAGER_SET_MANUAL_CONTROL with pitch = joystick.y. This abstracts the radio configuration from the user interface.
2. Smooth Zooming:
   • Scenario: A variable-speed zoom rocker on a smart controller.
   • Action: The controller sends zoom = 0.5 (half speed in) or zoom = -1.0 (full speed out), allowing precise lens control without needing complex rate calculations.

Summary

The WINCH_STATUS message reports the telemetry from an onboard winch system (e.g., used for delivery or retrieval). It allows the GCS to display line length, tension, and operational state.

Status

Supported

Directionality

• TX (Transmit): Autopilot (Reports winch status to GCS)
• RX (Receive): None

Transmission (TX)

The message is generated by the AP_Winch library. Support varies by backend.

Core Logic

The implementation example is in AP_Winch_Daiwa::send_status within libraries/AP_Winch/AP_Winch_Daiwa.cpp:77.

• Daiwa Winch: Reports full telemetry including tension, voltage, current, and clutch status.
• PWM Winch: Reports estimated line length and desired speed (as it lacks feedback).

Data Fields

• time_usec: Timestamp (microseconds since UNIX epoch or microseconds since system boot).
• line_length: Length of the line released.
• speed: Speed of the line release.
• tension: Tension on the line.
• voltage: Voltage of the battery supplying the winch.
• current: Current draw from the winch.
• temperature: Temperature of the motor.
• status: Status flags.

Practical Use Cases

1. Package Delivery:
   • Scenario: A drone hovers to lower a package.
   • Action: The winch lowers the line. The GCS monitors line_length. When the package touches the ground, tension drops, allowing the GCS (or Lua script) to trigger the release mechanism.

Key Codebase Locations

• libraries/AP_Winch/AP_Winch_Daiwa.cpp:77: Implementation of the sender.