Revision as of 01:25, 29 September 2020

The information on this page refers to firmware v2.57e and higher.

In addition to the serial commands, the STorM32 controller also understands MAVLink messages, as defined in the MAVLink standard. The STorM32 controller supports a rich set of MAVLink messages and features, the MAVLink 2 protocol, the MAVLink Camera Protocol, and the MAVLink FTP microservice.

The STorM32 controller in fact integrates two MAVLink components, which are referred to as the MAVLink Gimbal and MAVLink Camera components:

MAVLink Gimbal: This component deals with the gimbal operation. It is the part which you know from older firmware versions, but with massively extended functionality.
MAVLink Camera: This component is coupled with the NT Camera and provides a complete MAVLink Camera Protocol microservice server. It allows you to control the camera through MAVLink in unprecedented useful ways.

The MAVLink Gimbal and MAVLink Camera components share some parameters, but function-wise they are independent of each other. That is, both can be used simultaneously, the MAVLink Gimbal component can be used alone without the MAVLink Camera component, and vice versa.

Comment: In case you find it confusing what "two MAVLink components" is supposed to mean, then just connect the STorM32 controller (with both components enabled) to MissionPlanner: You will find that it will show you two components, one named GIMBAL and the other named CAMERA :).

Parameters

The MAVLink parameters are located in the [GUI:Interfaces Tool] window, which is accessible via the [GUI:Experts Only] menu.

It has the following parameters:

Mavlink Gimbal: Enables the MAVLink Gimbal component and sets its component ID and gimbal device ID.
Mavlink Gimbal Stream: Activates emission of the selected message by the Gimbal component. Also determines if the STorM32 controller is in gimbal manager mode.
Mavlink ComPort: Selects the serial com port which is used for the MAVLink communication. Applies to both the MAVLink Gimbal and MAVLink Camera components.
Mavlink System ID: Sets the system ID of the STorM32 controller (default = “0”). Applies to both the MAVLink Gimbal and MAVLink Camera components. If it is set to “0”, then the system ID is autodetected, i.e., the STorM32 waits for incoming heartbeat messages from an autopilot and then uses its system ID.
Mavlink Version: Sets the used MAVLink protocol version (default = “Mavlink2”). Applies to both the MAVLink Gimbal and MAVLink Camera components. Must be set to “Mavlink2” for the MAVLink Gimbal and Camera components to fully work (MAVLink 1 protocol supports only a subset of messages).
Mavlink Camera: Enables the MAVLink Camera component and sets its component ID.

The STorM32 system ID should match the system ID of the autopilot, or autodetection should be enabled with Mavlink System ID = “0” (which is the default).

STorM32 supports the MAVLink 1 and MAVLink 2 protocols, which can be set via the parameter Mavlink Version. Per default MAVLink 2 is enabled, and it is highly recommended to use it.

Comment: The MAVLINK field in the [GUI:Dashboard] Info Center shows MAVLINK is PRESENT when the STorM32 controller is receiving valid MAVLink messages, implying a MAVLink connection is established. This can be handy for diagnosis.

Comment: If Mavlink Gimbal or Mavlink Camera is set, then the serial port selected in Mavlink ComPort is exclusive to the MAVLink communication. That is, incoming MAVLink messages on this port are accepted and served, but serial commands are rejected, while on all other ports serial messages are accepted but MAVLink messages rejected. If both parameters are off, then the STorM32 controller will, in addition to the serial commands, also accept MAVLink messages on any of its serial ports, but no outgoing MAVLink messages such as heartbeats will be emitted.

Comment: The baudrate of the selected serial port is determined by the respective baudrate parameter in the [GUI:Expert] tab. Per default it is 115200 bps. It is recommended to use a baudrate of 230400 bps, if possible.

Comment: For v1.3x boards: When the UART port is selected, one cannot use a BT module and a serial MAVLink connection at the same time.

Gimbal Protocol V2

The STorM32 controller does not support the MAVLink Gimbal Protocol V2 (at least not for as long as it is not mature and proven out), with two notable exceptions:

The messages GIMBAL_DEVICE_INFORMATION and AUTOPILOT_STATE_FOR_GIMBAL_DEVICE are supported.

The STorM32 controller implements its own MAVLink dialect (storm32.xml) and the main part of it are its own versions of the gimbal device and gimbal manager messages (identifiable by the label STORM32 in the names). They may look somewhat similar to the standard messages, and they can adopt the same behavior and functionality as the standard, but provide a much richer concept for the gimbal manager operation than the standard.

Pass-Through

It is possible to connect the STorM32 GUI to any routing component in a MAVLink system, such as an autopilot or on-board companion computer, and to communicate directly with the STorM32 gimbal via MAVLink tunnel messages.

This is extremely convenient when the STorM32 gimbal is permanently installed in a vehicle, as it allows us to configure the gimbal without having to have physical access to the STorM32's USB or UART ports. The pass-through also works with wireless telemetry links, which opens up options such as tuning the gimbal during flight, and other unheard-of possibilities for in-flight control of the gimbal.

The pass-through mode of operation is enabled by checking in the GUI the [MAVLink] checkbox, which is located next to the [Port] combobox. The GUI then effectively operates like a mini MAVLink ground control station (the system ID is determined from the attached components, its component ID is MAV_COMP_ID_TUNNEL_NODE = 242 per default).

Comment: The pass-through communication is based on standard MAVLink, and thus should work for any MAVLink standard compliant autopilot.

Comment: Pass-through works for both the MAVLink Gimbal and MAVLink Camera components. The GUI chooses the MAVLink Gimbal if enabled, otherwise the MAVLink Camera for communication.

Comment: GUI functions which need physical access to a USB/UART port on the STorM32 controller do not work in pass-through mode. For instance, upgrading firmware won't work.

This preliminary demo video demonstrates the pass-through feature:

MAVLink FTP

The MAVLink Gimbal and MAVLink Camera components support the MAVLink FTP micro service, which allows us to download the various camera definition files stored in the STorM32 controller.

Supported OpCodes/Commands

These opcodes/commands are support (unsupported commands will be NACKed with error code Fail):

MAVFTP_OPCODE_None
MAVFTP_OPCODE_TerminateSession
MAVFTP_OPCODE_ResetSessions
MAVFTP_OPCODE_ListDirectory
MAVFTP_OPCODE_OpenFileRO
MAVFTP_OPCODE_ReadFile
MAVFTP_OPCODE_CalcFileCRC32

MAVLink Gimbal

The MAVLink Gimbal component is enabled with the Mavlink Gimbal parameter, which also determines its component ID: “Gimbal1” corresponds to MAV_COMP_ID_GIMBAL (= 154), “Gimbal2” to MAV_COMP_ID_GIMBAL2 (= 171), “Gimbal3” to MAV_COMP_ID_GIMBAL3 (= 172), and so on:

Mavlink Gimbal = “Gimbal1” or higher
Mavlink Gimbal Stream: Activates the emission of the selected message with a frequency of 4 Hz.

The system ID can be adjusted via the Mavlink System ID parameter, which usually can be left at its default value.

The gimbal device ID, which is relevant for the Gimbal Protocol V2, is always set to be identical to the component ID.

The STorM32 controller is in gimbal manager mode when Mavlink Gimbal Stream = “manager status”.

Messages

The following MAVLink messages are supported:

MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00)

See HEARTBEAT.

The emission of the heartbeat needs to be activated in the GUI via the Mavlink Gimbal parameter. The heartbeat is emitted at 1 Hz, with the following values:

type: MAV_TYPE_GIMBAL (= 26)
autopilot: MAV_AUTOPILOT_INVALID (= 8)
base_mode: MAV_MODE_FLAG_STABILIZE_ENABLED (= 0x10) and MAV_MODE_FLAG_SAFETY_ARMED (= 0x80) are set in NORMAL mode, MAV_MODE_FLAG_CUSTOM_MODE_ENABLED (= 0x01) is always set
custom_mode: lowest byte (0x000000FF) = STATE value; highest bit (0x80000000) = set if prearm checks have not passed
system_status: either MAV_STATE_BOOT (= 1), MAV_STATE_STANDBY (= 3), MAV_STATE_ACTIVE (= 4) or MAV_STATE_EMERGENCY (= 6)

The prearm check flag in the custom_mode field allows GCSes and autopilots to determine the STorM32's prearm check condition, and to act accordingly.

MAVLINK_MSG_ID_SYSTEM_TIME (#2, 0x02)

See SYSTEM_TIME.

The UNIX epoch time in this message is logged by the NT Logger (if time_unix_usec is > 0). The SYSTEM_TIME message is usually emitted by the autopilot, and the UNIX epoch time becomes > 0 when e.g. a 3D GPS fix has been obtained. The UNIX epoch time facilitates synchronizing the autopilot data logs and the NT Logger data logs.

Emission of the attitude message with 4 Hz can be activated in the GUI via the Mavlink Gimbal Stream parameter, or by requesting a data stream or single-shot emission with the MAV_CMD_SET_MESSAGE_INTERVAL or MAV_CMD_REQUEST_MESSAGE commands, respectively. The yaw angle is relative to the forward direction.

MAVLINK_MSG_ID_RC_CHANNLES (#65, 0x41)

See RC_CHANNELS.

The parameter Virtual Channel Configuration needs to be set to “serial” for the values received by this message to become available for inputs as “Virtual-1” to “Virtual-16”.

MAVLINK_MSG_ID_COMMAND_INT (#75, 0x4B)

See COMMAND_INT.

Same as for MAVLINK_MSG_ID_COMMAND_LONG, see next.

MAVLINK_MSG_ID_COMMAND_LONG (#76, 0x4C)

See COMMAND_LONG.

Each command is acknowledged with a COMMAND_ACK message (with result MAV_RESULT_ACCEPTED or MAV_RESULT_DENIED for supported commands, and MAV_RESULT_UNSUPPORTED otherwise). The following commands are supported (parameter fields not mentioned are ignored):

MAV_CMD_DO_SET_PARAMETER (#180, 0xB4)
* param1 = parameter index
* param2 = parameter value

MAV_CMD_DO_SET_SERVO (#183, 0xB7)
* param1 = instance (must be 0, else denied)
* param2 = pwm value (only 700...2300 accepted, else denied)

MAV_CMD_DO_DIGICAM_CONFIGURE (#202, 0xCA)
* param1 = mode 
     0: CAMERA_MODE_PHOTO
     1: CAMERA_MODE_VIDEO
* param6 = command identity 
     0: command accepted by all cameras
     1-6: command accepted only if camera is CAMERA1-CAMERA6

MAV_CMD_DO_DIGICAM_CONTROL (#203, 0xCB)
* param5 = shot
     if CAMERA_MODE_PHOTO: 
         0: off
         1: SHUTTER
     if CAMERA_MODE_VIDEO
         0: VIDEOOFF
         1: VIDEOON
* param6 = command identity 
     0: command accepted by all cameras
     1-6: command accepted only if camera is CAMERA1-CAMERA6

MAV_CMD_DO_MOUNT_CONFIGURE (#204, 0xCC)
* param1 = mount_mode (0 = MAV_MOUNT_MODE_RETRACT and 1 = MAV_MOUNT_MODE_NEUTRAL recenters the camera)
 
The command is denied in gimbal manager mode.

MAV_CMD_DO_MOUNT_CONTROL (#205, 0xCD)
* param1 = pitch, angle in degree (COMMENT: the sign is opposite to convention!)
* param2 = roll, angle in degree
* param3 = yaw, angle in degree (COMMENT: the sign is opposite to convention!)
* param7 = mount_mode (0 = MAV_MOUNT_MODE_RETRACT and 1 = MAV_MOUNT_MODE_NEUTRAL recenters the camera)
 
The command is denied in gimbal manager mode.

MAV_CMD_DO_SET_CAM_TRIGG_DIST(#206, 0xCE)
* param1 = distance (must be 0, else denied)
* param3 = trigger camera once immediately 
     0: off
     1: SHUTTER

MAV_CMD_PREFLIGHT_STORAGE (#245, 0xF5)
* param1 = parameter storage
     0: restore parameter values from EEPROM
     1: store parameter values in EEPROM
     2: ignored, as it maybe harmful

MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN(#246, 0xF6)
* param4
     0: do nothing
     1: restart with full reset
     2: shut down motors

MAV_CMD_GET_MESSAGE_INTERVAL (#510, 0x01FE)
* param1 =  MAVLink message ID;

MAV_CMD_SET_MESSAGE_INTERVAL (#511, 0x01FF)
* param1 =  message ID of the message to stream
     30: stream ATTITUDE message
     158: stream MOUNT_STATUS message (target is set according to param7, for details see message description)
     62001: stream STORM32_GIMBAL_DEVICE_STATUS message (target is set according to param7, see message description)
     62011: stream STORM32_GIMBAL_MANAGER_STATUS message
     62020: stream X_SHOT_MANAGER_STATUS message
* param2 = interval between two messages, in microseconds; set to -1 to disable
* param7 = request target
 
Stream rates of up to 100 Hz are supported. Note however that this can take a significant toll and may strain the STorM32's microcontroller capabilities. Please resort to common sense. The resulting stream rate is in multiples of 1.5 ms.

MAV_CMD_REQUEST_MESSAGE (#512, 0x0200)
* param1 = message ID of the requested message
     30: send ATTITUDE message
     148: send AUTOPILOT_VERSION message
     158: send MOUNT_STATUS message (target is set according to param7, default is requester IDs)
     253: send STATUSTEXT message with firmware and board type information
     283: send GIMBAL_DEVICE_INFORMATION message
     300: send PROTOCOL_VERSION message
     62000: send STORM32_GIMBAL_DEVICE_INFORMATION message
     62001: send STORM32_GIMBAL_DEVICE_STATUS message (target is set according to param7, default is requester IDs)
     62010: send STORM32_GIMBAL_MANAGER_INFORMATION message (only if in gimbal manager mode)
     62011: send STORM32_GIMBAL_MANAGER_STATUS message (only if in gimbal manager mode)
     62020: send X_SHOT_MANAGER_STATUS message
* param7 = response target

MAV_CMD_REQUEST_PROTOCOL_VERSION (#519, 0x0207)
  send PROTOCOL_VERSION message (still supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_REQUEST_AUTOPILOT_CAPABILITIES (#520, 0x0208)
  send AUTOPILOT_VERSION message (still supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_STORM32_DO_GIMBAL_MANAGER_SETUP(#62000, 0xF230)
  This command is handled in gimbal manager mode. The gimbal device ID (param7) must match the STorM32's gimbal component ID.

MAV_CMD_STORM32_DO_GIMBAL_MANAGER_TILTPAN (#62002, 0xF232)
  This command is handled in gimbal manager mode. The gimbal device ID (param7) must match the STorM32's gimbal component ID.

MAV_CMD_X_DO_SHOT_MANAGER_CONFIGURE (#62020, 0xF244)
* param1 = shot manager mode
* param2 = shot state

MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D)

See COMMAND_ACK.

MAVLINK_MSG_ID_FILE_TRANSFER_PROTOCOL (#110, 0x6E)

See FILE_TRANSFER_PROTOCOL.

MAVLINK_MSG_ID_AUTOPILOT_VERSION (#148, 0x94)

See AUTOPILOT_VERSION.

The flight_sw_version and board_version fields are set to the firmware version and board revision, VID and PID are set to 0x16D0 and 0x0FCB, respectively, and UID is set to the STM32 UUID.

MAVLINK_MSG_ID_DIGICAM_CONTROL (#155, 0x9B)

ArduPilot specific message. See DIGICAM_CONTROL.

Deprecated message, but supported for compatibility.

MAVLINK_MSG_ID_MOUNT_CONFIGURE (#156, 0x9C)

ArduPilot specific message. See MOUNT_CONFIGURE.

Deprecated message, but supported for compatibility.

The message is denied in gimbal manager mode.

MAVLINK_MSG_ID_MOUNT_CONTROL (#157, 0x9D)

ArduPilot specific message. See MOUNT_CONTROL.

Deprecated message, but supported for compatibility.

The message is denied in gimbal manager mode.

MAVLINK_MSG_ID_MOUNT_STATUS (#158, 0x9E)

ArduPilot specific message. See MOUNT_STATUS.

Emission of this message with 4 Hz can be activated in the GUI with the Mavlink Gimbal Stream parameter, with a user defined rate by requesting a data stream with the MAV_CMD_SET_MESSAGE_INTERVAL command, or by requesting a single-shot emission with the MAV_CMD_REQUEST_MESSAGE command. The yaw angle is relative to the forward direction.

The 4 Hz message stream activated with Mavlink Gimbal Stream is always broadcast. The messages emitted as result of MAV_CMD_SET_MESSAGE_INTERVAL or MAV_CMD_REQUEST_MESSAGE commands can be broadcast or targeted, as specified by param7 in the command. For MAV_CMD_SET_MESSAGE_INTERVAL: If a stream of targeted messages is requested, then the emission is in addition to the broadcast 4 Hz stream (if activated). If a broadcast stream is requested, it overrules the broadcast 4 Hz stream.

This allows for two streams, one broadcast stream at low rate e.g. to inform a GCS and one targeted stream at high rate e.g. to inform an on-board companion computer.

MAVLINK_MSG_ID_AUTOPILOT_VERSION_REQUEST (#183, 0xB7)

ArduPilot specific message. See AUTOPILOT_VERSION_REQUEST.

Is supported, but better use MAV_CMD_REQUEST_MESSAGE instead.

MAVLINK_MSG_ID_MESSAGE_INTERVAL (#244, 0xF4)

See MESSAGE_INTERVAL.

MAVLINK_MSG_ID_STATUSTEXT (#253, 0xFD)

See STATUSTEXT.

This message is sent out after a PARAM_REQUEST_LIST has been served, and provides firmware and board type information.

Emission of this message with a user-supplied text can also be triggered through a script using the SENDMAVTEXT script command.

MAVLINK_MSG_ID_GIMBAL_DEVICE_INFORMATION (#283, 0x11B)

See GIMBAL_DEVICE_INFORMATION.

Note that the standard cap_flags field is only 16 bits wide and thus doesn't display the higher STorM32-specific bits (storm32.xml).

MAVLINK_MSG_ID_AUTOPILOT_STATE_FOR_GIMBAL_DEVICE (#286, 0x11E)

See AUTOPILOT_STATE_FOR_GIMBAL_DEVICE.

This message can be send to the STorM32 controller and is then used for STorM32-Link.

MAVLINK_MSG_ID_PROTOCOL_VERSION (#300, 0x12C)

See PROTOCOL_VERSION.

MAVLINK_MSG_ID_TUNNEL (#385, 0x181)

See TUNNEL.

The STorM32 controller occupies the block of payload_type values from 200 - 209 (see MAV_TUNNEL_PAYLOAD_TYPE). The payload types 200 and 201 are used for communicating with the GUI. Payload types 202 and 203 are for communicating with a flight controller, but can also be used otherwise.