Differences

This shows you the differences between two versions of the page.

Link to this comparison view

mavlink:start [2018/02/14 05:21]
hamishwillee
mavlink:start [2018/07/10 12:15] (current)
hamishwillee [Protocol Internals]
Line 1: Line 1:
 ~~NOTOC~~ ~~NOTOC~~
  
-[[https://​mavlink.io/​en/​|MAVLINK DOCUMENTATION HAS MOVED HERE!]] The remainder of this documentation is being migrated and deleted.+**[[https://​mavlink.io/​en/​|MAVLINK DOCUMENTATION HAS MOVED HERE!]] The remainder of this documentation is being migrated and deleted. 
 +** 
 +**Broken links, etc should be ignored - the content has either been moved or is no longer relevant.**
  
 ====== MAVLink Micro Air Vehicle Communication Protocol ====== ====== MAVLink Micro Air Vehicle Communication Protocol ======
- 
- 
  
 {{:​mavlink:​mavlink-logo.png?​400&​nolink|MAVLink Logo}} {{:​mavlink:​mavlink-logo.png?​400&​nolink|MAVLink Logo}}
Line 17: Line 17:
 === Message Specification === === Message Specification ===
  
-//**The current MAVLink Protocol Version can be looked up here: [[http://mavlink.org/​messages/​common|Common MAVLink Message Documentation]]**//​+//**The current MAVLink Protocol Version can be looked up here: [[https://mavlink.io/en/​messages/​common.html|Common MAVLink Message Documentation]]**//​
  
  
Line 29: Line 29:
 ===== Protocol Internals ===== ===== Protocol Internals =====
  
-  * [[https://​mavlink.io/​en/​serialization.html|Serialization]] (Section "​On-the-wire format and extra CRC calculation"​ is highly recommended article explaining API vs Internal formats). ​+  * [[https://​mavlink.io/​en/guide/​serialization.html|Serialization]] (Section "​On-the-wire format and extra CRC calculation"​ is highly recommended article explaining API vs Internal formats). ​
   * [[release_11]]   * [[release_11]]
   * [[mission_interface]]   * [[mission_interface]]
-    * [[waypoint_protocol]] 
-    * [[parameter_protocol]] 
-    * [[image_transmission_protocol]] 
     * [[control_interface]]     * [[control_interface]]
-  * [[http://​mavlink.org/​messages/​common|Common MAVLink Messages]] 
  
  
Line 43: Line 39:
  
 ====== MAVLink Code and Generator ====== ====== MAVLink Code and Generator ======
- 
-There is a "​common message set" containing widely used messages, which is distributed as header-only C library. If you like to use your own custom messages, you can generate these with the [[:​mavlink:​generator]] or [[http://​qgroundcontrol.org|QGroundControl]]. 
- 
-The MAVLink message definitions and generator code is hosted at: 
- 
-  * https://​github.com/​mavlink/​mavlink/​ 
- 
-Installation / usage instructions can be found at: 
- 
-  * [[:​mavlink:​installation]] 
- 
-Instructions how to use the generator can be found at: 
- 
-  * [[:​mavlink:​generator]] 
  
 Instructions how to package MAVLink releases (**developers only**) can be found here: Instructions how to package MAVLink releases (**developers only**) can be found here:
Line 64: Line 46:
 ====== MAVLink Ecosystem ====== ====== MAVLink Ecosystem ======
  
-There are by now many systems and software packages using MAVLink: +Migrated to mavlink.io: https://​github.com/​mavlink/​mavlink-devguide/pull/69/files
- +
-==== MAVLink Mailing List and Developers ==== +
- +
-  * Mailing list http://​groups.google.com/​group/​mavlink +
-  * Maintainer: Lorenz Meier, <lm@inf.ethz.ch>​ +
-  * Developer team: Lorenz Meier, Andrew Tridgell, James Goppert +
- +
-==== Autopilots using MAVLink ==== +
- +
-  * [[http://​code.google.com/​p/​ardupilot-mega/​|ArduPilotMega]] (main protocol) +
-  * [[http://​pixhawk.ethz.ch/​wiki/​electronics/​imu|pxIMU Autopilot]] (main protocol) +
-  * [[http://​slugsuav.soe.ucsc.edu/​index.html|SLUGS Autopilot]] (main protocol) +
-  * [[http://​www.aerialrobotics.eu/​flexipilot/​flexipilot1.2-osd-en.pdf|FLEXIPILOT]] (optional protocol) +
-  * [[http://​code.google.com/​p/​gentlenav/​wiki/​MatrixPilot|UAVDevBoard/​Gentlenav/​MatrixPilot]] (optional protocol) +
-  * [[http://​www.sensesoar.ethz.ch/​doku.php?​id=news|SenseSoar Autopilot]] (main protocol) +
-  * [[http://​www.sky-drones.com/​|SmartAP Autopilot]] (main protocol) +
-  * [[http://​autoquad.org|AutoQuad 6 AutoPilot]] (main protocol) +
-==== Software packages using MAVLink ==== +
- +
-  * [[http://​fightingwalrus.com/​pages/​idronectrl|iDroneCtrl (iOS)]] +
-  * [[http://​www.qgroundcontrol.org/​|QGroundControl (Windows/​Mac/​Linux)]] +
-  * [[http://​code.google.com/​p/​happykillmore-gcs/​|HK Ground Control Station (Windows)]] +
-  * [[http://​code.google.com/​p/​ardupilot-mega/​wiki/​Mission|APM Planner (Windows/​Mac)]] +
-  * [[http://​autoquad.org/​software-downloads/?​category=2|QGroundControl w/ AutoQuad MainWidget (Windows/​Mac/​Linux)]] +
-  * [[http://​code.google.com/​p/​copter-gcs/​|Copter GCS (Android)]] +
-  * [[http://​autoquad.org/​software-downloads/?​category=2|AutoQuad GCS (Android)]] +
-  * ROS to MAVLink bridge: https://​github.com/​mavlink/​mavlink-ros +
-  * MAVCONN Lightweight Aerial Middleware http://pixhawk.ethz.ch/​software/​middleware/​start +
-  * oooArk / MAVSim http://​www.youtube.com/​watch?​v=-wQVrM5SL2o&​fe +
-  * [[pymavlink|MAVLink python bindings]] +
-  * [[http://​ardupilot.github.io/​MAVProxy/​html/​index.html|MAVProxy]] (allows to connect multiple UDP/serial links, including flightgear) +
-==== Projects using MAVLink ====+
  
-  * ArduPilotMega http://​code.google.com/​p/​ardupilot-mega/​ 
-  * MatrixPilot UAV DevBoard http://​code.google.com/​p/​gentlenav/​ 
-  * PIXHAWK http://​pixhawk.ethz.ch/​ 
-  * ETH Flying Machine Arena http://​www.idsc.ethz.ch/​Research_DAndrea/​FMA 
-  * ETH SenseSoar Solar Airplane Project http://​www.sensesoar.ethz.ch/​doku.php?​id=news 
-  * ETH Skye Blimp Project http://​www.projectskye.ch/​ 
-  * UC Santa Cruz SLUGS http://​slugsuav.soe.ucsc.edu/​index.html 
-  * ArduCAM OSD http://​code.google.com/​p/​arducam-osd/​ 
-  * Sky-Drones - UAV Flight Control Systems http://​www.sky-drones.com/​ 
-  * AutoQuad - Autonomous Multirotor Vehicle controller http://​autoquad.org/​ 
 ====== License ====== ====== License ======
  
-The MAVLink generator is LGPL licensed and its output is MIT licensed and can therefore be used as a library royalty-free in closed-source and open-source applications.+See https://​mavlink.io/​en/#​license
  
 ====== Frequently Asked Questions (FAQ) ====== ====== Frequently Asked Questions (FAQ) ======
  
-=== Upgrading from 0.9.0 to 1.0.0 === +FAQ moved to mavlink.iohttps://github.com/mavlink/mavlink-devguide/pull/70
- +
-  * **QIs the upgrade easily done?** - Yes, v.1.0.0 is almost fully API-compatible with v.0.9.0. Only a few messages have changed, all protocol-functions like the message parsing (mavlink_parse_char) are fully compatible. +
-  * **QWhat are the main benefits from upgrading?​** - 1. MAVLink now uses the little-endian wire encoding, which makes is a lot more efficient on most platforms. It still supports little and big endian platforms. 2. It now checks the packet format of each message, so if two communication partners have different formats for the same message it will detect this mismatch. 3. It now has support for smaller message buffers. 4. The parameter protocol now supports 32 unsigned and signed integer and float values. 5. MAVLink now supports IEEE 754 double precision floating point numbers. 6. All messages are tested with an automatically generated test suite, making the protocol even safer to use. 7. Some messages have been cleaned up to better suit actual flight use. 8. MAVLink comes per default now with C/C++ and Python support. +
-  * **Q: Is the new version to be used soon?** - Yes, QGroundControl is fully ported to it and ArduPilotMega and PIXHAWK already are porting their software. Soon all adopters will have ported to the new version, simply because it is not too much effort. +
- +
- +
-=== Users === +
- +
-  * **Q: How many aircraft does MAVLink support?** - 255 aircraft, ranging from 1 to 255. 0 is not a valid aircraft id. +
-  * **Q: How efficient is MAVLink?** - With just 8 bytes overhead per packet, including start sign and packet drop detection, MAVLink is a very efficient protocol. +
-  * **Q: Where can I use MAVLink?** - MAVLink has been shown to work on multiple microcontrollers and operating systems, including ARM7, ATMega, dsPic, STM32 and Windows, Linux, MacOS and iOS. +
-  * **Q: How safe is MAVLink?** - MAVLink has been used for more than two years in the PIXHAWK MAV project in flight and relies on the well-established ITU X.25 checksum for packet corruption detection. +
- +
-=== Developers === +
- +
-  * **Q: Can I use MAVLink in a closed source application without copyright issues?** - Yes, without any limitations. The LGPL license only requires you to contribute changes to MAVLink itself to the community, not any code that uses MAVLink. So you are not required to publish any of your application code. +
-  * **Q: MAVLink uses only one start sign - isn't this less safe than using two or three start signs?** - No. A packet start sign is always used to "sync up" to the start of a message. To actually "​prove"​ that the received data is a message and not random noise, the message length and check sum is needed. Using more start signs would allow to better "​guess"​ a packet start in a random noise channel. Since MAV telemetry is however not random noise, using more start signs does not help to increase the certainty about a packet start, because if the decoding state machine does only depend on the packet start sign, it will reject all packets containing the start sign in their payload. ​//Example: Most protocols encode payload length and message id in the header, often as continuing fields. If the start sign is e.g. (0x35 0x55) (two bytes), which is in decimal (53 85), a packet with length 53 and ID 85 will always be rejected by the decoder.// To circumvent these systematic faults, the message should only be rejected if the checksum mismatches. Given these constraints,​ one can as well just use one packet start sign and save unneccesary bytes on the communication link. +
-  * **Q: How does MAVLink detect and decode messages in the byte stream?​** ​MAVLink waits for the packet start sign, then reads the packet length and matches the checksum after //**n**// bytes. If the checksum matches, it returns the decoded packet and waits again for the start sign. If bytes are altered or lost, it will drop the current message and continue the next try on the following message. +
-  * **Q: What use do the system and component IDs have?** - The system ID reflects the current aircraft. MAVLink can be used with multiple aircraft simultaneously. The component ID reflects the onboard component, e.g. the IMU, the autopilot or the onboard computer. This allows to use MAVLink both for onboard-communication and for off-board telemetry. +
-  * **Q: MAVLink contains a sequence number in the header - is this really necessary?​** - Yes. MAVLink is part of the safety critical components of an unmanned air system. A bad communication link dropping many packets can endanger the flight safety of the aircraft and has to be monitored. Having the sequence in the header allows MAVLink to continously provide feedback about the packet drop rate and thus allows the aircraft or ground control station to take action. +
-  * **Q: I would like to help improve the decoding/​encoding routines or other features. Can MAVLink be changed?** - Yes, but only very, very carefully with safety testing. MAVLink is by now used as a safety-critical component in many autopilot systems and has undergone more than two years of testing. Please suggest new features on the [[http://​groups.google.com/​group/​mavlink|MAVLink mailing list]].+
  
 ===== Packet Anatomy ===== ===== Packet Anatomy =====
  
-This is the anatomy of one packet. It is inspired by the [[wp>​Controller_Area_Network|CAN]] and SAE AS-4 standards. +Section moved into mavlink.io: https://​github.com/​mavlink/mavlink-devguide/pull/72
- +
-{{:mavlink:​mavlink-packet.png?​400|MAVLink packet}}\\ +
-\\ +
-\\ +
- +
- +
-^    Byte Index      ^ Content ​                          ​^ ​ Value                    ^ Explanation ​          ^ +
-|                  0 | Packet start sign                | v1.00xFE (v0.9: 0x55)        | Indicates the start of a new packet. ​ | +
-|                  1 | Payload length ​                  | 0 - 255                    | Indicates length of the following payload. ​ | +
-|                  2 | Packet sequence ​                 | 0 - 255                    | Each component counts up his send sequence. Allows to detect packet loss  | +
-|                  3 | System ID                        | 1 - 255                    | ID of the SENDING system. Allows to differentiate different MAVs on the same network. ​ | +
-|                  4 | Component ID                     | 0 - 255                    | ID of the SENDING component. Allows to differentiate different components of the same system, e.g. the IMU and the autopilot. ​ | +
-|                  5 | Message ID                       | 0 - 255                    | ID of the message - the id defines what the payload "​means"​ and how it should be correctly decoded. ​ | +
-|         6 to (n+6) | Data                             | (0 - 255) bytes            | Data of the message, depends on the message id.  | +
-|     (n+7) to (n+8) | Checksum (low byte, high byte)   | ITU X.25/SAE AS-4 hash, **excluding packet start sign, so bytes 1..(n+6)** Note: The checksum also includes MAVLINK_CRC_EXTRA (Number computed from message fields. Protects the packet from decoding a different version of the same packet but with different variables). ​     || +
- +
-  * The checksum is the same as used in ITU X.25 and SAE AS-4 standards ([[wp>​Cyclic_redundancy_check#​Commonly_used_and_standardized_CRCs|CRC-16-CCITT]]),​ documented in [[http://​www.sae.org/​servlets/​productDetail?​PROD_TYP=STD&​PROD_CD=AS5669A|SAE AS5669A]]. **Please see the MAVLink source code for a documented C-implementation of it. [[https://​github.com/​pixhawk/mavlink/blob/master/​include/​checksum.h|LINK TO CHECKSUM]]** +
-  * The minimum packet length is 8 bytes for acknowledgement packets without payload +
-  * The maximum packet length is 263 bytes for full payload+
 ===== Supported data types ===== ===== Supported data types =====
  
Line 176: Line 76:
   * **uint8_t_mavlink_version** - Unsigned 8 bit field automatically filled on sending with the current MAVLink version - it cannot be written, just read from the packet like a normal uint8_t field   * **uint8_t_mavlink_version** - Unsigned 8 bit field automatically filled on sending with the current MAVLink version - it cannot be written, just read from the packet like a normal uint8_t field
  
-===== 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 | 
  
-====== Future Work / Ideas ====== 
  
-  * Variable length arrays 
-  * Support for bitfields (e.g. packing 8 boolean values into one uint8_t, but providing C-function calls to all eight booleans. So users would not have to fiddle with shifting / masking themselves.) 
-  * Variable header, allowing to set target system and target component (no change to protocol, only convenience functions to access it) 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported