Optimized high speed nRF24L01+ driver class documentation v1.5.0
TMRh20 2020 - Optimized fork of the nRF24L01+ driver
Loading...
Searching...
No Matches
RF24.h
Go to the documentation of this file.
1/*
2 Copyright (C) 2011 J. Coliz <maniacbug@ymail.com>
3
4 This program is free software; you can redistribute it and/or
5 modify it under the terms of the GNU General Public License
6 version 2 as published by the Free Software Foundation.
7 */
8
14
15#ifndef RF24_H_
16#define RF24_H_
17
18#include "RF24_config.h"
19
20#if defined(RF24_LINUX) || defined(LITTLEWIRE)
21 #include "utility/includes.h"
22#elif defined SOFTSPI
23 #include <DigitalIO.h>
24#endif
25
70
89
110
130
136
140typedef enum
141{
142#include "nRF24L01.h"
144 RF24_IRQ_NONE = 0,
146 RF24_TX_DF = 1 << MASK_MAX_RT,
148 RF24_TX_DS = 1 << TX_DS,
150 RF24_RX_DR = 1 << RX_DR,
152 RF24_IRQ_ALL = (1 << MASK_MAX_RT) | (1 << TX_DS) | (1 << RX_DR),
154
159class RF24
160{
161private:
162#ifdef SOFTSPI
163 SoftSPI<SOFT_SPI_MISO_PIN, SOFT_SPI_MOSI_PIN, SOFT_SPI_SCK_PIN, SPI_MODE> spi;
164#elif defined(SPI_UART)
165 SPIUARTClass uspi;
166#endif
167
168#if defined(RF24_LINUX) || defined(XMEGA_D3) /* XMEGA can use SPI class */
169 SPI spi;
170#endif // defined (RF24_LINUX) || defined (XMEGA_D3)
171#if defined(RF24_SPI_PTR)
172 _SPI* _spi;
173#endif // defined (RF24_SPI_PTR)
175 rf24_gpio_pin_t ce_pin; /* "Chip Enable" pin, activates the RX or TX role */
176 rf24_gpio_pin_t csn_pin; /* SPI Chip select */
177 uint32_t spi_speed; /* SPI Bus Speed */
178#if defined(RF24_LINUX) || defined(XMEGA_D3) || defined(RF24_RP2)
179 uint8_t spi_rxbuff[32 + 1]; //SPI receive buffer (payload max 32 bytes)
180 uint8_t spi_txbuff[32 + 1]; //SPI transmit buffer (payload max 32 bytes + 1 byte for the command)
181#endif
182 uint8_t status; /* The status byte returned from every SPI transaction */
183 uint8_t payload_size; /* Fixed size of payloads */
184 uint8_t pipe0_reading_address[5]; /* Last address set on pipe 0 for reading. */
185 uint8_t pipe0_writing_address[5]; /* Last address set on pipe 0 for writing. */
186 uint8_t config_reg; /* For storing the value of the NRF_CONFIG register */
187 bool _is_p_variant; /* For storing the result of testing the toggleFeatures() affect */
188 bool _is_p0_rx; /* For keeping track of pipe 0's usage in user-triggered RX mode. */
190protected:
197 inline void beginTransaction();
199 inline void endTransaction();
204 uint8_t addr_width;
217 void read_register(uint8_t reg, uint8_t* buf, uint8_t len);
225 uint8_t read_register(uint8_t reg);
227public:
255 RF24(rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin, uint32_t _spi_speed = RF24_SPI_SPEED);
267 RF24(uint32_t _spi_speed = RF24_SPI_SPEED);
269#if defined(RF24_LINUX)
270 virtual ~RF24() {};
271#endif
272
287 bool begin(void);
288
289#if defined(RF24_SPI_PTR) || defined(DOXYGEN_FORCED)
305 bool begin(_SPI* spiBus);
306
329 bool begin(_SPI* spiBus, rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin);
330#endif // defined (RF24_SPI_PTR) || defined (DOXYGEN_FORCED)
331
341 bool begin(rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin);
342
346 bool isChipConnected();
347
368 void startListening(void);
369
383 void stopListening(void);
384
390 void stopListening(const uint8_t* txAddress);
391
423 bool available(void);
424
481 void read(void* buf, uint8_t len);
482
523 bool write(const void* buf, uint8_t len);
524
571
572 void openWritingPipe(const uint8_t* address);
573
618 void openReadingPipe(uint8_t number, const uint8_t* address);
619
627
642 void ce(bool level);
643
658 void printDetails(void);
659
668 void printStatus(uint8_t flags);
669
693 void printPrettyDetails(void);
694
738 uint16_t sprintfPrettyDetails(char* debugging_information);
739
793 void encodeRadioDetails(uint8_t* encoded_status);
794
852 bool available(uint8_t* pipe_num);
853
867 bool rxFifoFull();
868
877 rf24_fifo_state_e isFifo(bool about_tx);
878
889 bool isFifo(bool about_tx, bool check_empty);
890
908 void powerDown(void);
909
916 void powerUp(void);
917
951 bool write(const void* buf, uint8_t len, const bool multicast);
952
1001 bool writeFast(const void* buf, uint8_t len);
1002
1038 bool writeFast(const void* buf, uint8_t len, const bool multicast);
1039
1081 bool writeBlocking(const void* buf, uint8_t len, uint32_t timeout);
1082
1114 bool txStandBy();
1115
1141 bool txStandBy(uint32_t timeout, bool startTx = 0);
1142
1187 bool writeAckPayload(uint8_t pipe, const void* buf, uint8_t len);
1188
1209 uint8_t clearStatusFlags(uint8_t flags = RF24_IRQ_ALL);
1210
1227 void setStatusFlags(uint8_t flags = RF24_IRQ_NONE);
1228
1241 uint8_t getStatusFlags();
1242
1251 uint8_t update();
1252
1291 void startFastWrite(const void* buf, uint8_t len, const bool multicast, bool startTx = 1);
1292
1326 bool startWrite(const void* buf, uint8_t len, const bool multicast);
1327
1358 void reUseTX();
1359
1367 uint8_t flush_tx(void);
1368
1374 uint8_t flush_rx(void);
1375
1384 bool testCarrier(void);
1385
1404 bool testRPD(void);
1405
1413 bool isValid();
1414
1421 void closeReadingPipe(uint8_t pipe);
1422
1423#if defined(FAILURE_HANDLING)
1455#endif // defined (FAILURE_HANDLING)
1456
1466
1473 void setAddressWidth(uint8_t a_width);
1474
1490 void setRetries(uint8_t delay, uint8_t count);
1491
1508 void setChannel(uint8_t channel);
1509
1522 uint8_t getChannel(void);
1523
1541 void setPayloadSize(uint8_t size);
1542
1557 uint8_t getPayloadSize(void);
1558
1579 uint8_t getDynamicPayloadSize(void);
1580
1600 void enableAckPayload(void);
1601
1607 void disableAckPayload(void);
1608
1616 void enableDynamicPayloads(void);
1617
1627 void disableDynamicPayloads(void);
1628
1647 void enableDynamicAck();
1648
1655 bool isPVariant(void);
1656
1687 void setAutoAck(bool enable);
1688
1727 void setAutoAck(uint8_t pipe, bool enable);
1728
1746 void setPALevel(uint8_t level, bool lnaEnable = 1);
1747
1754 uint8_t getPALevel(void);
1755
1763 uint8_t getARC(void);
1764
1781 bool setDataRate(rf24_datarate_e speed);
1782
1790
1802 void setCRCLength(rf24_crclength_e length);
1803
1812
1818 void disableCRC(void);
1819
1831 uint32_t txDelay;
1832
1841 uint32_t csDelay;
1842
1858 void startConstCarrier(rf24_pa_dbm_e level, uint8_t channel);
1859
1874 void stopConstCarrier(void);
1875
1883 void toggleAllPipes(bool isEnabled);
1884
1894 void setRadiation(uint8_t level, rf24_datarate_e speed, bool lnaEnable = true);
1895
1903
1928 void openReadingPipe(uint8_t number, uint64_t address);
1929
1944 void openWritingPipe(uint64_t address);
1945
1956 bool isAckPayloadAvailable(void);
1957
1993 void maskIRQ(bool tx_ok, bool tx_fail, bool rx_ready);
1994
2028 void whatHappened(bool& tx_ok, bool& tx_fail, bool& rx_ready);
2029
2039 void stopListening(const uint64_t txAddress);
2040
2041private:
2051
2056 void _init_obj();
2057
2063 bool _init_radio();
2064
2068 bool _init_pins();
2069
2080 void csn(bool mode);
2081
2091 void write_register(uint8_t reg, const uint8_t* buf, uint8_t len);
2092
2101 void write_register(uint8_t reg, uint8_t value);
2102
2114 void write_payload(const void* buf, uint8_t len, const uint8_t writeType);
2115
2126 void read_payload(void* buf, uint8_t len);
2127
2128#if !defined(MINIMAL)
2129
2137 void print_observe_tx(uint8_t value);
2138
2150 void print_byte_register(const char* name, uint8_t reg, uint8_t qty = 1);
2151
2163 void print_address_register(const char* name, uint8_t reg, uint8_t qty = 1);
2164
2177 uint8_t sprintf_address_register(char* out_buffer, uint8_t reg, uint8_t qty = 1);
2178#endif
2179
2186 void toggle_features(void);
2187
2188#if defined(FAILURE_HANDLING) || defined(RF24_LINUX)
2189
2190 void errNotify(void);
2191
2192#endif
2193
2200 inline uint8_t _data_rate_reg_value(rf24_datarate_e speed);
2201
2209 inline uint8_t _pa_level_reg_value(uint8_t level, bool lnaEnable);
2210
2212};
2213
2223
2234
2250
2260
2273
2286
2295
2308
2318
2328
2352
2371
2377
2392
2408
2427
2443
2459
2476
2489
2500
2512
2523
2539
2549
2562
2563#endif // RF24_H_
#define RF24_SPI_SPEED
The default SPI speed (in Hz)
Definition RF24_config.h:44
Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver.
Definition RF24.h:160
void disableAckPayload(void)
Definition RF24.cpp:1793
RF24(rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin, uint32_t _spi_speed=RF24_SPI_SPEED)
Definition RF24.cpp:560
uint16_t sprintfPrettyDetails(char *debugging_information)
Definition RF24.cpp:836
bool begin(void)
Definition RF24.cpp:973
uint8_t getPayloadSize(void)
Definition RF24.cpp:639
bool available(void)
Definition RF24.cpp:1532
bool txStandBy()
Definition RF24.cpp:1443
void endTransaction()
Definition RF24.cpp:135
bool failureDetected
Definition RF24.h:1454
void startListening(void)
Definition RF24.cpp:1144
bool isAckPayloadAvailable(void)
Definition RF24.cpp:1833
void ce(bool level)
Definition RF24.cpp:103
void printPrettyDetails(void)
Definition RF24.cpp:739
void setPayloadSize(uint8_t size)
Definition RF24.cpp:626
bool isValid()
Definition RF24.cpp:1137
bool writeAckPayload(uint8_t pipe, const void *buf, uint8_t len)
Definition RF24.cpp:1820
void stopConstCarrier(void)
Definition RF24.cpp:2050
rf24_fifo_state_e isFifo(bool about_tx)
Definition RF24.cpp:1428
bool dynamic_payloads_enabled
Definition RF24.h:206
void enableDynamicPayloads(void)
Definition RF24.cpp:1734
bool writeFast(const void *buf, uint8_t len)
Definition RF24.cpp:1376
void disableDynamicPayloads(void)
Definition RF24.cpp:1754
void setRetries(uint8_t delay, uint8_t count)
Definition RF24.cpp:2010
bool write(const void *buf, uint8_t len)
Definition RF24.cpp:1291
uint8_t getARC(void)
Definition RF24.cpp:1912
uint8_t flush_rx(void)
Definition RF24.cpp:469
void beginTransaction()
Definition RF24.cpp:117
void powerUp(void)
Definition RF24.cpp:1222
void setChannel(uint8_t channel)
Definition RF24.cpp:613
void disableCRC(void)
Definition RF24.cpp:2003
void enableDynamicAck()
Definition RF24.cpp:1807
bool isPVariant(void)
Definition RF24.cpp:1840
uint8_t getDynamicPayloadSize(void)
Definition RF24.cpp:1519
bool ack_payloads_enabled
Definition RF24.h:202
uint8_t getChannel(void)
Definition RF24.cpp:619
void stopListening(void)
Definition RF24.cpp:1168
rf24_datarate_e getDataRate(void)
Definition RF24.cpp:1939
bool testRPD(void)
Definition RF24.cpp:1889
void setCRCLength(rf24_crclength_e length)
Definition RF24.cpp:1963
void read(void *buf, uint8_t len)
Definition RF24.cpp:1550
uint32_t txDelay
Definition RF24.h:1831
void closeReadingPipe(uint8_t pipe)
Definition RF24.cpp:1708
void read_register(uint8_t reg, uint8_t *buf, uint8_t len)
Definition RF24.cpp:149
void openReadingPipe(uint8_t number, const uint8_t *address)
Definition RF24.cpp:1679
void powerDown(void)
Definition RF24.cpp:1212
void toggleAllPipes(bool isEnabled)
Open or close all data pipes.
Definition RF24.cpp:2070
uint8_t addr_width
Definition RF24.h:204
void setPALevel(uint8_t level, bool lnaEnable=1)
Definition RF24.cpp:1896
rf24_crclength_e getCRCLength(void)
Definition RF24.cpp:1983
void encodeRadioDetails(uint8_t *encoded_status)
Definition RF24.cpp:919
void maskIRQ(bool tx_ok, bool tx_fail, bool rx_ready)
Definition RF24.cpp:1508
void enableAckPayload(void)
Definition RF24.cpp:1775
bool isChipConnected()
Definition RF24.cpp:1130
void startConstCarrier(rf24_pa_dbm_e level, uint8_t channel)
Definition RF24.cpp:2016
void startFastWrite(const void *buf, uint8_t len, const bool multicast, bool startTx=1)
Definition RF24.cpp:1388
uint32_t csDelay
Definition RF24.h:1841
bool testCarrier(void)
Definition RF24.cpp:1882
bool rxFifoFull()
Definition RF24.cpp:1421
void setAddressWidth(uint8_t a_width)
Definition RF24.cpp:1664
void setRadiation(uint8_t level, rf24_datarate_e speed, bool lnaEnable=true)
configure the RF_SETUP register in 1 transaction
Definition RF24.cpp:2120
uint8_t flush_tx(void)
Definition RF24.cpp:478
bool startWrite(const void *buf, uint8_t len, const bool multicast)
Definition RF24.cpp:1401
void printDetails(void)
Definition RF24.cpp:693
void printStatus(uint8_t flags)
Definition RF24.cpp:488
bool writeBlocking(const void *buf, uint8_t len, uint32_t timeout)
Definition RF24.cpp:1299
void reUseTX()
Definition RF24.cpp:1334
bool setDataRate(rf24_datarate_e speed)
Definition RF24.cpp:1919
void setAutoAck(bool enable)
Definition RF24.cpp:1847
void openWritingPipe(const uint8_t *address)
Definition RF24.cpp:1620
uint8_t getPALevel(void)
Definition RF24.cpp:1905
void whatHappened(bool &tx_ok, bool &tx_fail, bool &rx_ready)
Definition RF24.cpp:1562
rf24_crclength_e
Definition RF24.h:102
@ RF24_CRC_16
Definition RF24.h:108
@ RF24_CRC_DISABLED
Definition RF24.h:104
@ RF24_CRC_8
Definition RF24.h:106
rf24_datarate_e
Definition RF24.h:81
@ RF24_2MBPS
Definition RF24.h:85
@ RF24_250KBPS
Definition RF24.h:87
@ RF24_1MBPS
Definition RF24.h:83
rf24_pa_dbm_e
Definition RF24.h:36
@ RF24_PA_ERROR
Definition RF24.h:68
@ RF24_PA_MIN
Definition RF24.h:43
@ RF24_PA_LOW
Definition RF24.h:50
@ RF24_PA_MAX
Definition RF24.h:64
@ RF24_PA_HIGH
Definition RF24.h:57
#define delay(millisec)
uint16_t rf24_gpio_pin_t
#define _SPI
uint8_t clearStatusFlags(uint8_t flags=RF24_IRQ_ALL)
Definition RF24.cpp:1576
uint8_t getStatusFlags()
Definition RF24.cpp:1593
rf24_irq_flags_e
An enumeration of constants used to configure Status flags.
Definition RF24.h:141
uint8_t update()
Definition RF24.cpp:1600
void setStatusFlags(uint8_t flags=RF24_IRQ_NONE)
Definition RF24.cpp:1584
@ RF24_TX_DS
Represents an event where TX Data Sent successfully.
Definition RF24.h:277
@ RF24_IRQ_NONE
An alias of 0 to describe no IRQ events enabled.
Definition RF24.h:273
@ RF24_TX_DF
Represents an event where TX Data Failed to send.
Definition RF24.h:275
@ RF24_RX_DR
Represents an event where RX Data is Ready to RF24::read().
Definition RF24.h:279
@ RF24_IRQ_ALL
Equivalent to RF24_RX_DR | RF24_TX_DS | RF24_TX_DF.
Definition RF24.h:281
rf24_fifo_state_e
Definition RF24.h:120
@ RF24_FIFO_INVALID
Represents corruption of data over SPI (when observed).
Definition RF24.h:128
@ RF24_FIFO_FULL
The FIFO is full.
Definition RF24.h:126
@ RF24_FIFO_OCCUPIED
The FIFO is not full nor empty, but it is occupied with 1 or 2 payloads.
Definition RF24.h:122
@ RF24_FIFO_EMPTY
The FIFO is empty.
Definition RF24.h:124
#define MASK_MAX_RT
Definition nRF24L01.h:57
#define RX_DR
Definition nRF24L01.h:81
#define TX_DS
Definition nRF24L01.h:82