MAVSDK-Python

This is the gRPC-based Python wrapper for MAVSDK, published on PyPI as mavsdk-grpc and imported as mavsdk_grpc.

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).

⚠️ Renamed from mavsdk to mavsdk-grpc

This wrapper used to be published as mavsdk. That name on PyPI now refers to the native MAVSDK binding, which has a different API and no gRPC dependency — see the migration guide.

This project carries on under the mavsdk-grpc name, including releases tracking MAVSDK v4. If you were using mavsdk:

• Install mavsdk-grpc and use import mavsdk_grpc as mavsdk — the code is identical. The separate import name is deliberate, so that the two packages can never overwrite each other's files.
• Or pin mavsdk<4 to freeze on the last release under the old name, which will not receive further updates.

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 used to have a Getting started with MAVSDK-Python (web.archive.org) guide if you're a beginner and not sure where to start.

API Reference docs

-> API Reference documentation.

Install using pip from PyPi

Note for Raspberry Pi 1/2 and Zero:

This wrapper requires grpcio. However, there are no binary packets of grpcio for armv6 available via pip (also see files on pypi.org). In this case, install grpcio via the package manager, e.g. sudo apt-get install python3-grpcio.

To install it, simply run:

pip3 install mavsdk-grpc

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_grpc import System

...

drone = System()
await drone.connect(system_address="udpin://0.0.0.0: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

Adding support for new plugins

In case you updated the ./proto submodule to include a new plugin, you will also have to manually edit the file mavsdk/system.py to register the plugin.

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

Formatting checks before committing

We use the following checks in CI:

pipx run ruff format --check --line-length=100 examples
pipx run ruff check --select=ASYNC,RUF006,E,F --line-length=100 examples
pipx run codespell .

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.