Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-27 18:27:05 +08:00
Code Issues Actions 30 Packages Projects Releases Wiki Activity

docs(mavlink): MAVLink Profiles - separate topic (#26816)

Browse Source
This commit is contained in:
Hamish Willee
2026-03-19 13:32:30 +11:00
committed by GitHub
parent 0f38a581d1
commit a91037705c
5 changed files with 82 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/SUMMARY.md
+1
View File
@@ -757,6 +757,7 @@
- [MAVLink Messaging](mavlink/index.md) - [MAVLink Messaging](mavlink/index.md)
- [Adding Messages](mavlink/adding_messages.md) - [Adding Messages](mavlink/adding_messages.md)
- [Streaming Messages](mavlink/streaming_messages.md) - [Streaming Messages](mavlink/streaming_messages.md)
- [MAVLink Profiles](mavlink/mavlink_profiles.md)
- [Receiving Messages](mavlink/receiving_messages.md) - [Receiving Messages](mavlink/receiving_messages.md)
- [Custom MAVLink Messages](mavlink/custom_messages.md) - [Custom MAVLink Messages](mavlink/custom_messages.md)
- [Message Signing](mavlink/message_signing.md) - [Message Signing](mavlink/message_signing.md)
docs/en/mavlink/index.md
+1
View File
@@ -9,6 +9,7 @@ It also links instructions for how you can add PX4 support for:
- [Adding Standard Messages](../mavlink/adding_messages.md) - [Adding Standard Messages](../mavlink/adding_messages.md)
- [Streaming MAVLink messages](../mavlink/streaming_messages.md) - [Streaming MAVLink messages](../mavlink/streaming_messages.md)
- [Configuring/Using MAVLink Profiles](../mavlink/mavlink_profiles.md)
- [Handling incoming MAVLink messages (and writing to a uORB topic)](../mavlink/receiving_messages.md) - [Handling incoming MAVLink messages (and writing to a uORB topic)](../mavlink/receiving_messages.md)
- [Custom MAVLink Messages](../mavlink/custom_messages.md) - [Custom MAVLink Messages](../mavlink/custom_messages.md)
- [Message Signing](../mavlink/message_signing.md) - [Message Signing](../mavlink/message_signing.md)
docs/en/mavlink/mavlink_profiles.md
+67
View File
@@ -0,0 +1,67 @@
# MAVLink Profiles
A MAVLink _profile_ (also called a _mode_) defines a set of messages that can be streamed by default on a MAVLink channel and their rates.
This section lists the profiles, and explains how they can be used and extended.
## Available Profiles
The available profiles (in source-code declaration order) are:
- _Normal_ (`MAVLINK_MODE_NORMAL`): Set of messages for a GCS.
- _Onboard_ (`MAVLINK_MODE_ONBOARD`): Set of messages for a companion computer on a fast link (such as Ethernet).
- _Gimbal_ (`MAVLINK_MODE_GIMBAL`): Messages for a gimbal. Note this also enables message forwarding.
- _External Vision_ (`MAVLINK_MODE_EXTVISION`): Messages for offboard vision systems.
- _External Vision Minimal_ (`MAVLINK_MODE_EXTVISIONMIN`): Messages for offboard vision systems on slower links.
- _OSD_ (`MAVLINK_MODE_OSD`): Set of messages for an OSD system.
- _Magic_ (`MAVLINK_MODE_MAGIC`): No messages streamed by default. Used when configuring streaming dynamically via MAVLink.
- _Custom_ (`MAVLINK_MODE_CUSTOM`): Same as `MAVLINK_MODE_MAGIC`.
- _Config_ (`MAVLINK_MODE_CONFIG`): Set of messages for configuration interface, sent at higher rates. This is used, for example, to send the `MAVLINK_MODE_NORMAL` message set via USB to a GCS.
- _Iridium_ (`MAVLINK_MODE_IRIDIUM`): Streams `HIGH_LATENCY2` message to an iridium satellite phone.
- _Minimal_ (`MAVLINK_MODE_MINIMAL`): Minimal set of messages for use with a GCS on a poor telemetry link.
- _Onboard Low Bandwidth_ (`MAVLINK_MODE_ONBOARD_LOW_BANDWIDTH`): Set of messages to be streamed to a companion computer for re-routing to a reduced-traffic link, such as a GCS.
- _Low Bandwidth_ (`MAVLINK_MODE_LOW_BANDWIDTH`): Reduced message set for low bandwidth links.
- _uAvionix_ (`MAVLINK_MODE_UAVIONIX`): Messages for a uAvionix ADS-B beacon.
- _Distance Sensor_ (`MAVLINK_MODE_DISTANCE_SENSOR`): Streams distance sensor data at unlimited rate.
:::tip
The profile defines the _default_ messages and rates.
A connected MAVLink system can still request the streams/rates it wants using [MAV_CMD_SET_MESSAGE_INTERVAL](https://mavlink.io/en/messages/common.html#MAV_CMD_SET_MESSAGE_INTERVAL).
:::
To find the exact messages in each profile, search for ` configure_streams_to_default` (or the above profile names) in [mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp).
## Assigning Profiles to Ports
[MAVLink Peripherals](../peripherals/mavlink_peripherals.md) explains how to set up a port for communicating over MAVLink.
This uses the concept of an abstract [MAVLink instance](../peripherals/mavlink_peripherals.md#mavlink-instances) which is then assigned to a serial port.
The profile associated with a particular MAVLink instance is set using the associated `MAV_X_MODE` parameter:
- [MAV_0_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE)
- [MAV_1_MODE](../advanced_config/parameter_reference.md#MAV_1_MODE)
- [MAV_2_MODE](../advanced_config/parameter_reference.md#MAV_2_MODE)
There are also dedicated profile parameters for ports that are not configured via MAVLink instances:
- [USB_MAV_MODE](../advanced_config/parameter_reference.md#USB_MAV_MODE): Profile for the USB port (used when MAVLink is set or detected on USB).
- [MAV_S_MODE](../advanced_config/parameter_reference.md#MAV_S_MODE): Profile for the internal SOM (System on Module) to FMU communication channel, used on boards where the FMU and companion computer are co-located on the same module.
Note that not all profiles can necessarily be set on these ports.
## Adding Messages to a Profile
You can add messages to a profile in appropriate `case` switch in the [Mavlink::configure_streams_to_default(const char \*configure_single_stream)](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp#L1430) method (see [mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp)).
If you're testing with a GCS over USB you might add the message to the `MAVLINK_MODE_CONFIG` case using the `configure_stream_local()` method.
For example, to stream `BATTERY_STATUS_DEMO` at 5 Hz:
```cpp
case MAVLINK_MODE_CONFIG: // USB
// Note: streams requiring low latency come first
...
configure_stream_local("BATTERY_STATUS_DEMO", 5.0f);
...
```
See [Streaming MAVLink Messages](streaming_messages.md) for a more detailed example.
docs/en/mavlink/streaming_messages.md
+10 -21
View File
@@ -4,7 +4,7 @@ This tutorial demonstrates how to stream a uORB message as a MAVLink message, an
## Overview ## Overview
[MAVLink messages](../middleware/mavlink.md) are streamed using a streaming class, derived from `MavlinkStream`, that has been added to the PX4 stream list. [MAVLink messages](../middleware/mavlink.md) are streamed using a streaming class, derived from `MavlinkStream`, that has been added to the [PX4 stream list](#add-the-new-class-to-the-streaming-list).
The class has framework methods that you implement so PX4 can get information it needs from the generated MAVLink message definition. The class has framework methods that you implement so PX4 can get information it needs from the generated MAVLink message definition.
It also has a `send()` method that is called each time the message needs to be sent — you override this to copy information from a uORB subscription to the MAVLink message object that is to be sent. It also has a `send()` method that is called each time the message needs to be sent — you override this to copy information from a uORB subscription to the MAVLink message object that is to be sent.
@@ -187,15 +187,17 @@ Most streaming classes are very similar (see examples in [/src/modules/mavlink/s
::: :::
Next we include our new class in [mavlink_messages.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_messages.cpp#L2193). ### Add the new class to the streaming list
Add the line below to the part of the file where all the other streams are included:
Next we add our new class to the streaming list.
First open [mavlink_messages.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_messages.cpp#L2193) and add the line below to the part of the file where all the other streams are included:
```cpp ```cpp
#include "streams/BATTERY_STATUS_DEMO.hpp" #include "streams/BATTERY_STATUS_DEMO.hpp"
``` ```
Finally append the stream class to the `streams_list` at the bottom of Then append the stream class to the `streams_list` at the bottom of [mavlink_messages.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_messages.cpp)
[mavlink_messages.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_messages.cpp)
```C ```C
StreamListItem *streams_list[] = { StreamListItem *streams_list[] = {
@@ -212,24 +214,11 @@ We cover that in the next sections.
## Streaming by Default ## Streaming by Default
The easiest way to stream your messages by default (as part of a build) is to add them to [mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp) in the appropriate message group. The easiest way to stream your messages by default (as part of a build) is to add them to appropriate [MAVLink Profile](../mavlink/mavlink_profiles.md), such as `MAVLINK_MODE_NORMAL` if you're streaming to a GCS over WiFI, or `MAVLINK_MODE_OSD` for an OSD device.
If you search in the file you'll find groups of messages defined in a switch statement: This is covered in [Adding Messages to a Profile](..//mavlink/mavlink_profiles.md#adding-messages-to-a-profile), but in summary you first open [mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp), search for the method `Mavlink::configure_streams_to_default`, and then find the profile that you wish to update.
- `MAVLINK_MODE_NORMAL`: Streamed to a GCS. If you're just testing on a GCS, you could add the message to the `MAVLINK_MODE_NORMAL` case using the `configure_stream_local()` method.
- `MAVLINK_MODE_ONBOARD`: Streamed to a companion computer on a fast link, such as Ethernet
- `MAVLINK_MODE_ONBOARD_LOW_BANDWIDTH`: Streamed to a companion computer for re-routing to a reduced-traffic link, such as a GCS.
- `MAVLINK_MODE_GIMBAL`: Streamed to a gimbal
- `MAVLINK_MODE_EXTVISION`: Streamed to an external vision system
- `MAVLINK_MODE_EXTVISIONMIN`: Streamed to an external vision system on a slower link
- `MAVLINK_MODE_OSD`: Streamed to an OSD, such as an FPV headset.
- `MAVLINK_MODE_CUSTOM`: Stream nothing by default. Used when configuring streaming using MAVLink.
- `MAVLINK_MODE_MAGIC`: Same as `MAVLINK_MODE_CUSTOM`
- `MAVLINK_MODE_CONFIG`: Streaming over USB with higher rates than `MAVLINK_MODE_NORMAL`.
- `MAVLINK_MODE_MINIMAL`: Stream a minimal set of messages. Normally used for poor telemetry links.
- `MAVLINK_MODE_IRIDIUM`: Streamed to an iridium satellite phone
Normally you'll be testing on a GCS, so you could just add the message to the `MAVLINK_MODE_NORMAL` case using the `configure_stream_local()` method.
For example, to stream `BATTERY_STATUS_DEMO` at 5 Hz: For example, to stream `BATTERY_STATUS_DEMO` at 5 Hz:
```cpp ```cpp
docs/en/peripherals/mavlink_peripherals.md
+3 -23
View File
@@ -26,29 +26,8 @@ The parameters for each instance are:
- <a id="MAV_X_CONFIG"></a>[MAV_X_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG) - Set the serial port (UART) for this instance "X", where X is 0, 1, 2. - <a id="MAV_X_CONFIG"></a>[MAV_X_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG) - Set the serial port (UART) for this instance "X", where X is 0, 1, 2.
It can be any unused port, e.g.: `TELEM2`, `TELEM3`, `GPS2` etc. It can be any unused port, e.g.: `TELEM2`, `TELEM3`, `GPS2` etc.
For more information see [Serial Port Configuration](../peripherals/serial_configuration.md). For more information see [Serial Port Configuration](../peripherals/serial_configuration.md).
- <a id="MAV_X_MODE"></a>[MAV_X_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE) - Specify the telemetry mode/target (the set of messages to stream for the current instance and their rate). - <a id="MAV_X_MODE"></a>[MAV_X_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE) - Specify the [MAVLink profile](../mavlink/mavlink_profiles.md) for the instance, such as _Normal_ or _OSD_.
The default values are: Profiles define a particular set of streamed messages and their rates — you should choose a profile that is appropriate for your channel and the peripheral.
- _Normal_: Standard set of messages for a GCS.
- _Custom_ or _Magic_: Nothing (in the default PX4 implementation).
Modes may be used for testing when developing a new mode.
- _Onboard_: Standard set of messages for a companion computer.
- _OSD_: Standard set of messages for an OSD system.
- _Config_: Standard set of messages and rate configuration for a fast link (e.g. USB).
- _Minimal_: Minimal set of messages for use with a GCS connected on a high latency link.
- _External Vision_: Messages for offboard vision systems.
- _Gimbal_: Messages for a gimbal. Note this also enables [message forwarding](#MAV_X_FORWARD)
- _Onboard Low Bandwidth_: Standard set of messages for a companion computer connected on a lower speed link.
- _uAvionix_: Messages for a uAvionix ADS-B beacon.
::: info
If you need to find the specific set of message for each mode search for `MAVLINK_MODE_` in [/src/modules/mavlink/mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp).
:::
:::tip
The mode defines the _default_ messages and rates.
A connected MAVLink system can still request the streams/rates that it wants using [MAV_CMD_SET_MESSAGE_INTERVAL](https://mavlink.io/en/messages/common.html#MAV_CMD_SET_MESSAGE_INTERVAL).
:::
- <a id="MAV_X_RATE"></a>[MAV_X_RATE](../advanced_config/parameter_reference.md#MAV_0_MODE) - Set the maximum _data rate_ for this instance (bytes/second). - <a id="MAV_X_RATE"></a>[MAV_X_RATE](../advanced_config/parameter_reference.md#MAV_0_MODE) - Set the maximum _data rate_ for this instance (bytes/second).
- This is the combined rate for all streams of individual message (the rates for individual messages are reduced if the total rate exceeds this value). - This is the combined rate for all streams of individual message (the rates for individual messages are reduced if the total rate exceeds this value).
- The default setting will generally be acceptable, but might be reduced if the telemetry link becomes saturated and too many messages are being dropped. - The default setting will generally be acceptable, but might be reduced if the telemetry link becomes saturated and too many messages are being dropped.
@@ -116,6 +95,7 @@ Links to setup instructions for specific MAVLink components:
## See Also ## See Also
- [MAVLink Profiles](../mavlink/mavlink_profiles.md)
- [Serial Port Configuration](../peripherals/serial_configuration.md) - [Serial Port Configuration](../peripherals/serial_configuration.md)
- [PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration](../advanced_config/ethernet_setup.md#px4-mavlink-serial-port-configuration) - [PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration](../advanced_config/ethernet_setup.md#px4-mavlink-serial-port-configuration)
- [Serial Port Mapping](../hardware/serial_port_mapping.md) - [Serial Port Mapping](../hardware/serial_port_mapping.md)