The camera protocol is used to configure camera payloads and request their status. It supports photo capture, and video capture and streaming. It also includes messages to query and configure the onboard camera storage.
The Dronecode Camera Manager provides an implementation of this protocol.
We are transitioning from specific request commands to a single generic requestor. GCS and MAVLink SDKs/apps should support both approaches as we migrate to exclusive use of the new method (documented here). For more information see Migration Notes for GCS & Camera Servers.
Camera components are expected to follow the Heartbeat/Connection Protocol and sent a constant flow of heartbeats (nominally at 1Hz). Each camera must use a different pre-defined camera component ID: MAV_COMP_ID_CAMERA to MAV_COMP_ID_CAMERA6.
The first time a heartbeat is detected from a new camera, a GCS (or other receiving system) should start the Camera Identification process.
If a receiving system stops receiving heartbeats from the camera it is assumed to be disconnected, and should be removed from the list of available cameras. If heartbeats are again detected, the camera identification process below must be restarted from the beginning.
Basic Camera Operations
The CAMERA_INFORMATION.flags provides information about camera capabilities. It contains a bitmap of CAMERA_CAP_FLAGS values that tell the GCS if the camera supports still image capture, video capture, or video streaming, and if it needs to be in a certain mode for capture, etc.
The camera identification operation identifies all the available cameras and determines their capabilities.
Camera identification must be carried out before all other operations!
The first time a heartbeat is received from a new camera component, the GCS will send it a MAV_CMD_REQUEST_MESSAGE message asking for CAMERA_INFORMATION (message id 259). The camera will then respond with the a COMMAND_ACK message containing a result. On success (result is MAV_RESULT_ACCEPTED) the camera component must then send a CAMERA_INFORMATION message.
The operation follows the normal Command Protocol rules for command/acknowledgment (if no
COMMAND_ACK response is received for
MAV_CMD_REQUEST_MESSAGE the command will be re-sent a number of times before failing). If
CAMERA_INFORMATION is not received after receiving an ACK with
MAV_RESULT_ACCEPTED, the protocol assumes the message was lost, and the cycle of sending
MAV_CMD_REQUEST_MESSAGE is repeated. If
CAMERA_INFORMATION is still not received after three cycle repeats, the GCS may assume that the camera is not supported.
CAMERA_INFORMATION response contains the bare minimum information about the camera and what it can or cannot do. This is sufficient for basic image and/or video capture.
If a camera provides finer control over its settings
CAMERA_INFORMATION.cam_definition_uri will include a URI to a Camera Definition File. If this URI exists, the GCS will request it, parse it and prepare the UI for the user to control the camera settings.
A GCS that implements this protocol is expected to support both HTTP (
http://) and MAVLink FTP (
mftp://) URIs for download of the camera definition file. If the camera provides an HTTP or MAVLink FTP interface, the definition file can be hosted on the camera itself. Otherwise, it can be hosted anywhere (on any reachable server).
CAMERA_INFORMATION.cam_definition_version field should provide a version for the definition file, allowing the GCS to cache it. Once downloaded, it would only be requested again if the version number changes.
If a vehicle has more than one camera, each camera will have a different component ID and send its own heartbeat. The GCS should create multiple instances of a camera controller based on the component ID of each camera. All commands are sent to a specific camera by addressing the command to a specific component ID.
Some cameras must be in a certain mode for still and/or video capture.
The GCS can determine if it needs to make sure the camera is in the proper mode prior to sending a start capture (image or video) command by checking whether the CAMERA_CAP_FLAGS_HAS_MODES bit is set true in CAMERA_INFORMATION.flags.
In addition, some cameras can capture images in any mode but with different resolutions. For example, a 20 megapixel camera would take a full resolution image when set to
CAMERA_MODE_IMAGE but only at the current video resolution if it is set to
To get the current mode, the GCS would send a MAV_CMD_REQUEST_MESSAGE command asking for CAMERA_SETTINGS. The camera component will then respond with the COMMAND_ACK message containing a result. On success (
COMMAND_ACK.result is MAV_RESULT_ACCEPTED) the camera must then send a CAMERA_SETTINGS message. The current mode is the
The sequence is shown below:
Command acknowledgment and message resending is handled in the same way as for camera identification (if a successful ACK is received the camera will expect the
CAMERA_SETTINGSmessage, and repeat the cycle - up to 3 times - until it is received).
To set the camera to a specific mode, the GCS would send the MAV_CMD_SET_CAMERA_MODE command with the appropriate mode.
The sequence is shown below:
The operation follows the normal Command Protocol rules for command/acknowledgment.
Before capturing images and/or videos, a GCS should query the storage status to determine if the camera has enough free space for these operations (and provide the user with feedback as to the current storage status). The GCS will send the MAV_CMD_REQUEST_MESSAGE command and it expects a COMMAND_ACK message back as well as a STORAGE_INFORMATION response. For formatting (or erasing depending on your implementation), the GCS will send a MAV_CMD_STORAGE_FORMAT command.
Camera Capture Status
In addition to querying about storage status, the GCS will also request the current Camera Capture Status in order to provide the user with proper UI indicators. The GCS will send a MAV_CMD_REQUEST_MESSAGE command asking for [CAMERA_CAPTURE_STATUS] and it expects a COMMAND_ACK message back as well as a CAMERA_CAPTURE_STATUS response.
Still Image Capture
A camera supports still image capture if the CAMERA_CAP_FLAGS_CAPTURE_IMAGE bit is set in CAMERA_INFORMATION.flags.
A GCS/MAVLink app uses the MAV_CMD_IMAGE_START_CAPTURE command to request that the camera capture a specified number of images (or forever), and the duration between them. The camera immediately returns the normal command acknowledgment (MAV_RESULT).
Each time an image is captured, the camera broadcasts a CAMERA_IMAGE_CAPTURED message. This message not only tells the GCS the image was captured, it is also intended for geo-tagging.
The camera must iterate
CAMERA_IMAGE_CAPTURED.image_indexand the counter used in
CAMERA_CAPTURE_STATUS.image_countfor every new image capture (these values iterate until explicitly cleared using MAV_CMD_STORAGE_FORMAT). The index and total image count can be used to re-request missing images (e.g. images captured when the vehicle was out of telemetry range).
The MAV_CMD_IMAGE_STOP_CAPTURE command can optionally be sent to stop an image capture sequence (this is needed if image capture has been set to continue forever).
The still image capture message sequence for missions (as described above) is shown below:
The message sequence for interactive user-initiated image capture through a GUI is slightly different. In this case the GCS should:
- Confirm that the camera is ready to take images before allowing the user to request image capture.
- It does this by by sending MAV_CMD_REQUEST_MESSAGE asking for CAMERA_CAPTURE_STATUS.
- The camera should return a
MAV_RESULTand then CAMERA_CAPTURE_STATUS.
- The GCS should check that the status is "Idle" before enabling camera capture in the GUI.
- Send MAV_CMD_IMAGE_START_CAPTURE specifying a single image (only).
The sequence is as shown below:
Request Lost CAMERA_IMAGE_CAPTURED Messages
The camera broadcasts a CAMERA_IMAGE_CAPTURED every time a new image is captured, iterating both the current image index (
CAMERA_IMAGE_CAPTURED.image_index) and the total image count (
These messages can be lost during transmission; for example if the vehicle is out of data-link range of the ground stations.
Lost image capture messages can be detected by comparing GCS and camera image counts. Individual entries can be requested using MAV_CMD_REQUEST_MESSAGE, where
param2="the index of the missing image".
The camera image log iterates "forever" (but may be explicitly reset using MAV_CMD_STORAGE_FORMAT.param3=1).
A camera supports video capture if the CAMERA_CAP_FLAGS_CAPTURE_VIDEO bit is set in CAMERA_INFORMATION.flags.
To start recording videos, the GCS uses the MAV_CMD_VIDEO_START_CAPTURE command. If requested, the CAMERA_CAPTURE_STATUS message is sent to the GCS at a set interval.
To stop recording, the GCS uses the MAV_CMD_VIDEO_STOP_CAPTURE command.
The GCS should already have identified all connected cameras by their heartbeat and followed the Camera Identification steps to get CAMERA_INFORMATION for every camera.
A camera is capable of streaming video if it sets the CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM bit set in CAMERA_INFORMATION.flags.
The sequence for requesting all video streams from a particular camera is shown below:
The steps are:
- GCS follows the Camera Identification steps to get CAMERA_INFORMATION for every camera.
- GCS checks if CAMERA_INFORMATION.flags contains the CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM flag.
- If so, the GCS sends the MAV_CMD_REQUEST_MESSAGE message to the camera requesting the video streaming configuration (
param1=269) for all streams (
param2=0). > Note A GCS can also request information for a particular stream by setting its id in
- Camera returns a VIDEO_STREAM_INFORMATION message for the specified stream or all streams it supports.
If your camera only provides video streaming and nothing else (no camera features), the CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM flag is the only flag you need to set. The GCS will then provide video streaming support and skip camera control.
Camera components that are powered from their own battery should publish BATTERY_STATUS messages.
Other components like a GCS will typically only use the camera
BATTERY_STATUS.battery_remaining field (or possibly
time_remaining); generally other fields can be set as "not supported".
|MAV_CMD_REQUEST_MESSAGE||Send command to request any message||to be used|
|CAMERA_INFORMATION||Basic information about camera including supported features and URI link to extended information (|
|CAMERA_SETTINGS||Timestamp and camera mode information.|
|MAV_CMD_SET_CAMERA_MODE||Send command to set CAMERA_MODE.|
|VIDEO_STREAM_INFORMATION||Information defining a video stream configuration. If a camera has more than one video stream, it would send one of this for each video stream, with their specific configuration. Each stream must have its own, unique |
|VIDEO_STREAM_STATUS||Information updating a video stream configuration.|
|STORAGE_INFORMATION||Storage information (e.g. number and type of storage devices, total/used/available capacity, read/write speeds).|
|MAV_CMD_STORAGE_FORMAT||Send command to format the specified storage device.|
|CAMERA_CAPTURE_STATUS||Camera capture status, including current capture type (if any), capture interval, available capacity.|
|MAV_CMD_IMAGE_START_CAPTURE||Send command to start image capture, specifying the duration between captures and total number of images to capture.|
|MAV_CMD_IMAGE_STOP_CAPTURE||Send command to stop image capture.|
|CAMERA_IMAGE_CAPTURED||Information about image captured (returned to GPS every time an image is captured).|
|MAV_CMD_VIDEO_START_CAPTURE||Send command to start video capture, specifying the frequency that CAMERA_CAPTURE_STATUS messages should be sent while recording.|
|MAV_CMD_VIDEO_STOP_CAPTURE||Send command to stop video capture.|
|MAV_CMD_VIDEO_START_STREAMING||Send command to start video streaming for the given Stream ID (|
|MAV_CMD_VIDEO_STOP_STREAMING||Send command to stop video streaming for the given Stream ID (|
|MAV_CMD_REQUEST_CAMERA_SETTINGS||Send command to request CAMERA_SETTINGS.||deprecated|
|MAV_CMD_REQUEST_CAMERA_INFORMATION||Send command to request CAMERA_INFORMATION.||deprecated|
|MAV_CMD_REQUEST_VIDEO_STREAM_INFORMATION||Send command to request VIDEO_STREAM_INFORMATION. This is sent once for each camera when a camera is detected and it has set the CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM flag within the CAMERA_INFORMATION message ||deprecated|
|MAV_CMD_REQUEST_VIDEO_STREAM_STATUS||Send command to request VIDEO_STREAM_STATUS. This is sent whenever there is a mode change (when MAV_CMD_SET_CAMERA_MODE is sent.) It allows the camera to update the stream configuration when a camera mode change occurs.||deprecated|
|MAV_CMD_REQUEST_STORAGE_INFORMATION||Send command to request STORAGE_INFORMATION.||deprecated|
|MAV_CMD_REQUEST_CAMERA_CAPTURE_STATUS||Send command to request CAMERA_CAPTURE_STATUS.||deprecated|
|CAMERA_CAP_FLAGS||Camera capability flags (Bitmap). For example: ability to capture images in video mode, support for survey mode etc. Received in CAMERA_INFORMATION.|
|CAMERA_MODE||Camera mode (image, video, survey etc.). Received in CAMERA_SETTINGS.|
|VIDEO_STREAM_TYPE||Type of stream - e.g. RTSP, MPEG. Received in VIDEO_STREAM_INFORMATION .|
|VIDEO_STREAM_STATUS_FLAGS||Bitmap of stream status flags - e.g. zoom, thermal imaging, etc. Received in VIDEO_STREAM_INFORMATION .|
Migration Notes for GCS & MAVLink SDKs
The original definition of this protocol used specific commands to query for each type of information requested from the camera: MAV_CMD_REQUEST_CAMERA_INFORMATION (for CAMERA_INFORMATION), MAV_CMD_REQUEST_CAMERA_SETTINGS, MAV_CMD_REQUEST_CAMERA_CAPTURE_STATUS, MAV_CMD_REQUEST_VIDEO_STREAM_INFORMATION, MAV_CMD_REQUEST_STORAGE_INFORMATION.
The latest version replaces all of these specific commands with the general requestor MAV_CMD_REQUEST_MESSAGE.
The transition works like this:
- Cameras need to handle both approaches for now (i.e. support both new generic and old specific commands).
- Ground stations will move from using the old specific commands to using both. They can try the new one and if they don't get an answer within a timeout they need to fall back to the previous command.
- After the new commands have been established in server and ground stations, the old specific commands may be removed from the implementations.