Optimized high speed nRF24L01+ driver class documentation  1.4.2
TMRh20 2020 - Optimized fork of the nRF24L01+ driver
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 
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 
26 
36 typedef enum {
70 
80 typedef enum {
88 
100 typedef enum {
108 
114 class RF24 {
115 private:
116  #ifdef SOFTSPI
117  SoftSPI<SOFT_SPI_MISO_PIN, SOFT_SPI_MOSI_PIN, SOFT_SPI_SCK_PIN, SPI_MODE> spi;
118  #elif defined (SPI_UART)
119  SPIUARTClass uspi;
120  #endif
121 
122  #if defined (RF24_LINUX) || defined (XMEGA_D3) || defined (RF24_RP2) /* XMEGA can use SPI class */
123  SPI spi;
124  #endif // defined (RF24_LINUX) || defined (XMEGA_D3)
125  #if defined (RF24_SPI_PTR)
126  _SPI* _spi;
127  #endif // defined (RF24_SPI_PTR)
128  #if defined (MRAA)
129  GPIO gpio;
130  #endif
131 
132  uint16_t ce_pin;
133  uint16_t csn_pin;
134  uint32_t spi_speed;
135  #if defined (RF24_LINUX) || defined (XMEGA_D3) || defined (RF24_RP2)
136  uint8_t spi_rxbuff[32+1] ; //SPI receive buffer (payload max 32 bytes)
137  uint8_t spi_txbuff[32+1] ; //SPI transmit buffer (payload max 32 bytes + 1 byte for the command)
138  #endif
139  uint8_t status;
140  uint8_t payload_size;
141  uint8_t pipe0_reading_address[5];
142  uint8_t config_reg;
143  bool _is_p_variant;
144  bool _is_p0_rx;
146 protected:
153  inline void beginTransaction();
154 
155  inline void endTransaction();
156 
158  uint8_t addr_width;
170  void read_register(uint8_t reg, uint8_t* buf, uint8_t len);
171 
178  uint8_t read_register(uint8_t reg);
179 
180 public:
181 
207  RF24(uint16_t _cepin, uint16_t _cspin, uint32_t _spi_speed = RF24_SPI_SPEED);
208 
219  RF24(uint32_t _spi_speed = RF24_SPI_SPEED);
220 
221  #if defined (RF24_LINUX)
222  virtual ~RF24() {};
223  #endif
224 
239  bool begin(void);
240 
241  #if defined (RF24_SPI_PTR) || defined (DOXYGEN_FORCED)
257  bool begin(_SPI* spiBus);
258 
279  bool begin(_SPI* spiBus, uint16_t _cepin, uint16_t _cspin);
280  #endif // defined (RF24_SPI_PTR) || defined (DOXYGEN_FORCED)
281 
291  bool begin(uint16_t _cepin, uint16_t _cspin);
292 
296  bool isChipConnected();
297 
318  void startListening(void);
319 
333  void stopListening(void);
334 
366  bool available(void);
367 
423  void read(void* buf, uint8_t len);
424 
465  bool write(const void* buf, uint8_t len);
466 
509  void openWritingPipe(const uint8_t* address);
510 
551  void openReadingPipe(uint8_t number, const uint8_t* address);
552 
575  void printDetails(void);
576 
600  void printPrettyDetails(void);
601 
657  bool available(uint8_t* pipe_num);
658 
672  bool rxFifoFull();
673 
691  void powerDown(void);
692 
699  void powerUp(void);
700 
734  bool write(const void* buf, uint8_t len, const bool multicast);
735 
780  bool writeFast(const void* buf, uint8_t len);
781 
810  bool writeFast(const void* buf, uint8_t len, const bool multicast);
811 
853  bool writeBlocking(const void* buf, uint8_t len, uint32_t timeout);
854 
886  bool txStandBy();
887 
913  bool txStandBy(uint32_t timeout, bool startTx = 0);
914 
959  bool writeAckPayload(uint8_t pipe, const void* buf, uint8_t len);
960 
991  void whatHappened(bool& tx_ok, bool& tx_fail, bool& rx_ready);
992 
1031  void startFastWrite(const void* buf, uint8_t len, const bool multicast, bool startTx = 1);
1032 
1066  bool startWrite(const void* buf, uint8_t len, const bool multicast);
1067 
1098  void reUseTX();
1099 
1107  uint8_t flush_tx(void);
1108 
1114  uint8_t flush_rx(void);
1115 
1124  bool testCarrier(void);
1125 
1144  bool testRPD(void);
1145 
1153  bool isValid();
1154 
1161  void closeReadingPipe(uint8_t pipe);
1162 
1163  #if defined (FAILURE_HANDLING)
1194  #endif // defined (FAILURE_HANDLING)
1195 
1212  void setAddressWidth(uint8_t a_width);
1213 
1229  void setRetries(uint8_t delay, uint8_t count);
1230 
1247  void setChannel(uint8_t channel);
1248 
1261  uint8_t getChannel(void);
1262 
1280  void setPayloadSize(uint8_t size);
1281 
1296  uint8_t getPayloadSize(void);
1297 
1318  uint8_t getDynamicPayloadSize(void);
1319 
1339  void enableAckPayload(void);
1340 
1346  void disableAckPayload(void);
1347 
1355  void enableDynamicPayloads(void);
1356 
1366  void disableDynamicPayloads(void);
1367 
1386  void enableDynamicAck();
1387 
1394  bool isPVariant(void);
1395 
1426  void setAutoAck(bool enable);
1427 
1466  void setAutoAck(uint8_t pipe, bool enable);
1467 
1485  void setPALevel(uint8_t level, bool lnaEnable = 1);
1486 
1493  uint8_t getPALevel(void);
1494 
1502  uint8_t getARC(void);
1503 
1520  bool setDataRate(rf24_datarate_e speed);
1521 
1529 
1540  void setCRCLength(rf24_crclength_e length);
1541 
1549 
1555  void disableCRC(void);
1556 
1587  void maskIRQ(bool tx_ok, bool tx_fail, bool rx_ready);
1588 
1600  uint32_t txDelay;
1601 
1610  uint32_t csDelay;
1611 
1627  void startConstCarrier(rf24_pa_dbm_e level, uint8_t channel);
1628 
1643  void stopConstCarrier(void);
1644 
1652  void toggleAllPipes(bool isEnabled);
1653 
1663  void setRadiation(uint8_t level, rf24_datarate_e speed, bool lnaEnable = true);
1664 
1692  void openReadingPipe(uint8_t number, uint64_t address);
1693 
1707  void openWritingPipe(uint64_t address);
1708 
1718  bool isAckPayloadAvailable(void);
1719 
1720 private:
1721 
1736  void _init_obj();
1737 
1743  bool _init_radio();
1744 
1748  bool _init_pins();
1749 
1760  void csn(bool mode);
1761 
1768  void ce(bool level);
1769 
1779  void write_register(uint8_t reg, const uint8_t* buf, uint8_t len);
1780 
1791  void write_register(uint8_t reg, uint8_t value, bool is_cmd_only = false);
1792 
1804  void write_payload(const void* buf, uint8_t len, const uint8_t writeType);
1805 
1816  void read_payload(void* buf, uint8_t len);
1817 
1823  uint8_t get_status(void);
1824 
1825  #if !defined (MINIMAL)
1826 
1834  void print_status(uint8_t status);
1835 
1843  void print_observe_tx(uint8_t value);
1844 
1856  void print_byte_register(const char* name, uint8_t reg, uint8_t qty = 1);
1857 
1869  void print_address_register(const char* name, uint8_t reg, uint8_t qty = 1);
1870 
1871  #endif
1872 
1879  void toggle_features(void);
1880 
1881  #if defined (FAILURE_HANDLING) || defined (RF24_LINUX)
1882 
1883  void errNotify(void);
1884 
1885  #endif
1886 
1893  inline uint8_t _data_rate_reg_value(rf24_datarate_e speed);
1894 
1902  inline uint8_t _pa_level_reg_value(uint8_t level, bool lnaEnable);
1903 
1906 };
1907 
1908 
2258 #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:114
void disableAckPayload(void)
Definition: RF24.cpp:1571
bool begin(void)
Definition: RF24.cpp:820
uint8_t getPayloadSize(void)
Definition: RF24.cpp:586
RF24(uint16_t _cepin, uint16_t _cspin, uint32_t _spi_speed=RF24_SPI_SPEED)
Definition: RF24.cpp:527
bool available(void)
Definition: RF24.cpp:1346
bool txStandBy()
Definition: RF24.cpp:1255
void endTransaction()
Definition: RF24.cpp:132
bool failureDetected
Definition: RF24.h:1193
void startListening(void)
Definition: RF24.cpp:998
bool isAckPayloadAvailable(void)
Definition: RF24.cpp:1611
void printPrettyDetails(void)
Definition: RF24.cpp:697
void setPayloadSize(uint8_t size)
Definition: RF24.cpp:574
bool isValid()
Definition: RF24.cpp:991
bool writeAckPayload(uint8_t pipe, const void *buf, uint8_t len)
Definition: RF24.cpp:1598
void stopConstCarrier(void)
Definition: RF24.cpp:1824
bool dynamic_payloads_enabled
Definition: RF24.h:159
void enableDynamicPayloads(void)
Definition: RF24.cpp:1513
bool writeFast(const void *buf, uint8_t len)
Definition: RF24.cpp:1208
void disableDynamicPayloads(void)
Definition: RF24.cpp:1532
void setRetries(uint8_t delay, uint8_t count)
Definition: RF24.cpp:1783
bool write(const void *buf, uint8_t len)
Definition: RF24.cpp:1124
uint8_t getARC(void)
Definition: RF24.cpp:1689
uint8_t flush_rx(void)
Definition: RF24.cpp:443
void beginTransaction()
Definition: RF24.cpp:114
void powerUp(void)
Definition: RF24.cpp:1055
void setChannel(uint8_t channel)
Definition: RF24.cpp:561
void disableCRC(void)
Definition: RF24.cpp:1776
void enableDynamicAck()
Definition: RF24.cpp:1585
bool isPVariant(void)
Definition: RF24.cpp:1618
uint8_t getDynamicPayloadSize(void)
Definition: RF24.cpp:1332
bool ack_payloads_enabled
Definition: RF24.h:157
uint8_t getChannel(void)
Definition: RF24.cpp:567
void stopListening(void)
Definition: RF24.cpp:1020
rf24_datarate_e getDataRate(void)
Definition: RF24.cpp:1717
bool testRPD(void)
Definition: RF24.cpp:1665
void setCRCLength(rf24_crclength_e length)
Definition: RF24.cpp:1739
void read(void *buf, uint8_t len)
Definition: RF24.cpp:1369
uint32_t txDelay
Definition: RF24.h:1600
void closeReadingPipe(uint8_t pipe)
Definition: RF24.cpp:1487
void read_register(uint8_t reg, uint8_t *buf, uint8_t len)
Definition: RF24.cpp:146
void openReadingPipe(uint8_t number, const uint8_t *address)
Definition: RF24.cpp:1460
void powerDown(void)
Definition: RF24.cpp:1045
void toggleAllPipes(bool isEnabled)
Open or close all data pipes.
Definition: RF24.cpp:1839
uint8_t addr_width
Definition: RF24.h:158
void setPALevel(uint8_t level, bool lnaEnable=1)
Definition: RF24.cpp:1672
rf24_crclength_e getCRCLength(void)
Definition: RF24.cpp:1757
void maskIRQ(bool tx_ok, bool tx_fail, bool rx_ready)
Definition: RF24.cpp:1321
void enableAckPayload(void)
Definition: RF24.cpp:1553
bool isChipConnected()
Definition: RF24.cpp:984
void startConstCarrier(rf24_pa_dbm_e level, uint8_t channel)
Definition: RF24.cpp:1789
void startFastWrite(const void *buf, uint8_t len, const bool multicast, bool startTx=1)
Definition: RF24.cpp:1220
uint32_t csDelay
Definition: RF24.h:1610
bool testCarrier(void)
Definition: RF24.cpp:1658
bool rxFifoFull()
Definition: RF24.cpp:1248
void setAddressWidth(uint8_t a_width)
Definition: RF24.cpp:1445
void setRadiation(uint8_t level, rf24_datarate_e speed, bool lnaEnable=true)
configure the RF_SETUP register in 1 transaction
Definition: RF24.cpp:1890
uint8_t flush_tx(void)
Definition: RF24.cpp:451
bool startWrite(const void *buf, uint8_t len, const bool multicast)
Definition: RF24.cpp:1233
void printDetails(void)
Definition: RF24.cpp:653
bool writeBlocking(const void *buf, uint8_t len, uint32_t timeout)
Definition: RF24.cpp:1131
void reUseTX()
Definition: RF24.cpp:1167
bool setDataRate(rf24_datarate_e speed)
Definition: RF24.cpp:1697
void setAutoAck(bool enable)
Definition: RF24.cpp:1625
void openWritingPipe(const uint8_t *address)
Definition: RF24.cpp:1406
uint8_t getPALevel(void)
Definition: RF24.cpp:1681
void whatHappened(bool &tx_ok, bool &tx_fail, bool &rx_ready)
Definition: RF24.cpp:1382
rf24_crclength_e
Definition: RF24.h:100
@ RF24_CRC_16
Definition: RF24.h:106
@ RF24_CRC_DISABLED
Definition: RF24.h:102
@ RF24_CRC_8
Definition: RF24.h:104
rf24_datarate_e
Definition: RF24.h:80
@ RF24_2MBPS
Definition: RF24.h:84
@ RF24_250KBPS
Definition: RF24.h:86
@ RF24_1MBPS
Definition: RF24.h:82
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
GPIO()
#define delay(milisec)
#define _SPI