forked from nRF24/RF24
-
Notifications
You must be signed in to change notification settings - Fork 0
/
RF24.h
2450 lines (2299 loc) · 95.5 KB
/
RF24.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Copyright (C) 2011 J. Coliz <[email protected]>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
version 2 as published by the Free Software Foundation.
*/
/**
* @file RF24.h
*
* Class declaration for RF24 and helper enums
*/
#ifndef __RF24_H__
#define __RF24_H__
#include "RF24_config.h"
#if defined(RF24_LINUX) || defined(LITTLEWIRE)
#include "utility/includes.h"
#elif defined SOFTSPI
#include <DigitalIO.h>
#endif
/**
* @defgroup PALevel Power Amplifier level
* Power Amplifier level. The units dBm (decibel-milliwatts or dB<sub>mW</sub>)
* represents a logarithmic signal loss.
* @see
* - RF24::setPALevel()
* - RF24::getPALevel()
* @{
*/
typedef enum
{
/**
* (0) represents:
* nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0
* :-------:|:-----------------------------:|:----------------------------:
* -18 dBm | -6 dBm | -12 dBm
*/
RF24_PA_MIN = 0,
/**
* (1) represents:
* nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0
* :-------:|:-----------------------------:|:----------------------------:
* -12 dBm | 0 dBm | -4 dBm
*/
RF24_PA_LOW,
/**
* (2) represents:
* nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0
* :-------:|:-----------------------------:|:----------------------------:
* -6 dBm | 3 dBm | 1 dBm
*/
RF24_PA_HIGH,
/**
* (3) represents:
* nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0
* :-------:|:-----------------------------:|:----------------------------:
* 0 dBm | 7 dBm | 4 dBm
*/
RF24_PA_MAX,
/**
* (4) This should not be used and remains for backward compatibility.
*/
RF24_PA_ERROR
} rf24_pa_dbm_e;
/**
* @}
* @defgroup Datarate datarate
* How fast data moves through the air. Units are in bits per second (bps).
* @see
* - RF24::setDataRate()
* - RF24::getDataRate()
* @{
*/
typedef enum
{
/** (0) represents 1 Mbps */
RF24_1MBPS = 0,
/** (1) represents 2 Mbps */
RF24_2MBPS,
/** (2) represents 250 kbps */
RF24_250KBPS
} rf24_datarate_e;
/**
* @}
* @defgroup CRCLength CRC length
* The length of a CRC checksum that is used (if any). Cyclical Redundancy
* Checking (CRC) is commonly used to ensure data integrity.
* @see
* - RF24::setCRCLength()
* - RF24::getCRCLength()
* - RF24::disableCRC()
* @{
*/
typedef enum
{
/** (0) represents no CRC checksum is used */
RF24_CRC_DISABLED = 0,
/** (1) represents CRC 8 bit checksum is used */
RF24_CRC_8,
/** (2) represents CRC 16 bit checksum is used */
RF24_CRC_16
} rf24_crclength_e;
/**
* @}
* @brief Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver
*/
class RF24
{
private:
#ifdef SOFTSPI
SoftSPI<SOFT_SPI_MISO_PIN, SOFT_SPI_MOSI_PIN, SOFT_SPI_SCK_PIN, SPI_MODE> spi;
#elif defined(SPI_UART)
SPIUARTClass uspi;
#endif
#if defined(RF24_LINUX) || defined(XMEGA_D3) || defined(RF24_RP2) /* XMEGA can use SPI class */
SPI spi;
#endif // defined (RF24_LINUX) || defined (XMEGA_D3)
#if defined(RF24_SPI_PTR)
_SPI* _spi;
#endif // defined (RF24_SPI_PTR)
#if defined(MRAA)
GPIO gpio;
#endif
uint16_t ce_pin; /* "Chip Enable" pin, activates the RX or TX role */
uint16_t csn_pin; /* SPI Chip select */
#if defined(STM32)
GPIO_TypeDef* ce_port;
GPIO_TypeDef* csn_port;
#endif
uint32_t spi_speed; /* SPI Bus Speed */
#if defined(RF24_LINUX) || defined(XMEGA_D3) || defined(RF24_RP2)
uint8_t spi_rxbuff[32 + 1]; //SPI receive buffer (payload max 32 bytes)
uint8_t spi_txbuff[32 + 1]; //SPI transmit buffer (payload max 32 bytes + 1 byte for the command)
#endif
uint8_t status; /* The status byte returned from every SPI transaction */
uint8_t payload_size; /* Fixed size of payloads */
uint8_t pipe0_reading_address[5]; /* Last address set on pipe 0 for reading. */
uint8_t config_reg; /* For storing the value of the NRF_CONFIG register */
bool _is_p_variant; /* For storing the result of testing the toggleFeatures() affect */
bool _is_p0_rx; /* For keeping track of pipe 0's usage in user-triggered RX mode. */
protected:
/**
* SPI transactions
*
* Common code for SPI transactions including CSN toggle
*
*/
inline void beginTransaction();
inline void endTransaction();
/** Whether ack payloads are enabled. */
bool ack_payloads_enabled;
/** The address width to use (3, 4 or 5 bytes). */
uint8_t addr_width;
/** Whether dynamic payloads are enabled. */
bool dynamic_payloads_enabled;
/**
* Read a chunk of data in from a register
*
* @param reg Which register. Use constants from nRF24L01.h
* @param[out] buf Where to put the data
* @param len How many bytes of data to transfer
* @note This returns nothing. Older versions of this function returned the status
* byte, but that it now saved to a private member on all SPI transactions.
*/
void read_register(uint8_t reg, uint8_t* buf, uint8_t len);
/**
* Read single byte from a register
*
* @param reg Which register. Use constants from nRF24L01.h
* @return Current value of register @p reg
*/
uint8_t read_register(uint8_t reg);
public:
/**
* @name Primary public interface
*
* These are the main methods you need to operate the chip
*/
/**@{*/
/**
* RF24 Constructor
*
* Creates a new instance of this driver. Before using, you create an instance
* and send in the unique pins that this chip is connected to.
*
* See [Related Pages](pages.html) for device specific information
*
* @param _cepin The pin attached to Chip Enable on the RF module
* @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module.
* - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI)
* is not supported. This means that the Due's pins 4, 10, or 52 are not mandated options (can use any digital output pin) for the radio's CSN pin.
* @param _spi_speed The SPI speed in Hz ie: 1000000 == 1Mhz
* - Users can specify default SPI speed by modifying @ref RF24_SPI_SPEED in @ref RF24_config.h
* - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
* - Older/Unsupported Arduino devices will use a default clock divider & settings configuration
* - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7
*/
RF24(uint16_t _cepin, uint16_t _cspin, uint32_t _spi_speed = RF24_SPI_SPEED);
/**
* A constructor for initializing the radio's hardware dynamically
* @warning You MUST use begin(uint16_t, uint16_t) or begin(_SPI*, uint16_t, uint16_t) to pass both the digital output pin
* numbers connected to the radio's CE and CSN pins.
* @param _spi_speed The SPI speed in Hz ie: 1000000 == 1Mhz
* - Users can specify default SPI speed by modifying @ref RF24_SPI_SPEED in @ref RF24_config.h
* - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
* - Older/Unsupported Arduino devices will use a default clock divider & settings configuration
* - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7
*/
RF24(uint32_t _spi_speed = RF24_SPI_SPEED);
#if defined(RF24_LINUX)
virtual ~RF24() {};
#endif
/**
* Begin operation of the chip
*
* Call this in setup(), before calling any other methods.
* @code
* if (!radio.begin()) {
* Serial.println(F("radio hardware not responding!"));
* while (1) {} // hold program in infinite loop to prevent subsequent errors
* }
* @endcode
* @return
* - `true` if the radio was successfully initialized
* - `false` if the MCU failed to communicate with the radio hardware
*/
bool begin(void);
#if (defined(RF24_SPI_PTR) || defined(DOXYGEN_FORCED)) && !defined(STM32)
/**
* Same as begin(), but allows specifying a non-default SPI bus to use.
*
* @note This function assumes the `SPI::begin()` method was called before to
* calling this function.
*
* @warning This function is for the Arduino platforms only
*
* @param spiBus A pointer or reference to an instantiated SPI bus object.
* The `_SPI` datatype is a "wrapped" definition that will represent
* various SPI implementations based on the specified platform.
* @see Review the [Arduino support page](md_docs_arduino.html).
*
* @return same result as begin()
*/
bool begin(_SPI* spiBus);
/**
* Same as begin(), but allows dynamically specifying a SPI bus, CE pin,
* and CSN pin to use.
*
* @note This function assumes the `SPI::begin()` method was called before to
* calling this function.
*
* @warning This function is for the Arduino platforms only
*
* @param spiBus A pointer or reference to an instantiated SPI bus object.
* The `_SPI` datatype is a "wrapped" definition that will represent
* various SPI implementations based on the specified platform.
* @param _cepin The pin attached to Chip Enable on the RF module
* @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module.
* - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI)
* is not supported. This means that the Due's pins 4, 10, or 52 are not mandated options (can use any digital output pin) for the radio's CSN pin.
*
* @see Review the [Arduino support page](md_docs_arduino.html).
*
* @return same result as begin()
*/
bool begin(_SPI* spiBus, uint16_t _cepin, uint16_t _cspin);
#endif // defined (RF24_SPI_PTR) || defined (DOXYGEN_FORCED)
#if defined(STM32)
/**
* Same as begin(), but allows dynamically specifying a SPI bus, CE pin,
* and CSN pin to use.
*
* @note This function assumes the `SPI::begin()` method was called before to
* calling this function.
*
* @warning This function is for the Arduino platforms only
*
* @param spiBus A pointer or reference to an instantiated SPI bus object.
* The `_SPI` datatype is a "wrapped" definition that will represent
* various SPI implementations based on the specified platform.
* @param _cepin The pin attached to Chip Enable on the RF module.
* @param _ceport The handle object associated with the pin attached to Chip Enable on the RF module.
* @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module.
* @param _csport The handle object associated with the pin attached to Chip Select (often labeled CSN) on the radio module.
* - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI)
* is not supported. This means that the Due's pins 4, 10, or 52 are not mandated options (can use any digital output pin) for the radio's CSN pin.
*
* @see Review the [Arduino support page](md_docs_arduino.html).
*
* @return same result as begin()
*/
bool begin(SPI_HandleTypeDef * spiBus, uint16_t _cepin, GPIO_TypeDef* _ceport, uint16_t _cspin, GPIO_TypeDef* _csport);
#endif
/**
* Same as begin(), but allows dynamically specifying a CE pin
* and CSN pin to use.
* @param _cepin The pin attached to Chip Enable on the RF module
* @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module.
* - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI)
* is not supported. This means that the Due's pins 4, 10, or 52 are not mandated options (can use any digital output pin) for the radio's CSN pin.
* @return same result as begin()
*/
bool begin(uint16_t _cepin, uint16_t _cspin);
/**
* Checks if the chip is connected to the SPI bus
*/
bool isChipConnected();
/**
* Start listening on the pipes opened for reading.
*
* 1. Be sure to call openReadingPipe() first.
* 2. Do not call write() while in this mode, without first calling stopListening().
* 3. Call available() to check for incoming traffic, and read() to get it.
*
* Open reading pipe 1 using address `0xCCCECCCECC`
* @code
* byte address[] = {0xCC, 0xCE, 0xCC, 0xCE, 0xCC};
* radio.openReadingPipe(1,address);
* radio.startListening();
* @endcode
*
* @note If there was a call to openReadingPipe() about pipe 0 prior to
* calling this function, then this function will re-write the address
* that was last set to reading pipe 0. This is because openWritingPipe()
* will overwrite the address to reading pipe 0 for proper auto-ack
* functionality.
*/
void startListening(void);
/**
* Stop listening for incoming messages, and switch to transmit mode.
*
* Do this before calling write().
* @code
* radio.stopListening();
* radio.write(&data, sizeof(data));
* @endcode
*
* @note When the ACK payloads feature is enabled, the TX FIFO buffers are
* flushed when calling this function. This is meant to discard any ACK
* payloads that were not appended to acknowledgment packets.
*/
void stopListening(void);
/**
* Check whether there are bytes available to be read
* @code
* if(radio.available()){
* radio.read(&data,sizeof(data));
* }
* @endcode
*
* @see available(uint8_t*)
*
* @return True if there is a payload available, false if none is
*
* @warning This function relies on the information about the pipe number
* that received the next available payload. According to the datasheet,
* the data about the pipe number that received the next available payload
* is "unreliable" during a FALLING transition on the IRQ pin. This means
* you should call whatHappened() before calling this function
* during an ISR (Interrupt Service Routine). For example:
* @code
* void isrCallbackFunction() {
* bool tx_ds, tx_df, rx_dr;
* radio.whatHappened(tx_ds, tx_df, rx_dr); // resets the IRQ pin to HIGH
* radio.available(); // returned data should now be reliable
* }
*
* void setup() {
* pinMode(IRQ_PIN, INPUT);
* attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING);
* }
* @endcode
*/
bool available(void);
/**
* Read payload data from the RX FIFO buffer(s).
*
* The length of data read is usually the next available payload's length
* @see
* - getPayloadSize()
* - getDynamicPayloadSize()
*
* @note I specifically chose `void*` as a data type to make it easier
* for beginners to use. No casting needed.
*
* @param buf Pointer to a buffer where the data should be written
* @param len Maximum number of bytes to read into the buffer. This
* value should match the length of the object referenced using the
* `buf` parameter. The absolute maximum number of bytes that can be read
* in one call is 32 (for dynamic payload lengths) or whatever number was
* previously passed to setPayloadSize() (for static payload lengths).
* @remark
* @parblock
* Remember that each call to read() fetches data from the
* RX FIFO beginning with the first byte from the first available
* payload. A payload is not removed from the RX FIFO until it's
* entire length (or more) is fetched using read().
*
* - If `len` parameter's value is less than the available payload's
* length, then the payload remains in the RX FIFO.
* - If `len` parameter's value is greater than the first of multiple
* available payloads, then the data saved to the `buf`
* parameter's object will be supplemented with data from the next
* available payload.
* - If `len` parameter's value is greater than the last available
* payload's length, then the last byte in the payload is used as
* padding for the data saved to the `buf` parameter's object.
* The nRF24L01 will repeatedly use the last byte from the last
* payload even when read() is called with an empty RX FIFO.
* @endparblock
* @note To use this function in the python wrapper, remember that
* only the `len` parameter is required because this function (in the
* python wrapper) returns the payload data as a buffer protocol object
* (bytearray object).
* @code{.py}
* # let `radio` be the instantiated RF24 object
* if radio.available():
* length = radio.getDynamicPayloadSize() # or radio.getPayloadSize() for static payload sizes
* received_payload = radio.read(length)
* @endcode
*
* @note This function no longer returns a boolean. Use available to
* determine if packets are available. The `RX_DR` Interrupt flag is now
* cleared with this function instead of when calling available().
* @code
* if(radio.available()) {
* radio.read(&data, sizeof(data));
* }
* @endcode
*/
void read(void* buf, uint8_t len);
/**
* Be sure to call openWritingPipe() first to set the destination
* of where to write to.
*
* This blocks until the message is successfully acknowledged by
* the receiver or the timeout/retransmit maxima are reached. In
* the current configuration, the max delay here is 60-70ms.
*
* The maximum size of data written is the fixed payload size, see
* getPayloadSize(). However, you can write less, and the remainder
* will just be filled with zeroes.
*
* TX/RX/RT interrupt flags will be cleared every time write is called
*
* @param buf Pointer to the data to be sent
* @param len Number of bytes to be sent
*
* @code
* radio.stopListening();
* radio.write(&data,sizeof(data));
* @endcode
*
* @note The `len` parameter must be omitted when using the python
* wrapper because the length of the payload is determined automatically.
* To use this function in the python wrapper:
* @code{.py}
* # let `radio` be the instantiated RF24 object
* buffer = b"Hello World" # a `bytes` object
* radio.write(buffer)
* @endcode
*
* @return
* - `true` if the payload was delivered successfully and an acknowledgement
* (ACK packet) was received. If auto-ack is disabled, then any attempt
* to transmit will also return true (even if the payload was not
* received).
* - `false` if the payload was sent but was not acknowledged with an ACK
* packet. This condition can only be reported if the auto-ack feature
* is on.
*/
bool write(const void* buf, uint8_t len);
/**
* New: Open a pipe for writing via byte array. Old addressing format retained
* for compatibility.
*
* Only one writing pipe can be opened at once, but this function changes
* the address that is used to transmit (ACK payloads/packets do not apply
* here). Be sure to call stopListening() prior to calling this function.
*
* Addresses are assigned via a byte array, default is 5 byte address length
*
* @code
* uint8_t addresses[][6] = {"1Node", "2Node"};
* radio.openWritingPipe(addresses[0]);
* @endcode
* @code
* uint8_t address[] = { 0xCC, 0xCE, 0xCC, 0xCE, 0xCC };
* radio.openWritingPipe(address);
* address[0] = 0x33;
* radio.openReadingPipe(1, address);
* @endcode
*
* @warning This function will overwrite the address set to reading pipe 0
* as stipulated by the datasheet for proper auto-ack functionality in TX
* mode. Use this function to ensure proper transmission acknowledgement
* when the address set to reading pipe 0 (via openReadingPipe()) does not
* match the address passed to this function. If the auto-ack feature is
* disabled, then this function will still overwrite the address for
* reading pipe 0 regardless.
*
* @see
* - setAddressWidth()
* - startListening()
*
* @param address The address to be used for outgoing transmissions (uses
* pipe 0). Coordinate this address amongst other receiving nodes (the
* pipe numbers don't need to match).
*
* @remark There is no address length parameter because this function will
* always write the number of bytes that the radio addresses are configured
* to use (set with setAddressWidth()).
*/
void openWritingPipe(const uint8_t* address);
/**
* Open a pipe for reading
*
* Up to 6 pipes can be open for reading at once. Open all the required
* reading pipes, and then call startListening().
*
* @see
* - openWritingPipe()
* - setAddressWidth()
*
* @note Pipes 0 and 1 will store a full 5-byte address. Pipes 2-5 will technically
* only store a single byte, borrowing up to 4 additional bytes from pipe 1 per the
* assigned address width.
* Pipes 1-5 should share the same address, except the first byte.
* Only the first byte in the array should be unique, e.g.
* @code
* uint8_t addresses[][6] = {"Prime", "2Node", "3xxxx", "4xxxx"};
* openReadingPipe(0, addresses[0]); // address used is "Prime"
* openReadingPipe(1, addresses[1]); // address used is "2Node"
* openReadingPipe(2, addresses[2]); // address used is "3Node"
* openReadingPipe(3, addresses[3]); // address used is "4Node"
* @endcode
*
* @warning
* @parblock
* If the reading pipe 0 is opened by this function, the address
* passed to this function (for pipe 0) will be restored at every call to
* startListening().
*
* Read
* http://maniacalbits.blogspot.com/2013/04/rf24-addressing-nrf24l01-radios-require.html
* to understand how to avoid using malformed addresses. This address
* restoration is implemented because of the underlying necessary
* functionality of openWritingPipe().
* @endparblock
*
* @param number Which pipe to open. Only pipe numbers 0-5 are available,
* an address assigned to any pipe number not in that range will be ignored.
* @param address The 24, 32 or 40 bit address of the pipe to open.
*
* There is no address length parameter because this function will
* always write the number of bytes (for pipes 0 and 1) that the radio
* addresses are configured to use (set with setAddressWidth()).
*/
void openReadingPipe(uint8_t number, const uint8_t* address);
/**@}*/
/**
* @name Advanced Operation
*
* Methods you can use to drive the chip in more advanced ways
*/
/**@{*/
/**
* Print a giant block of debugging information to stdout
*
* @warning Does nothing if stdout is not defined. See fdevopen in stdio.h
* The printf.h file is included with the library for Arduino.
* @code
* #include <printf.h>
* setup(){
* Serial.begin(115200);
* printf_begin();
* ...
* }
* @endcode
*/
void printDetails(void);
/**
* Print a giant block of debugging information to stdout. This function
* differs from printDetails() because it makes the information more
* understandable without having to look up the datasheet or convert
* hexadecimal to binary. Only use this function if your application can
* spare extra bytes of memory.
*
* @warning Does nothing if stdout is not defined. See fdevopen in stdio.h
* The printf.h file is included with the library for Arduino.
* @code
* #include <printf.h>
* setup(){
* Serial.begin(115200);
* printf_begin();
* // ...
* }
* @endcode
*
* @note If the automatic acknowledgements feature is configured differently
* for each pipe, then a binary representation is used in which bits 0-5
* represent pipes 0-5 respectively. A `0` means the feature is disabled, and
* a `1` means the feature is enabled.
*/
void printPrettyDetails(void);
/**
* Put a giant block of debugging information in a char array. This function
* differs from printPrettyDetails() because it uses `sprintf()` and does not use
* a predefined output stream (like `Serial` or stdout). Only use this function if
* your application can spare extra bytes of memory. This can also be used for boards that
* do not support `printf()` (which is required for printDetails() and printPrettyDetails()).
*
* @remark
* The C standard function [sprintf()](http://www.cplusplus.com/reference/cstdio/sprintf)
* formats a C-string in the exact same way as `printf()` but outputs (by reference)
* into a char array. The formatted string literal for sprintf() is stored
* in nonvolatile program memory.
*
* @warning Use a buffer of sufficient size for the `debugging_information`. Start
* with a char array that has at least 870 elements. There is no overflow protection when using
* sprintf(), so the output buffer must be sized correctly or the resulting behavior will
* be undefined.
* @code
* char buffer[870] = {'\0'};
* uint16_t used_chars = radio.sprintfPrettyDetails(buffer);
* Serial.println(buffer);
* Serial.print(F("strlen = "));
* Serial.println(used_chars + 1); // +1 for c-strings' null terminating byte
* @endcode
*
* @param debugging_information The c-string buffer that the debugging
* information is stored to. This must be allocated to a minimum of 870 bytes of memory.
* @returns The number of characters altered in the given buffer. Remember that,
* like `sprintf()`, this returned number does not include the null terminating byte.
*
* This function is available in the python wrapper, but it accepts no parameters and
* returns a string. It does not return the number of characters in the string.
* @code{.py}
* debug_info = radio.sprintfPrettyDetails()
* print(debug_info)
* print("str_len =", len(debug_info))
* @endcode
*
* @note If the automatic acknowledgements feature is configured differently
* for each pipe, then a binary representation is used in which bits 0-5
* represent pipes 0-5 respectively. A `0` means the feature is disabled, and
* a `1` means the feature is enabled.
*/
uint16_t sprintfPrettyDetails(char* debugging_information);
/**
* Encode radio debugging information into an array of uint8_t. This function
* differs from other debug output methods because the debug information can
* be decoded by an external program.
*
* This function is not available in the python wrapper because it is intended for
* use on processors with very limited available resources.
*
* @remark
* This function uses much less ram than other `*print*Details()` methods.
*
* @code
* uint8_t encoded_details[43] = {0};
* radio.encodeRadioDetails(encoded_details);
* @endcode
*
* @param encoded_status The uint8_t array that RF24 radio details are
* encoded into. This array must be at least 43 bytes in length; any less would surely
* cause undefined behavior.
*
* Registers names and/or data corresponding to the index of the `encoded_details` array:
* | index | register/data |
* |------:|:--------------|
* | 0 | NRF_CONFIG |
* | 1 | EN_AA |
* | 2 | EN_RXADDR |
* | 3 | SETUP_AW |
* | 4 | SETUP_RETR |
* | 5 | RF_CH |
* | 6 | RF_SETUP |
* | 7 | NRF_STATUS |
* | 8 | OBSERVE_TX |
* | 9 | CD (aka RPD) |
* | 10-14 | RX_ADDR_P0 |
* | 15-19 | RX_ADDR_P1 |
* | 20 | RX_ADDR_P2 |
* | 21 | RX_ADDR_P3 |
* | 22 | RX_ADDR_P4 |
* | 23 | RX_ADDR_P5 |
* | 24-28 | TX_ADDR |
* | 29 | RX_PW_P0 |
* | 30 | RX_PW_P1 |
* | 31 | RX_PW_P2 |
* | 32 | RX_PW_P3 |
* | 33 | RX_PW_P4 |
* | 34 | RX_PW_P5 |
* | 35 | FIFO_STATUS |
* | 36 | DYNPD |
* | 37 | FEATURE |
* | 38-39 | ce_pin |
* | 40-41 | csn_pin |
* | 42 | SPI speed (in MHz) or'd with (isPlusVariant << 4) |
*/
void encodeRadioDetails(uint8_t* encoded_status);
/**
* Test whether there are bytes available to be read from the
* FIFO buffers.
*
* @note This function is named `available_pipe()` in the python wrapper.
* @parblock
* Additionally, the `available_pipe()` function (which
* takes no arguments) returns a 2 item tuple containing (ordered by
* tuple's indices):
* - A boolean describing if there is a payload available to read from
* the RX FIFO buffers.
* - The pipe number that received the next available payload in the RX
* FIFO buffers. If the item at the tuple's index 0 is `False`, then
* this pipe number is invalid.
*
* To use this function in python:
* @code{.py}
* # let `radio` be the instantiated RF24 object
* has_payload, pipe_number = radio.available_pipe() # expand the tuple to 2 variables
* if has_payload:
* print("Received a payload with pipe", pipe_number)
* @endcode
* @endparblock
*
* @param[out] pipe_num Which pipe has the payload available
* @code
* uint8_t pipeNum;
* if(radio.available(&pipeNum)){
* radio.read(&data, sizeof(data));
* Serial.print("Received data on pipe ");
* Serial.println(pipeNum);
* }
* @endcode
*
* @warning According to the datasheet, the data saved to `pipe_num` is
* "unreliable" during a FALLING transition on the IRQ pin. This means you
* should call whatHappened() before calling this function during
* an ISR (Interrupt Service Routine). For example:
* @code
* void isrCallbackFunction() {
* bool tx_ds, tx_df, rx_dr;
* radio.whatHappened(tx_ds, tx_df, rx_dr); // resets the IRQ pin to HIGH
* uint8_t pipe; // initialize pipe data
* radio.available(&pipe); // pipe data should now be reliable
* }
*
* void setup() {
* pinMode(IRQ_PIN, INPUT);
* attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING);
* }
* @endcode
*
* @return
* - `true` if there is a payload available in the top (first out)
* level RX FIFO.
* - `false` if there is nothing available in the RX FIFO because it is
* empty.
*/
bool available(uint8_t* pipe_num);
/**
* Use this function to check if the radio's RX FIFO levels are all
* occupied. This can be used to prevent data loss because any incoming
* transmissions are rejected if there is no unoccupied levels in the RX
* FIFO to store the incoming payload. Remember that each level can hold
* up to a maximum of 32 bytes.
* @return
* - `true` if all three 3 levels of the RX FIFO buffers are occupied.
* - `false` if there is one or more levels available in the RX FIFO
* buffers. Remember that this does not always mean that the RX FIFO
* buffers are empty; use available() to see if the RX FIFO buffers are
* empty or not.
*/
bool rxFifoFull();
/**
* @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO
* @return
* - `0` if the specified FIFO is neither full nor empty.
* - `1` if the specified FIFO is empty.
* - `2` if the specified FIFO is full.
*/
uint8_t isFifo(bool about_tx);
/**
* @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO
* @param check_empty
* - `true` checks if the specified FIFO is empty
* - `false` checks is the specified FIFO is full.
* @return A boolean answer to the question "is the [TX/RX] FIFO [empty/full]?"
*/
bool isFifo(bool about_tx, bool check_empty);
/**
* Enter low-power mode
*
* To return to normal power mode, call powerUp().
*
* @note After calling startListening(), a basic radio will consume about 13.5mA
* at max PA level.
* During active transmission, the radio will consume about 11.5mA, but this will
* be reduced to 26uA (.026mA) between sending.
* In full powerDown mode, the radio will consume approximately 900nA (.0009mA)
*
* @code
* radio.powerDown();
* avr_enter_sleep_mode(); // Custom function to sleep the device
* radio.powerUp();
* @endcode
*/
void powerDown(void);
/**
* Leave low-power mode - required for normal radio operation after calling powerDown()
*
* To return to low power mode, call powerDown().
* @note This will take up to 5ms for maximum compatibility
*/
void powerUp(void);
/**
* Write for single NOACK writes. Optionally disable
* acknowledgements/auto-retries for a single payload using the
* multicast parameter set to true.
*
* Can be used with enableAckPayload() to request a response
* @see
* - setAutoAck()
* - write()
*
* @param buf Pointer to the data to be sent
* @param len Number of bytes to be sent
* @param multicast Request ACK response (false), or no ACK response
* (true). Be sure to have called enableDynamicAck() at least once before
* setting this parameter.
* @return
* - `true` if the payload was delivered successfully and an acknowledgement
* (ACK packet) was received. If auto-ack is disabled, then any attempt
* to transmit will also return true (even if the payload was not
* received).
* - `false` if the payload was sent but was not acknowledged with an ACK
* packet. This condition can only be reported if the auto-ack feature
* is on.
*
* @note The `len` parameter must be omitted when using the python
* wrapper because the length of the payload is determined automatically.
* To use this function in the python wrapper:
* @code{.py}
* # let `radio` be the instantiated RF24 object
* buffer = b"Hello World" # a `bytes` object
* radio.write(buffer, False) # False = the multicast parameter
* @endcode
*/
bool write(const void* buf, uint8_t len, const bool multicast);
/**
* This will not block until the 3 FIFO buffers are filled with data.
* Once the FIFOs are full, writeFast() will simply wait for a buffer to
* become available or a transmission failure (returning `true` or `false`
* respectively).
*
* @warning
* @parblock
* It is important to never keep the nRF24L01 in TX mode and FIFO full for more than 4ms at a time. If the auto
* retransmit is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO
* to clear by issuing txStandBy() or ensure appropriate time between transmissions.
*
* Use txStandBy() when this function returns `false`.
*
* Example (Partial blocking):
* @code
* radio.writeFast(&buf,32); // Writes 1 payload to the buffers
* txStandBy(); // Returns 0 if failed. 1 if success. Blocks only until MAX_RT timeout or success. Data flushed on fail.
*
* radio.writeFast(&buf,32); // Writes 1 payload to the buffers
* txStandBy(1000); // Using extended timeouts, returns 1 if success. Retries failed payloads for 1 seconds before returning 0.
* @endcode
* @endparblock
*
* @see
* - setAutoAck()
* - txStandBy()
* - write()
* - writeBlocking()
*
* @param buf Pointer to the data to be sent
* @param len Number of bytes to be sent
* @return
* - `true` if the payload passed to `buf` was loaded in the TX FIFO.
* - `false` if the payload passed to `buf` was not loaded in the TX FIFO
* because a previous payload already in the TX FIFO failed to
* transmit. This condition can only be reported if the auto-ack feature
* is on.
*
* @note The `len` parameter must be omitted when using the python
* wrapper because the length of the payload is determined automatically.
* To use this function in the python wrapper:
* @code{.py}
* # let `radio` be the instantiated RF24 object
* buffer = b"Hello World" # a `bytes` object
* radio.writeFast(buffer)
* @endcode
*/
bool writeFast(const void* buf, uint8_t len);
/**
* Similar to writeFast(const void*, uint8_t) but allows for single NOACK writes.
* Optionally disable acknowledgements/auto-retries for a single payload using the
* multicast parameter set to `true`.
*
* @warning If the auto-ack feature is enabled, then it is strongly encouraged to call
* txStandBy() when this function returns `false`.
*
* @see
* - setAutoAck()
* - txStandBy()
* - write()
* - writeBlocking()
*
* @param buf Pointer to the data to be sent
* @param len Number of bytes to be sent
* @param multicast Request ACK response (false), or no ACK response
* (true). Be sure to have called enableDynamicAck() at least once before
* setting this parameter.
* @return
* - `true` if the payload passed to `buf` was loaded in the TX FIFO.
* - `false` if the payload passed to `buf` was not loaded in the TX FIFO
* because a previous payload already in the TX FIFO failed to
* transmit. This condition can only be reported if the auto-ack feature
* is on (and the multicast parameter is set to false).
*
* @note The `len` parameter must be omitted when using the python
* wrapper because the length of the payload is determined automatically.
* To use this function in the python wrapper:
* @code{.py}
* # let `radio` be the instantiated RF24 object
* buffer = b"Hello World" # a `bytes` object
* radio.writeFast(buffer, False) # False = the multicast parameter
* @endcode
*/
bool writeFast(const void* buf, uint8_t len, const bool multicast);
/**
* This function extends the auto-retry mechanism to any specified duration.
* It will not block until the 3 FIFO buffers are filled with data.
* If so the library will auto retry until a new payload is written
* or the user specified timeout period is reached.
* @warning It is important to never keep the nRF24L01 in TX mode and FIFO full for more than 4ms at a time. If the auto
* retransmit is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO
* to clear by issuing txStandBy() or ensure appropriate time between transmissions.
*
* Example (Full blocking):
* @code
* radio.writeBlocking(&buf, sizeof(buf), 1000); // Wait up to 1 second to write 1 payload to the buffers
* radio.txStandBy(1000); // Wait up to 1 second for the payload to send. Return 1 if ok, 0 if failed.
* // Blocks only until user timeout or success. Data flushed on fail.