PX4 Guide (main)

English

中文 (Chinese)
한국어 (Korean)
Мови (Ukrainian)

English

中文 (Chinese)
한국어 (Korean)
Мови (Ukrainian)

Appearance

MAVLink Cameras (Camera Protocol v2) ​

This topic explains how to use PX4 with a MAVLink camera that implements the MAVLink Camera Protocol v2 with PX4 and a Ground Station.

TIP

This is the recommended way to integrate a camera with PX4!

Overview ​

The MAVLink Camera Protocol v2 allows querying of what features are supported by a camera, and provides commands to control image and video capture, stream video, set zoom and focus, select between infrared and visible light feeds, set where captured data is saved, and so on.

A camera may implement the protocol natively, but most MAVLink camera setups involve PX4 communicating with a camera manager running on a companion computer, which then interfaces between MAVLink and the camera's native protocol.

Generally speaking PX4's "integration" with a camera is to re-emit camera commands found in missions using the command protocol. Otherwise it may act as a bridge, forwarding commands between a ground station and the camera if there is no direct MAVLink channel.

INFO

PX4 does not support using MAVLink Camera Protocol v2 commands to control cameras that are attached to flight controller outputs. While this is technically possible, it would require PX4 to implement a camera manager interface.

Controlling the Camera ​

Cameras are discovered using the MAVLink connection protocol, based on their HEARTBEAT.type being set to MAV_TYPE_CAMERA.

TIP

Cameras should also use a component ID in the recommended range, such as MAV_COMP_ID_CAMERA, but generally this cannot be relied on to verify that a MAVLink component is a camera.

Once a camera is discovered its properties and capabilities can be queried by using MAV_CMD_REQUEST_MESSAGE to request the CAMERA_INFORMATION message, and then inspecting the flags field to determine what standard features in CAMERA_CAP_FLAGS are supported.

Based on the flags, you can determine what other commands and messages are supported by the camera. The full set of messages, commands, and enums are summarised here.

Additional parameters of a camera may be exposed in a camera definition file that is linked from CAMERA_INFORMATION.cam_definition_uri. A GCS or SDK can expose these settings though a generic UI, without having to understand any context. These parameters cannot directly be set in missions and have no specific setter commands.

MAVLink Camera Protocol v2 describes all the interactions in more detail.

Ground stations and MAVLink SDKs discover cameras and their capabilities as described in the previous section.

A ground station can use any feature exposed by the camera. PX4 has no role in this interaction other than forwarding MAVLink traffic between the camera and ground station or SDK, if needed.

Camera Commands in Missions ​

PX4 allows the following subset of Camera Protocol v2 commands in missions:

PX4 re-emits the camera commands found in missions as MAVLink commands. The system id of the emitted commands is the same as the ID of the autopilot. The component id of the commands can vary. The first four commands are addressed to MAV_COMP_ID_CAMERA (100) (if a camera has this component ID, it will execute the indicated command). The camera mode, zoom, and focus, commands are sent to a component with id of MAV_COMP_ID_ALL.

INFO

PX4 currently ignores the target camera id in MAV_CMD_IMAGE_START_CAPTURE and other camera messages. See PX4-Autopilot#23083.

Manual Controllers ​

Joystick buttons can be configured to trigger image capture or toggle video capture.

PX4 emits MAVLink Camera Protocol v2 commands such as MAV_CMD_IMAGE_START_CAPTURE when the associated Joystick button is pressed. This feature only works for this kind of camera and joystick - there is no support for RC Controllers.

PX4 Configuration ​

You will need to provide a MAVLink channel to any connected cameras so that PX4 can emit any camera commands found in missions. If your MAVLink network is such that PX4 is "between" your camera and your ground station, you will also need to forward communications so that they can communicate.

First attach the camera to an unused serial port on your flight controller, such as TELEM2 (you might also use an Ethernet port if present on both your flight controller and the camera). Then configure the selected port as a MAVLink Peripheral.

The linked document explains how, but in summary:

  1. Modify an unused MAV_n_CONFIG parameter, such as MAV_2_CONFIG, so that it is assigned to port to which you connected the camera/companion computer.
  2. Set the corresponding MAV_2_MODE to 2 (Onboard). This ensures that the right set of MAVLink messages are emitted for a companion computer (or camera).
  3. Set MAV_2_FORWARD to enable forwarding of communications from the port to other ports, such as the one that is connected to the ground station.
  4. You may need to set some of the other parameters, depending on your connection type and any particular requirements of the camera on the expected baud rate, and so on.

Manual Control ​

Joystick buttons can be mapped to capture images, and to toggle video capture on and off.

Camera Managers ​

If you want to use a camera that does not natively support the MAVLink camera protocol you will need a MAVLink camera manager. The camera manager runs on a companion computer and bridges between the MAVLink camera protocol interface and the camera's native interface.

There are "extensible" camera managers that can be used with many different cameras, camera managers designed to work with a specific camera, and you can also write your own (for example, using MAVSDK server plugins).

Generic/extensible camera managers:

Camera-specfic camera managers:

  • SIYI A8 mini camera manager - MAVSDK-plugin based camera manager for the SIYI A8 mini (includes tutorial).

    TIP

    This is a good example of how MAVSDK can be used to create a MAVLink camera protocol interface for a particular camera.

When using a camera manager you connect the companion computer to the flight controller (rather than directly to the camera), and you'll need additional software on the computer to route MAVLink traffic to the camera manager on the companion computer, such as mavlink-router.

More information about camera manager and companion computer setups can be found in: