diff options
Diffstat (limited to '.pio/libdeps/esp32-s3-n16r8/RF24/docs/arduino.md')
| -rw-r--r-- | .pio/libdeps/esp32-s3-n16r8/RF24/docs/arduino.md | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/.pio/libdeps/esp32-s3-n16r8/RF24/docs/arduino.md b/.pio/libdeps/esp32-s3-n16r8/RF24/docs/arduino.md new file mode 100644 index 0000000..a1068b4 --- /dev/null +++ b/.pio/libdeps/esp32-s3-n16r8/RF24/docs/arduino.md @@ -0,0 +1,288 @@ +# Arduino + +@tableofcontents + +<!-- markdownlint-disable MD031 --> +RF24 is fully compatible with Arduino boards. + +See [Arduino Board reference](http://www.arduino.cc/en/Reference/Board) and [Arduino SPI reference](http://arduino.cc/en/Reference/SPI) for more information + +RF24 makes use of the standard hardware SPI pins (MISO, MOSI, SCK) and requires two additional pins, to control +the chip-select and chip-enable functions. + +```cpp +RF24 radio(ce_pin, cs_pin); +``` + +These pins must be chosen and designated by the user and can use any +available pins. + +## Alternate SPI Support + +RF24 supports alternate SPI methods, in case the standard hardware SPI pins are otherwise unavailable. + +### Software Driven SPI + +Software driven SPI is provided by the [DigitalIO library](https://github.com/greiman/DigitalIO). + +Setup: + +1. Install the digitalIO library +2. Open RF24_config.h in a text editor. + Uncomment the line + ```cpp + #define SOFTSPI + ``` + or add the build flag/option + ```shell + -DSOFTSPI + ``` +3. In your sketch, add + ```cpp + #include <DigitalIO.h> + ``` + +@note Note: Pins are listed as follows and can be modified by editing the RF24_config.h file. + +```cpp +#define SOFT_SPI_MISO_PIN 16 +#define SOFT_SPI_MOSI_PIN 15 +#define SOFT_SPI_SCK_PIN 14 +``` + +Or add the build flag/option + +```shell +-DSOFT_SPI_MISO_PIN=16 -DSOFT_SPI_MOSI_PIN=15 -DSOFT_SPI_SCK_PIN=14 +``` + +### Alternate Hardware (UART) Driven SPI + +The Serial Port (UART) on Arduino can also function in SPI mode, and can double-buffer data, while the +default SPI hardware cannot. + +The SPI_UART library is available at [TMRh20/Sketches](https://github.com/TMRh20/Sketches/tree/master/SPI_UART) + +Enabling: + +1. Install the SPI_UART library +2. Edit RF24_config.h and uncomment + ```cpp + #define SPI_UART + ``` +3. In your sketch, add + ```cpp + #include <SPI_UART.h> + ``` + +SPI_UART SPI Pin Connections: +| NRF |Arduino Uno Pin| +|----:|:--------------| +| MOSI| TX(0) | +| MISO| RX(1) | +| SCK | XCK(4) | +| CE | User Specified| +| CSN | User Specified| + +@note SPI_UART on Mega boards requires soldering to an unused pin on the chip. See [#24](https://github.com/TMRh20/RF24/issues/24) for more information on SPI_UART. + +### Using a specific SPI Bus + +An alternate SPI bus can be specified using the overloaded `RF24::begin(_SPI*)` method. +This is useful for some boards that offer more than 1 hardware-driven SPI bus or certain Arduino +cores that implement a software-driven (AKA bit-banged) SPI bus that does not use the DigitalIO +library. + +@warning The SPI bus object's `SPIClass::begin()` method **must** be called before +calling the overloaded `RF24::begin(_SPI*)` method. + +Below are some example snippets that demonstrate how this can be done. + +#### ESP8266 example + +@see The following example code is meant for the popular NodeMCU board. Please refer to the +[ESP8266 ArduinoCore's SPI documentation](https://arduino-esp8266.readthedocs.io/en/latest/libraries.html#spi) +for [other ESP8266-based boards](https://arduino-esp8266.readthedocs.io/en/latest/boards.html#). + +```cpp +#include <SPI.h> +#include <RF24.h> + +// notice these pin numbers are not the same used in the library examples +RF24 radio(D4, D3); // the (ce_pin, csn_pin) connected to the radio + +void setup() { + Serial.begin(115200); + while (!Serial) {} //some boards need this + + // by default (with no arguments passed) SPI uses D5 (HSCLK), D6 (HMISO), D7 (HMOSI) + SPI.pins(6, 7, 8, 0); + // this means the following pins are used for the SPI bus: + // MOSI = SD1 + // MISO = SD0 + // SCLK = CLK + // CSN = GPIO0 (labeled D3 on the board) + // **notice we also passed `D3` to the RF24 constructor's csn_pin parameter** + + SPI.begin(); + + if (!radio.begin(&SPI)) { + Serial.println(F("radio hardware not responding!!")); + while (1) {} // hold program in infinite loop to prevent subsequent errors + } + + // ... continue with program as normal (see library examples/ folder) +} +``` + +#### ESP32 example + +@see Please review the Espressif's +[SPI_Multiple_Buses.ino example for the ESP32](https://github.com/espressif/arduino-esp32/blob/master/libraries/SPI/examples/SPI_Multiple_Buses/SPI_Multiple_Buses.ino) +located in their ArduinoCore repository (along with the SPI library for the ESP32). + +```cpp +#include <SPI.h> +#include <RF24.h> + +// to use custom-defined pins, uncomment the following +// #define MY_MISO 26 +// #define MY_MOSI 27 +// #define MY_SCLK 25 +// #define MY_SS 32 // pass MY_SS as the csn_pin parameter to the RF24 constructor + +// notice these pin numbers are not the same used in the library examples +RF24 radio(2, 0); // the (ce_pin, csn_pin) connected to the radio + +SPIClass* hspi = nullptr; // we'll instantiate this in the `setup()` function +// by default the HSPI bus pre-defines the following pins +// HSPI_MISO = 12 +// HSPI_MOSI = 13 +// HSPI_SCLK = 14 +// HSPI_SS = 15 + +void setup() { + Serial.begin(115200); + while (!Serial) {} //some boards need this + + hspi = new SPIClass(HSPI); // by default VSPI is used + hspi->begin(); + // to use the custom defined pins, uncomment the following + // hspi->begin(MY_SCLK, MY_MISO, MY_MOSI, MY_SS) + + if (!radio.begin(hspi)) { + Serial.println(F("radio hardware not responding!!")); + while (1) {} // hold program in infinite loop to prevent subsequent errors + } + + // ... continue with program as normal (see library examples/ folder) +} +``` + +#### Teensy example + +@see The overloaded RF24::begin(\_SPI\*) is not needed according to the +[Teensyduino SPI documentation](https://www.pjrc.com/teensy/td_libs_SPI.html). +Please review the table provided in the +[Teensyduino documentation](https://www.pjrc.com/teensy/td_libs_SPI.html) for what pins are used by +default for certain Teensy boards. + +```cpp +#include <SPI.h> +#include <RF24.h> + +// these pins are the alternate SPI pins available for Teensy LC/3.0/3.1/3.2/3.5/3.6 +#define MY_MISO 8 +#define MY_MOSI 7 +#define MY_SCLK 14 + +// notice these pin numbers are not the same used in the library examples +RF24 radio(2, 0); // the (ce_pin, csn_pin) connected to the radio + +void setup() { + Serial.begin(115200); + while (!Serial) {} //some boards need this + + SPI.setMOSI(MY_MOSI); + SPI.setMISO(MY_MISO); + SPI.setSCK(MY_SCLK); + + if (!radio.begin()) { + Serial.println(F("radio hardware not responding!!")); + while (1) {} // hold program in infinite loop to prevent subsequent errors + } + + // ... continue with program as normal (see library examples/ folder) +} +``` + +<!-- +#### MBED example +@see The [ArduinoCore-mbed SPI library](https://github.com/arduino/ArduinoCore-mbed/tree/master/libraries/SPI) +has predefined the possible hardware-driven SPI buses. This applies to Arduino Nano 33 BLE and +Arduino Portenta boards. + +```cpp +#include <SPI.h> +#include <RF24.h> + +RF24 radio(7, 8); // the (ce_pin, csn_pin) connected to the radio + +void setup() { + Serial.begin(115200); + while (!Serial) {} //some boards need this + + SPI1.begin(); + + if (!radio.begin(&SPI1)) { + Serial.println(F("radio hardware not responding!!")); + while (1) {} // hold program in infinite loop to prevent subsequent errors + } + + // ... continue with program as normal (see library examples/ folder) +} +``` + +#### ATSAMD21 example +@see The Support for secondary SPI bus on ATSAMD21 chips is scarcely documented. However, +[Sparkfun has a tutorial about using a second SPI bus](https://learn.sparkfun.com/tutorials/adding-more-sercom-ports-for-samd-boards/adding-an-spi) +that often refers to the +[ArduinoCore-samd SPI library source code](https://github.com/arduino/ArduinoCore-samd/blob/master/libraries/SPI/SPI.h). This example applies Sparkfun's tutorial toward the RF24 library. +Special thanks to [ex-caliper](https://github.com/ex-caliper) for the lead! + +```cpp +#include <SPI.h> +#include <RF24.h> +#include "wiring_private.h" // pinPeripheral() + +// Define the pins are the alternate SPI pins we will use. These pin numbers ARE NOT chosen at random. +// The Sparkfun tutorial explains these choices in more detail (link is in "See Also" comment above). +#define MY_MISO 3 +#define MY_MOSI 4 +#define MY_SCLK 5 + +// instantiate the secondary SPI bus +SPIClass MY_SPI(&sercom2, MY_MISO, MY_SCLK, MY_MOSI, SPI_PAD_0_SCK_3, SERCOM_RX_PAD_1); + +// notice these pin numbers are not the same used in the library examples +RF24 radio(7, 6); // the (ce_pin, csn_pin) connected to the radio + +void setup() { + Serial.begin(115200); + while (!Serial) {} //some boards need this + + // enable the alternate functionality for our secondary SPI bus' pins + pinPeripheral(MY_MISO, PIO_SERCOM_ALT); + pinPeripheral(MY_MOSI, PIO_SERCOM_ALT); + pinPeripheral(MY_SCLK, PIO_SERCOM); + + MY_SPI.begin(); // initialize the secondary SPI bus + + if (!radio.begin(&MY_SPI)) { + Serial.println(F("radio hardware not responding!!")); + while (1) {} // hold program in infinite loop to prevent subsequent errors + } + + // ... continue with program as normal (see library examples/ folder) +} +``` --> |