C++ Examples

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.

Example	Description
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

Using QGroundControl

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: udp://:14540

On Linux/macOS you would run the following (from the /build directory):

build/takeoff_and_land udp://:14540

For Windows you would run the following (from the \build\Debug\ directory):

build\Debug\takeoff_and_land.exe udp://:14540

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

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.

Examples