API Reference

Overview

By design, the API is meant to be simplistic & easy to integrate into your existing sketches/projects.

Code examples are provided as 'pseudo-code' to help convey the context of a particular function and how it should be used.

The API

Constructors & instantiation

⚠️ ATTENTION ⚠️
You MUST NOT use any of CRSF for Arduino's API functions before instantiation.
You MUST create an instance of CRSF for Arduino before you can use its API.

Constructors

• CRSFforArduino()

This is the default constructor. It creates an instance of CRSF for Arduino.
Serial1 from the Arduino API is used to provide communications to & from your TBS Crossfire or ExpressLRS receiver.
In the case of STM32 targets, Serial1 is not available on some STM32 targets.
Therefore, the next available HardwareSerial instance is automatically picked based on availability. EG CRSF for Arduino will default to Serial2 if it's available. If Serial2 is not available, Serial3 is automatically picked.

• CRSFforArduino(HardwareSerial *serialPort)

This constructor is where you can provide your own custom HardwareSerial instance.
This gives you the flexibility of assigning any arbitrary UART port to CRSF for Arduino.

Instantiation

#include "CRSFforArduino.h"

/* Declare a null pointer to CRSF for Arduino. */
CRSFforArduino *crsf = nullptr;

void setup()
{
    /* Instantiate CRSF for Arduino. */
    crsf = new CRSFforArduino();
}

void loop()
{
    /* Your main code here... */
}

Initialising & de-initialising CRSF for Arduino

This is where you actually start using CRSF for Arduino.

Initialiser

• CRSFforArduino::begin()
• Return type: bool
  • true if initialisation is successful.
  • false if initialisation failed.

NB: The appropriate baud rate and configuration is done for you.

The example below demonstrates how to initialise CRSF for Arduino.
NB: The return check on the initialiser has been omitted for simplicity's sake.

#include "CRSFforArduino.h"

/* Declare a null pointer to CRSF for Arduino. */
CRSFforArduino *crsf = nullptr;

void setup()
{
    /* Instantiate CRSF for Arduino. */
    crsf = new CRSFforArduino();

    /* Initialise CRSF for Arduino. */
    crsf->begin();
}

void loop()
{
    /* Your main code here... */
}

De-initialiser

• CRSFforArduino::end()

This de-initialises CRSF for Arduino by disabling hardware serial communications with your RC receiver, & freeing up the previously configured hardware serial port.

⚠️ ATTENTION ⚠️
This does not delete any previously allocated memory for CRSF for Arduino.
You MUST delete this memory yourself using delete <YOUR_CRSF_OBJECT>, where <YOUR_CRSF_OBJECT> is the name you gave to your instance of CRSF for Arduino. EG If you're following the examples above, the name given is crsf. So delete crsf;

The example below shows how to correctly de-initialise CRSF for Arduino and free up the resources that were allocated to it.
In this example, a limited number of executions are done before CRSF for Arduino is completely destroyed.

#include "CRSFforArduino.h"

int loopExecutions = 0;

CRSFforArduino *crsf = nullptr;

void setup()
{
    crsf = new CRSFforArduino();

    if (crsf->begin() != true)
    {
        /* CRSF for Arduino failed to initialise.
        Clean-up the resources that it previously allocated, and then free up the memory it allocated. */
        crsf->end();
        delete crsf;
        crsf = nullptr;
    }
}

void loop()
{
    /* Guard CRSF for Arduino's API with a null check. */
    if (crsf != nullptr)
    {
        /* Increment the loop executions counter. */
        loopExecutions++;

        /* After five loop executions, destroy CRSF for Arduino. */
        if (loopExecutions >= 5)
        {
            crsf->end();
            delete crsf;
            crsf = nullptr;
        }
    }
}

Running CRSF for Arduino

CRSF for Arduino uses an event-driven API for reading RC Channels, Link Statistics, and setting Flight Modes.
These events are handled internally and they have their own respective callback functions that you can register in your sketches.

The main function

• CRSFforArduino::update()

This function must be placed inside your main loop(), or in some other function or service routine that is updated as quickly as possible.
It should be updated at least every 4 milliseconds or faster.

#include "CRSFforArduino.h"

CRSFforArduino *crsf = nullptr;

void setup()
{
    crsf = new CRSFforArduino();

    /* Initialise CRSF for Arduino, and clean up
    any allocated resources if initialisation fails. */
    if (crsf->begin() != true)
    {
        crsf->end();
        delete crsf;
        crsf = nullptr;
    }
}

void loop()
{
    /* Guard CRSF for Arduino's API with a null check. */
    if (crsf != nullptr)
    {
        /* Call CRSF for Arduino's main function here. */
        crsf->update();
    }
}

Events - Link Statistics

This is your first port of call, because it gives you insight as to the stability of your receiver's connection with your transmitter.
Here, you have access to RSSI, Link Quality, Signal-to-Noise Ratio, and Transmitter Power.

• CRSFforArduino::setLinkStatisticsCallback(void (*callback)(serialReceiverLayer::link_statistics_t linkStatistics))

#include "CRSFforArduino.h"

CRSFforArduino *crsf = nullptr;

void onLinkStatisticsUpdate(serialReceiverLayer::link_statistics_t);

void setup()
{
    crsf = new CRSFforArduino();

    /* Initialise CRSF for Arduino. */
    if (crsf->begin() == true)
    {
        /* CRSF for Arduino initialised successfully.
        We can now register the Link Statistics event. */
        crsf->setLinkStatisticsCallback(onLinkStatisticsUpdate);
    }
    else
    {
        /* Clean up any resources,
        if initialisation fails. */
        crsf->end();
        delete crsf;
        crsf = nullptr;
    }
}

void loop()
{
    /* Guard CRSF for Arduino's API with a null check. */
    if (crsf != nullptr)
    {
        /* Call CRSF for Arduino's main function here. */
        crsf->update();
    }
}

void onLinkStatisticsUpdate(serialReceiverLayer::link_statistics_t linkStatistics)
{
    /* This is your Link Statistics Event Callback.
    By using the linkStatistics parameter that's passed in,
    you have access to the following:
    - linkStatistics.rssi
    - linkStatistics.lqi
    - linkStatistics.snr
    - linkStatistics.tx_power

    For the purposes of this example, these values are simply
    printed to the Serial Monitor at a rate of 5 Hz. */

    static unsigned long lastPrint = 0;
    if (millis() - lastPrint >= 200)
    {
        lastPrint = millis();
        Serial.print("Link Statistics: ");
        Serial.print("RSSI: ");
        Serial.print(linkStatistics.rssi);
        Serial.print(", Link Quality: ");
        Serial.print(linkStatistics.lqi);
        Serial.print(", Signal-to-Noise Ratio: ");
        Serial.print(linkStatistics.snr);
        Serial.print(", Transmitter Power: ");
        Serial.println(linkStatistics.tx_power);
    }
}

Events - RC Channels

Events - Flight Modes