MAVLink Communication: Difference between revisions

From STorM32-BGC Wiki
Jump to navigation Jump to search
 
(706 intermediate revisions by the same user not shown)
Line 1: Line 1:
''The information on this page refers to firmware v2.46e and higher.''
<span style="font-size:88%">''The information on this page refers to firmware v2.70a and higher.''</span>


In addition to the [[Serial_Communication|serial commands]], the STorM32 controller also understands MAVLink messages, as defined in the [https://mavlink.io/en/ MAVLink] standard. The STorM32 controller in fact supports a rich set of MAVLink messages and features, as well as the [https://mavlink.io/en/guide/mavlink_2.html MAVLink 2] protocol, and might be by far the most integrated MAVLink capable gimbal controller available.
In addition to the [[Serial_Communication|serial commands]], the STorM32 controller also understands MAVLink messages, as defined in the [https://mavlink.io/en/ MAVLink] standard. The STorM32 controller supports a rich set of MAVLink messages and features, the [https://mavlink.io/en/guide/mavlink_2.html MAVLink 2] protocol, the [https://mavlink.io/en/services/gimbal_v2.html Gimbal Protocol v2], the [https://mavlink.io/en/services/camera.html MAVLink Camera Protocol], and the [https://mavlink.io/en/services/ftp.html MAVLink FTP] microservice<!--, and partially also the [https://mavlink.io/en/services/gimbal_v2.html MAVLink Gimbal Protocol V2]-->.


The STorM32 controller integrates '''''two''''' MAVLink components, which are referred to as the MAVLink Gimbal and MAVLink Camera components:
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, and is the part which you know from older firmware versions.
* '''''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 related to the [[NT_Camera|NT Camera]], and provides a complete [https://mavlink.io/en/services/camera.html MAVLink Camera Protocol microservice] server. It allows you to control the camera through MAVLink in unprecedented useful ways.
* '''''MAVLink Camera''''': This component is coupled with the [[NT_Camera|NT Camera]] and provides a complete [https://mavlink.io/en/services/camera.html 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 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.
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.
 
<!--Concerning the new MAVLink gimbal protocol v2, the [https://mavlink.io/en/services/gimbal_v2.html official documentation] is of course a good resource. This link you may also find useful: [http://www.olliw.eu/2020/mavlink-gimbal-protocol-v2/ MAVLink Gimbal Protocol V2: Intro and Overview].-->
{{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|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 :).}}
{{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 :).}}
Line 18: Line 17:
= Parameters =
= Parameters =


The MAVLink parameters are located in the {{GUI|Interfaces Tool}} window, which is accessible via the {{GUI|Experts Only}} menu.  
The STorM32's MAVLink parameters are located in the {{GUI|Interfaces Tool}} window, which is accessible via the {{GUI|Experts Only}} menu.  


It has the following parameters:
It has the following parameters:


* {{PARAMNAME|Mavlink Gimbal}}: Enables the MAVLink Gimbal component and sets its component ID.
* {{PARAMNAME|Mavlink Gimbal}}: Enables the MAVLink Gimbal component and sets its component ID and gimbal device ID.
* {{PARAMNAME|Mavlink Gimbal Stream}}: Activates emission of the selected message by the Gimbal component.
* {{PARAMNAME|Mavlink Gimbal Stream}}: Activates emission of the selected message by the gimbal component. Also determines if the STorM32 controller is in gimbal device or gimbal manager operation mode.
* {{PARAMNAME|Mavlink ComPort}}: Selects the serial com port which shall be used for the MAVLink communication. Applies to both the MAVLink Gimbal and MAVLink Camera components.
* {{PARAMNAME|Mavlink ComPort}}: Selects the serial com port which is used for the MAVLink communication. Applies to both the MAVLink Gimbal and MAVLink Camera components.
* {{PARAMNAME|Mavlink System ID}}: Sets the system ID of the STorM32 controller (default = {{PARAMVALUE|0}}). Applies to both the MAVLink Gimbal and MAVLink Camera components. If it is set to {{PARAMVALUE|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.
* {{PARAMNAME|Mavlink System ID}}: Sets the system ID of the STorM32 controller (default = {{PARAMVALUE|0}}). Applies to both the MAVLink Gimbal and MAVLink Camera components. If it is set to {{PARAMVALUE|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.
* {{PARAMNAME|Mavlink Version}}: Sets the used MAVLink protocol version (default = {{PARAMVALUE|Mavlink2}}). Applies to both the MAVLink Gimbal and MAVLink Camera components. Must be set to {{PARAMVALUE|Mavlink2}} for the MAVLink Camera component to fully work.
* {{PARAMNAME|Mavlink Camera}}: Enables the MAVLink Camera component and sets its component ID.
* {{PARAMNAME|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 {{PARAMNAME|Mavlink System ID}} = {{PARAMVALUE|0}} (which is the default).
The STorM32 system ID should match the system ID of the autopilot, or autodetection should be enabled with {{PARAMNAME|Mavlink System ID}} = {{PARAMVALUE|0}} (which is the default).


STorM32 supports the MAVLink 1 and MAVLink 2 protocols, which can be set via the parameter {{PARAMNAME|Mavlink Version}}. Per default MAVLink 2 is enabled, and it is highly recommended to use it.
The baudrate of the serial port selected with {{PARAMNAME|Mavlink ComPort}} is determined by the respective baudrate parameter in the {{GUI|Interfaces Tool}} window. Per default it is 115200 bps. It is recommended to use a baudrate of 230400 bps, if possible.
 
{{COMMENT|In the {{GUI|Dashboard}} Info Center, the MAVLINK field 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 {{PARAMNAME|Mavlink Gimbal}} or {{PARAMNAME|Mavlink Camera}} is set, then the serial port selected in {{PARAMNAME|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 are 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 it will not emit any MAVLink messages such as heartbeats.}}
 
{{COMMENT|Implication of the previous comment: If the USB port is selected in {{PARAMNAME|Mavlink ComPort}} one cannot connect to the GUI via the STorM32's USB port anymore.}}
 
{{COMMENT|For v1.3x boards: If the UART port is selected for MAVLink, then the BT module and the serial MAVLink connection cannot be used at the same time.}}
 
= MAVLink Protocol Version =
 
STorM32 uses the [https://mavlink.io/en/guide/mavlink_version.html MAVLink v2] protocol version.
 
It also supports the MAVLink v1 protocol insofar as it properly reads and handles incoming MAVLink v1 packets, but it does not send out v1 packets, i.e., all MAVLink messages emitted by the STorM32 controller are in the MAVLink v2 protocol format.
 
{{COMMENT|In older STorM32 firmware versions it was possible to choose between MAVLink v1 and v2 formats. This option has been removed, there really should be no reason nowadays anymore to not use MAVLink v2.}}
 
= Gimbal Protocol V2 =
 
The STorM32 controller fully supports the '''''gimbal device''''' messages of the [https://mavlink.io/en/services/gimbal_v2.html MAVLink Gimbal Protocol V2] standard (i.e. can operate as a v2 compliant gimbal device); it does not support the '''''gimbal manager''''' messages of this protocol (i.e. cannot be used as a v2 compliant gimbal manager).
 
In detail: The messages [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_INFORMATION GIMBAL_DEVICE_INFORMATION], [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_ATTITUDE_STATUS GIMBAL_DEVICE_ATTITUDE_STATUS], [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_SET_ATTITUDE GIMBAL_DEVICE_SET_ATTITUDE], and [https://mavlink.io/en/messages/common.html#AUTOPILOT_STATE_FOR_GIMBAL_DEVICE AUTOPILOT_STATE_FOR_GIMBAL_DEVICE] are fully supported. Note: This does not imply that all possible functionality is supported, e.g., currently YAW_IN_EARTH_FRAME is not supported.
 
In addition, the STorM32 controller implements its own MAVLink dialect ([https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/storm32.xml storm32.xml]). A main part of it is the [http://www.olliw.eu/2020/mavlink-gimbal-protocol-v2/ STorM32 Gimbal Protocol], which defines the STorM32's versions of the gimbal manager messages (identifiable by the 'STORM32' label in the names). They may look somewhat similar to the standard gimbal manager messages, and they can indeed adopt the same behavior and functionality as the standard, but the underlying concept provides a richer and more mature concept for gimbal operation than the standard. For details please consult the article [http://www.olliw.eu/2020/mavlink-gimbal-protocol-v2/ STorM32 Gimbal Protocol].
 
In order to identify a STorM32 gimbal, e.g. to determine if the STorM32's extensions are available, request the GIMBAL_DEVICE_INFORMATION message. The vendor name and model name fields are populated with "olliw.eu" and "STorM32", respectively, which should allow unambiguous identification. One also can request the AUTOPILOT_VERSION message. The VID and PID are 0x16D0 and 0x0FCB, and they are globally unique to the STorM32 controller.
<!--
* The messages [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_INFORMATION GIMBAL_DEVICE_INFORMATION], [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_ATTITUDE_STATUS], and [https://mavlink.io/en/messages/common.html#AUTOPILOT_STATE_FOR_GIMBAL_DEVICE AUTOPILOT_STATE_FOR_GIMBAL_DEVICE] are fully supported.
* The message [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_SET_ATTITUDE]is supported with the
 
The message [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_INFORMATION GIMBAL_DEVICE_INFORMATION], which should be requested anyways, can also be used to identify if it is a STorM32 gimbal, and thus if the STorM32 gimbal protocol v2 is available.
 
The STorM32 controller supports the [https://mavlink.io/en/services/gimbal_v2.html MAVLink Gimbal Protocol V2] in parts. It supports the gimbal device messages except of one, but does not support the gimbal manager messages defined in that standard.
 
The STorM32 controller implements its own dialect (storm32.xml) and the main part of it are alternative versions of the gimbal manager messages (identifiable by the label STORM32 in the names). They may look somewhat similar to the standard messages, but in fact implement a very different concept for the gimbal manager operation as compared to the standard.-->
<!--
The STorM32 controller can act as a gimbal device. This is the default mode, and active if the STorM32 controller is not in gimbal manager mode. It supports the gimbal device related {{MAVLINK|GIMBAL_DEVICE_XXX}} messages. It also handles incoming {{MAVLINK|AUTOPILOT_STATE_FOR_GIMBAL_DEVICE}} messages, and uses it for the [[STorM32-Link]].
 
The STorM32 controller can also be put into gimbal manager mode. In this mode in addition the {{MAVLINK|GIMBAL_MANAGER_XXX}} messages as well as the command {{MAVLINK|MAV_CMD_DO_GIMBAL_MANAGER_TILTPAN}} are supported. The message {{MAVLINK|GIMBAL_DEVICE_SET_ATTITUDE}} is denied. If another gimbal manager is found in the system, then the gimbal manager mode is terminated and the STorM32 controller falls back to default (gimbal device) behavior. The gimbal manager mode is not compliant with the MAVLink standard; use it (only) in combination with projects of the OlliW ecosystem (BetaPilot, MAVLink for OpenTx, easyMav).
 
The old (v1) and new (v2) gimbal protocol messages are accepted simultaneously, when not in gimbal manager mode. For example, the STorM32 controller can also always be controlled via the {{MAVLINK|DO_MOUNT_CONTROL}} command. The user is responsible for configuring her/his setup such that the old and new gimbal protocol messages don't interfere. In gimbal manager mode, the {{MAVLINK|DO_MOUNT_CONFIGURE}} and {{MAVLINK|DO_MOUNT_CONTROL}} commands are denied.
-->
 
= Virtual Channels =
 
The STorM32 controller listens to the [https://mavlink.io/en/messages/common.html#RC_CHANNELS RC_CHANNELS] and the mLRS specific RADIO_RC_CHANNELS MAVLink messages, and can be configured to use their channel values as virtual input (for configuration see e.g. the manual [[Using STorM32 with BetaPilot]] or [[Using STorM32 with ArduPilot]]).
 
In this configuration, all STorM32 [[Inputs and Functions|functions]] can be invoked by selecting any of the {{PARAMVALUE|Virtual-1}} - {{PARAMVALUE|Virtual-16}} input channels, exactly as one would do it if the STorM32 controller would be directly connected to a receiver by traditional means (PWM, PPM, sbus, and so on), except that the ppm values for the virtual input channels are read off the RC_CHANNELS or RADIO_RC_CHANNELS MAVLink message. This allows us to do many useful things, such as activating a script or triggering video on/off from the transmitter.


{{COMMENT|The STorM32 controller always accepts and serves incoming MAVLink messages on any of its serial ports, irrespective of the {{PARAMNAME|Mavlink Gimbal}}, {{PARAMNAME|Mavlink Camera}} and {{PARAMNAME|Mavlink ComPort}} settings. However, all outgoing messages such as heartbeats are emitted only on the selected serial port, and this port also does not accept incoming serial commands, i.e., is exclusive for MAVLink communication.}}
{{COMMENT|The STorM32 controller is not requesting the RC_CHANNELS MAVLink message by itself. This must be achieved by e.g. the flight controller, and the how to do it depends on specifics such as flight controller firmware, system setup, and so on. Usually, the flight controller has an option which makes it streaming this message. In case of BetaPilot, this message is streamed by default.}}


{{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.}}
= STorM32-Link =


{{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.}}
The STorM32 controller listens to the [https://mavlink.io/en/messages/common.html#AUTOPILOT_STATE_FOR_GIMBAL_DEVICE AUTOPILOT_STATE_FOR_GIMBAL_DEVICE] MAVLink message, and can be configured to use its data for the [[STorM32-Link]].
 
For details on the configuration, please read the manual [[Using STorM32 with BetaPilot]].


= Pass-Through =
= 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.
It is possible to connect the STorM32 GUI to any routing component in a MAVLink system, such as the autopilot or an 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.
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 {{GUIFIELD|MAVLink}} checkbox, which is located next to the {{GUIFIELD|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).
The pass-through mode of operation is enabled by checking in the GUI the {{GUIFIELD|MAVLink}} checkbox, which is located next to the {{GUIFIELD|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 {{MAVLINK|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 compatible autopilot.}}
{{COMMENT|The pass-through communication is based on standard MAVLink, and thus should work with any MAVLink standard compliant autopilot. The bottom line is that it may not work on systems which do not fully support the MAVLink standard.}}


{{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|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 firmwares won't work.}}
{{COMMENT|GUI features 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:
This preliminary demo video demonstrates the pass-through feature:
Line 59: Line 107:
|}
|}


= MAVLink FTP =
= MAVLink Parameters =
 
All STorM32 parameters are exposed to the MAVLink parameter interface, i.e., the STorM32 controller can equally be configured also via MAVLink.


The MAVLink Camera component supports the [https://mavlink.io/en/services/ftp.html MAVLink FTP micro service] to the extend that it allows us to download the various camera definition files stored in the STorM32 controller.  
The MAVLink parameter names are slightly different to the names in the GUI, but the differences are small enough to allow unique identification. Both the normal [https://mavlink.io/en/services/parameter.html parameter protocol] as well as the [https://mavlink.io/en/services/parameter_ext.html extended parameter protocol] are supported. The parameter values are [https://mavlink.io/en/services/parameter.html#parameter-encoding byte-wise] encoded (the [https://mavlink.io/en/messages/common.html#MAV_PROTOCOL_CAPABILITY_PARAM_ENCODE_BYTEWISE MAV_PROTOCOL_CAPABILITY_PARAM_ENCODE_BYTEWISE] bit is set in the capabilities field of the [https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION AUTOPILOT_VERSION] message).


On STorM32 boards with F103RE chip (the typical STorM32 board has a F103RC chip), also the MAVLink Gimbal component supports MAVLinkFTP; it allows us to download the component definition files stored in the STorM32 controller.
{{COMMENT|The parameters are only written to but not stored permanently into the STorM32 controller when they are changed by sending a PARAM_SET or PARAM_EXT_SET message. In order to store the settings permanently the MAVLink command [https://mavlink.io/en/messages/common.html#MAV_CMD_PREFLIGHT_STORAGE MAV_CMD_PREFLIGHT_STORAGE] needs to be send to the STorM32 controller with param1 &#x3d; 1. Some ground control stations, like MissionPlanner, do send the MAV_CMD_PREFLIGHT_STORAGE message, some others do not.}}


{{COMMENT|For the MAVLink Gimbal, MAVLinkFTP is currently enabled also on STorM32 boards with F103RC chip, but this is so only momentarily for testing purposes and will be disabled eventually.}}
= MAVLink FTP =
 
The MAVLink Gimbal and MAVLink Camera components support the [https://mavlink.io/en/services/ftp.html MAVLink FTP micro service], which allows us to download various gimbal and camera definition files stored in the STorM32 controller.  


=== Supported OpCodes/Commands ===
=== Supported OpCodes/Commands ===
Line 77: Line 129:
  MAVFTP_OPCODE_ReadFile
  MAVFTP_OPCODE_ReadFile
  MAVFTP_OPCODE_CalcFileCRC32
  MAVFTP_OPCODE_CalcFileCRC32
MAVFTP_OPCODE_BurstReadFile


= Comments on Compatibility =
<!--= MAVLink Events =
 
The MAVLink Gimbal component makes use of the [https://mavlink.io/en/services/events.html MAVLink event micro service] in order to report the prearm status flags. The event definition json file can be found [https://github.com/olliw42/storm32bgc/blob/master/mavlink/storm32_meta_events_v262.json here].
 
Divergent from the protocol, the [https://mavlink.io/en/messages/common.html#REQUEST_EVENT REQUEST_EVENT] message is not served by sending a stream of reponses for each requested event, but by (re)sending only the last event.
 
The prearm checks need to be enabled, by setting the parameter {{PARAMNAME|Prearm Checks}} to a non-zero value.
-->
= Testing the Connection =
 
The serial MAVLink connection can be tested in several ways. Suggestions are given in [[Using_STorM32_with_BetaPilot#Testing_the_Connection | Using STorM32 with BetaPilot: Testing the Connection]].
 
= MAVLink Gimbal =
 
Setting the {{PARAMNAME|Mavlink Gimbal}} parameter enables the MAVLink Gimbal component, and also determines its component ID: {{PARAMVALUE|Gimbal1}} corresponds to {{MAVLINK|MAV_COMP_ID_GIMBAL}} (= 154), {{PARAMVALUE|Gimbal2}} to {{MAVLINK|MAV_COMP_ID_GIMBAL2}} (= 171), {{PARAMVALUE|Gimbal3}} to {{MAVLINK|MAV_COMP_ID_GIMBAL3}} (= 172),  and so on.
 
* {{PARAMNAME|Mavlink Gimbal}} = {{PARAMVALUE|Gimbal1}} or higher
* {{PARAMNAME|Mavlink Gimbal Stream}}: Activates the emission of the selected message with a frequency of 4 Hz. Also determines if the STorM32 controller is in gimbal device or gimbal manager operation mode.
 
The system ID can be adjusted via the {{PARAMNAME|Mavlink System ID}} parameter, which usually can be left at its default value (0).
 
The gimbal device ID, which is relevant for the [[#Gimbal Protocol V2|Gimbal Protocol V2]] and [[#Gimbal Protocol V2|STorM32 Gimbal Protocol]] extensions, is always set to be identical to the component ID.


The STorM32's MAVLink support is fully compatible with the MAVLink standard (much time has been actually invested into ensuring this).  
The STorM32 controller becomes a '''''gimbal manager''''' when {{PARAMNAME|Mavlink Gimbal Stream}} = {{PARAMVALUE|manager status}} is set and it behaves as a '''''gimbal device''''' when {{PARAMNAME|Mavlink Gimbal Stream}} = {{PARAMVALUE|device status}} is set. Otherwise it behaves as in the "old" gimbal protocol.


However, not all flight stacks fully support the MAVLink standard.
A common setting for {{PARAMNAME|Mavlink Gimbal Stream}} is {{PARAMVALUE|device status}}, when newer autopilot and/or GCS firmwares are used (which properly support the v2 gimbal protocol). For older autopilot/GCS firmwares, one typically would select {{PARAMVALUE|mountstatus}}.


The MAVLink messages and commands related to the control of a gimbal as used by [http://ardupilot.org/ ArduPilot]-based systems are somewhat of a mess; they suffer from history, bugs, and wrong usage. This has lead to a variety of issues.
{{COMMENT|Note that unless STorM32 is in gimbal manager mode, it accepts both the newer gimbal device messages and the older mount messages. The difference is "only" that when it is in gimbal device mode it is stricter on enforcing the gimbal device rules (e.g. for RC control to work one needs to set the respective gimbal device flags).}}


A drastic example is the [https://3dr.com/solo-drone/ 3DR Solo] drone. Here the issue is a combination of all of them, the infamous "reversed signs", use of the non-standard/deprecated messages, and improper use of target system and component IDs: ArduPilot supports the official COMMAND_LONG commands (see [https://mavlink.io/en/services/gimbal.html Gimbal protocol]) as well as it's own MOUNT_CONFIGURE and MOUNT_CONTROL messages. For that reason, the STorM32 controller of course also supported these. However, the 3DR Solo firmware emits MOUNT_CONFIGURE/MOUNT_CONTROL messages with target (0,1), which are forwarded to the gimbal according to the [https://mavlink.io/en/guide/routing.html MAVLink routing] rules, whereas the ArduPilot mount class sends MAV_CMD_DO_MOUNT_CONTROL commands to the gimbal. This leads to the situation that the STorM32 receives both the commands and the messages, which however carry conflicting data, and in addition there is a bug in the ArduPilot code.
{{COMMENT|The STorM32's gimbal manager is not compliant to the v2 gimbal manager protocol, but the STorM32's version of a gimbal manager.}}


Therefore, the STorM32's behavior has been changed with firmware v2.42: The ArduPilot-specific MOUNT_CONFIGURE and MOUNT_CONTROL messages are '''''not''''' supported anymore (except if explicitly enabled by setting
The MAVLink Gimbal component supports the [https://mavlink.io/en/services/ftp.html File Transfer Protocol] micro service, which allows us to download e.g. component metadata .json files directly from the STorM32 gimbal controller.
{{PARAMNAME|Mavlink Version}} = {{PARAMVALUE|Mavlink1+v0.96}}).
<!--== Stream Options ==


This resolves issues like those with the 3DR Solo: The messages send out by the Solo and forwarded to the STorM32 are ignored, so that the STorM32 only acts on the proper commands from the flight controller (this still doesn't make things work very well in MAVLINK_TARGETING mode however due to another bug in the ArduPilot code, but that's the best the STorM32 can do).
The {{PARAMNAME|Mavlink Gimbal Stream}} parameter allows us to activate the emission of the selected message. It also determines the behavior of the STorM32 controller concerning the MAVLink Gimbal Protocol V2 and STorM32 Gimbal Protocol.


= MAVLink Gimbal =
The possible settings are:


The MAVLink Gimbal component is enabled with the {{PARAMNAME|Mavlink Gimbal}} parameter, which also determines its component ID: {{PARAMVALUE|Gimbal1}} corresponds to MAV_COMP_ID_GIMBAL (= 154), {{PARAMVALUE|Gimbal2}} to MAV_COMP_ID_GIMBAL2 (= 171), {{PARAMVALUE|Gimbal3}} to MAV_COMP_ID_GIMBAL3 (= 172),  and so on:
* {{PARAMVALUE|attitude}}: Streams the message ATTITUDE with 4 Hz. It otherwise has no effect on the STorM32 controller behavior.


* {{PARAMNAME|Mavlink Gimbal}} = {{PARAMVALUE|Gimbal1}} or higher
* {{PARAMVALUE|mountstatus}}: Streams the message MOUNT_STATUS with 4 Hz. It otherwise has no effect on the STorM32 controller behavior.
* {{PARAMNAME|Mavlink Gimbal Stream}}: Activates the emission of the selected message with a frequency of 4 Hz.


The system ID can be adjusted via the {{PARAMNAME|Mavlink System ID}} parameter, which usually can be left at its default value.
* {{PARAMVALUE|device status}}: Streams the message STORM32_GIMBAL_DEVICE_STATUS with 4 Hz.


With the setting {{PARAMNAME|Mavlink Version}} = {{PARAMVALUE|Mavlink1+v0.96}}, the "old" MAVLink behavior is enabled. Especially, the ArduPilot-specific messages [https://mavlink.io/en/messages/ardupilotmega.html#DIGICAM_CONTROL DIGICAM_CONTROL], [https://mavlink.io/en/messages/ardupilotmega.html#MOUNT_CONFIGURE MOUNT_CONFIGURE], and [https://mavlink.io/en/messages/ardupilotmega.html#MOUNT_CONTROL MOUNT_CONTROL] are then also supported.
* {{PARAMVALUE|manager status}}: Streams the messages STORM32_GIMBAL_DEVICE_STATUS and STORM32_GIMBAL_MANAGER_STATUS with 4 Hz and 1 Hz respectively.


* {{PARAMVALUE|v2 status}}: Streams the message GIMBAL_DEVICE_ATTITUDE_STATUS with 4 Hz. Comment: This setting is not available through the GUI, it needs to be set by other means (e.g. by a companion sending a respective MAVLink message).
-->
== Messages ==
== Messages ==


The following MAVLink messages are supported:
The following MAVLink messages are supported by the STorM32 gimbal component:


==== MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00) ====
==== MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00) (out) ====


See [https://mavlink.io/en/messages/common.html#HEARTBEAT HEARTBEAT].  
See [https://mavlink.io/en/messages/common.html#HEARTBEAT HEARTBEAT].  


The emission of the heartbeat needs to be activated in the GUI via the {{PARAMNAME|Mavlink Gimbal}} parameter. The heartbeat is emitted at 1 Hz, with the following values:
The emission of the heartbeat needs to be activated in the GUI via the {{PARAMNAME|Mavlink Gimbal}} parameter. The heartbeat is emitted at 1 Hz, with the following values:
* type: MAV_TYPE_GIMBAL (= 26)
  * type: MAV_TYPE_GIMBAL (= 26)
* autopilot: MAV_AUTOPILOT_INVALID (= 8)
  * autopilot: MAV_AUTOPILOT_INVALID (= 8)
* base_mode: MAV_MODE_FLAG_SAFETY_ARMED (= 0x80) is set in NORMAL mode, MAV_MODE_FLAG_CUSTOM_MODE_ENABLED (= 0x01) is always set
  * base_mode:  
* custom_mode: STATE value of the o323bgc firmware
      when in NORMAL mode MAV_MODE_FLAG_STABILIZE_ENABLED (= 0x10) and MAV_MODE_FLAG_SAFETY_ARMED (= 0x80) are set
* system_status: either MAV_STATE_BOOT (= 1), MAV_STATE_ACTIVE (= 4) or MAV_STATE_EMERGENCY (= 6)
  * custom_mode:
      lowest byte (0x000000FF): STATE value
      2nd & 3rd bytes (0x00FFFF00): prearm checks flags
      highest bit (0x80000000): bit is set if prearm checks are 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) (in) ====
 
See [https://mavlink.io/en/messages/common.html#SYSTEM_TIME SYSTEM_TIME].
 
The UNIX epoch time in this message is logged by the NT Logger (if time_unix_usec is > 0). The {{MAVLINK|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.


==== MAVLINK_MSG_ID_PARAM_REQUEST_READ (#20, 0x14) ====
==== MAVLINK_MSG_ID_PARAM_REQUEST_READ (#20, 0x14) (in) ====


See [https://mavlink.io/en/messages/common.html#PARAM_REQUEST_READ PARAM_REQUEST_READ].
See [https://mavlink.io/en/messages/common.html#PARAM_REQUEST_READ PARAM_REQUEST_READ].


==== MAVLINK_MSG_ID_PARAM_REQUEST_LIST (#21, 0x15) ====
==== MAVLINK_MSG_ID_PARAM_REQUEST_LIST (#21, 0x15) (in) ====


See [https://mavlink.io/en/messages/common.html#PARAM_REQUEST_LIST PARAM_REQUEST_LIST].
See [https://mavlink.io/en/messages/common.html#PARAM_REQUEST_LIST PARAM_REQUEST_LIST].


==== MAVLINK_MSG_ID_PARAM_VALUE (#22, 0x16) ====
==== MAVLINK_MSG_ID_PARAM_VALUE (#22, 0x16) (out) ====


See [https://mavlink.io/en/messages/common.html#PARAM_VALUE PARAM_VALUE].
See [https://mavlink.io/en/messages/common.html#PARAM_VALUE PARAM_VALUE].


==== MAVLINK_MSG_ID_PARAM_SET (#23, 0x17) ====
==== MAVLINK_MSG_ID_PARAM_SET (#23, 0x17) (in) ====


See [http://mavlink.org/messages/common#PARAM_SET PARAM_SET].
See [http://mavlink.org/messages/common#PARAM_SET PARAM_SET].


==== MAVLINK_MSG_ID_ATTITUDE (#30, 0x1E) ====
==== MAVLINK_MSG_ID_RC_CHANNELS (#65, 0x41) (in) ====
 
See [https://mavlink.io/en/messages/common.html#ATTITUDE ATTITUDE].
 
The emission of the attitude message with 4 Hz can be activated in the GUI via the {{PARAMNAME|Mavlink Gimbal Stream}} parameter, and 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 [https://mavlink.io/en/messages/common.html#RC_CHANNELS RC_CHANNELS].
See [https://mavlink.io/en/messages/common.html#RC_CHANNELS RC_CHANNELS].
When an ArduPilot autopilot (= MAV_AUTOPILOT_ARDUPILOTMEGA) is detected, streaming of this message by the autopilot is requested with req_stream_id = MAV_DATA_STREAM_RC_CHANNELS and req_message_rate = 10.


The parameter {{PARAMNAME|Virtual Channel Configuration}} needs to be set to {{PARAMVALUE|serial}} for the values received by this message to become available for inputs as {{PARAMVALUE|Virtual-1}} to {{PARAMVALUE|Virtual-16}}.
The parameter {{PARAMNAME|Virtual Channel Configuration}} needs to be set to {{PARAMVALUE|serial}} for the values received by this message to become available for inputs as {{PARAMVALUE|Virtual-1}} to {{PARAMVALUE|Virtual-16}}.


==== MAVLINK_MSG_ID_COMMAND_INT (#75, 0x4B) ====
==== MAVLINK_MSG_ID_COMMAND_INT (#75, 0x4B) (in) ====


See [https://mavlink.io/en/messages/common.html#COMMAND_INT COMMAND_INT].
See [https://mavlink.io/en/messages/common.html#COMMAND_INT COMMAND_INT].


Same as for MAVLINK_MSG_ID_COMMAND_LONG, see next.
Same as for {{MAVLINK|MAVLINK_MSG_ID_COMMAND_LONG}}, see next.


==== MAVLINK_MSG_ID_COMMAND_LONG (#76, 0x4C) ====
==== MAVLINK_MSG_ID_COMMAND_LONG (#76, 0x4C) (in) ====


See [https://mavlink.io/en/messages/common.html#COMMAND_LONG COMMAND_LONG].  
See [https://mavlink.io/en/messages/common.html#COMMAND_LONG 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):
Each command is acknowledged with a {{MAVLINK|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)
  MAV_CMD_DO_SET_PARAMETER (#180, 0xB4)
Line 190: Line 270:


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


  MAV_CMD_DO_MOUNT_CONTROL (#205, 0xCD)
  MAV_CMD_DO_MOUNT_CONTROL (#205, 0xCD)
Line 196: Line 278:
  * param2 = roll, angle in degree
  * param2 = roll, angle in degree
  * param3 = yaw, angle in degree (COMMENT: the sign is opposite to convention!)
  * 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)
  * param7 = mount_mode (0 = MAV_MOUNT_MODE_RETRACT retracts and 1 = MAV_MOUNT_MODE_NEUTRAL recenters the camera)
&nbsp;
The command is denied in gimbal manager mode.


  MAV_CMD_DO_SET_CAM_TRIGG_DIST(#206, 0xCE)
  MAV_CMD_DO_SET_CAM_TRIGG_DIST (#206, 0xCE)
  * param1 = distance (must be 0, else denied)
  * param1 = distance (must be 0, else denied)
  * param3 = trigger camera once immediately  
  * param3 = trigger camera once immediately  
Line 210: Line 294:
       2: ignored, as it maybe harmful
       2: ignored, as it maybe harmful


  MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN(#246, 0xF6)
  MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN (#246, 0xF6)
  * param4
  * param3
       0: do nothing
       0: do nothing
       1: restart with full reset
       1: restart with full reset
       2: shut down motors
       2: shut down motors
* param4 = component ID, must be 0 or match gimbal ID


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


  MAV_CMD_SET_MESSAGE_INTERVAL (#511, 0x01FF)
  MAV_CMD_SET_MESSAGE_INTERVAL (#511, 0x01FF)
  * param1 =  MAVLink message ID
  * param1 =  message ID of the message to stream
      158: stream MOUNT_STATUS message (target is set according to param7, for details see message description)
      285: stream GIMBAL_DEVICE_ATTITUDE_STATUS message (target is set according to param7, see message description)
      60011: stream STORM32_GIMBAL_MANAGER_STATUS message (only if in gimbal manager mode)
<!--      60020: stream X_SHOT_MANAGER_STATUS message-->
  * param2 = interval between two messages, in microseconds; set to -1 to disable
  * param2 = interval between two messages, in microseconds; set to -1 to disable
  * param7 = request target
  * param7 = request target
  &nbsp;
  &nbsp;
The periodic emission of one of these messages can be requested:
  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.
  * ATTITUDE (message id = 30)
  * MOUNT_STATUS (message id = 158) (target is set according to param4, default is broadcasting)
  * MOUNT_ORIENTATION (message id = 265)
  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.


  MAV_CMD_REQUEST_MESSAGE (#512, 0x0200)
  MAV_CMD_REQUEST_MESSAGE (#512, 0x0200)
  * param1 = message ID of the requested message 
  * param1 = message ID of the requested message
      30: send ATTITUDE message
       148: send AUTOPILOT_VERSION message
       148: send AUTOPILOT_VERSION message
       158: send MOUNT_STATUS message (target is set according to param7, default is requester IDs)
       158: send MOUNT_STATUS message (target is set according to param7, default is requester IDs)
       265: send MOUNT_ORIENTATION message
       253: send STATUSTEXT message with firmware and board type information
<!--      280: send GIMBAL_MANAGER_INFORMATION message (only if in gimbal manager mode)-->
<!--      281: send GIMBAL_MANAGER_STATUS message (only if in gimbal manager mode)-->
      283: send GIMBAL_DEVICE_INFORMATION message
      285: send GIMBAL_DEVICE_ATTITUDE_STATUS message (target is set according to param7, default is requester IDs)
       300: send PROTOCOL_VERSION message
       300: send PROTOCOL_VERSION message
       700: send COMPONENT_INFORMATION message
       397: send COMPONENT_METADATA message
      60010: send STORM32_GIMBAL_MANAGER_INFORMATION message (only if in gimbal manager mode)
      60011: send STORM32_GIMBAL_MANAGER_STATUS message (only if in gimbal manager mode)
<!--      60020: send X_SHOT_MANAGER_STATUS message-->
  * param7 = response target
  * param7 = response target


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


  MAV_CMD_REQUEST_AUTOPILOT_CAPABILITIES (#520, 0x0208)
  MAV_CMD_REQUEST_AUTOPILOT_CAPABILITIES (#520, 0x0208)
   send AUTOPILOT_VERSION message
   send AUTOPILOT_VERSION message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)
 
MAV_CMD_DO_SEND_BANNER (#42428, 0xA5BC)
  send STATUSTEXT messages with banner
 
MAV_CMD_STORM32_DO_GIMBAL_MANAGER_CONTROL_PITCHYAW (#60002, 0xEA62)
  This command is handled in gimbal manager mode. The gimbal device ID (param7) must match the STorM32's gimbal component ID.


  MAV_CMD_REQUEST_COMPONENT_INFORMATION (#700)
  MAV_CMD_STORM32_DO_GIMBAL_MANAGER_SETUP (#60010, 0xEA6A)
   send COMPONENT_INFORMATION message
   This command is handled in gimbal manager mode. The gimbal device ID (param7) must match the STorM32's gimbal component ID.
  this is not official and work in progress, see https://github.com/mavlink/mavlink/issues/1133
<!--
MAV_CMD_QSHOT_DO_CONFIGURE (#60020, 0xEA74)
* param1 = shot mode
* param2 = shot state
-->


==== MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D) ====
==== MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D) (out) ====


See [https://mavlink.io/en/messages/common.html#COMMAND_ACK COMMAND_ACK].
See [https://mavlink.io/en/messages/common.html#COMMAND_ACK COMMAND_ACK].


==== MAVLINK_MSG_ID_AUTOPILOT_VERSION (#148, 0x94) ====
==== MAVLINK_MSG_ID_FILE_TRANSFER_PROTOCOL (#110, 0x6E) (in/out) ====
 
See [https://mavlink.io/en/messages/common.html#FILE_TRANSFER_PROTOCOL FILE_TRANSFER_PROTOCOL].
 
==== MAVLINK_MSG_ID_AUTOPILOT_VERSION (#148, 0x94) (out) ====
 
See [https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION AUTOPILOT_VERSION].
 
The flight_sw_version and board_version fields are set to the firmware version and board revision (firmware version: e.g. 262 for version v2.62x, board revision: e.g. 33 for v3.3 boards). VID and PID are set to 0x16D0 and 0x0FCB, respectively. UID is set to the STM32 UUID.
<!--
==== MAVLINK_MSG_ID_DIGICAM_CONTROL (#155, 0x9B) (in) ====
 
Not supported any further (was ArduPilot specific message, see [https://mavlink.io/en/messages/ardupilotmega.html#DIGICAM_CONTROL DIGICAM_CONTROL]).
 
==== MAVLINK_MSG_ID_MOUNT_CONFIGURE (#156, 0x9C) (in) ====
 
Not supported any further (was ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#MOUNT_CONFIGURE MOUNT_CONFIGURE]).


See [https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION AUTOPILOT_VERSION].
==== MAVLINK_MSG_ID_MOUNT_CONTROL (#157, 0x9D) (in) ====


==== MAVLINK_MSG_ID_MOUNT_STATUS (#158, 0x9E) ====
Not supported any further (was ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#MOUNT_CONTROL MOUNT_CONTROL]).
-->
==== MAVLINK_MSG_ID_MOUNT_STATUS (#158, 0x9E) (out) ====


ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#MOUNT_STATUS MOUNT_STATUS].  
ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#MOUNT_STATUS MOUNT_STATUS].  


The emission of the mount status message with 4 Hz can be activated in the GUI via the {{PARAMNAME|Mavlink Gimbal Stream}} parameter, and 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. The target is set to target_system = 0, target_component = 0, or as set by the MAV_CMD_SET_MESSAGE_INTERVAL command.-->
Emission of this message with 4 Hz can be activated in the GUI with the {{PARAMNAME|Mavlink Gimbal Stream}} parameter. It also can be emitted with a user defined rate by requesting a data stream with the {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} command, or by requesting a single-shot emission with the {{MAVLINK|MAV_CMD_REQUEST_MESSAGE}} command. The yaw angle is relative to the forward direction (vehicle frame).


==== MAVLINK_MSG_ID_AUTOPILOT_VERSION_REQUEST (#183, 0xB7) ====
The 4 Hz message stream activated with {{PARAMNAME|Mavlink Gimbal Stream}} is always broadcast. The messages emitted as result of {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} or {{MAVLINK|MAV_CMD_REQUEST_MESSAGE}} commands can be broadcast or targeted, as specified by param7 in the command. When requested with {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} it holds: 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, a broadcast stream at a low rate, e.g. to inform a GCS, plus a targeted stream at a high rate, e.g. to inform an on-board companion computer.
 
Consider to use the [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_ATTITUDE_STATUS GIMBAL_DEVICE_ATTITUDE_STATUS] message instead of MOUNT_STATUS, i.e., to set {{PARAMNAME|Mavlink Gimbal Stream}} = {{PARAMVALUE|device status}} for enabling a 4 Hz stream.
 
{{COMMENT|Broadcast message streams at high rate should be avoided, as they may overburden the telemetry link to the ground.}}
 
==== MAVLINK_MSG_ID_AUTOPILOT_VERSION_REQUEST (#183, 0xB7) (in) ====


ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#AUTOPILOT_VERSION_REQUEST AUTOPILOT_VERSION_REQUEST].
ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#AUTOPILOT_VERSION_REQUEST AUTOPILOT_VERSION_REQUEST].


==== MAVLINK_MSG_ID_MESSAGE_INTERVAL (#244, 0xF4) ====
Is supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead.
 
==== MAVLINK_MSG_ID_MESSAGE_INTERVAL (#244, 0xF4) (out) ====


See [https://mavlink.io/en/messages/common.html#MESSAGE_INTERVAL MESSAGE_INTERVAL].
See [https://mavlink.io/en/messages/common.html#MESSAGE_INTERVAL MESSAGE_INTERVAL].


==== MAVLINK_MSG_ID_STATUSTEXT (#253, 0xFD) ====
==== MAVLINK_MSG_ID_STATUSTEXT (#253, 0xFD) (out) ====


See [https://mavlink.io/en/messages/common.html#STATUSTEXT STATUSTEXT].  
See [https://mavlink.io/en/messages/common.html#STATUSTEXT STATUSTEXT].  


This message is sent out after a PARAM_REQUEST_LIST has been served, and provides firmware and board type information.
This message is sent out after a {{MAVLINK|PARAM_REQUEST_LIST}} has been served, and provides firmware and board type information. It also can be requested with the MAV_CMD_REQUEST_MESSAGE or MAV_CMD_DO_SEND_BANNER commands.
 
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_MANAGER_INFORMATION (#280, 0x118) (out) ====
 
See [https://mavlink.io/en/messages/common.html#GIMBAL_MANAGER_INFORMATION GIMBAL_MANAGER_INFORMATION].
 
This message can be requested in gimbal manager mode.
 
==== MAVLINK_MSG_ID_GIMBAL_MANAGER_STATUS (#281, 0x119) (out) ====
 
See [https://mavlink.io/en/messages/common.html#GIMBAL_MANAGER_STATUS GIMBAL_MANAGER_STATUS].
 
Used to detect the presence of a gimbal manager in the system. Streamed in gimbal manager mode.
 
==== MAVLINK_MSG_ID_GIMBAL_MANAGER_SET_ATTITUDE (#282, 0x11A) (in) ====
 
See [https://mavlink.io/en/messages/common.html#GIMBAL_MANAGER_SET_ATTITUDE GIMBAL_MANAGER_SET_ATTITUDE].
 
This message is handled in gimbal manager mode. The gimbal device ID must match the STorM32's gimbal component ID.
-->
 
==== MAVLINK_MSG_ID_GIMBAL_DEVICE_INFORMATION (#283, 0x11B) (out) ====
 
See [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_INFORMATION GIMBAL_DEVICE_INFORMATION].
 
The min/max values reported in this message are the RC Input Min/Max values for each axis, if the axis is enabled (for disabled axes NAN is reported).
 
==== MAVLINK_MSG_ID_GIMBAL_DEVICE_SET_ATTITUDE (#284, 0x11C) (in) ====
 
See [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_SET_ATTITUDE GIMBAL_DEVICE_SET_ATTITUDE].
 
Only handled if not in gimbal manager mode. Current limitations: Yaw in earth frame is not supported, even when the STorM32-Link is enabled and available. The velocity fields are not supported and ignored.
 
The message is rejected when not either the YAW_IN_VEHICLE_FRAME or the YAW_IN_EARTH_FRAME flag is set (that is, the legacy usage of this message is not supported).
 
==== MAVLINK_MSG_ID_GIMBAL_DEVICE_ATTITUDE_STATUS (#285, 0x11D) (out) ====
 
See [https://mavlink.io/en/messages/common.html#GIMBAL_DEVICE_ATTITUDE_STATUS GIMBAL_DEVICE_ATTITUDE_STATUS].
 
Emission of this message with 4 Hz can be activated in the GUI with the {{PARAMNAME|Mavlink Gimbal Stream}} parameter. It also can be emitted with a user defined rate by requesting a data stream with the {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} command, or by requesting a single-shot emission with the {{MAVLINK|MAV_CMD_REQUEST_MESSAGE}} command. The yaw angle in the message's quaternion is relative to the forward direction (vehicle frame) (the flag GIMBAL_DEVICE_FLAGS_YAW_IN_VEHICLE_FRAME is set and GIMBAL_DEVICE_FLAGS_YAW_IN_EARTH_FRAME is unset). The yaw angle relative to north (earth frame) can be determined from delta_yaw, if it is not unknown (not set to NaN).
 
The 4 Hz message stream activated with {{PARAMNAME|Mavlink Gimbal Stream}} is always broadcast. The messages emitted as result of {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} or {{MAVLINK|MAV_CMD_REQUEST_MESSAGE}} commands can be broadcast or targeted, as specified by param7 in the command. When requested with {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} it holds: 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, a broadcast stream at a low rate, e.g. to inform a GCS, plus a targeted stream at a high rate, e.g. to inform an on-board companion computer.
 
{{COMMENT|Broadcast message streams at high rate should be avoided, as they may overburden the telemetry link to the ground.}}
 
==== MAVLINK_MSG_ID_AUTOPILOT_STATE_FOR_GIMBAL_DEVICE (#286, 0x11E) (in) ====
 
See [https://mavlink.io/en/messages/common.html#AUTOPILOT_STATE_FOR_GIMBAL_DEVICE AUTOPILOT_STATE_FOR_GIMBAL_DEVICE].  


==== MAVLINK_MSG_ID_MOUNT_ORIENTATION (#265, 0x109) ====
This message can be send to the STorM32 controller and is then used for [[STorM32-Link]].


See [https://mavlink.io/en/messages/common.html#MOUNT_ORIENTATION MOUNT_ORIENTATION].
<!--
==== MAVLINK_MSG_ID_GIMBAL_MANAGER_SET_TILTPAN (#287, 0x11F) ====


The emission of the mount orientation message with 4 Hz can be activated in the GUI via the {{PARAMNAME|Mavlink Gimbal Stream}} parameter, and 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.
See [https://mavlink.io/en/messages/common.html#GIMBAL_MANAGER_SET_TILTPAN GIMBAL_MANAGER_SET_TILTPAN].


==== MAVLINK_MSG_ID_PROTOCOL_VERSION (#300, 0x12C) ====
This message is handled in gimbal manager mode. The gimbal device ID must match the STorM32's gimbal component ID.
-->
==== MAVLINK_MSG_ID_PROTOCOL_VERSION (#300, 0x12C) (out) ====


See [https://mavlink.io/en/messages/common.html#PROTOCOL_VERSION PROTOCOL_VERSION].
See [https://mavlink.io/en/messages/common.html#PROTOCOL_VERSION PROTOCOL_VERSION].


==== MAVLINK_MSG_ID_TUNNEL (#385, 0x181) ====
==== MAVLINK_MSG_ID_TUNNEL (#385, 0x181) (in/out) ====


See [https://mavlink.io/en/messages/common.html#TUNNEL TUNNEL].
See [https://mavlink.io/en/messages/common.html#TUNNEL TUNNEL].
Line 294: Line 477:
The STorM32 controller occupies the block of payload_type values from 200 - 209 (see [https://mavlink.io/en/messages/common.html#MAV_TUNNEL_PAYLOAD_TYPE 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.
The STorM32 controller occupies the block of payload_type values from 200 - 209 (see [https://mavlink.io/en/messages/common.html#MAV_TUNNEL_PAYLOAD_TYPE 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.


==== MAVLINK_MSG_ID_COMPONENT_INFORMATION (#700) ====
==== MAVLINK_MSG_ID_COMPONENT_METADATA (#397, 0x18D) (out) ====
 
See [https://mavlink.io/en/messages/common.html#COMPONENT_METADATA COMPONENT_METADATA].
 
<!--
==== MAVLINK_MSG_ID_EVENT (#410, 0x19A) (out) ====
 
See [https://mavlink.io/en/messages/common.html#EVENT EVENT].
 
Is emitted at intervals of 0.2 Hz, or immediately if the event status has changed. Is used to report the prearm status. Only emitted if prearm checks are enabled ({{PARAMNAME|Prearm Checks}} = non-zero value).
 
==== MAVLINK_MSG_ID_CURRENT_EVENT_SEQUENCE (#411, 0x19B) (out) ====
 
See [https://mavlink.io/en/messages/common.html#CURRENT_EVENT_SEQUENCE CURRENT_EVENT_SEQUENCE].
 
Is emitted at intervals of 0.2 Hz. Only emitted if prearm checks are enabled ({{PARAMNAME|Prearm Checks}} = non-zero value).
 
==== MAVLINK_MSG_ID_REQUEST_EVENT (#412, 0x19C) (in) ====
 
See [https://mavlink.io/en/messages/common.html#REQUEST_EVENT REQUEST_EVENT].
 
The request is served by sending the last event.
-->
==== MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_INFORMATION (#60010, 0xEA6A) (out) ====
 
STorM32 specific message. See [https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/storm32.xml storm32.xml].
 
Only emitted if in gimbal manager mode.
 
==== MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_STATUS (#60011, 0xEA6B) (out) ====
 
STorM32 specific message. See [https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/storm32.xml storm32.xml].
 
Emission of this message with 1 Hz can be activated in the GUI with the {{PARAMNAME|Mavlink Gimbal Stream}} parameter, can be emitted with a user defined rate by requesting a data stream with the {{MAVLINK|MAV_CMD_SET_MESSAGE_INTERVAL}} command, or by requesting a single-shot emission with the {{MAVLINK|MAV_CMD_REQUEST_MESSAGE}} command.
 
If the STorM32 controller is in gimbal manager mode and this message is received, then it will fall back to gimbal device mode (only one gimbal manager is allowed per gimbal).
 
==== MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_CONTROL (#60012, 0xEA6C) (in) ====
 
STorM32 specific message. See [https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/storm32.xml storm32.xml].
 
Only handled if in gimbal manager mode.
 
==== MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_CONTROL_PITCHYAW (#60013, 0xEA6D) (in) ====
 
STorM32 specific message. See [https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/storm32.xml storm32.xml].
 
Only handled if in gimbal manager mode.
 
==== MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_CORRECT_ROLL (#60014, 0xEA6E) (in) ====


This is not official and work in progress, see https://github.com/mavlink/mavlink/issues/1133.
STorM32 specific message. See [https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/storm32.xml storm32.xml].
 
Only handled if in gimbal manager mode.
 
==== MAVLINK_MSG_ID_RADIO_RC_CHANNELS (#60045, 0xEA8D) (in) ====
 
mLRS specific message. See [https://github.com/mavlink/mavlink/blob/0c7792edfeee7cf08e531cb4ce5b4f01854e5724/message_definitions/v1.0/storm32.xml storm32.xml].
 
The parameter {{PARAMNAME|Virtual Channel Configuration}} needs to be set to {{PARAMVALUE|serial}} for the values received by this message to become available for inputs as {{PARAMVALUE|Virtual-1}} to {{PARAMVALUE|Virtual-16}}.


= MAVLink Camera =
= MAVLink Camera =


The MAVLink Camera component is independent on the MAVLink Gimbal component, and can also be used then the MAVLink Gimbal component is disabled.
The MAVLink Camera component is independent on the MAVLink Gimbal component, and can also be used when the MAVLink Gimbal component is disabled.


The setting in the {{PARAMNAME|Mavlink Camera}} parameter enables the MAVLink Camera component, and determines its component ID: {{PARAMVALUE|Camera1}} corresponds to MAV_COMP_ID_CAMERA (= 100), {{PARAMVALUE|Camera2}} to MAV_COMP_ID_CAMERA2 (= 101), and so on. In addition, MAVLink 2 must be enabled; otherwise many functions of the MAVLink Camera component won't work properly:
Setting the {{PARAMNAME|Mavlink Camera}} parameter enables the MAVLink Camera component, and determines its component ID: {{PARAMVALUE|Camera1}} corresponds to {{MAVLINK|MAV_COMP_ID_CAMERA}} (= 100), {{PARAMVALUE|Camera2}} to {{MAVLINK|MAV_COMP_ID_CAMERA2}} (= 101), and so on.


* {{PARAMNAME|Mavlink Camera}} = {{PARAMVALUE|Camera1}} or higher
* {{PARAMNAME|Mavlink Camera}} = {{PARAMVALUE|Camera1}} or higher
* {{PARAMNAME|Mavlink Version}} = {{PARAMVALUE|Mavlink2}}


The system ID of the MAVLink Camera component is determined by the parameter {{PARAMNAME|Mavlink System ID}}, which is also used by the MAVLink Gimbal component, and usually can be left at its default value.
The system ID of the MAVLink Camera component is determined by the parameter {{PARAMNAME|Mavlink System ID}}, which is also used by the MAVLink Gimbal component, and usually can be left at its default value (0).


The MAVLink Camera component supports the [https://mavlink.io/en/services/ftp.html File Transfer Protocol] micro service, which allows us to download the camera definition .xml files directly from the STorM32 gimbal controller.  
The MAVLink Camera component supports the [https://mavlink.io/en/services/ftp.html File Transfer Protocol] micro service, which allows us to download the camera definition .xml files directly from the STorM32 gimbal controller. They are stored in .xz compressed format (i.e. the extension of the respective file is .xml.xz).


The MAVLink Camera component is deeply related to the [[NT Camera]]. This means that it works in conjunction with the {{PARAMNAME|Camera Control}} function and associated parameters in the {{GUI|Functions}} tab.
The MAVLink Camera component is deeply related to the [[NT Camera]]. This means that it works in conjunction with the {{PARAMNAME|Camera Control}} function and associated parameters in the {{GUI|Functions}} tab.
Line 317: Line 556:
== Messages ==
== Messages ==


The following MAVLink messages are supported:
The following MAVLink messages are supported by the STorM32 camera component:


==== MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00) ====
==== MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00) ====
Line 326: Line 565:
* type: MAV_TYPE_CAMERA (= 30)
* type: MAV_TYPE_CAMERA (= 30)
* autopilot: MAV_AUTOPILOT_INVALID (= 8)
* autopilot: MAV_AUTOPILOT_INVALID (= 8)
* base_mode: 0
* base_mode: MAV_MODE_FLAG_SAFETY_ARMED (= 0x80)
* custom_mode: 0
* custom_mode: highest bit (0x80000000) = set if prearm checks have not passed
* system_status: MAV_STATE_ACTIVE (= 4)
* system_status: MAV_STATE_ACTIVE (= 4)
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_PARAM_REQUEST_READ (#20, 0x14) ====
==== MAVLINK_MSG_ID_PARAM_REQUEST_READ (#20, 0x14) ====
Line 345: Line 586:


See [http://mavlink.org/messages/common#PARAM_SET PARAM_SET].
See [http://mavlink.org/messages/common#PARAM_SET PARAM_SET].
<!--
==== MAVLINK_MSG_ID_RC_CHANNELS_RAW (#35, 0x23) ====
See [https://mavlink.io/en/messages/common.html#RC_CHANNELS_RAW RC_CHANNELS_RAW].
The parameter {{PARAMNAME|Virtual Channel Configuration}} needs to be set to {{PARAMVALUE|serial}} for the values received by this message to become available for inputs as {{PARAMVALUE|Virtual-1}} to {{PARAMVALUE|Virtual-8}}. The inputs for {{PARAMVALUE|Virtual-9}} to {{PARAMVALUE|Virtual-16}} are set to center.
-->
==== MAVLINK_MSG_ID_RC_CHANNELS (#65, 0x41) ====
See [https://mavlink.io/en/messages/common.html#RC_CHANNELS RC_CHANNELS].
The parameter {{PARAMNAME|Virtual Channel Configuration}} needs to be set to {{PARAMVALUE|serial}} for the values received by this message to become available for inputs as {{PARAMVALUE|Virtual-1}} to {{PARAMVALUE|Virtual-16}}.


==== MAVLINK_MSG_ID_COMMAND_INT (#75, 0x4B) ====
==== MAVLINK_MSG_ID_COMMAND_INT (#75, 0x4B) ====
Line 350: Line 603:
See [https://mavlink.io/en/messages/common.html#COMMAND_INT COMMAND_INT].  
See [https://mavlink.io/en/messages/common.html#COMMAND_INT COMMAND_INT].  


Same as for MAVLINK_MSG_ID_COMMAND_LONG, see next.
Same as for {{MAVLINK|MAVLINK_MSG_ID_COMMAND_LONG}}, see next.


==== MAVLINK_MSG_ID_COMMAND_LONG (#76, 0x4C) ====
==== MAVLINK_MSG_ID_COMMAND_LONG (#76, 0x4C) ====
Line 356: Line 609:
See [https://mavlink.io/en/messages/common.html#COMMAND_LONG COMMAND_LONG].  
See [https://mavlink.io/en/messages/common.html#COMMAND_LONG 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):
Each command is acknowledged with a {{MAVLINK|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_DIGICAM_CONFIGURE (#202, 0xCA)
  MAV_CMD_DO_DIGICAM_CONFIGURE (#202, 0xCA)
Line 382: Line 635:
       147: send BATTERY_STATUS message
       147: send BATTERY_STATUS message
       148: send AUTOPILOT_VERSION message
       148: send AUTOPILOT_VERSION message
      253: send STATUSTEXT message with firmware and board type information
       259: send CAMERA_INFORMATION message
       259: send CAMERA_INFORMATION message
       260: send CAMERA_SETTINGS message
       260: send CAMERA_SETTINGS message
       261: send STORAGE_INFORMATION message
       261: send STORAGE_INFORMATION message
       262: send CAMERA_CAPTURE_STATUS message
       262: send CAMERA_CAPTURE_STATUS message
      263: (CAMERA_IMAGE_CAPTURED) returns COMMAND_ACK with MAV_CMD_ACK_DENIED
       300: send PROTOCOL_VERSION message
       300: send PROTOCOL_VERSION message
      397: send COMPONENT_METADATA message
  * param7 = response target
  * param7 = response target


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


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


  MAV_CMD_REQUEST_CAMERA_INFORMATION (#521, 0x0209)
  MAV_CMD_REQUEST_CAMERA_INFORMATION (#521, 0x0209)
  * param1 = request camera capabilities
  * param1 = request camera capabilities
       1: send CAMERA_INFORMATION message
       1: send CAMERA_INFORMATION message
(supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)


  MAV_CMD_REQUEST_CAMERA_SETTINGS (#522, 0x020A)
  MAV_CMD_REQUEST_CAMERA_SETTINGS (#522, 0x020A)
   send CAMERA_SETTINGS message
   send CAMERA_SETTINGS message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)


  MAV_CMD_REQUEST_STORAGE_INFORMATION (#525, 0x020D)
  MAV_CMD_REQUEST_STORAGE_INFORMATION (#525, 0x020D)
   send STORAGE_INFORMATION message
   send STORAGE_INFORMATION message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)


  MAV_CMD_STORAGE_FORMAT (#526, 0x020E)
  MAV_CMD_STORAGE_FORMAT (#526, 0x020E)
Line 409: Line 666:


  MAV_CMD_REQUEST_CAMERA_CAPTURE_STATUS (#527, 0x020F)
  MAV_CMD_REQUEST_CAMERA_CAPTURE_STATUS (#527, 0x020F)
   send CAMERA_CAPTURE_STATUS message
   send CAMERA_CAPTURE_STATUS message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)


  MAV_CMD_RESET_CAMERA_SETTINGS (#529, 0x0211)
  MAV_CMD_RESET_CAMERA_SETTINGS (#529, 0x0211)
Line 418: Line 675:


  MAV_CMD_SET_CAMERA_ZOOM (#531, 0x0213)
  MAV_CMD_SET_CAMERA_ZOOM (#531, 0x0213)
  returns COMMAND_ACK with MAV_CMD_ACK_DENIED
* param1 = zoom type
* param2 = zoom level


  MAV_CMD_SET_CAMERA_FOCUS (#532, 0x0214)
  MAV_CMD_SET_CAMERA_FOCUS (#532, 0x0214)
Line 432: Line 690:


  MAV_CMD_REQUEST_CAMERA_IMAGE_CAPTURE (#2002, 0x07D2)
  MAV_CMD_REQUEST_CAMERA_IMAGE_CAPTURE (#2002, 0x07D2)
   returns COMMAND_ACK with MAV_CMD_ACK_DENIED
   returns COMMAND_ACK with MAV_CMD_ACK_DENIED (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)


  MAV_CMD_VIDEO_START_CAPTURE (#2500, 0x09C4)
  MAV_CMD_VIDEO_START_CAPTURE (#2500, 0x09C4)
Line 440: Line 698:
  MAV_CMD_VIDEO_STOP_CAPTURE (#2501, 0x09C5)
  MAV_CMD_VIDEO_STOP_CAPTURE (#2501, 0x09C5)
  * param1 = video stream ID
  * param1 = video stream ID
MAV_CMD_DO_SEND_BANNER (#42428, 0xA5BC)
  send STATUSTEXT messages with banner


==== MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D) ====
==== MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D) ====
Line 458: Line 719:


See [https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION AUTOPILOT_VERSION].
See [https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION 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_AUTOPILOT_VERSION_REQUEST (#183, 0xB7) ====
==== MAVLINK_MSG_ID_AUTOPILOT_VERSION_REQUEST (#183, 0xB7) ====


ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#AUTOPILOT_VERSION_REQUEST AUTOPILOT_VERSION_REQUEST].
ArduPilot specific message. See [https://mavlink.io/en/messages/ardupilotmega.html#AUTOPILOT_VERSION_REQUEST AUTOPILOT_VERSION_REQUEST].
Is supported, but deprecated, use MAV_CMD_REQUEST_MESSAGE instead.
==== MAVLINK_MSG_ID_STATUSTEXT (#253, 0xFD) ====
See [https://mavlink.io/en/messages/common.html#STATUSTEXT STATUSTEXT].
This message is sent out after a {{MAVLINK|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_CAMERA_INFORMATION (#259, 0x103) ====
==== MAVLINK_MSG_ID_CAMERA_INFORMATION (#259, 0x103) ====
Line 511: Line 784:
See [https://mavlink.io/en/messages/common.html#TUNNEL TUNNEL].
See [https://mavlink.io/en/messages/common.html#TUNNEL TUNNEL].


The STorM32 controller occupies the block of payload_type values from 200 - 209 (see [https://mavlink.io/en/messages/common.html#MAV_TUNNEL_PAYLOAD_TYPE MAV_TUNNEL_PAYLOAD_TYPE]). The MAVLink Camera component supports the payload types 200 and 201 for communicating with the GUI.
The STorM32 controller occupies the block of payload_type values from 200 - 209 (see [https://mavlink.io/en/messages/common.html#MAV_TUNNEL_PAYLOAD_TYPE MAV_TUNNEL_PAYLOAD_TYPE]). The MAVLink Camera component supports the payload types 200 and 201 for communicating with the GUI. Payload types 204 and 205 are used for NT Camera implementations on a companion.
 
==== MAVLINK_MSG_ID_COMPONENT_METADATA (#397, 0x18D) ====
 
See [https://mavlink.io/en/messages/common.html#COMPONENT_METADATA COMPONENT_METADATA].
 
==== MAVLINK_MSG_ID_RADIO_RC_CHANNELS (#60045, 0xEA8D) (in) ====
 
mLRS specific message. See [https://github.com/mavlink/mavlink/blob/0c7792edfeee7cf08e531cb4ce5b4f01854e5724/message_definitions/v1.0/storm32.xml storm32.xml].
 
The parameter {{PARAMNAME|Virtual Channel Configuration}} needs to be set to {{PARAMVALUE|serial}} for the values received by this message to become available for inputs as {{PARAMVALUE|Virtual-1}} to {{PARAMVALUE|Virtual-16}}.
 
= Comments on Compatibility =
 
STorM32's MAVLink support fully embraces the MAVLink standard, as defined by the MAVLink project ([https://github.com/mavlink/mavlink], [https://mavlink.io/en/ mavlink.io]).
 
However, some implementations may not support all messages of the MAVLink standard, or may implement some of them differently/incorrectly.
 
=== ArduPilot ===
 
Generally, ArduPilot's handling and routing of the gimbal and camera MAVLink messages and commands can have its issues, and can vary a lot with version. Besides flaws, issues arrise often because of non-standard conform use of MAVLink messages or violating the MAVLink protocol itself. It is best to explore the situation carefully for the ArduPilot version in use.
 
See also [[Using STorM32 with ArduPilot]].
 
=== PX4 ===
 
TBD.

Latest revision as of 04:01, 27 February 2024

The information on this page refers to firmware v2.70a 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 Gimbal Protocol v2, 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 STorM32's 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 device or gimbal manager operation 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 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).

The baudrate of the serial port selected with Mavlink ComPort is determined by the respective baudrate parameter in the [GUI:Interfaces Tool] window. Per default it is 115200 bps. It is recommended to use a baudrate of 230400 bps, if possible.

Comment: In the [GUI:Dashboard] Info Center, the MAVLINK field 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 are 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 it will not emit any MAVLink messages such as heartbeats.

Comment: Implication of the previous comment: If the USB port is selected in Mavlink ComPort one cannot connect to the GUI via the STorM32's USB port anymore.

Comment: For v1.3x boards: If the UART port is selected for MAVLink, then the BT module and the serial MAVLink connection cannot be used at the same time.

MAVLink Protocol Version

STorM32 uses the MAVLink v2 protocol version.

It also supports the MAVLink v1 protocol insofar as it properly reads and handles incoming MAVLink v1 packets, but it does not send out v1 packets, i.e., all MAVLink messages emitted by the STorM32 controller are in the MAVLink v2 protocol format.

Comment: In older STorM32 firmware versions it was possible to choose between MAVLink v1 and v2 formats. This option has been removed, there really should be no reason nowadays anymore to not use MAVLink v2.

Gimbal Protocol V2

The STorM32 controller fully supports the gimbal device messages of the MAVLink Gimbal Protocol V2 standard (i.e. can operate as a v2 compliant gimbal device); it does not support the gimbal manager messages of this protocol (i.e. cannot be used as a v2 compliant gimbal manager).

In detail: The messages GIMBAL_DEVICE_INFORMATION, GIMBAL_DEVICE_ATTITUDE_STATUS, GIMBAL_DEVICE_SET_ATTITUDE, and AUTOPILOT_STATE_FOR_GIMBAL_DEVICE are fully supported. Note: This does not imply that all possible functionality is supported, e.g., currently YAW_IN_EARTH_FRAME is not supported.

In addition, the STorM32 controller implements its own MAVLink dialect (storm32.xml). A main part of it is the STorM32 Gimbal Protocol, which defines the STorM32's versions of the gimbal manager messages (identifiable by the 'STORM32' label in the names). They may look somewhat similar to the standard gimbal manager messages, and they can indeed adopt the same behavior and functionality as the standard, but the underlying concept provides a richer and more mature concept for gimbal operation than the standard. For details please consult the article STorM32 Gimbal Protocol.

In order to identify a STorM32 gimbal, e.g. to determine if the STorM32's extensions are available, request the GIMBAL_DEVICE_INFORMATION message. The vendor name and model name fields are populated with "olliw.eu" and "STorM32", respectively, which should allow unambiguous identification. One also can request the AUTOPILOT_VERSION message. The VID and PID are 0x16D0 and 0x0FCB, and they are globally unique to the STorM32 controller.

Virtual Channels

The STorM32 controller listens to the RC_CHANNELS and the mLRS specific RADIO_RC_CHANNELS MAVLink messages, and can be configured to use their channel values as virtual input (for configuration see e.g. the manual Using STorM32 with BetaPilot or Using STorM32 with ArduPilot).

In this configuration, all STorM32 functions can be invoked by selecting any of the “Virtual-1” - “Virtual-16” input channels, exactly as one would do it if the STorM32 controller would be directly connected to a receiver by traditional means (PWM, PPM, sbus, and so on), except that the ppm values for the virtual input channels are read off the RC_CHANNELS or RADIO_RC_CHANNELS MAVLink message. This allows us to do many useful things, such as activating a script or triggering video on/off from the transmitter.

Comment: The STorM32 controller is not requesting the RC_CHANNELS MAVLink message by itself. This must be achieved by e.g. the flight controller, and the how to do it depends on specifics such as flight controller firmware, system setup, and so on. Usually, the flight controller has an option which makes it streaming this message. In case of BetaPilot, this message is streamed by default.

STorM32-Link

The STorM32 controller listens to the AUTOPILOT_STATE_FOR_GIMBAL_DEVICE MAVLink message, and can be configured to use its data for the STorM32-Link.

For details on the configuration, please read the manual Using STorM32 with BetaPilot.

Pass-Through

It is possible to connect the STorM32 GUI to any routing component in a MAVLink system, such as the autopilot or an 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 with any MAVLink standard compliant autopilot. The bottom line is that it may not work on systems which do not fully support the MAVLink standard.

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 features 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 Parameters

All STorM32 parameters are exposed to the MAVLink parameter interface, i.e., the STorM32 controller can equally be configured also via MAVLink.

The MAVLink parameter names are slightly different to the names in the GUI, but the differences are small enough to allow unique identification. Both the normal parameter protocol as well as the extended parameter protocol are supported. The parameter values are byte-wise encoded (the MAV_PROTOCOL_CAPABILITY_PARAM_ENCODE_BYTEWISE bit is set in the capabilities field of the AUTOPILOT_VERSION message).

Comment: The parameters are only written to but not stored permanently into the STorM32 controller when they are changed by sending a PARAM_SET or PARAM_EXT_SET message. In order to store the settings permanently the MAVLink command MAV_CMD_PREFLIGHT_STORAGE needs to be send to the STorM32 controller with param1 = 1. Some ground control stations, like MissionPlanner, do send the MAV_CMD_PREFLIGHT_STORAGE message, some others do not.

MAVLink FTP

The MAVLink Gimbal and MAVLink Camera components support the MAVLink FTP micro service, which allows us to download various gimbal and 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
MAVFTP_OPCODE_BurstReadFile

Testing the Connection

The serial MAVLink connection can be tested in several ways. Suggestions are given in Using STorM32 with BetaPilot: Testing the Connection.

MAVLink Gimbal

Setting the Mavlink Gimbal parameter enables the MAVLink Gimbal component, and 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. Also determines if the STorM32 controller is in gimbal device or gimbal manager operation mode.

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

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

The STorM32 controller becomes a gimbal manager when Mavlink Gimbal Stream = “manager status” is set and it behaves as a gimbal device when Mavlink Gimbal Stream = “device status” is set. Otherwise it behaves as in the "old" gimbal protocol.

A common setting for Mavlink Gimbal Stream is “device status”, when newer autopilot and/or GCS firmwares are used (which properly support the v2 gimbal protocol). For older autopilot/GCS firmwares, one typically would select “mountstatus”.

Comment: Note that unless STorM32 is in gimbal manager mode, it accepts both the newer gimbal device messages and the older mount messages. The difference is "only" that when it is in gimbal device mode it is stricter on enforcing the gimbal device rules (e.g. for RC control to work one needs to set the respective gimbal device flags).

Comment: The STorM32's gimbal manager is not compliant to the v2 gimbal manager protocol, but the STorM32's version of a gimbal manager.

The MAVLink Gimbal component supports the File Transfer Protocol micro service, which allows us to download e.g. component metadata .json files directly from the STorM32 gimbal controller.

Messages

The following MAVLink messages are supported by the STorM32 gimbal component:

MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00) (out)

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: 
     when in NORMAL mode MAV_MODE_FLAG_STABILIZE_ENABLED (= 0x10) and MAV_MODE_FLAG_SAFETY_ARMED (= 0x80) are set
 * custom_mode:
     lowest byte (0x000000FF): STATE value
     2nd & 3rd bytes (0x00FFFF00): prearm checks flags
     highest bit (0x80000000): bit is set if prearm checks are 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) (in)

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.

MAVLINK_MSG_ID_PARAM_REQUEST_READ (#20, 0x14) (in)

See PARAM_REQUEST_READ.

MAVLINK_MSG_ID_PARAM_REQUEST_LIST (#21, 0x15) (in)

See PARAM_REQUEST_LIST.

MAVLINK_MSG_ID_PARAM_VALUE (#22, 0x16) (out)

See PARAM_VALUE.

MAVLINK_MSG_ID_PARAM_SET (#23, 0x17) (in)

See PARAM_SET.

MAVLINK_MSG_ID_RC_CHANNELS (#65, 0x41) (in)

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) (in)

See COMMAND_INT.

Same as for MAVLINK_MSG_ID_COMMAND_LONG, see next.

MAVLINK_MSG_ID_COMMAND_LONG (#76, 0x4C) (in)

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 retracts 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 retracts 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)
* param3
     0: do nothing
     1: restart with full reset
     2: shut down motors
* param4 = component ID, must be 0 or match gimbal ID

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
     158: stream MOUNT_STATUS message (target is set according to param7, for details see message description)
     285: stream GIMBAL_DEVICE_ATTITUDE_STATUS message (target is set according to param7, see message description)
     60011: stream STORM32_GIMBAL_MANAGER_STATUS message (only if in gimbal manager mode)
* 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
     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
     285: send GIMBAL_DEVICE_ATTITUDE_STATUS message (target is set according to param7, default is requester IDs)
     300: send PROTOCOL_VERSION message
     397: send COMPONENT_METADATA message
     60010: send STORM32_GIMBAL_MANAGER_INFORMATION message (only if in gimbal manager mode)
     60011: send STORM32_GIMBAL_MANAGER_STATUS message (only if in gimbal manager mode)
* param7 = response target

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

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

MAV_CMD_DO_SEND_BANNER (#42428, 0xA5BC)
  send STATUSTEXT messages with banner

MAV_CMD_STORM32_DO_GIMBAL_MANAGER_CONTROL_PITCHYAW (#60002, 0xEA62)
  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_SETUP (#60010, 0xEA6A)
  This command is handled in gimbal manager mode. The gimbal device ID (param7) must match the STorM32's gimbal component ID.

MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D) (out)

See COMMAND_ACK.

MAVLINK_MSG_ID_FILE_TRANSFER_PROTOCOL (#110, 0x6E) (in/out)

See FILE_TRANSFER_PROTOCOL.

MAVLINK_MSG_ID_AUTOPILOT_VERSION (#148, 0x94) (out)

See AUTOPILOT_VERSION.

The flight_sw_version and board_version fields are set to the firmware version and board revision (firmware version: e.g. 262 for version v2.62x, board revision: e.g. 33 for v3.3 boards). VID and PID are set to 0x16D0 and 0x0FCB, respectively. UID is set to the STM32 UUID.

MAVLINK_MSG_ID_MOUNT_STATUS (#158, 0x9E) (out)

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. It also can be emitted 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 (vehicle frame).

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. When requested with MAV_CMD_SET_MESSAGE_INTERVAL it holds: 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, a broadcast stream at a low rate, e.g. to inform a GCS, plus a targeted stream at a high rate, e.g. to inform an on-board companion computer.

Consider to use the GIMBAL_DEVICE_ATTITUDE_STATUS message instead of MOUNT_STATUS, i.e., to set Mavlink Gimbal Stream = “device status” for enabling a 4 Hz stream.

Comment: Broadcast message streams at high rate should be avoided, as they may overburden the telemetry link to the ground.

MAVLINK_MSG_ID_AUTOPILOT_VERSION_REQUEST (#183, 0xB7) (in)

ArduPilot specific message. See AUTOPILOT_VERSION_REQUEST.

Is supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead.

MAVLINK_MSG_ID_MESSAGE_INTERVAL (#244, 0xF4) (out)

See MESSAGE_INTERVAL.

MAVLINK_MSG_ID_STATUSTEXT (#253, 0xFD) (out)

See STATUSTEXT.

This message is sent out after a PARAM_REQUEST_LIST has been served, and provides firmware and board type information. It also can be requested with the MAV_CMD_REQUEST_MESSAGE or MAV_CMD_DO_SEND_BANNER commands.

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) (out)

See GIMBAL_DEVICE_INFORMATION.

The min/max values reported in this message are the RC Input Min/Max values for each axis, if the axis is enabled (for disabled axes NAN is reported).

MAVLINK_MSG_ID_GIMBAL_DEVICE_SET_ATTITUDE (#284, 0x11C) (in)

See GIMBAL_DEVICE_SET_ATTITUDE.

Only handled if not in gimbal manager mode. Current limitations: Yaw in earth frame is not supported, even when the STorM32-Link is enabled and available. The velocity fields are not supported and ignored.

The message is rejected when not either the YAW_IN_VEHICLE_FRAME or the YAW_IN_EARTH_FRAME flag is set (that is, the legacy usage of this message is not supported).

MAVLINK_MSG_ID_GIMBAL_DEVICE_ATTITUDE_STATUS (#285, 0x11D) (out)

See GIMBAL_DEVICE_ATTITUDE_STATUS.

Emission of this message with 4 Hz can be activated in the GUI with the Mavlink Gimbal Stream parameter. It also can be emitted 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 in the message's quaternion is relative to the forward direction (vehicle frame) (the flag GIMBAL_DEVICE_FLAGS_YAW_IN_VEHICLE_FRAME is set and GIMBAL_DEVICE_FLAGS_YAW_IN_EARTH_FRAME is unset). The yaw angle relative to north (earth frame) can be determined from delta_yaw, if it is not unknown (not set to NaN).

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. When requested with MAV_CMD_SET_MESSAGE_INTERVAL it holds: 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, a broadcast stream at a low rate, e.g. to inform a GCS, plus a targeted stream at a high rate, e.g. to inform an on-board companion computer.

Comment: Broadcast message streams at high rate should be avoided, as they may overburden the telemetry link to the ground.

MAVLINK_MSG_ID_AUTOPILOT_STATE_FOR_GIMBAL_DEVICE (#286, 0x11E) (in)

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) (out)

See PROTOCOL_VERSION.

MAVLINK_MSG_ID_TUNNEL (#385, 0x181) (in/out)

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.

MAVLINK_MSG_ID_COMPONENT_METADATA (#397, 0x18D) (out)

See COMPONENT_METADATA.

MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_INFORMATION (#60010, 0xEA6A) (out)

STorM32 specific message. See storm32.xml.

Only emitted if in gimbal manager mode.

MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_STATUS (#60011, 0xEA6B) (out)

STorM32 specific message. See storm32.xml.

Emission of this message with 1 Hz can be activated in the GUI with the Mavlink Gimbal Stream parameter, can be emitted 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.

If the STorM32 controller is in gimbal manager mode and this message is received, then it will fall back to gimbal device mode (only one gimbal manager is allowed per gimbal).

MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_CONTROL (#60012, 0xEA6C) (in)

STorM32 specific message. See storm32.xml.

Only handled if in gimbal manager mode.

MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_CONTROL_PITCHYAW (#60013, 0xEA6D) (in)

STorM32 specific message. See storm32.xml.

Only handled if in gimbal manager mode.

MAVLINK_MSG_ID_STORM32_GIMBAL_MANAGER_CORRECT_ROLL (#60014, 0xEA6E) (in)

STorM32 specific message. See storm32.xml.

Only handled if in gimbal manager mode.

MAVLINK_MSG_ID_RADIO_RC_CHANNELS (#60045, 0xEA8D) (in)

mLRS specific message. See storm32.xml.

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 Camera

The MAVLink Camera component is independent on the MAVLink Gimbal component, and can also be used when the MAVLink Gimbal component is disabled.

Setting the Mavlink Camera parameter enables the MAVLink Camera component, and determines its component ID: “Camera1” corresponds to MAV_COMP_ID_CAMERA (= 100), “Camera2” to MAV_COMP_ID_CAMERA2 (= 101), and so on.

  • Mavlink Camera = “Camera1” or higher

The system ID of the MAVLink Camera component is determined by the parameter Mavlink System ID, which is also used by the MAVLink Gimbal component, and usually can be left at its default value (0).

The MAVLink Camera component supports the File Transfer Protocol micro service, which allows us to download the camera definition .xml files directly from the STorM32 gimbal controller. They are stored in .xz compressed format (i.e. the extension of the respective file is .xml.xz).

The MAVLink Camera component is deeply related to the NT Camera. This means that it works in conjunction with the Camera Control function and associated parameters in the [GUI:Functions] tab.

Comment: For camera models which need to establish a connection to the NT Camera module for operation, such as the GoPro Hero5, the heartbeat will be emitted only when a connection is established. For these camera models the connection status is displayed in the [GUI:Dashboard].

Messages

The following MAVLink messages are supported by the STorM32 camera component:

MAVLINK_MSG_ID_HEARTBEAT (#0, 0x00)

See HEARTBEAT.

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

  • type: MAV_TYPE_CAMERA (= 30)
  • autopilot: MAV_AUTOPILOT_INVALID (= 8)
  • base_mode: MAV_MODE_FLAG_SAFETY_ARMED (= 0x80)
  • custom_mode: highest bit (0x80000000) = set if prearm checks have not passed
  • system_status: MAV_STATE_ACTIVE (= 4)

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_PARAM_REQUEST_READ (#20, 0x14)

See PARAM_REQUEST_READ.

MAVLINK_MSG_ID_PARAM_REQUEST_LIST (#21, 0x15)

See PARAM_REQUEST_LIST.

MAVLINK_MSG_ID_PARAM_VALUE (#22, 0x16)

See PARAM_VALUE.

MAVLINK_MSG_ID_PARAM_SET (#23, 0x17)

See PARAM_SET.

MAVLINK_MSG_ID_RC_CHANNELS (#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_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_REQUEST_MESSAGE (#512, 0x0200)
* param1 = message ID of the requested message  
     147: send BATTERY_STATUS message
     148: send AUTOPILOT_VERSION message
     253: send STATUSTEXT message with firmware and board type information
     259: send CAMERA_INFORMATION message
     260: send CAMERA_SETTINGS message
     261: send STORAGE_INFORMATION message
     262: send CAMERA_CAPTURE_STATUS message
     263: (CAMERA_IMAGE_CAPTURED) returns COMMAND_ACK with MAV_CMD_ACK_DENIED
     300: send PROTOCOL_VERSION message
     397: send COMPONENT_METADATA message
* param7 = response target

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

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

MAV_CMD_REQUEST_CAMERA_INFORMATION (#521, 0x0209)
* param1 = request camera capabilities
     1: send CAMERA_INFORMATION message
(supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_REQUEST_CAMERA_SETTINGS (#522, 0x020A)
  send CAMERA_SETTINGS message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_REQUEST_STORAGE_INFORMATION (#525, 0x020D)
  send STORAGE_INFORMATION message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_STORAGE_FORMAT (#526, 0x020E)
  returns COMMAND_ACK with MAV_CMD_ACK_DENIED

MAV_CMD_REQUEST_CAMERA_CAPTURE_STATUS (#527, 0x020F)
  send CAMERA_CAPTURE_STATUS message (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_RESET_CAMERA_SETTINGS (#529, 0x0211)
* param1 = reset (must be 0, else denied)

MAV_CMD_SET_CAMERA_MODE (#530, 0x0212)
* param2 = camera mode

MAV_CMD_SET_CAMERA_ZOOM (#531, 0x0213)
* param1 = zoom type
* param2 = zoom level

MAV_CMD_SET_CAMERA_FOCUS (#532, 0x0214)
  returns COMMAND_ACK with MAV_CMD_ACK_DENIED

MAV_CMD_IMAGE_START_CAPTURE (#2000, 0x07D0)
* param2 = desired elapsed time between two consecutive pictures (in seconds)
* param3 = total number of images to capture
* param4 = capture sequence number starting

MAV_CMD_IMAGE_STOP_CAPTURE (#2001, 0x07D18)
  stops capturing images

MAV_CMD_REQUEST_CAMERA_IMAGE_CAPTURE (#2002, 0x07D2)
  returns COMMAND_ACK with MAV_CMD_ACK_DENIED (supported, but is deprecated, use MAV_CMD_REQUEST_MESSAGE instead)

MAV_CMD_VIDEO_START_CAPTURE (#2500, 0x09C4)
* param1 = video stream ID 
* param2 = frequency CAMERA_CAPTURE_STATUS messages should be sent while recording

MAV_CMD_VIDEO_STOP_CAPTURE (#2501, 0x09C5)
* param1 = video stream ID

MAV_CMD_DO_SEND_BANNER (#42428, 0xA5BC)
  send STATUSTEXT messages with banner

MAVLINK_MSG_ID_COMMAND_ACK (#77, 0x4D)

See COMMAND_ACK.

MAVLINK_MSG_ID_FILE_TRANSFER_PROTOCOL (#110, 0x6E)

See FILE_TRANSFER_PROTOCOL.

The opcodes TerminateSession, ResetSessions, ListDirectory, OpenFileRO, ReadFile and CalcFileCRC32 are supported.

MAVLINK_MSG_ID_BATTERY_STATUS (#147, 0x93)

See BATTERY_STATUS.

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_AUTOPILOT_VERSION_REQUEST (#183, 0xB7)

ArduPilot specific message. See AUTOPILOT_VERSION_REQUEST.

Is supported, but deprecated, use MAV_CMD_REQUEST_MESSAGE instead.

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_CAMERA_INFORMATION (#259, 0x103)

See CAMERA_INFORMATION.

MAVLINK_MSG_ID_CAMERA_SETTINGS (#260, 0x104)

See CAMERA_SETTINGS.

MAVLINK_MSG_ID_STORAGE_INFORMATION (#261, 0x105)

See STORAGE_INFORMATION.

MAVLINK_MSG_ID_CAMERA_CAPTURE_STATUS (#262, 0x106)

See CAMERA_CAPTURE_STATUS.

MAVLINK_MSG_ID_CAMERA_IMAGE_CAPTURED (#263, 0x107)

See CAMERA_IMAGE_CAPTURED.

MAVLINK_MSG_ID_PROTOCOL_VERSION (#300, 0x12C)

See PROTOCOL_VERSION.

MAVLINK_MSG_ID_PARAM_EXT_REQUEST_READ (#320, 0x140)

See PARAM_EXT_REQUEST_READ.

MAVLINK_MSG_ID_PARAM_EXT_REQUEST_LIST (#321, 0x141)

See PARAM_EXT_REQUEST_LIST.

MAVLINK_MSG_ID_PARAM_EXT_VALUE (#322, 0x142)

See PARAM_EXT_VALUE.

MAVLINK_MSG_ID_PARAM_EXT_SET (#323, 0x143)

See PARAM_EXT_SET.

MAVLINK_MSG_ID_PARAM_EXT_ACK (#324, 0x144)

See PARAM_EXT_ACK.

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 MAVLink Camera component supports the payload types 200 and 201 for communicating with the GUI. Payload types 204 and 205 are used for NT Camera implementations on a companion.

MAVLINK_MSG_ID_COMPONENT_METADATA (#397, 0x18D)

See COMPONENT_METADATA.

MAVLINK_MSG_ID_RADIO_RC_CHANNELS (#60045, 0xEA8D) (in)

mLRS specific message. See storm32.xml.

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”.

Comments on Compatibility

STorM32's MAVLink support fully embraces the MAVLink standard, as defined by the MAVLink project ([1], mavlink.io).

However, some implementations may not support all messages of the MAVLink standard, or may implement some of them differently/incorrectly.

ArduPilot

Generally, ArduPilot's handling and routing of the gimbal and camera MAVLink messages and commands can have its issues, and can vary a lot with version. Besides flaws, issues arrise often because of non-standard conform use of MAVLink messages or violating the MAVLink protocol itself. It is best to explore the situation carefully for the ArduPilot version in use.

See also Using STorM32 with ArduPilot.

PX4

TBD.

Retrieved from "http:///storm32bgc-wiki/index.php?title=MAVLink_Communication&oldid=11627"