Information about writing example code is covered in the Contributing > Writing Plugins (plugin developers should initially create integration tests rather than examples for new code).
This section contains examples showing how to use MAVSDK.
|Battery||Simple example to demonstrate how to imitate a smart battery.|
|Calibrate||Simple example showing how to initiate calibration of gyro, accelerometer, magnetometer.|
|Fly Mission||Shows how to create, upload, and run missions.|
|Fly Multiple Drones||Example to connect multiple vehicles and make them follow their own separate plan file. Also saves the telemetry information to CSV files.|
|Follow Me Mode||Demonstrates how to put vehicle in Follow Me Mode and set the current target position and relative position of the drone.|
|GeoFence Inclusion||Demonstrates how to define and upload a simple polygonal inclusion GeoFence.|
|MAVShell||Creates and starts an interactive shell session.|
|MAVLink FTP Client||Demonstrates how to create/use a MAVLink FTP client.|
|MAVLink FTP Server||Demonstrates how to start/set up a MAVLink FTP server.|
|Multiple Drones||Example to connect multiple vehicles and make them take off and land in parallel.|
|Offboard Velocity Control||Demonstrates how to control a vehicle in Offboard mode using velocity commands (in both the NED and body frames).|
|Takeoff and Land||Shows basic usage of the SDK (connect to port, detect system (vehicle), arm, takeoff, land, get telemetry)|
|VTOL Transitions||Shows how to transition a VTOL vehicle between copter and fixed-wing modes.|
|Tune||Shows how to construct and play a tune.|
The examples are "largely" built and run in the same way, as described in the following section (any exceptions are covered in the page for the associated example).
Some of the examples define flight behaviour relative to the default home position in the simulator (e.g. Fly Mission). Care should be taken if using them on a real vehicle.
Trying the Examples
The easiest way to test the examples is to use a simulated PX4 vehicle that is running on the same computer. First start PX4 in SITL (Simulation), optionally start QGroundControl to observe the vehicle, then build and run the example code.
The simulator broadcasts to the standard PX4 UDP port for connecting to offboard APIs (14540). The examples connect to this port using either add_any_connection() or add_udp_connection().
Setting up a Simulator
PX4 supports a number of simulators. In order to set up the jMAVSim or Gazebo simulator, you can simply follow the standard PX4 toolchain setup instructions for macOS or Ubuntu Linux.
JMAVSim can only be used to simulate multicopters. Gazebo additionally supports a number of other vehicles (e.g. VTOL, Rovers, fixed-wing etc.).
After running a standard installation, a simulation can be started from the PX4 /Firmware directory using the command:
- Multicopter (jMAVSim):
make px4_sitl jmavsim
- Multicopter (Gazebo):
make px4_sitl gazebo
- VTOL (Gazebo):
make px4_sitl gazebo_standard_vtol
You can use QGroundControl to connect to PX4 and observe vehicle movement and behaviour while the examples are running. QGroundControl will automatically connect to the PX4 simulation as soon as it is started.
See QGroundControl > Download and Install for information about setting up QGroundControl on your platform.
Building the Examples
To build the examples follow the instructions below, replacing takeoff_and_land with the name of the specific example.
The examples require the MAVSDK library to be installed. See installation guide if that is not already the case.
Then build the example:
cd examples/takeoff_and_land/ cmake -Bbuild -H. cmake --build build -j4
if MAVSDK is installed locally (e.g. on Windows) you need to pass the location to cmake:
cmake -Bbuild -DCMAKE_PREFIX_PATH=wherever_mavsdk_is_locally_installed
Running the Examples
You can then run the example, specifying the connection URL as the first argument.
When running with the Simulator, you will use the connection string:
On Linux/macOS you would run the following (from the /build directory):
For Windows you would run the following (from the \build\Debug\ directory):
Most examples will create a binary with the same name as the example. The name that is used is specified in the CMakeLists.txt file as the first value in the call to
If you have already started the simulation the example code should connect to PX4, and you will be able to observe behaviour through the SDK terminal, SITL terminal, and/or QGroundControl.