Document how to specify Serial pins

[woodchuck]

Thank you sooo much for this library. My son has built a little mouse-sized treadmobile from scratch, and this has allowed us to control it via a Matek ELRS receiver and an Arduino Nano esp32. Our biggest obstacle to getting this working was getting the serial ports configured. This is partly due to my unfamiliarity with the Arduino API, and may not apply to other devices the same way, but it might be helpful to expand the documentation to show how to explicitly configure Serial for Serial Monitor output, and Serial1 (or Serial2) with pins of your choosing -- 8 and 7 in our case:

CRSFforArduino crsf = CRSFforArduino(&Serial1);

void setup() {
  Serial.begin(9600);

  Serial1.begin(420000, SERIAL_8N1, D8, D7);
  while (!Serial1) {
    ;
  }
  ...

[ZZ-Cat]

You're very welcome. =^/.^=

For ESP32 targets: Currently, there isn't a built-in way to assign custom pins as of yet.
This is already in the pipeline in the upcoming release of Version 1.1.0, as you're not the only one that's asked for this.
As I have been made aware, ESP32-based targets assign the pins during the call to the related begin() function. This is significantly different to how SAMD21-based and SAMD51/SAME51-based targets achieve this. With SAMD21 and SAMx5y targets, pin assignments are done with the constructor, as opposed to the begin() function.
At the time, I assumed that all targets assigned pins through their UART constructor(s). But, have since found out that it isn't the case for all targets that CRSF for Arduino is compatible with. It seems to me that ESP32 targets are the only ones affected, so far.

When I add it in, the documentation will reflect this.
I MAY provide documentation on how to go about assigning the custom pins.
For the time being, what you have here as a work-around SHOULD work.

If you need more information, CRSF for Arduino is reasonably documented and comes with its own API Reference, plus a section on resource management.
...and yes, in the Resource Management section, I call out the bad practices what Arduino "teaches" you.

When you're using CRSF for Arduino in particular, it is strongly RECOMMENDED that you take advantage of dynamic memory.
For example, your use case here MAY look something like this:

#include "CRSFforArduino.h"

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

void setup()
{
    /* Allocate memory and a custom UART to CRSF for Arduino. */
    crsf = new CRSFforArduino(&Serial1);

    /* Allocate and initialise the hardware required by CRSF for Arduino. */
    if (crsf->begin() == true)
    {
        /* Hardware allocated successfully.
        The rest of CRSF for Arduino's functionality should be initialised here.
        Anything else that depends on CRSF for Arduino `MUST` be initialised here, as well.
        EG Servos, motor controllers etc.
        From Woodchuck's example, CRSF for Arduino may try to internally initialise Serial1
        with its default settings. So, it `SHOULD` be overridden here. */

        // 1. Clean out both Tx and Rx buffers.
        Serial1.flush();
        while(Serial1.available())
        {
            Serial1.read();
        }

        // 2. De-allocate the previous lot of configurations, and wait a little.
        Serial1.end();
        delay(100); // This delay `MAY NOT` be necessary.

        // 3. Re-initialise `Serial1` with the required configuration.
        Serial1.begin(420000, SERIAL_8N1, D8, D7);

        // 4. Lastly, ensure there's no "garbage" in the UART's Rx buffer.
        while(Serial1.available())
        {
            Serial1.read();
        }
    }
    else
    {
        /* Hardware allocation failed.
        Anything that succeeded during the call to 'begin()' MUST be
        freed to avoid hardware and memory leaks. */
        crsf->end();
        delete crsf;
        crsf = nullptr;

        /* You may choose to stop here, although it is `RECOMMENDED` that you avoid this practice,
        because you could be starving other tasks and/or parts of your firmware that `MAY` run, but
        aren't dependent on CRSF for Arduino.
        If you do this, either do a 20 ms delay _or_ ensure 'yield()' is called, especially if you're using
        an ESP32 target. */
        // while (1)
        // {
        //     delay(20);
        // }
    }
}

void loop()
{
    /* CRSF for Arduino's API `MUST NOT` be accessed unless an instance of itself has been created. */
    if (crsf != nullptr)
    {
        /* Run CRSF for Arduino's main function. */
        crsf->update();

        /* Anything else that depends on CRSF for Arduino's functionality, you `SHOULD NOT` run that outside the
        context of this statement block. */
    }
}

[woodchuck]

Thanks for these details. 🙇 We'll adjust our code accordingly!

[woodchuck]

We've updated to use the 1.0.2 release and its support for assigning pins in the constructor. It works great!!

https://www.youtube.com/shorts/9VHilN0apCI

[ZZ-Cat]

Excellent. =^/,..,^=