MultiWii / Cleanflight / Baseflight Communication Library (C++)

This library implements the MultiWii Serial Protocol (MSP) for communicating with a MultiWii or Cleanflight flight controller (FC) over a serial device. It defines a low-level API for sending+encoding and receiving+decoding MSP messages, and a high-level API with a subscriber pattern to periodically request data from the FC and call callback functions as soon as a message is received.

The communication has been tested with MultiWii 2.4 on an Arduino Nano 3.0 where it can achieve a update rate of approximately 340Hz (for a FC cycle time of 2.8ms / 357Hz) and Betaflight on a Naze32 Rev6 with update rates of max. 1200Hz.

Installation and Test

Linux (Ubuntu / Debian)

install asio and ninja:

sudo apt install -y --no-install-recommends ninja-build libasio-dev

check out the source code and use cmake to compile:

cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Release
cmake --build build

run the example program given the path to the serial device:
```
./msp_read_test /dev/ttyUSB0
```

Windows

Requirements

CMake
asio: download asio-1.20.0.zip and extract the header files, e.g. to C:\asio-1.20.0
Visual C++ Build Tools: https://visualstudio.microsoft.com/de/downloads/

Build and Test

open the Developer Command Prompt for Visual Studio

change to the directory where you checked out msp and run:

cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DASIO_ROOT=C:\asio-1.20.0
cmake --build build

test with serial device:
```
msp_read_test.exe COM3
```

Hardware Setup

You can connect to Arduino or Naze32 boards either by (1) using a built-in USB-to-Serial connector or (2) by direct serial connection (RX->TX, TX->RX, GND->GND, VCC->VCC). The first option is preferable for high transfer rates, as the direct connection is more exposed to transmission errors.

MultiWii

the MSP update rate is determined by variable LOOP_TIME in config.h
- e.g. #define LOOP_TIME 2800 sets the loop time to 2800µs and the update rate to 1/0.0028 s = 357.14 Hz
Some Arduino boards with an integrated USB-to-serial converter auto-reset themselves when a serial connection is established. If you send messages to the FC right after opening a connection the FC will miss your request and will not send a response. You can prevent this by either a delay between opening a connection and sending messages, or by disabling the Data Terminal Ready (DTR) line, e.g. via stty -F /dev/ttyUSB0 -hupcl.

Cleanflight / Betaflight

change the update rate for the serial task in the range 100 ... 2000Hz
- e.g. to 2000Hz: set serial_update_rate_hz=2000, then save
it might be necessary to increase the serial baudrate in the Ports configuration tab

Sending and Receiving RC commands

activate feature RX_MSP
- via GUI: Configuration -> Receiver -> Receiver Mode -> MSP RX input
- via CLI: execute feature RX_MSP

Beginning with Cleanflight 2 and Betaflight 3, MSP_SET_RAW_RC messages are ignored on some targets with insufficient flash memory (like the naze32). You can verify this, if MSP_RC messages return an empty list of channels. To activate MSP_SET_RAW_RC messages on these targets, you need to add #define USE_RX_MSP to your target.h, e.g. src/main/target/NAZE/target.h.

FlightContoller API

The FlightContoller API allows the user to send/receive messages from the flight controller. Messages may be queried periodically, or on demand.

Instantiation

Instantiate and setup the FlightController class:

#include <FlightController.hpp>

fcu::FlightController fcu;

// do connection and setup
fcu.connect("/dev/ttyUSB0", 115200);

Periodic request for messages

Messages that need to be queried periodically can be handled automatically using a subscription. This can be done with a class method or a stand-alone function.

Class method pattern

Define a class that holds callback functions to process information of received message. The function signature is void <callback_name>(const <child_of_msp::Message>& ).

class App {
public:
    void onStatus(const msp::Status& status) {
        std::cout<<status;
    }

    void onImu(const msp::Imu& imu) {
        std::cout<<imu;
    }
}

Instantiate class with callbacks and register them to the FCU with the desired update rate in seconds:

App app;

fcu.subscribe(&App::onStatus, &app, 0.1);
fcu.subscribe(&App::onImu, &app, 0.01);

Requests are sent to and processed by the flight controller as fast as possible. It is important to note that the MultiWii FCU only processed a single message per cycle. All subscribed messages therefore share the effective bandwidth of 1/(2800 us) = 357 messages per second.

Lambda pattern

The FlightController::subscribe method is restricted to callbacks which return void and take an argument of const msp::Message&. In order to call a method that doesn't match that signature (maybe it needs additional information), it sometimes is useful to wrap the non-compliant method in a lambda that matches the expected signature.

auto callback = [](const msp::msg::RawImu& imu){
    // ImuSI is not a subclass of msp::Message, so it's not suitable for use as a callback argument
    std::cout << msp::msg::ImuSI(imu, 512.0, 1.0/4.096, 0.92f/10.0f, 9.80665f);
}

fcu.subscribe<msp::msg::RawImu>(callback, 0.1);

Manual sending of messages

Additional messages that are not sent periodically can be dispatched by the method

bool sendMessage(msp::Message &message, const double timeout = 0)

You need to instantiate an instance of the object matching the message you want to send and provide it to the method with an optional timeout. If the timeout paramter is 0, then the method will wait (possibly forever) until a response is received from the flight controller. A strictly positive value will limit the waiting to the specified interval.

msp::Status status;
if (fcu.sendMessage(status) ) {
    // status will contain the values returned by the flight controller
}

msp::SetCalibrationData calibration;
calibration.acc_zero_x = 0;
calibration.acc_zero_y = 0;
calibration.acc_zero_x = 0;
calibration.acc_gain_x = 1;
calibration.acc_gain_y = 1;
calibration.acc_gain_z = 1;
if (fcu.sendMessage(calibration) ) {
    // calibration data has been sent
    // since this message does not have any return data, the values are unchanged
}

If the message is of a type that has a data response from the flight controller, the instance of the message provided to the sendMessage call will contain the values unpacked from the flight controller's response.

christianrauch / msp

readme