Arduino Logo

mavlink

This library supports the MAVLink protocol, which is a common protocol for interfacing with ground control stations (i.e. Mission Planner and QGroundControl). This library has been specifically built for drone / UAS applications and tested against QGroundControl.

Description

MAVLink is a messaging protocol for communicating between drone components, located both on and off the vehicle. The protocol consists of many message and microservice definitions and C headers are available for packing, unpacking, sending, and parsing messages. This library implements each microservice as a class and then wraps all of them into a parent class for easier integration with vehicle software. The supported microservices are:

Heartbeat: establishes communication with other MAVLink components and relays information on vehicle type and status.
Utility: sends status texts to the ground station.
Telemetry: sends sensor and estimation data for display on a ground station or use in a MAVLink component. Can also receive SCALED_IMU, SCALED_PRESSURE, GPS_RAW_INT, ATTITUDE, VFR_HUD, LOCAL_POSITION_NED, and GLOBAL_POSITION_NED messages and output the received data.
Parameter: defines parameters whose values can be set by other MAVLink components, such as ground stations. Useful for defining on-board excitations, tunable control law gains, etc. Only floating point types are currently supported.
Mission: enables Mission Items to be sent to the drone from a ground station. These can include flight plans, fences, and rally points.
UTM: implements the UAS Traffic Management (UTM) microservice, broadcasting the UTM data from the drone and receiving UTM data from other nearby drones.

The MAVLink protocol is massive and documentation is sometimes sparse with respect to how components should communicate with each other (the order of messages, what actions the drone or ground control station should take on receiving each message). Further, ground control stations often only use a subset of MAVLink. This library attempts to simplify MAVLink usage by providing an intuitive interface and abstracting away the microservice details.

This library has been tested extensively against QGroundControl. If functionality appears to be missing or implemented incorrectly, please submit an issue detailing the observed behavior, the expected behavior, and the ground control station used.

Installation

Arduino

Simply clone or download and extract the zipped library into your Arduino/libraries folder. In addition to this library, the Bolder Flight Systems Units library must be installed. The library is added as:

#include "mavlink.h"

An example is located in examples/arduino/mavlink_example/mavlink_example.ino. This library is tested with Teensy 3.x, 4.x, and LC devices and is expected to work with other Arduino ARM devices. It is not expected to work with AVR devices.

CMake

CMake is used to build this library, which is exported as a library target called mavlink. The header is added as:

#include "mavlink.h"

The library can also be compiled stand-alone using the CMake idiom of creating a build directory and then, from within that directory, issuing:

cmake .. -DMCU=MK66FX1M0
make

This will build the library and an example executable called mavlink_example. The example executable source files are located at examples/cmake/mavlink_example.cc. Notice that the cmake command includes a define specifying the microcontroller the code is being compiled for. This is required to correctly configure the code, CPU frequency, and compile/linker options. The available MCUs are:

MK20DX128
MK20DX256
MK64FX512
MK66FX1M0
MKL26Z64
IMXRT1062_T40
IMXRT1062_T41
IMXRT1062_MMOD

These are known to work with the same packages used in Teensy products. Also switching packages is known to work well, as long as it's only a package change.

The mavlink_example target also has a _hex for creating the hex file and an _upload for using the Teensy CLI Uploader to flash the Teensy. Please note that the CMake build tooling is expected to be run under Linux or WSL, instructions for setting up your build environment can be found in our build-tools repo.

Namespace

This library is within the namespace bfs

Methods

Mission Item

MissionItem This struct defines a Mission Item, which can be a waypoint in a flight plan, a fence vertex, or a rally point. The struct is defined as:

| Name | Description | | --- | --- | | bool autocontinue | Whether to automatically continue to the next MissionItem | | uint8_t frame | The coordinate frame of the MissionItem | | uint16_t cmd | The command associated with the MissionItem | | float param1 | Command dependent parameter | | float param2 | Command dependent parameter | | float param3 | Command dependent parameter | | float param4 | Command dependent parameter | | int32_t x | Typically latitude represented as 1e7 degrees | | int32_t y | Typically longitude represented as 1e7 degrees | | float z | Typically altitude, but can be dependent on the command and frame |

MavLink

MavLink<std::size_t N, std::size_t M> The MavLink constructor is templated with the number of parameters to support and the number of received UTM messages.

/* MavLink object support 5 parameters and up to 10 simultaneous UTM broadcasts received */
bfs::MavLink<5, 10> mavlink;

Config

inline void hardware_serial(HardwareSerial *bus) Sets the hardware serial bus to use.

mavlink.hardware_serial(&Serial4);

inline void aircraft_type(const AircraftType type) Sets the aircraft type, which the ground control station uses for configuring displays and options (i.e. how the vehicle takes off, the type of icon used to display the vehicle).

mavlink.aircraft_type(bfs::FIXED_WING);

Available aircraft types are: | Enum | Value (int8_t) | Description | | ------------------ | ----- | ------------------- | | FIXED_WING | 0 | Fixed-wing aircraft | | HELICOPTER | 1 | Helicopter | | MULTIROTOR | 2 | Multirotor | | VTOL | 3 | VTOL aircraft |

inline void sys_id(const uint8_t sys_id) Used to set a non-default system id. By default the system id is set to 1. This could be used if other vehicles are connected to the ground control station to avoid conflicting system ids.

inline void comp_id(const uint8_t comp_id) Used to set a non-default component id. By default the component id is set to 1 (MAV_COMP_ID_AUTOPILOT1).

inline void gnss_serial(HardwareSerial *bus) Sets the hardware serial bus connected to the GNSS receiver to provide RTCM corrections from a base station GNSS as transmitted via MAV Link from the ground control station software. It is assumed that the serial port is configured external to this class (i.e. serial port initialized and baudrate set correctly).

inline void mission(MissionItem * const mission, const std::size_t mission_size, MissionItem * const temp) Sets storage location for flight plans given a pointer for the data, the number of Mission Items that can be stored, and a pointer for temporary data. The temporary storage location is used while the ground station uploads flight plans, fences, and rally points. Once the upload is complete and verified, it's moved to the correct mission, fence, and rally point storage location. It's assumed that the temporary storage is at least as large as the largest storage location for flight plans, fences, and rally points. For example, if there is enough storage for 250 flight plan mission items, 100 fence points, and 5 rally points, the temporary storage would need at least enough capacity for 250 mission items.

inline void fence(MissionItem * const fence, const std::size_t fence_size) Sets the storage location and size for fence points.

inline void rally(MissionItem * const rally, const std::size_t rally_size) Sets the storage location and size for rally points.

std::array<bfs::MissionItem, 250> mission;
std::array<bfs::MissionItem, 100> fence;
std::array<bfs::MissionItem, 5> rally;
std::array<bfs::MissionItem, 250> temp;
mavlink.mission(mission.data(), mission.size(), temp.data());
mavlink.fence(fence.data(), fence.size());
mavlink.rally(rally.data(), rally.size());

Setup / Update

void Begin(uint32_t baud) Initializes communication given a baudrate.

mavlink.Begin(57600);

void Update() Should be run often, sends, receives, and parses MAVLink messages.

while (1) {
  mavlink.Update();
}

GCS Link

bool gcs_link_established() Returns true if communication has been established with a GCS.

bool gcs_link_lost() Returns true if communication has been established with a GCS and a heartbeat from the GCS has not been received

Mavlink

Install / Use

README