Gimbal Protocol (v2)

This version is marked as work-in-progress. This means that it is still subject to change.

This version supersedes Gimbal Protocol v1

Introduction

The gimbal protocol allows MAVLink control over the attitude/orientation of cameras (or other sensors) mounted on the drone. The orientation can be: controlled by the pilot in real time (e.g. using a joystick from a ground station), set as part of a mission, or moved based on camera tracking.

The protocol also defines what status information is published for developers, configurators, as well as users of the drone. It additionally provides guidance to manage conflicts between commands from different sources.

The protocol supports a number of hardware setups, and enables gimbals with varying capabilities.

The original protocol design document can be found here.

Concepts

Gimbal Manager and Gimbal Device

To accommodate gimbals with varying capabilities, and various hardware setups, "a gimbal" is conceptually split into two parts:

  • Gimbal Device: the actual gimbal device, hardware and software.
  • Gimbal Manager: software to deconflict gimbal messages and commands from different sources, and to abstract the capabilities of the Gimbal Device from gimbal users.

The Gimbal Manager and Gimbal Device expose respective message sets that can be used for: gimbal manager/device discovery, querying capabilities, publishing status, and various types of orientation/attitude control.

The key concept to understand is that a Gimbal Manager has a 1:1 relationship with a particular Gimbal Device, and is the only party on the MAVLink network that is allowed to directly command that device - it does so using the Gimbal Device message set.

The Gimbal Device must act only upon messages that come from the associated Gimbal Manager! The device will however broadcast its status to all parties on the network (not just its manager).

MAVLink applications (ground stations, developer APIs like the MAVSDK, etc.), and any other software that wants to control a particular gimbal, must do so via its Gimbal Manager, using the Gimbal Manager message set.

Note that the gimbal manager is (by default) implemented by the autopilot.

Common Set-ups

This section outlines the three most common hardware set-ups.

Simple gimbal directly connected to autopilot

In this (default) set-up the autopilot takes the role of the gimbal manager.

Standalone Integrated Camera/Gimbal

In this set-up the integrated camera/gimbal itself can be the Gimbal Manager.

Therefore, the gimbal device interface is internal (no implementation is required).

Onboard Computer with Camera and Gimbal Connected to Autopilot

In this set-up the Gimbal Manager can be on the onboard computer.

Commands from the GCS (etc.) are sent to the Gimbal Manager on the companion computer. Messages from the Gimbal Manager to the Gimbal Device need to be sent to/routed through the autopilot.

Multiple Gimbals

Multiple gimbals per drone are supported.

Component IDs

Multiple component IDs are reserved for gimbal devices: MAV_COMP_ID_GIMBAL, MAV_COMP_ID_GIMBAL2, MAV_COMP_ID_GIMBAL3, MAV_COMP_ID_GIMBAL4, MAV_COMP_ID_GIMBAL5, MAV_COMP_ID_GIMBAL6.

The listed component IDs should be used where possible (other ids may be used as long as the MAV_TYPE is correctly set to MAV_TYPE_GIMBAL).

Mapping from Gimbal Managers to Gimbal Devices

Every Gimbal Manager must to publish its associated Gimbal Device (there is a 1:1 relationship) in its GIMBAL_MANAGER_INFORMATION message.

A particular MAVLink component can implement multiple gimbal managers (e.g. an autopilot can implement two gimbal managers in order to control two gimbal devices).

Addressing of Gimbal Devices

Gimbal Manager commands and messages have a param field to indicate the component ID of the Gimbal Device that they intend to control.

A system that wants to control a particular gimbal device will send messages to the component that has the manager(s), specifying the particular device to be controlled.

If all gimbal devices should be controlled (on the component that has the gimbal managers), this param/field can be set to 0 (signalling "all").

Implementation and Messages

Messages between Ground Station and Gimbal Manager

Discovery of Gimbal Manager

A ground station should initially discover all gimbal managers by sending a broadcast MAV_CMD_REQUEST_MESSAGE for GIMBAL_MANAGER_INFORMATION. Every gimbal manager should respond with GIMBAL_MANAGER_INFORMATION.

The GIMBAL_MANAGER_INFORMATION contains important information such as gimbal capabilities (GIMBAL_MANAGER_CAP_FLAGS), maximum angles and angle rates, as well as the gimbal_component which is the component ID of the Gimbal Device controlled by this Gimbal Manager.

Gimbal Manager Status

A Gimbal Manager should send out GIMBAL_MANAGER_STATUS at a low regular rate (e.g. 5 Hz) to inform the ground station about its status.

A ground station can manually control a gimbal by sending GIMBAL_MANAGER_SET_ATTITUDE. This allows controlling the gimbal with angles, or angular rates, or both.

Messages between Gimbal Manager and Gimbal Device

Discovery of Gimbal Device

The MAVlink node where the Gimbal Manager is implemented needs to discover Gimbal Devices by sending a broadcast MAV_CMD_REQUEST_MESSAGE for GIMBAL_DEVICE_INFORMATION. Every gimbal device should respond with GIMBAL_DEVICE_INFORMATION.

The MAVLink node should then create as many Gimbal Manager instances as Gimbal Devices found.

Control of a Gimbal Device

To control the angle and/or angular rate of the Gimbal Device, use the message GIMBAL_DEVICE_SET_ATTITUDE. If the gimbal manager has multiple gimbal control inputs available it should deconflict them as explained below.

Autopilot State for Gimbal Device

The autopilot should also send the message AUTOPILOT_STATE_FOR_GIMBAL_DEVICE to the gimbal device. This data is required by the Gimbal Device attitude estimator (horizon compensation), as well as to anticipate the vehicle's movements (e.g. the feed forward angular velocity in z-axis, so the current yaw intention).

Gimbal Device Broadcast/Status Messages

The gimbal device should send out its attitude and status in GIMBAL_DEVICE_ATTITUDE_STATUS at a regular rate, e.g. 10 Hz.

This message is a meant as broadcast, so it's set to the GCS, Gimbal Manager, and all parties on the network (not just Gimbal Manager, like all other messages).

Gimbal Manager Deconfliction Rules

It is possible for multiple components to want to control a gimbal at the same time: e.g. a ground station, a companion computer, or the autopilot running a mission. This can create situations where the gimbal would receive conflicting messages from the different components, and hence may behave unintendedly or unexpectedly from the viewpoint of one of the components (and ultimately the user). Thus, decision making is required in order to establish proper and predictable gimbal operation.

The Gimbal Manager must deconflict the various inputs by implementing the rules below:

  1. If an attitude has been set using a command (DO_GIMBAL_MANAGER_TILTPAN, DO_SET_ROI_LOCATION, DO_GIMBAL_MANAGER_TRACK_POINT, or DO_GIMBAL_MANAGER_TRACK_RECTANGLE it takes precedence over any other input until a DO_GIMBAL_MANAGER_TILTPAN with GIMBAL_MANAGER_FLAGS_NONE or a DO_SET_ROI_NONE is set. Commands will interfere with each other, whichever command is received last takes precedence.
  2. A gimbal angle or tracking location initiated by a command can be nudged by GIMBAL_MANAGER_SET_ATTITUDE if the "nudge bit" is set.
  3. A gimbal angle or tracking location initiated by a command can be overridden by GIMBAL_MANAGER_SET_ATTITUDE if the "override bit" is set.

Nudging

Nudging is a slight deflection/change on top of the set gimbal attitude.

The behaviour is slightly different based on how the attitude has been set:

  • ROI: while set at ROI, the gimbal can be moved around to look around. If the sticks are let go, it will snap to the new selected ROI if supported and otherwise snap back to the previous one.
  • TRACK: while tracking a point or rectangle, nudging will move the gimbal angle only as much as so that the tracked object is still on the image (otherwise it would lose the tracking). If the sticks are let go, it will snap back to have the tracked object centered.
  • ATTITUDE: nudging allows deflection of the angle. If the sticks are let go it will go back to the set attitude.

Overriding

Overriding means that anything set is ignored. It is generally discouraged to use this unless something doesn’t work as intended, a mission is set-up incorrectly, etc.

Custom Gimbal Device Settings

Custom gimbal settings can be accomplished using the component information microservice which is based on a component definition file.(this is similar to the camera definition file).

FAQ

How to set the System ID of a gimbal device?

The system ID of all components (e.g. autopilot, companion computer, camera, gimbal) on a drone/system must be the same. This needs to be either done manually by configuration, or alternatively, the components need to listen to the heartbeat of the autopilot and then adjust their system ID accordingly.

When is Gimbal Device also a Gimbal Manager?

The default case should be to use the Gimbal Manager in the autopilot. The only exception to this are integrated solutions containing a camera and gimbal for functionality like visual tracking.

How to test Gimbal Device?

A Gimbal Device can be tested by connecting it to an autopilot with a Gimbal Manager. To avoid having to do a full setup including autopilot, a direct test using MAVSDK is planned.

Gimbals that use the (old) Gimbal Protocol v1 should still be supported by autopilot software. Basically, the Gimbal Manager needs to translate the commands to the old protocol.

Gimbals controlled using a protocol like PPM, PWM, SBUS or something proprietary can still be supported. The autopilot will have to act as the Gimbal Manager and provide the driver and translation to the respective protocol.

The autopilot needs to be configured to either accept MAVLink input (so GIMBAL_MANAGER_SET_ATTITUDE) or RC control.

For RC control, the channels will have to be manually mapped/configured to control the gimbal. It is up to the gimbal manager implementation to deconflict between RC and MAVLink input. This is in the same way that also RC input to fly needs to be selected from either RC or MAVLink and is up to the implementation. The recommendation is to make it configurable using for instance a parameter.

Message/Command/Enum Summary

Gimbal Manager Messages

This is the set of messages/enums for communicating with the gimbal manager (by ground station, autopilot, etc.).

MessageDescription
!!crwdBlockTags_16_sgaTkcolBdwrc!GIMBAL_MANAGER_INFORMATIONInformation about a high level gimbal manager. This message should be requested by a ground station using MAV_CMD_REQUEST_MESSAGE.
!!crwdBlockTags_17_sgaTkcolBdwrc!GIMBAL_MANAGER_STATUSCurrent status about a high level gimbal manager. This message should be broadcast at a low regular rate (e.g. 5Hz).
!!crwdBlockTags_18_sgaTkcolBdwrc!GIMBAL_MANAGER_SET_ATTITUDEHigh level message to control a gimbal's attitude. This message is to be sent to the gimbal manager (e.g. from a ground station).
CommandDescription
!!crwdBlockTags_21_sgaTkcolBdwrc!MAV_CMD_REQUEST_MESSAGERequest the target system(s) emit a single instance of a specified message. This is used to request GIMBAL_MANAGER_INFORMATION.
!!crwdBlockTags_22_sgaTkcolBdwrc!MAV_CMD_DO_GIMBAL_MANAGER_TILTPANHigh level setpoint to be sent to a gimbal manager to set a gimbal attitude. Note: a gimbal is never to react to this command but only the gimbal manager.
!!crwdBlockTags_23_sgaTkcolBdwrc!MAV_CMD_DO_SET_ROI_LOCATIONSets the region of interest (ROI) to a location. This can then be used by the vehicle's control system to control the vehicle attitude and the attitude of various sensors such as cameras. This command can be sent to a gimbal manager but not to a gimbal device. A gimbal is not to react to this message.
!!crwdBlockTags_24_sgaTkcolBdwrc!MAV_CMD_DO_SET_ROI_WPNEXT_OFFSETSets the region of interest (ROI) to be toward next waypoint, with optional pitch/roll/yaw offset. This can then be used by the vehicle's control system to control the vehicle attitude and the attitude of various sensors such as cameras. This command can be sent to a gimbal manager but not to a gimbal device. A gimbal device is not to react to this message.
!!crwdBlockTags_25_sgaTkcolBdwrc!MAV_CMD_DO_SET_ROI_SYSIDMount tracks system with specified system ID. Determination of target vehicle position may be done with GLOBAL_POSITION_INT or any other means. This command can be sent to a gimbal manager but not to a gimbal device. A gimbal device is not to react to this message.
!!crwdBlockTags_26_sgaTkcolBdwrc!MAV_CMD_DO_SET_ROI_NONECancels any previous ROI command returning the vehicle/sensors to default flight characteristics. This can then be used by the vehicle's control system to control the vehicle attitude and the attitude of various sensors such as cameras. This command can be sent to a gimbal manager but not to a gimbal device. A gimbal device is not to react to this message. After this command the gimbal manager should go back to manual input if available, and otherwise assume a neutral position.
!!crwdBlockTags_27_sgaTkcolBdwrc!MAV_CMD_DO_GIMBAL_MANAGER_TRACK_POINTIf the gimbal manager supports visual tracking (GIMBAL_MANAGER_CAP_FLAGS_HAS_TRACKING_POINT is set), this command allows to initiate the tracking. Such a tracking gimbal manager would usually be an integrated camera/gimbal, or alternatively a companion computer connected to a camera.
!!crwdBlockTags_28_sgaTkcolBdwrc!MAV_CMD_DO_GIMBAL_MANAGER_TRACK_RECTANGLEIf the gimbal supports visual tracking (GIMBAL_MANAGER_CAP_FLAGS_HAS_TRACKING_RECTANGLE is set), this command allows to initiate the tracking. Such a tracking gimbal manager would usually be an integrated camera/gimbal, or alternatively a companion computer connected to a camera.
EnumDescription
!!crwdBlockTags_30_sgaTkcolBdwrc!GIMBAL_MANAGER_FLAGSFlags for high level gimbal manager operation.
The first 16 bytes are identical to the GIMBAL_DEVICE_FLAGS. Used in MAV_CMD_DO_GIMBAL_MANAGER_TILTPAN, GIMBAL_MANAGER_STATUS , GIMBAL_MANAGER_SET_ATTITUDE.
!!crwdBlockTags_31_sgaTkcolBdwrc!GIMBAL_MANAGER_CAP_FLAGSGimbal manager high level capability flags (bitmap).
The first 16 bits are identical to the GIMBAL_DEVICE_CAP_FLAGS which are identical with GIMBAL_DEVICE_FLAGS. However, the gimbal manager does not need to copy the flags from the gimbal but can also enhance the capabilities and thus add flags. Used in GIMBAL_MANAGER_INFORMATION

Gimbal Device Messages

This is the set of messages/enums for communication between gimbal manager and gimbal device.

MessageDescription
!!crwdBlockTags_34_sgaTkcolBdwrc!GIMBAL_DEVICE_INFORMATIONInformation about a low level gimbal. This message should be requested by the gimbal manager or a ground station using MAV_CMD_REQUEST_MESSAGE.
!!crwdBlockTags_35_sgaTkcolBdwrc!GIMBAL_DEVICE_SET_ATTITUDELow level message to control a gimbal device's attitude. This message is to be sent from the gimbal manager to the gimbal device component. Angles and rates can be set to NaN according to use case.
!!crwdBlockTags_36_sgaTkcolBdwrc!GIMBAL_DEVICE_ATTITUDE_STATUSMessage reporting the status of a gimbal device. This message should be broadcasted by a gimbal device component.
CommandDescription
!!crwdBlockTags_38_sgaTkcolBdwrc!MAV_CMD_REQUEST_MESSAGERequest the target system(s) emit a single instance of a specified message. This is used to request GIMBAL_DEVICE_INFORMATION.
EnumDescription
!!crwdBlockTags_40_sgaTkcolBdwrc!GIMBAL_DEVICE_CAP_FLAGSGimbal device (low level) capability flags (bitmap).
Used in GIMBAL_DEVICE_INFORMATION.
!!crwdBlockTags_41_sgaTkcolBdwrc!GIMBAL_DEVICE_FLAGSFlags for gimbal device (lower level) operation.
Used in GIMBAL_DEVICE_ATTITUDE_STATUS and GIMBAL_DEVICE_SET_ATTITUDE.
!!crwdBlockTags_42_sgaTkcolBdwrc!GIMBAL_DEVICE_ERROR_FLAGSGimbal device (low level) error flags (bitmap, 0 means no error).
Used in GIMBAL_DEVICE_ATTITUDE_STATUS.

Sequences

Depicted below are message sequences for some common scenarious.

Discovery

This shows a possible sequence on startup. Note that the gimbal manager could already discover the gimbal device before the ground station asks for the information.

Normal Manual Control

During the normal manual control, all messages are streamed at a regular rate. Note that GIMBAL_DEVICE_ATTITUDE_STATUS is broadcast to anyone, so to the gimbal manager and also the ground station.

ROI Initiated from Ground Station

ROI can be started using a command and should also be stopped again with a command. The ROI command is translated to a gimbal attitude in the the gimbal manager.

Attitude Set During Mission

In this case the gimbal manager is implemented by the autopilot which "sends" the attitude command (for instance for a survey).

results matching ""

    No results matching ""