Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 101 lines (62 sloc) 6.396 kB
b71a242 @LorenzMeier README.md
LorenzMeier authored
1 [![Build Status](https://travis-ci.org/mavlink/mavlink.svg?branch=master)](https://travis-ci.org/mavlink/mavlink)
d3cf056 @arthurbenemann Added travis-ci build status to README
arthurbenemann authored
2
5c5714b @dagoodma Converted README.textile to README.md
dagoodma authored
3 ## MAVLink ##
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
4
0b28fcc @LorenzMeier Updated README
LorenzMeier authored
5 * Official Website: http://mavlink.org
84f2c95 @LorenzMeier Updated readme
LorenzMeier authored
6 * Source: [Mavlink Generator](https://github.com/mavlink/mavlink)
7 * Binaries (always up-to-date from master):
8 * [C/C++ header-only library](https://github.com/mavlink/c_library)
5c5714b @dagoodma Converted README.textile to README.md
dagoodma authored
9 * Mailing list: [Google Groups](http://groups.google.com/group/mavlink)
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
10
11 MAVLink -- Micro Air Vehicle Message Marshalling Library.
12
d96896e @bwmairs README improvements.
bwmairs authored
13 This is a library for lightweight communication between Micro Air Vehicles (swarm) and/or ground control stations. It allows for defining messages within XML files, which then are converted into appropriate source code for different languages. These XML files are called dialects, most of which build on the *common* dialect provided in `common.xml`.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
14
d96896e @bwmairs README improvements.
bwmairs authored
15 The MAVLink protocol performs byte-level serialization and so is appropriate for use with any type of radio modem.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
16
d96896e @bwmairs README improvements.
bwmairs authored
17 This repository is largely Python scripts that convert XML files into language-specific libraries. There are additional Python scripts providing examples and utilities for working with MAVLink data. These scripts, as well as the generated Python code for MAVLink dialects, require Python 2.7 or greater.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
18
d96896e @bwmairs README improvements.
bwmairs authored
19 Note that there are two incompatible versions of the MAVLink protocol: v0.9 and v1.0. Most programs, including [QGroundControl](https://github.com/mavlink/qgroundcontrol), have switched over to v1.0. The v0.9 protocol is **DEPRECATED** and should only be used to maintain backwards compatibility where necessary.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
20
d96896e @bwmairs README improvements.
bwmairs authored
21 ### Requirements ###
22 * Python 2.7+
23 * Tkinter (if GUI functionality is desired)
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
24
d96896e @bwmairs README improvements.
bwmairs authored
25 ### Installation ###
26 1. Clone into a user-writable directory.
27 2. Add the repository directory to your `PYTHONPATH`
e07ac96 @bwmairs Improve documentation for how to run included Python scripts.
bwmairs authored
28 3. Generate MAVLink parser files following the instructions in the next section *AND/OR* run included helper scripts described in the Scripts/Examples secion.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
29
d96896e @bwmairs README improvements.
bwmairs authored
30 ### Generating Language-specific Source Files ###
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
31
d96896e @bwmairs README improvements.
bwmairs authored
32 Language-specific files can be generated via a Python script from the command line or using a GUI. If a dialect XML file has a dependency on another XML file, they must be located in the same directory. Since most MAVLink dialects depend on the **common** messageset, it is recommend that you place your dialect with the others in `/message_definitions/v1.0/`.
33
34 Available languages are:
35
36 * C
37 * C#
b3ef8b6 @LorenzMeier Updated readme
LorenzMeier authored
38 * Java
d96896e @bwmairs README improvements.
bwmairs authored
39 * JavaScript
40 * Lua
41 * Python, version 2.7+
42
43 #### From a GUI (recommended) ####
44
45 mavgenerate.py is a header generation tool GUI written in Python. It requires Tkinter, which is only included with Python on Windows, so it will need to be installed separately on non-Windows platforms. It can be run from anywhere using Python's -m argument:
46
47 $ python -m mavgenerate
48
49 #### From the command line ####
50
51 mavgen.py is a command-line interface for generating a language-specific MAVLink library. This is actually the backend used by `mavgenerate.py`. After the `mavlink` directory has been added to the Python path, it can be run by executing from the command line:
52
22ab243 @legonigel Readme: Updated Mavgen Command line
legonigel authored
53 $ python -m pymavlink.tools.mavgen
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
54
5c5714b @dagoodma Converted README.textile to README.md
dagoodma authored
55 ### Usage ###
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
56
d96896e @bwmairs README improvements.
bwmairs authored
57 Using the generated MAVLink dialect libraries varies depending on the language, with language-specific details below:
58
59 #### C ####
7ac3828 @dagoodma Fixes to README.md formatting.
dagoodma authored
60 To use MAVLink, include the *mavlink.h* header file in your project:
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
61
5c5714b @dagoodma Converted README.textile to README.md
dagoodma authored
62 #include <mavlink.h>
d96896e @bwmairs README improvements.
bwmairs authored
63
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
64 Do not include the individual message files. In some cases you will have to add the main folder to the include search path as well. To be safe, we recommend these flags:
65
d96896e @bwmairs README improvements.
bwmairs authored
66 $ gcc -I mavlink/include -I mavlink/include/<your message set, e.g. common>
67
68 The C MAVLink library utilizes a channels metaphor to allow for simultaneous processing of multiple MAVLink streams in the same program. It is therefore important to use the correct channel for each operation as all receiving and transmitting functions provided by MAVLink require a channel. If only one MAVLink stream exists, channel 0 should be used by using the `MAVLINK_COMM_0` constant.
69
70 ##### Receiving ######
66f205e @Susurrus Update README.md
Susurrus authored
71 MAVLink reception is then done using `mavlink_helpers.h:mavlink_parse_char()`.
d96896e @bwmairs README improvements.
bwmairs authored
72
73 ##### Transmitting #####
66f205e @Susurrus Update README.md
Susurrus authored
74 Transmitting can be done by using the `mavlink_msg_*_pack()` function, where one is defined for every message. The packed message can then be serialized with `mavlink_helpers.h:mavlink_msg_to_send_buffer()` and then writing the resultant byte array out over the appropriate serial interface.
d96896e @bwmairs README improvements.
bwmairs authored
75
66f205e @Susurrus Update README.md
Susurrus authored
76 It is possible to simplify the above by writing wrappers around the transmitting/receiving code. A multi-byte writing macro can be defined, `MAVLINK_SEND_UART_BYTES()`, or a single-byte function can be defined, `comm_send_ch()`, that wrap the low-level driver for transmitting the data. If this is done, `MAVLINK_USE_CONVENIENCE_FUNCTIONS` must be defined.
d96896e @bwmairs README improvements.
bwmairs authored
77
78 ### Scripts/Examples ###
e07ac96 @bwmairs Improve documentation for how to run included Python scripts.
bwmairs authored
79 This MAVLink library also comes with supporting libraries and scripts for using, manipulating, and parsing MAVLink streams within the pymavlink, pymav
80 link/tools, and pymavlink/examples directories.
d96896e @bwmairs README improvements.
bwmairs authored
81
e07ac96 @bwmairs Improve documentation for how to run included Python scripts.
bwmairs authored
82 The scripts have the following requirements:
d96896e @bwmairs README improvements.
bwmairs authored
83 * Python 2.7+
84 * mavlink repository folder in `PYTHONPATH`
85 * Write access to the entire `mavlink` folder.
86 * Your dialect's XML file is in `message_definitions/*/`
87
e07ac96 @bwmairs Improve documentation for how to run included Python scripts.
bwmairs authored
88 Running these scripts can be done by running Python with the '-m' switch, which indicates that the given script exists on the PYTHONPATH. This is the proper way to run Python scripts that are part of a library as per PEP-328 (and the rejected PEP-3122). The following code runs `mavlogdump.py` in `/pymavlink/tools/` on the recorded MAVLink stream `test_run.mavlink` (other scripts in `/tools` and `/scripts` can be run in a similar fashion):
d96896e @bwmairs README improvements.
bwmairs authored
89
90 $ python -m pymavlink.tools.mavlogdump test_run.mavlink
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
91
5c5714b @dagoodma Converted README.textile to README.md
dagoodma authored
92 ### License ###
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
93
d96896e @bwmairs README improvements.
bwmairs authored
94 MAVLink is licensed under the terms of the Lesser General Public License (version 3) of the Free Software Foundation (LGPLv3). The C-language version of MAVLink is a header-only library, and as such compiling an application with it is considered "using the library", not a derived work. MAVLink can therefore be used without limits in any closed-source application without publishing the source code of the closed-source application.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
95
7ac3828 @dagoodma Fixes to README.md formatting.
dagoodma authored
96 See the *COPYING* file for more info.
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
97
5c5714b @dagoodma Converted README.textile to README.md
dagoodma authored
98 ### Credits ###
4aea0e4 @dagoodma Updated README to mention mavgen GUI.
dagoodma authored
99
d96896e @bwmairs README improvements.
bwmairs authored
100 &copy; 2009-2014 [Lorenz Meier](mailto:mail@qgroundcontrol.org)
Something went wrong with that request. Please try again.