mavlink/mavlink-devguide

MAVLink Developer Guide

MAVLink Developer Guide

MAVLink is a very lightweight, header-only message marshalling library for micro air vehicles / drones.

MAVLink follows a modern hybrid publish-subscribe and point-to-point design pattern: Data streams are sent / published as topics while configuration sub-protocols such as the mission protocol or parameter protocol are point-to-point with retransmission.

Tip Because MAVLink doesn't require any additional framing it is very well suited for applications with very limited communication bandwidth. It's reference implementation in C is highly optimized for resource-constrained systems with limited RAM and flash memory. It is field-proven and deployed in many products where it serves as interoperability interface between components of different manufacturers.

MAVLink was first released early 2009 by Lorenz Meier and has now a significant number of contributors.

The content of this book is CC-BY 4.0 licensed.

mavlink-devguide's Issues

Add website url to this github repo

Add website https://mavlink.io/ to front of repo (edit button near title).

@LorenzMeier I'd do this, but I don't have necessary rights. It is useful to be able to easily do round trip from Github to book and back again :-)

MAVLink 2 Packet Format includes non existent fields

https://mavlink.io/en/protocol/overview.html describes the MAVLink 2 Packet Format as follows:

uint8_t magic;              ///< protocol magic marker
uint8_t len;                ///< Length of payload
uint8_t incompat_flags;     ///< flags that must be understood
uint8_t compat_flags;       ///< flags that can be ignored if not understood
uint8_t seq;                ///< Sequence of packet
uint8_t sysid;              ///< ID of message sender system/aircraft
uint8_t compid;             ///< ID of the message sender component
uint8_t msgid 0:7;          ///< first 8 bits of the ID of the message
uint8_t msgid 8:15;         ///< middle 8 bits of the ID of the message
uint8_t msgid 16:23;        ///< last 8 bits of the ID of the message
uint8_t target_sysid;       ///< Optional field for point-to-point messages, used for payload else
uint8_t target_compid;      ///< Optional field for point-to-point messages, used for payload else
uint8_t payload[max 253];   ///< A maximum of 253 payload bytes
uint16_t checksum;          ///< X.25 CRC
uint8_t signature[13];      ///< Signature which allows ensuring that the link is tamper-proof

target_sysid and target_compid are not real protocol details, no parser handles the concept, it was never in any of the MAVLink 2.0 standard proposals, there is no way in a protocol level to tell if they are being used for this or not, and all existent parsers treat the payload length as 255 bytes. More importantly there are exsisting messages that need a 255 byte payload, you can't steal from this without breaking the ability to encode some messages. This needs to be removed from the documentation.

Message Definitions · Add doc on how to add messages

Message Definitions · MAVLink Developer Guide

Answer questions "what are the requirements for adding messages"/ how do we do it.

In mavlink/mavlink#942 (comment) I suggested:

1. Create a Git PR to put it into https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0
2. We'd expect the xml file to successfully build (i.e. be compliant with the DTD) and have comment/description about the platform it supports as a comment (ideally with platform URL/contacts).
3. Sensible file name - ie one you can instantly guess platform

Any other requirements?

Todo:

• Add links to instructions in PX4 and in ArduPilot docs for creating a custom message.
  • PX4
  • Ardupilot (?)

General questions for confirmation

Confirm:

• High level protocol doesn't do any resending or packet order checking - right? - #83 (comment)
• What general requirements does MAVLink put on resend rates/timeouts for AUTOPILOT_VERSION, HEARTBEAT, SYS_STATUS - see #83 (comment)
• Is Message Profile information useful? - #83 (comment)
• Message extensions - When/why do we use them, and why not everywhere? Assumption is that we use extensions because it is hard to coordinate message changes for existing systems (something we do want to improve going forward). I presume the reason we don't recommend these everywhere (ie drop the idea of reordering) is that there is benefit in reordering and in having the CRCEXTRA as a compatibility check?

CLOSED

• Are target_sysid and target_compid part of standard frame in MAVLink 2? - #83 (comment) - No
• MAVLink 2 field re-ordering and truncation unclear - #83 (comment)
• Is missionlib useful (status update): #83 (comment) - DELETED

NOTE, some of these might make good FAQs

Document _HASH_CHECK parameter

Add documentation for the _HASH_CHECK parameter cache mechanism. Info on this is:

• PX4/PX4-Autopilot#2982
• ArduPilot/ardupilot#3070

Add C interface example

@hamishwillee I believe that this would help adopters tremendously in getting started:
https://github.com/mavlink/c_uart_interface_example

Answer question: How do I find out what messages supported by a particular system

MAV_CMD_SET_MESSAGE_INTERVAL (and GET) clarifications

MAV_CMD_SET_MESSAGE_INTERVAL

• A system can have multiple logical and physical channels - which one does this apply on? (ie it can't be system global).

  • This would make sense as physical channel, because everything on one channel gets the same rates. But the code works by logical channel and there is no way to untangle the associated potential physical channels - so I think we're going to have to use logical channel and know that there is no way to resolve contention.

• Should the interval persist? If this is up to implementation, should we say so.

• Any ideas on what to do if multiple systems on channel are asking for different rates?

• MAV_CMD_GET_MESSAGE_INTERVAL

  • Same question about "which rate"

Is packaging still done for MAVLink?

Mavlink.org had a topic about packaging MAVLink (old source below). This seems to cover making a windows installer and "building mavlink".
What is this about? I thought mavlink wasn't "built" but rather "generated". Why would we need a windows installer?

The only useful stuff here seems to be the toolchain explanation: "Pymavlink is used to generate the C source code from the message definitions.".

THoughts?

====== MAVLink Packaging ======

//This page is intended for MAVLink developers only. If you just want to use the common message set, head to [[:mavlink:installation]], if you want to generate your own messages / your own dialect, head to [[:mavlink:generator]].//

===== Message Definitions =====

All mavlink messages are generated off of the definitions under the message_definitions of the mavlink git repository root directory.

===== PyMAVLink Generation =====

Pymavlink is used to generate the C source code from the message definitions. This is the portion of the cmake file that automates this build process. CMake is used here to manage file dependencies and automate package generation as shown later.

<code cmake>
# mavlink generation
macro(generateMavlink version definitions)
    foreach(definition ${definitions})
        set(targetName ${definition}-v${version})
        set(definitionAbsPath ${CMAKE_SOURCE_DIR}/message_definitions/v${version}/${definition})
        message(STATUS "processing: ${definitionAbsPath}")
        add_custom_command( 
            OUTPUT ${targetName}-stamp
            COMMAND ${PYTHON_EXECUTABLE} ${mavgen} --lang=C --wire-protocol=${version}
                --output=include/v${version} ${definitionAbsPath}
            COMMAND touch ${targetName}-stamp
            DEPENDS ${definitionAbsPath} ${mavgen}
            )
        add_custom_target(${targetName} ALL DEPENDS ${targetName}-stamp)
    endforeach()
endmacro()

# build
set(mavgen ${CMAKE_CURRENT_SOURCE_DIR}/pymavlink/generator/mavgen.py)
</code>

===== Packaging MAVLink Releases =====

==== Windows ====

  - Download cmake version 2.8 or later:http://www.cmake.org/cmake/resources/software.html
  - Download and setup git on windows: http://www.sparkfun.com/tutorials/165 (Great Sparkfun tutorial on this.)
  - Using Tortoise git, clone MAVLink.
  - <code>git clone git://github.com/mavlink/mavlink.git -b pymavlink_merge </code>
  - Use cmake gui, click configure, then click build.
  - Now navigate to the cmake build directory and type cpack. A nullsoft installer will be produced.

==== Linux ====

=== Install CMake and Download MAVLink ===

<code bash>
sudo apt-get install cmake
mkdir -P ~/home/Projects && cd ~/home/Projects
git clone git://github.com/mavlink/mavlink.git -b pymavlink_merge
cd mavlink
mkdir -P build
cd build && cmake ..
</code>

=== Compile MAVLink ===
<code bash>
cd ~/src/Projects/mavlink
mkdir -P build
cd build && cmake ..
</code>

=== Create a linux installer ===

If you are running Mac/ or a non-debian linux distribution this will create a self-extracting tarball package.
If you are running debian/ubunut it will create a debian installer that you can use to install mavlink on your system.

<code bash>
cd ~/src/Projects/mavlink/build-mingw && cpack
</code>

==== Cross-compiling on Linux for Windows ====

=== Install mingw cross env ===
This will take around 10 hours to complete so do it overnight. You can type make library for a specific library but this ends up being more work.

<code bash>
sudo apt-get install mercurial
mkdir -P ~/home/Projects && cd ~/home/Projects
http://mingw-cross-env.nongnu.org/
hg clone http://hg.savannah.nongnu.org/hgweb/mingw-cross-env
cd mingw-cross-env && make install
</code>

=== Run ranlib over all libs ===
Some libraries may fail to link correctly. To prevent this rerun ranlib over all the static libraries.
 
<code bash>
for file in $(find ./usr/i686-pc-mingw32/lib -regex ".+\.a")
do
    echo fixing $file
   ./user/bin/i686-pc-ming32-ranlib $file
done
</code>

=== Setup path for cmake-mingw ===

In the file ~/.profile you should create an alias for cmake-mingw

<code bash>
alias cmake-mingw=cmake -DCMAKE_TOOLCHAIN_FILE=~/home/Projects/mingw-cross-env/usr/i686-pc-mingw32/share/cmake/mingw-cross-env-conf.cmake
</code>

=== Download and compile the code ===

<code bash>
mkdir -P ~/home/Projects && cd ~/home/Projects
git clone git://github.com/mavlink/mavlink.git -b pymavlink_merge
cd mavlink
mkdir -P build-mingw
cd build-mingw && cmake-mingw ..
</code>

=== Create a windows installer ===

This step will create a nullsoft installer that you can use to install mavlink on your system.

<code bash>
cd ~/src/Projects/mavlink/build-mingw && cpack
</code>

Doc Bug: Protocols · MAVLink Developer Guide

I'm a bit confused about the over-the-wire protocol for MAVLink 2.

The documentation on this page indicates that MAVLink 2 messages with target sys/comp IDs will include the targets as part of the header, and will not sort them with the payload fields. (At least, that's how I'm interpreting the 'Mavlink 2 Packet Format' section)

However, looking through the generated C Library, it appears that the targets are treated as normal payload fields, and are not guaranteed to be at the beginning of the payload. For example, here is the C implementation of the VIDEO_STREAM_SETTINGS message, a MAVLink 2 only message.
https://github.com/mavlink/c_library_v2/blob/master/common/mavlink_msg_set_video_stream_settings.h

Perhaps a note should be added to clarify whether the targets are sorted as part of the payload, and whether or not they are included in the payload length.

Bug Page: Protocols · MAVLink Developer Guide

Document Ping Protocol

This protocol has been implemented in PX4 Firmware: PX4/PX4-Autopilot#9399

@mhkabir has kindly volunteered to document it

OK to rename this repo?

I'm involved with about 6 repos called devguide, and it is much easier to work out where I am in my local drive if they have a more descriptive filename.

1. Can we rename this to "mavlink_devguide" or "mavlink_dev_guide"? ... or something else?

Parameter Protocol - Add the _HASH check info?

PX4 implements the Parameter Protocol as written, but additionally supports some sort of caching of parameters that have been sent using a special parameter name HASH. I haven't looked at the details, but this should make it easier to inform a GCS that it is up to date without having to resend all parameters.

The requirement is to determine whether this is considered part of the spec, and if so, document it. If not part of spec, should still mention in.

How does burst mode work for FTP?

How does Burst ReadFile operations/streaming work?

I know that for normal reads, the file is read in chunks, with an ACK before each new chunk is sent. My guess is that for BurstReadFile the file is chunked and sent without waiting for a request - so basically you just send a stream of ACKs, with sequentially incremented sequence numbers. When you've sent everything you send the last ACK with the burst mode complete field set.

1. Is that correct?
2. Presumably the recipient is in burst mode, so it is sitting waiting for a bunch of ACKs and re-assembles the message - correct?
3. How is the recipient expected to cope with missing packets - it looks like after the burst is complete perhaps the recipient individually requests the missing packets - does it use a normal read/ACK process for that?

Doc Bug: Python (mavgen) · MAVLink Developer Guide

DESCRIBE PROBLEM WITH DOCS HERE

Bug Page: Python (mavgen) · MAVLink Developer Guide

Please correct “sytem_time_send()” to "system_time_send"

How do we cancel a mission upload/download?

Mission Protocol · MAVLink Developer Guide does not explain how to cancel a partially completed download/upload.

For download everything is driven by the GCS/API and that can just stop getting items whenever it likes - ie cancelling is just stopping.

For upload of mission to vehicle the API initiates the upload, which starts the process of the drone requesting mission items (which are returned in MISSION_ITEM or MISSION_ITEM_INT). In this case there is no ACK in the sequence, so how does an API tell the drone that it is ignoring future mission item requests and stopping the upload?

@julianoes , any ideas?

Setup signing when autopilot has unknown secret key

Situation:

1. The autopilot has been configured with a secret key.
2. That secret key is now unknown/forgotten.

Problem:
The autopilot drops unsigned or incorrectly signed SETUP_SIGNING messages, thus making it impossible to recover from a lost secret key via Mavlink communication.

Questions:

1. Is that a scenario that should be handled by Mavlink? Or is it expected that the autopilot device may have a reset secret key button or some other such recovery mechanism?
2. If it is a problem that Mavlink should provide a standard solution for, do we have such solution? If so, what is it?

Do we need information about performance?

The following performance below was copied from mavlink.org - I don't think it is at all useful.

What sorts of performance information might be useful?

• I guess something comparative - ie using MAVLink vs some other protocol
• Something that shows range/data loss limits for working with common autopilot systems
• Kind of data rates you can get over USB say for companion computer control, and what sort of specific things this allows vs what you can't do.

Not really sure. Maybe it isn't useful.

===== Performance =====

This protocol was totally geared towards two properties: Transmission speed and safety. It allows to check the message content, it also allows to detect lost messages but still only needs six bytes overhead for each packet.

=== Transmission examples ===

^ Link speed     ^ Hardware          ^ Update rate  ^ Payload    ^ Float values ^
|    115200 baud | XBee Pro 2.4 GHz  |        50 Hz |  224 bytes |           56 |
|    115200 baud | XBee Pro 2.4 GHz  |       100 Hz |  109 bytes |           27 |
|     57600 baud | XBee Pro 2.4 GHz  |       100 Hz |   51 bytes |           12 |
|      9600 baud | XBee Pro XSC 900  |        50 Hz |   13 bytes |            3 |
|      9600 baud | XBee Pro XSC 900  |        20 Hz |   42 bytes |           10 |

Instructions for playing with MAVLink

People who are interested in learning the protocol want to play around with code, and might not have a real vehicle.
We need instructions to help them do this without too much thinking - part of example code.

• Talk to a vehicle - connect and send messages.
• Talk to a GCS - pretend to be a vehicle
• Talk to example code server
• Talk to test suite ?

Probably just instructions to set up simulator in first place.

Clarify what needs to happen for MAVLink Routing

A few notes to add for routing:

• A MAVLink IP-based router does not need to check the CRC because these protocols have their own packet CRC.
• Unfortunately CRC_EXTRA prevents you from routing an unknown packet.
• The end user (not router) still needs to check the CRC, in order to get CRC_EXTRA and verify that the message is compatible.

@LorenzMeier -From mavlink email group:

• Is it possible to disable the CRC_EXTRA check so that routers can parse messages without having to know whether or not they are supported by the end point.
• If not, propose we add a compile-time flag to disable CRC checks. OK?

Create contribution and approval guidelines

We don't have any guidelines to contributing to MAVLink. We also don't have any clarification on how this project works with the downstream version on ArduPilot (the fork).

@dagar @julianoes Can we have a discussion about what the process is for updating different parts of the code, tooling, messages?

Highlight the pattern for point to point messages

Just removed the target sys and comp id that were incorrectly in packet format: #100.

The requirement is to add the pattern/conventions that we use for this type of message in Protocols

Propose merge /doc/MAVLink2.md into developer guide

Merge: https://github.com/mavlink/mavlink/blob/master/doc/MAVLink2.md
into
https://mavlink.io/en/mavlink_2.html

And then delete the original doc.

Any objections. Speak now or forever hold your peace!

Improve packet signing documentation

Packet signing is currently primarily about the C implementation. It needs to keep that information, but be more generic/reusable. That way we can have doc for people who want to understand how things work and implement their own generator, and separate docs on the detail for each generated MAVLink library.

Background for signing is here: https://docs.google.com/document/d/1ETle6qQRcaNWAmpG2wz0oOpFKSF_bcTmYMQvtTGI8ns/edit#heading=h.r1r08t7lr2pc

How does MAVLink versioning work in v1, v2

This is attempting to get clarification on versioning question I raised here: mavlink/mavlink#795 (comment)

Versioning in MAVLink is quite unclear. It is not clear:

1. What versioning mechanisms we have
2. What each versioning mechanism is supposed to achieve.
3. What are the shortcomings
4. How we might improve.

Ultimately the point of versioning is to ensure that systems are able to recognise and handle compatible messages - that they don't inadvertently attempt to handle messages they don't understand.

I think MAVLink handles the compatibility/version problem in the following way.

• All messages include a protocol-specific start byte. If a receiver doesn't understand the protocol (start byte) it will simply not see the message. This means old MAVLink 1 engines will ignore all v2 messages.
• MAVLink 2 messages with ids > 256 are not send when using v1 protocol.
• MAVLink 2 adds new fields to some MAVLink 1 messages (these are marked with the <extension> tag before new message fields).
  • These fields are not send (or received) in v1 messages.
  • These fields ignored if received by an implementation that doesn't understand them
  • These fields are zero filled when received by an implementation that understands them, but sent by a system that does not.
• All MAVLink messages include a CRC code, which captures the structure of the message definition (field names and order - presumably type?). If any of these things differ between sender and receiver then the CRC calculated for the message at each end will be different and the receiver will know the message is incompatible.
• MAVLink 2 also adds (in)compatibility flags, that contain flags about changes in the handling for the packet - for example, a different packet format that has been used. This can, for example, be used to prevent MAVLink 2 attempting to handle signing, if the implementation does not understand the signing format used.

So as above MAVLink 1 receivers will only handle MAVLink 1 messages. MAVLink 2 messages will get additional messages (id>256) and fields for low id messages. As far as I can tell, the only versioning check available is the CRC - you can tell if a message is compatible.

1. Is that correct - i.e. is "compatible version of message" the only check we have?
2. What if a message is incompatible - does the reciever (always/sometimes) send a response (what is it?) or is the message dropped?
3. How can the sender/receiver work out what version they each have to check compatibility.

The implication is that if you iterate a dialect you can add new messages, but you can't modify, remove or replace a message without breaking compatibility. If you break this compatibility you can't tell what version it happened in - all you can really do is make both ends update to the latest version of the dialect.

There are two other "versioning" artifacts in the message definitions.

      <mavlink>
      <version>3</version>
      <dialect>0</dialect>

4. What are these actually used for?
   • ie how are they used in the toolchain
   • what value should they have
   • when should the value iterate.
   • If a dialect includes a dialect (that has a version and dialect number), what does that mean?

MAVLink 2 Variable Length arrays doc incorrect?

MAVLink 2 > Variable length arrays says something that appears to be incorrect.

MAVLink 2 truncates any zero (empty) elements at the end of the largest array in a message. Other arrays in the message will not be truncated.

As far as I can see in the code this does not happen and is contradictory to our other docs. What actually happens is that whatever zero elements are at the end of the message will be stripped. That could be part or all of one or multiple fields (smallest sized objects based on reordering). It might not be part of an array.

Looking at the code and field reordering docs what happens is that

• all elements are ordered for sending by size of the object type from largest to smallest and within the object size, elements retain their declaration order.
• The message is packed by the sending code with all empty fields and values "zero filled".
• The sending code strips all zeros off the end of the message, gets the new payload length, and puts that into the message (which after some more playing around gets sent)
• When the message is received the payload is recovered. If the length of the received payload is less than the expected max for the message, the message buffer is zero filled at the end. This reconstructs the full expected message buffer.

There does not appear to be any code to handle sorting or stripping of empty array info.

Can anyone confirm. If I am incorrect, how does the array truncation work (can you show me the mavgen code?)

Further, this probably implies that large arrays that are more likely to be empty should be the last field in a message.

Can we please also rename the book on Gitbook

Currently this is:

Devguide
The MAVLink Developer Guide

But in theory this is where QGC Devguide should also live, and other things in future.

Lets change to:

MAVLink Developer Guide
MAVLink is a very lightweight, header-only message marshalling library for micro air vehicles / drones. This guide details the library protocols, routing, serialisation and the library reference implementation.

Migrate all content from mavlink.org with warnings

The content on mavlink.org is of unknown quality. I have been unable to get support with reviewing it and determining quality.

Plan is to import all the content and add a disclaimer that it is unverified/may be out of date/needs checking. I may also group it all in a folder that reflects that status.

Also will delete anything I am able to identify as not useful or already ported.

General:

• Update top header bar so goes to correct new sites.

List of all remaining docs (checked means "dealt with")

• MAVLink Micro Air Vehicle Communication Protocol (Start page)
• Dev entry point http://qgroundcontrol.org/dev/start
• http://qgroundcontrol.org/users/joystick Joysticks
• http://qgroundcontrol.org/mavlink/crc_extra_calculation -
• http://qgroundcontrol.org/playground/playground -
• http://qgroundcontrol.org/mavlink/mavproxy_startpage
• Legacy user guide entry point (http://qgroundcontrol.org/users/start)
• http://qgroundcontrol.org/users/record_qgroundcontrol
• http://qgroundcontrol.org/users/matlab_import
• http://qgroundcontrol.org/users/models
• MAVLink File Transfer Protocol (FTP)
• Image Transmission Protocol
• Control Interface
• Create a new MAVLink Message
• MAVLink Generator (C/C++, Python)
• Downloading / Installing MAVLink
• MAVLink Mission Interface
• MAVLink Mission Library (missionlib)
• MAVLink Packaging
• Parameter Protocol
• MAVLink v0.9 to v1.0 Porting Guide
• MAVLink Python Bindings
• MAVLink Release 1.1 Compatibility and Features
• Waypoint Protocol

Message Definitions need to include how to define messages

We need information about how to create new messages, including

• Style guide (e.g. for punctuation). Not including units in the text (except if conditional on something, so multiple options possible). Naming params etc. I wonder if we can astyle this?
• Units - what they are.
• General comments about message format/schema, and in particular about the allowed units: https://github.com/ArduPilot/pymavlink/blob/master/generator/mavschema.xsd#L58

This might be a new document, or as part of Message Definitions - but either way should be linked from message definitions.

We might also try auto-import the XML via gitbook.

Discussion on this started here: mavlink/mavlink#914 (comment)

Doc Bug: Generate MAVLink Libraries · MAVLink Developer Guide

DESCRIBE PROBLEM WITH DOCS HERE

Bug Page: Generate MAVLink Libraries · MAVLink Developer Guide

"mavgen" do not support generate c++ library for v1.0. When you try to do that, it will display the following error:
ValueError: C++ implementation only support --wire-protocol=2.0

Please correct the table in this page

Mission upload/download clarifications

@hamishwillee I was staring quite a while at these diagrams here today:
https://mavlink.io/en/services/mission.html#uploading_mission

And I have some questions that you might have thoughts on:

1. We describe the timeouts on the ground station side. What about the drone side? As far as I know the implementation we also have timeouts active on that side. Do we just omit these for clarity in the diagram or are the specs actually that the autopilot should not have to keep track of timeouts? (I think it probably should, otherwise it would not even know if something failed/timed out altogether).
2. What is supposed to happen if the last MISSION_ACK is lost on the link? Should we re-send the last MISSION_ITEM_INT until we get the ack? Or is a lost ack just the end of the world, and we have to redo everything?

Explain SYSTEM IDS and allocation

This question asks how System IDs are allocated: http://discuss.px4.io/t/what-is-and-how-does-one-select-a-system-id/6905/6

Check that we haven't covered this in the guide, and if not, make sure that this is covered. Also make sure that UUIDs are mentioned and the allocation strategy. Check component IDs have something sensible said too.

Camera Protocol - Add sequence diagrams

Camera Protocol · MAVLink Developer Guide

Could be made more clear with sequence diagrams (generate using mermaid plugin)

Are generators/generated files always LPGL/MIT?

We have multiple generated libraries. I see that both Python and C generators are LGPL and that the generated libraries are MIT.

Do all other generators and generated files follow the same pattern, and do they have to?

Message Signing - updates on implementations

Message Signing · MAVLink Developer Guide

Mission planner/ArduPilot have an implementation. This should be linked. The discussion on this can be found here:

• ArduPilot/ardupilot_wiki#1553
• https://discuss.ardupilot.org/t/enabling-mavlink-2-0-and-packet-signing/25656/11
• Mavproxy docs: https://ardupilot.github.io/MAVProxy/html/modules/signing.html

More user friendly guidance

There are better docs for getting to understand MAVLink. Essentially they are less "technical" and do not attempt to cover everything.

• https://discuss.ardupilot.org/t/mavlink-step-by-step/9629
• http://api.ning.com/files/i*tFWQTF2R*7Mmw7hksAU-u9IABKNDO9apguOiSOCfvi2znk1tXhur0Bt00jTOldFvob-Sczg3*lDcgChG26QaHZpzEcISM5/MAVLINK_FOR_DUMMIESPart1_v.1.1.pdf

We should learn from these and restructure for target audiences - those wishing to use MAVLink, or to create their own generators.

Mission Protocol - Clarifications on Geofence and Rally + Regular

Mission Protocol covers regular missions in detail, and mentions how you set the two "new in MAVLink 2" types: - MAV_MISSION_TYPE_FENCE, MAV_MISSION_TYPE_RALLY

1. For Rally Points, my assumption is:
   • A rally point is just like a flight plan mission except that you only use the MAV_CMD_NAV_RALLY_POINT as a command, and of course the mission_type
   • MAV_PROTOCOL_CAPABILITY_MISSION_RALLY should be set to specify support.

Is there anything else to them?

2. For Geofence,
   • I assume that you can define a bunch of things about the fence using these messages: MAV_CMD_NAV_FENCE_RETURN_POINT, MAV_CMD_NAV_FENCE_POLYGON_VERTEX_INCLUSION, MAV_CMD_NAV_FENCE_CIRCLE_INCLUSION, MAV_CMD_NAV_FENCE_CIRCLE_INCLUSION, MAV_CMD_NAV_FENCE_CIRCLE_EXCLUSION
   • Also that you can turn it on and off at different points in the mission using MAV_CMD_DO_FENCE_ENABLE?
   • If you support the feature you enable MAV_PROTOCOL_CAPABILITY_MISSION_FENCE

Is that right? In PX4 can these be sent outside of missions?

How do you use FENCE_ACTION, FENCE_BREACH ?

Field Reordering

Went looking through the docs to refresh myself on how field reordering works and didn't find it.

Maybe add what's documented here would be helpful. Perhaps add it to the "Serialization" page?

Not entirely sure what happens in MAVLink2 extended fields, are they factored in reordering or are they separate? Perhaps this should be clarified as well.

Protocol Overview · MAVLink Developer Guide - serialisation info MAVLink 1 only

Bug Page: Protocol Overview · MAVLink Developer Guide

The serialisation section needs to link to the serialization topic, and make it clear that this is MAV1 specific.

Contributions/Team page

Open-source 101 says that you have a page on contributing, project team, and acknowledgements (historical project team). Is there an original acknowledgements page somewhere I can mine for the last part? Are there any "ways of working" docs already around for this project?

Downstream projects

We probably should try to highlight the other projects that use MAVLink too - since it is widely used and that is a key selling point.

HOw about a Downstream projects section in the sidebar and/or a topic of the same name?

We could add PX4, UGS, Dronekit etc etc. Who else?

Negotiating versions with signed systems.

Questions: Must all connected entities share the same signature/protocol version?

EDITED: Following discussions. Original version here but is commented.

MAVLink Versions isn't very clear on this because it talks in terms of links and just two systems. It doesn't cover the case explicitly where you might have a link to a wifi network that has systems that support just MAVLink 1, MAVLink 2, and MAVLink 2 with signing.

Here are some assumptions that would be good to confirm:

1. A MAVLink network is made up of a set of "nodes". Each unique node is a component, which may be part of a system (and has ids for each of those).
2. Nodes on a network that are able to communicate with each other may be connected (they consider themselves reliably connected if they are regularly accepting HEARTBEAT messages from each other).
3. The connection between nodes can be over many transports - ie via a usb cable, via wifi, or bridged.
4. The physical interface from a particular node to the rest of the network is via a serial port (which might be connected to wifi or whatever).
5. Two nodes are able to talk to each other if they talk the same protocol/signature.
6. MAVLink version/signature settings are defined for the particular channel/port - not for each node (ie you can't easily specify that different nodes on the same port communicate with different MAVLink version.
   • It is not clear if this is a requirement of the standard or a requirement of the library but it is an implementation fact of both C and pymavlink libraries.
     • The C library refers to a channel, which is essentially a buffer that is fed to a particular serial port. The settings for the version of mavlink and signing are defined per channel.
     • Pymavlink refers to a "connection" but again this really represents a physical channel/port - it isn't a filter to a particular system/component
   • The term link is widely used to mean physical channel out of a node to one or more other nodes.
7. If signing is enabled on a system then it can only connect to systems that are set up with the same signature. It will drop any other heartbeats (by default).

Back to the original question:

Must all connected entities share the same signature/protocol version?

Yes. To be connected, nodes must share the same signature/protocol version.

For the C and Pymavlink implementations the settings for MAVLink version/signing are per-channel. So if a system wants to talk to other systems that have different versions/signatures (or none) then it should use separate channels for those.

In terms of negotiation,

• if signing is enabled there is no negotiation - a vehicle won't even "see" heartbeats from vehicles with the wrong signature since such messages are automatically dropped (though they may be forwarded if of broadcast type).
  • signing is set up separately over a secure link, using mechanisms that are suggested but not defined by the standard.
• If signing not enabled:
  • A mavlink 2 system can see mavlink 1 packets and choose to use mavlink 1 or mavlink 2.
  • Typically MAVLink 2 is desired, and MAVLink 1 is ONLY used for a few peripherals. So the typical configuration is that mavlink 1 peripherals are connected via their own channel (e.g. a cable). Everything else is mavlink 2, and can connect over another channel.
• The negotiation rules facilitate the above. Typically mavlink 1 is used by default and then the channel switches to mavlink 2 as soon as any mavlink 2 packets are detected.

Document Offboard Control protocol

Currently we use Protocols · MAVLink Developer Guide to group sub protocols (ie Mission, Command, etc). As part of documenting the protocol this also sensibly groups messages.

However we don't have any similar spot to group "interfaces" - logical sets of messages without any special protocol over/above the command protocol (say). For example Offboard (Control) messages.

Possible option is to make the Protocols section - Protocols & Interfaces.

Provide "mavlink message supported" flags for PX4 etc

Spawning discussion for this from other thread:

• #34 (comment)
• #34 (comment)
• #34 (comment)
• #34 (comment)

Idea is to make it easy for users to work out what messages are actually supported. Discussion on other thread ended with statement from @julianoes that the support flags would best live in the autopilot's repo.

See why common.xml doc is so heavyweight

Reported by users that one reason that old mavlink.org is used is that the mavlink.io message specs are slower to load.
Benchmarks (my computer, approx same time)

Action	mavlink.io	mavlink.org
common	944Kb / 1.64s	68.8Kb / 2.45s
transferred	1.54Mb	69.4kb
finish	8.1s	5.77s
DomContentLoaded	3.23	2.25
load	5.41s	3.14

Even though the file is clearly much bigger in gitbook. The time before you can start browsing HTML is fairly similar on my computer - about 3 seconds. Obviously on a slow link you'd get much worse performance from the big file load.

The rendering of the main content is very similar time - perhaps even faster. It feels a bit slower though, because the left panel sidebar is still rendering.

Doc Bug: MAVLink 2 - Superseded by one in source tree?

Should this MAVLink 2 page be replaced by the one in source tree: mavlink/doc/MAVLink2.md.

Doc Bug: Serialization - Check minimum bytes for MAV2 message

Bug Page: Serialization · MAVLink Developer Guide

This says 14, but check, because think it is 12

what is the meaning of "Allows up to 255 concurrent systems on the network"

what is the meaning of "Allows up to 255 concurrent systems on the network"? further mavlink protocol can send video ?

Split serialisation topic and better organise

https://mavlink.io/en/guide/serialization.html

This doc is primarily about the serialisation format - ie it is most useful for people implementing their own parsers.

The top however has a user example about the serialisation API.

I think the user info should go into the "Using" examples, and we should link to it from this doc. This doc should probably also move into a section for mavlink-library implementer developers.

Lets make this multi-lingual

I'll do this today.