# MAVSDK-Python
[](https://github.com/mavlink/MAVSDK-Python/actions/workflows/main.yml?query=branch%3Amain)
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](https://github.com/mavlink/MAVSDK-Proto)).
## Important Notes
- Python 3.7+ is required (because the wrapper is based on [asyncio](https://docs.python.org/3.7/library/asyncio.html)).
- 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)](https://web.archive.org/web/20201211155626/https://auterion.com/getting-started-with-mavsdk-python/) guide if you're a beginner and not sure where to start.
## API Reference docs
-> [API Reference documentation](http://mavsdk-python-docs.s3-website.eu-central-1.amazonaws.com/).
## Install using pip from PyPi
**Note for Raspberry Pi 1/2 and Zero:**
> MAVSDK-Python requires grpcio. However, there are no binary packets of grpcio for armv6 available via pip (also see [files on pypi.org](https://pypi.org/project/grpcio/#files)).
> In this case, install grpcio via the package manager, e.g. `sudo apt-get install python3-grpcio`.
To install mavsdk-python, simply run:
```sh
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:
```python
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](https://github.com/mavlink/mavsdk-proto), using our [templates](./other/templates). The generated files can be found in the [generated](./mavsdk/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](#generate-the-code).
### 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](./MAVSDK_SERVER_VERSION) contains exactly the tag name of the `mavsdk_server` release corresponding to the version of MAVSDK-Python. When the [proto](./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](https://github.com/mavlink/MAVSDK/releases) 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](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](https://github.com/mavlink/MAVSDK-Python/releases) 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/mavlink/MAVSDK-Python",
"name": "mavsdk",
"maintainer": "Jonas Vautherin, Julian Oes",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "jonas@auterion.com, julian.oes@auterion.com",
"keywords": null,
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "# MAVSDK-Python\n\n[](https://github.com/mavlink/MAVSDK-Python/actions/workflows/main.yml?query=branch%3Amain)\n\nThis is the Python wrapper for MAVSDK.\n\nThe 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](https://github.com/mavlink/MAVSDK-Proto)).\n\n\n## Important Notes\n\n- Python 3.7+ is required (because the wrapper is based on [asyncio](https://docs.python.org/3.7/library/asyncio.html)).\n- You may need to run `pip3` instead of `pip` and `python3` instead of `python`, depending of your system defaults.\n- Auterion used to have a [Getting started with MAVSDK-Python (web.archive.org)](https://web.archive.org/web/20201211155626/https://auterion.com/getting-started-with-mavsdk-python/) guide if you're a beginner and not sure where to start.\n\n## API Reference docs\n\n-> [API Reference documentation](http://mavsdk-python-docs.s3-website.eu-central-1.amazonaws.com/).\n\n## Install using pip from PyPi\n\n**Note for Raspberry Pi 1/2 and Zero:**\n\n> MAVSDK-Python requires grpcio. However, there are no binary packets of grpcio for armv6 available via pip (also see [files on pypi.org](https://pypi.org/project/grpcio/#files)).\n> In this case, install grpcio via the package manager, e.g. `sudo apt-get install python3-grpcio`.\n\n\nTo install mavsdk-python, simply run:\n\n```sh\npip3 install mavsdk\n```\n\nThe 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:\n\n```python\nfrom mavsdk import System\n\n...\n\ndrone = System()\nawait drone.connect(system_address=\"udp://:14540\")\n```\n\nNote: `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.\n\n## Run the examples\n\nOnce the package has been installed, the examples can be run:\n\n```\nexamples/takeoff_and_land.py\n```\n\nThe 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.\n\n## Contribute\n\nNote: this is more involved and targeted at contributors.\n\nMost of the code is auto-generated from the [proto definitions](https://github.com/mavlink/mavsdk-proto), using our [templates](./other/templates). The generated files can be found in the [generated](./mavsdk/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](#generate-the-code).\n\n### Clone the repo\n\nClone this repo and recursively update submodules:\n\n```\ngit clone https://github.com/mavlink/MAVSDK-Python --recursive\ncd MAVSDK-Python\n```\n\n### Install prerequisites\n\nFirst install the protoc plugin (`protoc-gen-mavsdk`):\n\n```\ncd proto/pb_plugins\npip3 install -r requirements.txt\n```\n\nYou can check that the plugin was installed with `$ which protoc-gen-mavsdk`, as it should now be in the PATH.\n\nThen go back to the root of the repo and install the dependencies of the SDK:\n\n```\ncd ../..\npip3 install -r requirements.txt -r requirements-dev.txt\n```\n\n### Generate the code\n\nRun the following helper script. It will generate the Python wrappers for each plugin.\n\n```\n./other/tools/run_protoc.sh\n```\n\n### Adding support for new plugins\n\nIn 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.\n\n### Update `mavsdk_server` version\n\n[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](./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).\n\n### Build and install the package locally\n\nAfter generating the wrapper and only in ARM architectures with linux, defines a variable `MAVSDK_SERVER_ARCH`:\n```\nexport MAVSDK_SERVER_ARCH=<ARM embedded architecture>\n```\nSupported architectures: `armv6l`, `armv7l` and `aarch64`. For example for Raspberry Pi it is `armv7l`, or `aarch64` (if a 64 bit distribution is used).\n\nThen 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:\n```\npython3 setup.py build\npip3 install -e .\n```\n\nNote: MAVDSK-Python runs `mavsdk/bin/mavsdk_server` when `await drone.connect()` is called. This binary comes from [MAVSDK](https://github.com/mavlink/MAVSDK/releases) and is downloaded during the `setup.py` step above.\n\n\n### Generate the API documentation\n\nMake sure the version tag is set correctly before generating new documentation.\n\n```\npip3 install -r requirements-docs.txt\nmake -C mavsdk html\n```\n\n\n### Release steps\n\n1. Check the proto submodule is up-to-date and the generated code has been updated.\n2. Check all required pull requests are merged to main\n3. Check [MAVSDK_SERVER_VERSION](MAVSDK_SERVER_VERSION) is set to the correct version of mavsdk_server.\n4. Create git tag on laster main, e.g.:\n ```\n git switch main\n git pull\n git tag X.Y.Z\n git push --tags\n ```\n5. Go to [releases page](https://github.com/mavlink/MAVSDK-Python/releases) and create new release.\n The CI will now:\n - Create and push a wheel for Windows, Linux and macOS to PyPi.\n - Generate the latest docs and push them to s3.\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for MAVSDK",
"version": "2.8.4",
"project_urls": {
"Bug Reports": "https://github.com/mavlink/MAVSDK-Python/issues",
"Homepage": "https://github.com/mavlink/MAVSDK-Python",
"Source": "https://github.com/mavlink/MAVSDK-Python/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f02079e5455cb555a757d8d3c76c3b3036f62b370172b915d26e803a86bd9d3",
"md5": "130ca479080251472739e275c51d014d",
"sha256": "3a7bf78b4e76d6c8eedcfc27fcdf3e8ffc7789474ada0ce585f685018a9a9353"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-linux_armv6l.whl",
"has_sig": false,
"md5_digest": "130ca479080251472739e275c51d014d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15071001,
"upload_time": "2024-10-21T00:05:18",
"upload_time_iso_8601": "2024-10-21T00:05:18.641913Z",
"url": "https://files.pythonhosted.org/packages/3f/02/079e5455cb555a757d8d3c76c3b3036f62b370172b915d26e803a86bd9d3/mavsdk-2.8.4-py3-none-linux_armv6l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1acab3adb91e9a99267670319215588ab4189a46b9c27547a69ce2c78b09e0c8",
"md5": "29868ee081100b3b2fa3d3b82572b9e2",
"sha256": "9a8f128e52ba3971c141928d7a35b03fe27c213d23573d4bba790e079a25106d"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-linux_armv7l.whl",
"has_sig": false,
"md5_digest": "29868ee081100b3b2fa3d3b82572b9e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15070992,
"upload_time": "2024-10-21T00:05:16",
"upload_time_iso_8601": "2024-10-21T00:05:16.686093Z",
"url": "https://files.pythonhosted.org/packages/1a/ca/b3adb91e9a99267670319215588ab4189a46b9c27547a69ce2c78b09e0c8/mavsdk-2.8.4-py3-none-linux_armv7l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6863cc6624a5b55b9b8760f2855fc0ce9a799d948a60912b5a71a1a0d94678c2",
"md5": "587dc05424604689f94274c237e1699d",
"sha256": "aa24f78bacc630172c6fbbe5453ca503b884aef57e537a5751ae4aaaffeb4eba"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "587dc05424604689f94274c237e1699d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11019630,
"upload_time": "2024-10-21T00:05:24",
"upload_time_iso_8601": "2024-10-21T00:05:24.934396Z",
"url": "https://files.pythonhosted.org/packages/68/63/cc6624a5b55b9b8760f2855fc0ce9a799d948a60912b5a71a1a0d94678c2/mavsdk-2.8.4-py3-none-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e8282090fc18707377eb3db6b9c80e8049cf95829ca79081846459eab07d21ed",
"md5": "399adbc10389cd176adf25ae01b5dafe",
"sha256": "33bca5326dc6ddb3799c2ce6b3ca2aa117d14cc572c4bcfee524fa276c1f5b5d"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "399adbc10389cd176adf25ae01b5dafe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10942079,
"upload_time": "2024-10-21T00:05:21",
"upload_time_iso_8601": "2024-10-21T00:05:21.032431Z",
"url": "https://files.pythonhosted.org/packages/e8/28/2090fc18707377eb3db6b9c80e8049cf95829ca79081846459eab07d21ed/mavsdk-2.8.4-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "714334134c69367b82a16c7ba187a77602c349e482e575bba21c1517de8dd4e9",
"md5": "499db7744faf6ea189498fac30a2feae",
"sha256": "c111a234e435920d9ec0a337edb24560e6c7e5dc0205e52c7d4a12513a6b262a"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "499db7744faf6ea189498fac30a2feae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16621780,
"upload_time": "2024-10-21T00:05:22",
"upload_time_iso_8601": "2024-10-21T00:05:22.177781Z",
"url": "https://files.pythonhosted.org/packages/71/43/34134c69367b82a16c7ba187a77602c349e482e575bba21c1517de8dd4e9/mavsdk-2.8.4-py3-none-manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9057a2e53443c25f6052e76dd3ebc57d29c462af0fc4cad81c5d1d6bdce80fd8",
"md5": "84c97ebe908266ea90473683bc0be8e9",
"sha256": "de32c1706da9aea3c1127a6f5f5869c8b893db2a94a70041f75ef367e7b0bfb3"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "84c97ebe908266ea90473683bc0be8e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13563709,
"upload_time": "2024-10-21T00:05:36",
"upload_time_iso_8601": "2024-10-21T00:05:36.010902Z",
"url": "https://files.pythonhosted.org/packages/90/57/a2e53443c25f6052e76dd3ebc57d29c462af0fc4cad81c5d1d6bdce80fd8/mavsdk-2.8.4-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7167807dedddf19c77fa213121fea9115f6f6a9d64724f558c796f5d59bd2c5b",
"md5": "4234a489bd76ba37d3bf8dedb0066b09",
"sha256": "df80d42a7755ff6829ffcd3587b75ed3437675658ba6f216b8941ca0f2df7946"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-win32.whl",
"has_sig": false,
"md5_digest": "4234a489bd76ba37d3bf8dedb0066b09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 364808,
"upload_time": "2024-10-21T00:07:09",
"upload_time_iso_8601": "2024-10-21T00:07:09.313769Z",
"url": "https://files.pythonhosted.org/packages/71/67/807dedddf19c77fa213121fea9115f6f6a9d64724f558c796f5d59bd2c5b/mavsdk-2.8.4-py3-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "120fa1148bb8bd211c56608ae85deeea46f060d43364536e2e566a5f33547fa1",
"md5": "aab2714a2195db4b4793135cfad5ba1b",
"sha256": "e0ab5dafb8c296518075492dd8164fa8c3669e8831a8bb90ad1064c08cbb6788"
},
"downloads": -1,
"filename": "mavsdk-2.8.4-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "aab2714a2195db4b4793135cfad5ba1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 364808,
"upload_time": "2024-10-21T00:06:14",
"upload_time_iso_8601": "2024-10-21T00:06:14.931842Z",
"url": "https://files.pythonhosted.org/packages/12/0f/a1148bb8bd211c56608ae85deeea46f060d43364536e2e566a5f33547fa1/mavsdk-2.8.4-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 00:05:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mavlink",
"github_project": "MAVSDK-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "protobuf",
"specs": [
[
"<=",
"3.20.1"
]
]
},
{
"name": "aiogrpc",
"specs": [
[
">=",
"1.8"
]
]
},
{
"name": "grpcio",
"specs": [
[
">=",
"1.50.0"
]
]
}
],
"tox": true,
"lcname": "mavsdk"
}
JSON
