Skip to content

API Reference

Jump to bottom
Cassandra "ZZ Cat" Robinson edited this page Aug 9, 2023 · 17 revisions

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.
Two types of code examples are provided for each function in the API. The first example is a simplistic approach, to convey a basic understanding of the API. The second example demonstrates how defensive programming measures could be used with CRSF for Arduino.

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.

Default settings are as follows:

  • Baud rate: 420 KB/s
  • UART Rx pin: 0
  • UART Tx pin: 1

The settings above means internally, Serial1 from the Arduino API is used to provide communications to & from your TBS Crossfire or ExpressLRS receiver.

  • CRSFforArduino(uint8_t RxPin, TxPin)

This constructor is currently a work-in-progress & it is not recommended to use in your projects for the time being.
When this constructor is properly fleshed out, you will be able to choose your own location for the UART Rx & Tx pins.

NB: These pin locations are subject to the limitations on specific locations of a particular chip-set's hardware UART ports & pin assignments.

Instantiation

There are two ways you can create an instance of CRSF for Arduino:

  1. Declare CRSF for Arduino as a global object.
    • Benefits:
      • Straightforward.
    • Drawbacks:
      • Creates both memory & hardware leaks.
      • CRSF for Arduino is globally initialised, which can impact other resources in a generously sized sketch where you need to juggle resources with other libraries.
  2. Declare a pointer to CRSF for Arduino.
    • Benefits:
      • You create a new instance of CRSF for Arduino when the rest of your sketch actually needs it.
      • You have deterministic error handling for when no memory is allocated.
      • As a defensive programming measure, you can guard code execution from trying to initialise CRSF for Arduino, when no memory was allocated.
      • You have far greater control over when the necessary resources for CRSF for Arduino are allocated & deallocated.
    • Drawbacks:
      • Slightly more complex.
      • To avoid memory & hardware leaks, you need to ensure that the object is deleted when your sketch is finished using CRSF for Arduino. This is fairly easy to do by using the delete operator.

Object declaration looks like this...

#include "CRSFforArduino.h"

/* Declare CRSF for Arduino as a global object. */
CRSFforArduino crsf = CRSFforArduino();

void setup()
{
    /* Your set-up code here... */
}

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

Using a pointer to CRSF for Arduino looks like this...

#include "CRSFforArduino.h"

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

void setup()
{
    /* You can create an instance of CRSF for Arduino when your sketch actually needs it. */
    crsf = new CRSFforArduino();

    /* You can check if the memory was actually allocated. */
    if (crsf != NULL)
    {
        /* Here is where you can initialise CRSF for Arduino. */
    }

    /* If no memory was allocated to CRSF for Arduino, here is where you can handle the error. */
    else
    {
        // Stop here, for now.
        while (true)
        {
            ;
        }
    }

    /* Your set-up code here... */
}

void loop()
{
    /* Your main code here.
    For the purposes of this example, loop() will execute for three times before deleting CRSF for Arduino. */
    for (int i = 0; i < 3; i++)
    {
        // Do nothing. This is only here to convey the context of what to do when your sketch is finished with CRSF for Arduino.
    }

    /* At some point, your hardware is finished using CRSF for Arduino.
    Therefore, you must free the resources that were previously allocated to prevent memory & hardware leaks.
    Pro Tip: As a defensive programming measure, check that CRSF for Arduino was already allocated. */
    if (crsf != NULL)
    {
        // This is how you free the resources that were allocated.
        delete crsf;

        /* NB: You MUST NOT use any of CRSF for Arduino's API functions.
        If you need to use the API again, you MUST create a new instance (see above) of CRSF for Arduino before any of its API functions.
    }

    /* Stop here, because the example above has finished executing & no further action is needed. */
    while (true)
    {
        ;
    }
}

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: Currently, it is not possible to provide your own baud rate or serial configuration (EG SERIAL_8N1).
This is by design because CRSF for Arduino requires a baud rate of 420 KB/s & SERIAL_8N1 configuration, & this is automatically configured for you.

The example below demonstrates how to initialise CRSF for Arduino.
For the sake of simplicity, no defensive programming measures are in place.

#include "CRSFforArduino.h"

/* CRSF for Arduino is declared as a global instance. */
CRSFforArduino crsf = CRSFforArduino();

void setup()
{
    /* Initialise CRSF for Arduino */
    crsf.begin();

    /* The rest of your set-up code here... */
}

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

The example below demonstrates how defensive programming measures can be applied to the initialiser.

#include "CRSFforArduino.h"

/* Only a pointer to CRSF for Arduino is declared. */
CRSFforArduino *crsf = nullptr;

void setup()
{

    /* Initialise CRSF for Arduino using defensive programming techniques. */
    crsf = new CRSFforArduino();
    if (crsf != NULL)
    {
        /* A defensive programming measure for the initialiser is to check that the return value is true.
        Any value other than true is an initialisation failure. */
        if (crsf.begin() != true)
        {
            /* Here is where you can catch the error.
            For the purposes of this example, code execution simply stops here. */
            while (true)
            {
                ;
            }
        }
    }
    else
    {
        /* If no memory is allocated for CRSF for Arduino then it simply cannot be initialised.
        As a defensive programming measure, you can catch the memory allocation error here.
        For the purposes of this example, code execution simply stops here. */
        while (true)
        {
            ;
        }
    }
}

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;

Clone this wiki locally