Krolyxon
Commit 3120783

Branches

Tags

Refs →

orion-rf.piolibdepsesp32-s3-n16r8RF24docsarduino.md

288 lines · 8.7 KB · Markdown

Raw Blame History Download
1# Arduino
2
3@tableofcontents
4
5<!-- markdownlint-disable MD031 -->
6RF24 is fully compatible with Arduino boards.
7
8See [Arduino Board reference](http://www.arduino.cc/en/Reference/Board) and [Arduino SPI reference](http://arduino.cc/en/Reference/SPI) for more information
9
10RF24 makes use of the standard hardware SPI pins (MISO, MOSI, SCK) and requires two additional pins, to control
11the chip-select and chip-enable functions.
12
13```cpp
14RF24 radio(ce_pin, cs_pin);
15```
16
17These pins must be chosen and designated by the user and can use any
18available pins.
19
20## Alternate SPI Support
21
22RF24 supports alternate SPI methods, in case the standard hardware SPI pins are otherwise unavailable.
23
24### Software Driven SPI
25
26Software driven SPI is provided by the [DigitalIO library](https://github.com/greiman/DigitalIO).
27
28Setup:
29
301. Install the digitalIO library
312. Open RF24_config.h in a text editor.
32 Uncomment the line
33 ```cpp
34 #define SOFTSPI
35 ```
36 or add the build flag/option
37 ```shell
38 -DSOFTSPI
39 ```
403. In your sketch, add
41 ```cpp
42 #include <DigitalIO.h>
43 ```
44
45@note Note: Pins are listed as follows and can be modified by editing the RF24_config.h file.
46
47```cpp
48#define SOFT_SPI_MISO_PIN 16
49#define SOFT_SPI_MOSI_PIN 15
50#define SOFT_SPI_SCK_PIN 14
51```
52
53Or add the build flag/option
54
55```shell
56-DSOFT_SPI_MISO_PIN=16 -DSOFT_SPI_MOSI_PIN=15 -DSOFT_SPI_SCK_PIN=14
57```
58
59### Alternate Hardware (UART) Driven SPI
60
61The Serial Port (UART) on Arduino can also function in SPI mode, and can double-buffer data, while the
62default SPI hardware cannot.
63
64The SPI_UART library is available at [TMRh20/Sketches](https://github.com/TMRh20/Sketches/tree/master/SPI_UART)
65
66Enabling:
67
681. Install the SPI_UART library
692. Edit RF24_config.h and uncomment
70 ```cpp
71 #define SPI_UART
72 ```
733. In your sketch, add
74 ```cpp
75 #include <SPI_UART.h>
76 ```
77
78SPI_UART SPI Pin Connections:
79| NRF |Arduino Uno Pin|
80|----:|:--------------|
81| MOSI| TX(0) |
82| MISO| RX(1) |
83| SCK | XCK(4) |
84| CE | User Specified|
85| CSN | User Specified|
86
87@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.
88
89### Using a specific SPI Bus
90
91An alternate SPI bus can be specified using the overloaded `RF24::begin(_SPI*)` method.
92This is useful for some boards that offer more than 1 hardware-driven SPI bus or certain Arduino
93cores that implement a software-driven (AKA bit-banged) SPI bus that does not use the DigitalIO
94library.
95
96@warning The SPI bus object's `SPIClass::begin()` method **must** be called before
97calling the overloaded `RF24::begin(_SPI*)` method.
98
99Below are some example snippets that demonstrate how this can be done.
100
101#### ESP8266 example
102
103@see The following example code is meant for the popular NodeMCU board. Please refer to the
104[ESP8266 ArduinoCore's SPI documentation](https://arduino-esp8266.readthedocs.io/en/latest/libraries.html#spi)
105for [other ESP8266-based boards](https://arduino-esp8266.readthedocs.io/en/latest/boards.html#).
106
107```cpp
108#include <SPI.h>
109#include <RF24.h>
110
111// notice these pin numbers are not the same used in the library examples
112RF24 radio(D4, D3); // the (ce_pin, csn_pin) connected to the radio
113
114void setup() {
115 Serial.begin(115200);
116 while (!Serial) {} //some boards need this
117
118 // by default (with no arguments passed) SPI uses D5 (HSCLK), D6 (HMISO), D7 (HMOSI)
119 SPI.pins(6, 7, 8, 0);
120 // this means the following pins are used for the SPI bus:
121 // MOSI = SD1
122 // MISO = SD0
123 // SCLK = CLK
124 // CSN = GPIO0 (labeled D3 on the board)
125 // **notice we also passed `D3` to the RF24 constructor's csn_pin parameter**
126
127 SPI.begin();
128
129 if (!radio.begin(&SPI)) {
130 Serial.println(F("radio hardware not responding!!"));
131 while (1) {} // hold program in infinite loop to prevent subsequent errors
132 }
133
134 // ... continue with program as normal (see library examples/ folder)
135}
136```
137
138#### ESP32 example
139
140@see Please review the Espressif's
141[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)
142located in their ArduinoCore repository (along with the SPI library for the ESP32).
143
144```cpp
145#include <SPI.h>
146#include <RF24.h>
147
148// to use custom-defined pins, uncomment the following
149// #define MY_MISO 26
150// #define MY_MOSI 27
151// #define MY_SCLK 25
152// #define MY_SS 32 // pass MY_SS as the csn_pin parameter to the RF24 constructor
153
154// notice these pin numbers are not the same used in the library examples
155RF24 radio(2, 0); // the (ce_pin, csn_pin) connected to the radio
156
157SPIClass* hspi = nullptr; // we'll instantiate this in the `setup()` function
158// by default the HSPI bus pre-defines the following pins
159// HSPI_MISO = 12
160// HSPI_MOSI = 13
161// HSPI_SCLK = 14
162// HSPI_SS = 15
163
164void setup() {
165 Serial.begin(115200);
166 while (!Serial) {} //some boards need this
167
168 hspi = new SPIClass(HSPI); // by default VSPI is used
169 hspi->begin();
170 // to use the custom defined pins, uncomment the following
171 // hspi->begin(MY_SCLK, MY_MISO, MY_MOSI, MY_SS)
172
173 if (!radio.begin(hspi)) {
174 Serial.println(F("radio hardware not responding!!"));
175 while (1) {} // hold program in infinite loop to prevent subsequent errors
176 }
177
178 // ... continue with program as normal (see library examples/ folder)
179}
180```
181
182#### Teensy example
183
184@see The overloaded RF24::begin(\_SPI\*) is not needed according to the
185[Teensyduino SPI documentation](https://www.pjrc.com/teensy/td_libs_SPI.html).
186Please review the table provided in the
187[Teensyduino documentation](https://www.pjrc.com/teensy/td_libs_SPI.html) for what pins are used by
188default for certain Teensy boards.
189
190```cpp
191#include <SPI.h>
192#include <RF24.h>
193
194// these pins are the alternate SPI pins available for Teensy LC/3.0/3.1/3.2/3.5/3.6
195#define MY_MISO 8
196#define MY_MOSI 7
197#define MY_SCLK 14
198
199// notice these pin numbers are not the same used in the library examples
200RF24 radio(2, 0); // the (ce_pin, csn_pin) connected to the radio
201
202void setup() {
203 Serial.begin(115200);
204 while (!Serial) {} //some boards need this
205
206 SPI.setMOSI(MY_MOSI);
207 SPI.setMISO(MY_MISO);
208 SPI.setSCK(MY_SCLK);
209
210 if (!radio.begin()) {
211 Serial.println(F("radio hardware not responding!!"));
212 while (1) {} // hold program in infinite loop to prevent subsequent errors
213 }
214
215 // ... continue with program as normal (see library examples/ folder)
216}
217```
218
219<!--
220#### MBED example
221@see The [ArduinoCore-mbed SPI library](https://github.com/arduino/ArduinoCore-mbed/tree/master/libraries/SPI)
222has predefined the possible hardware-driven SPI buses. This applies to Arduino Nano 33 BLE and
223Arduino Portenta boards.
224
225```cpp
226#include <SPI.h>
227#include <RF24.h>
228
229RF24 radio(7, 8); // the (ce_pin, csn_pin) connected to the radio
230
231void setup() {
232 Serial.begin(115200);
233 while (!Serial) {} //some boards need this
234
235 SPI1.begin();
236
237 if (!radio.begin(&SPI1)) {
238 Serial.println(F("radio hardware not responding!!"));
239 while (1) {} // hold program in infinite loop to prevent subsequent errors
240 }
241
242 // ... continue with program as normal (see library examples/ folder)
243}
244```
245
246#### ATSAMD21 example
247@see The Support for secondary SPI bus on ATSAMD21 chips is scarcely documented. However,
248[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)
249that often refers to the
250[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.
251Special thanks to [ex-caliper](https://github.com/ex-caliper) for the lead!
252
253```cpp
254#include <SPI.h>
255#include <RF24.h>
256#include "wiring_private.h" // pinPeripheral()
257
258// Define the pins are the alternate SPI pins we will use. These pin numbers ARE NOT chosen at random.
259// The Sparkfun tutorial explains these choices in more detail (link is in "See Also" comment above).
260#define MY_MISO 3
261#define MY_MOSI 4
262#define MY_SCLK 5
263
264// instantiate the secondary SPI bus
265SPIClass MY_SPI(&sercom2, MY_MISO, MY_SCLK, MY_MOSI, SPI_PAD_0_SCK_3, SERCOM_RX_PAD_1);
266
267// notice these pin numbers are not the same used in the library examples
268RF24 radio(7, 6); // the (ce_pin, csn_pin) connected to the radio
269
270void setup() {
271 Serial.begin(115200);
272 while (!Serial) {} //some boards need this
273
274 // enable the alternate functionality for our secondary SPI bus' pins
275 pinPeripheral(MY_MISO, PIO_SERCOM_ALT);
276 pinPeripheral(MY_MOSI, PIO_SERCOM_ALT);
277 pinPeripheral(MY_SCLK, PIO_SERCOM);
278
279 MY_SPI.begin(); // initialize the secondary SPI bus
280
281 if (!radio.begin(&MY_SPI)) {
282 Serial.println(F("radio hardware not responding!!"));
283 while (1) {} // hold program in infinite loop to prevent subsequent errors
284 }
285
286 // ... continue with program as normal (see library examples/ folder)
287}
288``` -->