From 5015feb58772c686ea8716c828d0adfcb52475ba Mon Sep 17 00:00:00 2001 From: Jonas Vautherin Date: Wed, 13 May 2020 16:21:22 +0200 Subject: [PATCH] Update README --- README.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 5502074c..6f9ded25 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The Python wrapper is based on a gRPC client communicating with the gRPC server - Python 3.6+ 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 has a [Getting started with MAVSDK-Python] (https://auterion.com/getting-started-with-mavsdk-python/) guide if you're a beginner and not sure where to start. +- Auterion has a [Getting started with MAVSDK-Python](https://auterion.com/getting-started-with-mavsdk-python/) guide if you're a beginner and not sure where to start. ## Install using pip from PyPi @@ -31,6 +31,8 @@ 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: @@ -39,11 +41,15 @@ Once the package has been installed, the examples can be run: examples/takeoff_and_land.py ``` -## Build and run from sources +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 targetted at contributors. -Note: this is more involved and targetted to 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). -### Get the Python wrapper +### Clone the repo Clone this repo and recursively update submodules: @@ -71,14 +77,18 @@ cd ../.. pip3 install -r requirements.txt -r requirements-dev.txt ``` -### Generate wrapper +### Generate the code -Run the following helper script. It will generate the Python wrappers for each plugin. If the submodules are not initialized already, the script will take care of it. +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](./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 you can install a development (editable) version of the package using: @@ -88,8 +98,8 @@ python3 setup.py build pip3 install -e . ``` -### Build mavsdk_server +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. -MAVDSK-Python runs the `mavsdk_server` when `await drone.connect()` is called. Under the hood, this will run `mavsdk/bin/mavsdk_server`, which has to be built separately from [MAVSDK](https://github.com/mavlink/MAVSDK) and copied there. +### Release to PyPi repository -For more help on this step, check the [docs on how to build from source](https://mavsdk.mavlink.io/develop/en/contributing/build.html). +The CI will create and push a wheel for Windows, Linux and macOS whenever a release tag is created.