mirror of
https://github.com/mavlink/mavlink-devguide.git
synced 2026-06-19 07:36:26 +00:00
add kr folder
This commit is contained in:
Jeyong Shin
@@ -1,4 +1,4 @@
|
||||
* [English](en/)
|
||||
* [Korean (한국어)](kr/)
|
||||
<!-- * [Chinese (中文)](zh/) -->
|
||||
<!-- * [Español](es/) -->
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# 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](mission_protocol.md) or [parameter protocol](parameter_protocol.md) are point-to-point with retransmission.
|
||||
|
||||
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/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](https://github.com/mavlink/mavlink/graphs/contributors).
|
||||
|
||||
The content of this book is CC-BY 4.0 licensed.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Summary
|
||||
|
||||
* [Introduction](README.md)
|
||||
* [Protocol Overview](protocol.md)
|
||||
* [Serialization](serialization.md)
|
||||
* [Routing](routing.md)
|
||||
* [General Telemetry](general_telemetry.md)
|
||||
* [Mission Protocol](mission_protocol.md)
|
||||
* [Parameter Protocol](parameter_protocol.md)
|
||||
* [Camera Protocol](camera_protocol.md)
|
||||
* [Gimbal Protocol](gimbal_protocol.md)
|
||||
@@ -0,0 +1,48 @@
|
||||
# Camera Protocol
|
||||
|
||||
The camera protocol allows to configure camera payloads and request their status. It supports photo and video cameras and includes messages to query and configure the onboard camera storage.
|
||||
|
||||
## Still camera control
|
||||
|
||||
### Message interface :
|
||||
|
||||
The [CAMERA\_IMAGE\_CAPTURED](http://mavlink.org/messages/common#CAMERA_IMAGE_CAPTURED) message is intended for geo-tagging and camera feedback. It should be sent by the camera when an image has been taken. This message is not intended for latency-sensitive consumers, but rather for automatic geotagging from the GCS. There is also a retransmission protocol in place for this message.
|
||||
|
||||
The [CAMERA\_TRIGGER](http://mavlink.org/messages/common#CAMERA_TRIGGER) message is intended for informing onboard systems that a trigger event has occurred. It does not guarantee that a camera image has been captured. It is intended to be used in situations where a frame drop is not critical, but rather where time-stamping of e.g image and IMU data is required in a low-latency fashion (e.g Visual Inertial Odometry)
|
||||
|
||||
|
||||
### Command interface :
|
||||
|
||||
**`MAV_CMD_DO_TRIGGER_CONTROL`** - Used to control the onboard camera _trigger_ (e.g which does camera control based on distance covered or time intervals). It should ONLY be used start/stop(unpause/pause) triggering functionality. **FIXME** : currently hackily used to set intervalometer cycle time, which should really be a different command.
|
||||
|
||||
| Command Parameter | Description |
|
||||
| -- | -- |
|
||||
| Param #1 | Trigger enable/disable (set to 0 for disable, 1 for start) |
|
||||
| Param #2 | Trigger cycle time in milliseconds. FIXME : this field has no place here |
|
||||
| Param #3 | Sequence reset (set to 1 to reset image sequence number, 0 to keep current sequence number) |
|
||||
|
||||
**`MAV_CMD_DO_DIGICAM_CONTROL` ** - Used to control an onboard camera. Should be forwarded by onboard MAVLink routing system for controlling cameras which directly support MAVLink. It may also be consumed by an onboard camera control module and used to control a 'naive' camera. When an onboard trigger module is active, which paces a camera based on vehicle state (e.g distance covered), the trigger module should also emit this command for other MAVLink-compatible cameras on the bus.
|
||||
|
||||
| Command Parameter | Description |
|
||||
| -- | -- |
|
||||
| Param #5 | Set to 1 to trigger a single image frame. |
|
||||
|
||||
TODO : this cmd has more params
|
||||
|
||||
**`MAV_CMD_DO_SET_CAM_TRIGG_DIST`** - Sets the distance interval for camera triggering. The camera is triggered each time this distance over ground is covered by the aircraft. **FIXME** : currently it is hackily used to modify (enable/disable) trigger state.
|
||||
|
||||
| Command Parameter | Description |
|
||||
| -- | -- |
|
||||
| Param #1 | Distance interval the camera should be triggered at in meters |
|
||||
|
||||
[PROPOSED] **`MAV_CMD_DO_SET_CAM_TRIGG_INTERVAL`** - Sets the time interval for camera triggering. The camera is triggered each time this interval expires. **FIXME** : we need to define this.
|
||||
|
||||
| Command Parameter | Description |
|
||||
| -- | -- |
|
||||
| Param #1 | Intervalometer cycle time in milliseconds. |
|
||||
|
||||
|
||||
## Video camera control
|
||||
|
||||
TODO : Julian, Gus
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# General Telemetry
|
||||
|
||||
MAVLink is designed to support sending continuous telemetry streams including position, velocity, attitude and similar key states of a drone.
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
# Gimbal Configuration Protocol
|
||||
|
||||
The gimbal configuration message set is using a number of commands and few special-purpose messages to configure a payload mount.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,118 @@
|
||||
# Mission Protocol
|
||||
|
||||
The mission protocol is a sub-protocol supporting guaranteed delivery of messages. It allows to transfer a mission over a lossy link.
|
||||
|
||||
## Upload a Mission to the Vehicle
|
||||
|
||||
The diagram below shows how the ground control station (GCS) can download a mission.
|
||||
|
||||
{% mermaid %}
|
||||
sequenceDiagram;
|
||||
participant GCS
|
||||
participant Drone
|
||||
GCS->>Drone: MISSION_COUNT
|
||||
GCS->>GCS: Start timeout
|
||||
Drone->>GCS: MISSION_REQUEST (0)
|
||||
GCS->>GCS: Start timeout
|
||||
GCS-->>Drone: MISSION_ITEM (0)
|
||||
Drone->>GCS: MISSION_REQUEST (1)
|
||||
GCS->>GCS: Start timeout
|
||||
GCS-->>Drone: MISSION_ITEM (1)
|
||||
Drone->>GCS: MISSION_ACK
|
||||
{% endmermaid %}
|
||||
|
||||
|
||||
## Download a Mission from the Vehicle
|
||||
|
||||
The diagram below shows the communication sequence to download a mission from the drone.
|
||||
|
||||
{% mermaid %}
|
||||
sequenceDiagram;
|
||||
participant GCS
|
||||
participant Drone
|
||||
GCS->>Drone: MISSION_REQUEST_LIST
|
||||
GCS->>GCS: Start timeout
|
||||
Drone-->>GCS: MISSION_COUNT
|
||||
GCS->>Drone: MISSION_REQUEST (0)
|
||||
GCS->>GCS: Start timeout
|
||||
Drone-->>GCS: MISSION_ITEM (0)
|
||||
GCS->>Drone: MISSION_REQUEST (1)
|
||||
GCS->>GCS: Start timeout
|
||||
Drone-->>GCS: MISSION_ITEM (1)
|
||||
GCS->>Drone: MISSION_ACK
|
||||
{% endmermaid %}
|
||||
|
||||
## Mission File Format
|
||||
|
||||
The standard file format for missions is JSON, as implemented in the QGroundControl [reference implementation](http://github.com/mavlink/qgroundcontrol). The JSON file format has additional meta data which is not serialized over the link. The JSON file below shows an example mission with two waypoints.
|
||||
|
||||
```json
|
||||
{
|
||||
"fileType": "Plan",
|
||||
"geoFence": {
|
||||
"polygon": [
|
||||
],
|
||||
"version": 1
|
||||
},
|
||||
"groundStation": "QGroundControl",
|
||||
"mission": {
|
||||
"cruiseSpeed": 16,
|
||||
"firmwareType": 12,
|
||||
"hoverSpeed": 4,
|
||||
"items": [
|
||||
{
|
||||
"autoContinue": true,
|
||||
"command": 22,
|
||||
"coordinate": [
|
||||
47.385913889999998,
|
||||
8.5520674900000007,
|
||||
15
|
||||
],
|
||||
"doJumpId": 1,
|
||||
"frame": 3,
|
||||
"params": [
|
||||
0,
|
||||
0,
|
||||
0,
|
||||
null
|
||||
],
|
||||
"type": "SimpleItem"
|
||||
},
|
||||
{
|
||||
"autoContinue": true,
|
||||
"command": 16,
|
||||
"coordinate": [
|
||||
47.383052030000002,
|
||||
8.5556602700000006,
|
||||
15
|
||||
],
|
||||
"doJumpId": 2,
|
||||
"frame": 3,
|
||||
"params": [
|
||||
0,
|
||||
0,
|
||||
0,
|
||||
null
|
||||
],
|
||||
"type": "SimpleItem"
|
||||
}
|
||||
],
|
||||
"plannedHomePosition": [
|
||||
47.386183686176871,
|
||||
8.5520674900000007,
|
||||
15
|
||||
],
|
||||
"vehicleType": 2,
|
||||
"version": 2
|
||||
},
|
||||
"rallyPoints": {
|
||||
"points": [
|
||||
],
|
||||
"version": 1
|
||||
},
|
||||
"version": 1
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Offboard Control Interface
|
||||
|
||||
The offboard control interface allows to send low-level and high-level attitude, velocity or position commands to the vehicle.
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
# Parameter Protocol
|
||||
|
||||
The parameter protocol is used to exchange key system settings and guarantees delivery.
|
||||
|
||||
{% mermaid %}
|
||||
sequenceDiagram;
|
||||
participant GCS
|
||||
participant Drone
|
||||
GCS->>Drone: PARAM_REQUEST_LIST
|
||||
Drone->>Drone: Start sending parameters
|
||||
Drone->>GCS: Send N parameters
|
||||
GCS->>GCS: Start receive timeout
|
||||
GCS->>Drone: Request dropped params with PARAM_REQUEST_READ
|
||||
|
||||
{% endmermaid %}
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
# Protocol Overview
|
||||
|
||||
MAVLink is a binary telemetry protocol designed for resource-constrained systems and bandwidth-constrained links. MAVLink is deployed in two major versions: v1.0 and v2.0, which is backwards-compatible \(v2.0 implementations can parse and send v1.0 packets\). Telemetry data streams are sent in a multicast design while protocol aspects that change the system configuration and require guaranteed delivery like the [mission protocol](mission_protocol.md) or [parameter protocol](parameter_protocol.md) are point-to-point with retransmission.
|
||||
|
||||
## MAVLink 1 Packet Format
|
||||
|
||||
Below is the over-the-wire format for a MAVLink 1 packet. The in-memory representation might differ.
|
||||
|
||||
```C
|
||||
uint8_t magic; ///< protocol magic marker
|
||||
uint8_t len; ///< Length of payload
|
||||
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; ///< ID of message in payload
|
||||
uint8_t payload[max 255]; ///< A maximum of 255 payload bytes
|
||||
uint16_t checksum; ///< X.25 CRC
|
||||
```
|
||||
|
||||
## MAVLink 2 Packet Format
|
||||
|
||||
Below is the over-the-wire format for a MAVLink 2 packet. The in-memory representation might differ.
|
||||
|
||||
```C
|
||||
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
|
||||
```
|
||||
|
||||
## Serialization
|
||||
|
||||
The over-the-wire format of MAVLink is optimized for resource-constrained systems and hence the field order is not the same as in the XML specification. The over-the-wire generator sorts all fields of the message according to size, with the largest fields \(uint64\_t\) first, then down to smaller fields. The sorting is done using a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), which ensures that fields that do not need to be reordered stay in the same order. This prevents alignment issues on the encoding / decoding systems and allows for very efficient packing / unpacking.
|
||||
|
||||
## Multicast Streams vs. Guaranteed Delivery
|
||||
|
||||
MAVLink is built for hybrid networks where high-rate data streams from data sources \(commonly drones\) flow to data sinks \(commonly ground stations\), but are mixed with transfers requiring guaranteed delivery. The key insight is that for most **telemetry streams** there is not a known or single recipient: Instead, typically an onboard computer, a ground control station and a cloud system all need the same data stream.
|
||||
|
||||
On the other hand configuring the **onboard mission** or changing the system configuration with **onboard parameters** requires point-to-point communication with guaranteed delivery. MAVLink achieves very high efficiency by allowing both modes of operation.
|
||||
|
||||
## Topic Mode \(publish-subscribe\)
|
||||
|
||||
In topic mode the protocol will not emit a target system and component ID for messages to save link bandwidth. Typical examples for this communication mode are all autopilot data streams like position, attitude, etc.
|
||||
|
||||
The main benefit of this multicast mode is that no additional overhead is generated and multiple subscribers can all receive this data.
|
||||
|
||||
## Point-to-Point Mode
|
||||
|
||||
In point-to-point mode MAVLink uses a target ID and target component. In most cases where these fields are used the sub-protocol also ensures guaranteed delivery \(missions, parameters, commands\).
|
||||
|
||||
## Integrity Checks / Checksum
|
||||
|
||||
MAVLink implements two integrity checks: The first check is on the integrity of the packet during transmission using the X.25 checksum \([CRC-16-CCITT](https://en.wikipedia.org/wiki/Cyclic_redundancy_check)\). This however only ensures that the data has not been altered on the link - it does not ensure consistency with the data definition. The second integrity check is on the [data description](https://en.wikipedia.org/wiki/Data_definition_language) to ensure that two messages with the same ID are indeed containing the same information. To achieve this the data definition itself is run through CRC-16-CCITT and the resulting value is used to seed the packet CRC. Most reference implementations store this constant in an array named **CRC\_EXTRA**.
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Routing
|
||||
|
||||
MAVLink 2.0 has a source system and component ID as well as a destination system and component ID. While the source IDs are part of every message, destination IDs are only assigned for cases where a destination ID is required.
|
||||
|
||||
|
||||
|
||||
## Router Implementation
|
||||
|
||||
The [MAVLink Router](https://github.com/01org/mavlink-router) created by Intel allows to mix-and-match different IP protocols with serial ports and route MAVLink traffic.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# Packet Serialization
|
||||
|
||||
Serialization and de-serialization is available for most common languages as part of the reference library.
|
||||
|
||||
{% method %}
|
||||
## Attitude Message Example
|
||||
|
||||
This first example shows how the MAVLink convenience serialization functions make it simple to send messages over a link.
|
||||
|
||||
{% sample lang="c" %}
|
||||
This is the function definition for the altitude message. Behind the scenes the serializer takes care of encoding the message and sending it out on the serial port.
|
||||
|
||||
```c
|
||||
static inline void mavlink_msg_attitude_send(mavlink_channel_t chan,
|
||||
uint32_t time_boot_ms, float roll, float pitch, float yaw,
|
||||
float rollspeed, float pitchspeed, float yawspeed);
|
||||
|
||||
```
|
||||
|
||||
{% sample lang="python" %}
|
||||
This is the function definition for the altitude message. Behind the scenes the serializer takes care of encoding the message and sending it out on the serial port.
|
||||
|
||||
```python
|
||||
def attitude_send(self, usec, roll, pitch, yaw,
|
||||
rollspeed, pitchspeed, yawspeed):
|
||||
```
|
||||
|
||||
{% common %}
|
||||
Whatever language you are using, the resulting binary data will be the same:
|
||||
|
||||
```
|
||||
0x55 0x1C 0x1E <time> <roll> <pitch> <yaw>
|
||||
<rollspeed> <pitchspeed> <yawspeed> <crc1> <crc2>
|
||||
```
|
||||
{% endmethod %}
|
||||
Reference in New Issue
Block a user