Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-03-23 10:03:41 +08:00
Code Issues Actions 7 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

1
docs/en/SUMMARY.md
View File

@@ -757,6 +757,7 @@
- [MAVLink Messaging](mavlink/index.md)
- [Adding Messages](mavlink/adding_messages.md)
- [Streaming Messages](mavlink/streaming_messages.md)
- [MAVLink Profiles](mavlink/mavlink_profiles.md)
- [Receiving Messages](mavlink/receiving_messages.md)
- [Custom MAVLink Messages](mavlink/custom_messages.md)
- [Message Signing](mavlink/message_signing.md)

1
docs/en/mavlink/index.md
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)
- [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)
- [Custom MAVLink Messages](../mavlink/custom_messages.md)
- [Message Signing](../mavlink/message_signing.md)

67
docs/en/mavlink/mavlink_profiles.md Normal file
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.

31
docs/en/mavlink/streaming_messages.md
View File

@@ -4,7 +4,7 @@ This tutorial demonstrates how to stream a uORB message as a MAVLink message, an
## 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.
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 line below to the part of the file where all the other streams are included:
### Add the new class to the streaming list
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
#include "streams/BATTERY_STATUS_DEMO.hpp"
```
Finally 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)
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)
```C
StreamListItem *streams_list[] = {
@@ -212,24 +214,11 @@ We cover that in the next sections.
## 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.
- `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.
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.
For example, to stream `BATTERY_STATUS_DEMO` at 5 Hz:
```cpp

26
docs/en/peripherals/mavlink_peripherals.md
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.
It can be any unused port, e.g.: `TELEM2`, `TELEM3`, `GPS2` etc.
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).
The default values are:
- _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_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_.
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.
- <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).
- 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
- [MAVLink Profiles](../mavlink/mavlink_profiles.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)
- [Serial Port Mapping](../hardware/serial_port_mapping.md)