• Stars
    star
    308
  • Rank 135,712 (Top 3 %)
  • Language
    Python
  • License
    BSD 3-Clause "New...
  • Created almost 7 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

MAVSDK client for Python.

MAVSDK-Python

GitHub Actions Status

This is the Python wrapper for MAVSDK.

The Python wrapper is based on a gRPC client communicating with the gRPC server written in C++. To use the Python wrapper the gRPC server called "backend" needs to be running on the same system. The wrapper is essentially auto-generated from the message definitions (proto files).

Important Notes

  • Python 3.7+ is required (because the wrapper is based on asyncio).
  • You may need to run pip3 instead of pip and python3 instead of python, depending of your system defaults.
  • Auterion has a Getting started with MAVSDK-Python guide if you're a beginner and not sure where to start.

API Reference docs

-> API Reference documentation.

Install using pip from PyPi

To install mavsdk-python, simply run:

pip3 install mavsdk

The package contains mavsdk_server already (previously called "backend"), which is started automatically when connecting (e.g. await drone.connect()). Have a look at the examples to see it used in practice. It will be something like:

from mavsdk import System

...

drone = System()
await drone.connect(system_address="udp://:14540")

Note: System() takes two named parameters: mavsdk_server_address and port. When left empty, they default to None and 50051, respectively, and mavsdk_server -p 50051 is run by await drone.connect(). If mavsdk_server_address is set (e.g. to "localhost"), then await drone.connect() will not start the embedded mavsdk_server and will try to connect to a server running at this address. This is useful for platforms where mavsdk_server does not come embedded, for debugging purposes, and for running mavsdk_server in a place different than where the MAVSDK-Python script is run.

Run the examples

Once the package has been installed, the examples can be run:

examples/takeoff_and_land.py

The examples assume that the embedded mavsdk_server binary can be run. In some cases (e.g. on Raspberry Pi), it may be necessary to run mavsdk_server manually, and therefore to set mavsdk_server_address='localhost' as described above.

Contribute

Note: this is more involved and targeted at contributors.

Most of the code is auto-generated from the proto definitions, using our templates. The generated files can be found in the generated folder. As a result, contributions are generally made in the templates or on the build system. Regularly, there is a need to update MAVSDK-Python to include the latest features defined in the proto definitions. This is described below.

Clone the repo

Clone this repo and recursively update submodules:

git clone https://github.com/mavlink/MAVSDK-Python --recursive
cd MAVSDK-Python

Install prerequisites

First install the protoc plugin (protoc-gen-mavsdk):

cd proto/pb_plugins
pip3 install -r requirements.txt

You can check that the plugin was installed with $ which protoc-gen-mavsdk, as it should now be in the PATH.

Then go back to the root of the repo and install the dependencies of the SDK:

cd ../..
pip3 install -r requirements.txt -r requirements-dev.txt

Generate the code

Run the following helper script. It will generate the Python wrappers for each plugin.

./other/tools/run_protoc.sh

Update mavsdk_server version

MAVSDK_SERVER_VERSION contains exactly the tag name of the mavsdk_server release corresponding to the version of MAVSDK-Python. When the proto submodule is updated here, chances are that mavsdk_server should be updated, too. Just edit this file, and the corresponding binary will be downloaded by the setup.py script (see below).

Build and install the package locally

After generating the wrapper and only in ARM architectures with linux, defines a variable MAVSDK_SERVER_ARCH:

export MAVSDK_SERVER_ARCH=<ARM embedded architecture>

Supported architectures: armv6l, armv7l and aarch64. For example for Raspberry Pi it is armv7l, or aarch64 (if a 64 bit distribution is used).

Then you can install a development version of the package, which links the package to the generated code in this local directory. To do so, use:

python3 setup.py build
pip3 install -e .

Note: MAVDSK-Python runs mavsdk/bin/mavsdk_server when await drone.connect() is called. This binary comes from MAVSDK and is downloaded during the setup.py step above.

Generate the API documentation

Make sure the version tag is set correctly before generating new documentation.

pip3 install -r requirements-docs.txt
make -C mavsdk html

Release steps

  1. Check the proto submodule is up-to-date and the generated code has been updated.
  2. Check all required pull requests are merged to main
  3. Check MAVSDK_SERVER_VERSION is set to the correct version of mavsdk_server.
  4. Create git tag on laster main, e.g.:
    git switch main
    git pull
    git tag X.Y.Z
    git push --tags
    
  5. Go to releases page and create new release. The CI will now:
    • Create and push a wheel for Windows, Linux and macOS to PyPi.
    • Generate the latest docs and push them to s3.

More Repositories

1

qgroundcontrol

Cross-platform ground control station for drones (Android, iOS, Mac OS, Linux, Windows)
C++
3,232
star
2

mavlink

Marshalling / communication library for drones.
Python
1,703
star
3

mavros

MAVLink to ROS gateway with proxy for Ground Control Station
C++
752
star
4

MAVSDK

API and library for MAVLink compatible systems written in C++17
C++
607
star
5

c_uart_interface_example

Simple MAVLink to UART interface example for *nix systems
C++
236
star
6

c_library_v2

Official reference C / C++ library for the v2 protocol
C
163
star
7

rust-mavlink

MAVLink library for Rust.
Rust
127
star
8

mavlink-devguide

MAVLink Developer Guide
HTML
98
star
9

mavlink-camera-manager

MAVLink Camera Manager Service
Rust
87
star
10

c_library_v1

MAVLink protocol C/C++ implementation auto-generated from latest protocol specs.
C
77
star
11

MAVSDK-Java

MAVSDK client for Java.
Jinja
70
star
12

mavlink2rest

mavlink2rest creates a REST server that provides mavlink information from a mavlink source
Rust
57
star
13

qgc-user-guide

QGroundControl User Guide (Gitbook source)
CSS
42
star
14

qgc-dev-guide

QGroundControl Developers Guide
41
star
15

MAVSDK-Proto

Collection of proto files used by gRPC in MAVSDK
Python
36
star
16

MAVSDK-Swift

MAVSDK client for Swift.
Swift
25
star
17

MAVSDK-JavaScript

JS wrapper for MAVSDK using grpc-web to generate a static http client, communicating through the Envoy proxy.
JavaScript
24
star
18

MAVSDK-docs

MAVSDK Guide Docs - Source Code
23
star
19

mavlink-gbp-release

git-buildpackage repository for releasing mavlink as 3-rd party library for ROS
CMake
21
star
20

MAVSDK-Rust

MAVSDK client for Rust. https://mavsdk.mavlink.io
Rust
16
star
21

MAVSDK-CSharp

MAVSDK client for C#. https://mavsdk.mavlink.io
C#
16
star
22

MAVSDK-Go

Go
15
star
23

containers

Docker image for building QGroundControl
Shell
15
star
24

MAVSDK-Swift-Example

Example app using MAVSDK for iOS (Swift)
Swift
14
star
25

libevents

C++
11
star
26

rfcs

Requests for Comment for MAVLink protocol spec
9
star
27

mavros-release

Bloom release repository for mavros.
7
star
28

mavlink-ivy-interface

MAVLink to IVY Bus Interface
C
6
star
29

docs.qgroundcontrol.com

QGroundControl User Guide Content: See https://github.com/mavlink/qgc-user-guide
HTML
5
star
30

dev.qgroundcontrol.com

QGroundControl Developers Guide Content: See https://github.com/mavlink/qgc-dev-guide
HTML
2
star
31

mavsdk.mavlink.io

Mavlink SDK guide
HTML
2
star
32

mavlink.io

Mavlink Developer Guide Content: See https://github.com/mavlink/mavlink-devguide
HTML
2
star
33

homebrew-mavsdk

Homebrew repository for MAVSDK
Ruby
1
star
34

MAVSDK-XCFramework

Swift
1
star