| 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 | |
| 9 | /** |
| 10 | * @file RF24.h |
| 11 | * |
| 12 | * Class declaration for RF24 and helper enums |
| 13 | */ |
| 14 | |
| 15 | #ifndef RF24_H_ |
| 16 | #define RF24_H_ |
| 17 | |
| 18 | #include "RF24_config.h" |
| 19 | #include "nRF24L01.h" |
| 20 | |
| 21 | #if defined(RF24_LINUX) || defined(LITTLEWIRE) |
| 22 | #include "utility/includes.h" |
| 23 | #elif defined SOFTSPI |
| 24 | #include <DigitalIO.h> |
| 25 | #endif |
| 26 | |
| 27 | /** |
| 28 | * @defgroup PALevel Power Amplifier level |
| 29 | * Power Amplifier level. The units dBm (decibel-milliwatts or dB<sub>mW</sub>) |
| 30 | * represents a logarithmic signal loss. |
| 31 | * @see |
| 32 | * - RF24::setPALevel() |
| 33 | * - RF24::getPALevel() |
| 34 | * @{ |
| 35 | */ |
| 36 | typedef enum |
| 37 | { |
| 38 | /** |
| 39 | * (0) represents: |
| 40 | * nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0 |
| 41 | * :-------:|:-----------------------------:|:----------------------------: |
| 42 | * -18 dBm | -6 dBm | -12 dBm |
| 43 | */ |
| 44 | RF24_PA_MIN = 0, |
| 45 | /** |
| 46 | * (1) represents: |
| 47 | * nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0 |
| 48 | * :-------:|:-----------------------------:|:----------------------------: |
| 49 | * -12 dBm | 0 dBm | -4 dBm |
| 50 | */ |
| 51 | RF24_PA_LOW, |
| 52 | /** |
| 53 | * (2) represents: |
| 54 | * nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0 |
| 55 | * :-------:|:-----------------------------:|:----------------------------: |
| 56 | * -6 dBm | 3 dBm | 1 dBm |
| 57 | */ |
| 58 | RF24_PA_HIGH, |
| 59 | /** |
| 60 | * (3) represents: |
| 61 | * nRF24L01 | Si24R1 with<br>lnaEnabled = 1 | Si24R1 with<br>lnaEnabled = 0 |
| 62 | * :-------:|:-----------------------------:|:----------------------------: |
| 63 | * 0 dBm | 7 dBm | 4 dBm |
| 64 | */ |
| 65 | RF24_PA_MAX, |
| 66 | /** |
| 67 | * (4) This should not be used and remains for backward compatibility. |
| 68 | */ |
| 69 | RF24_PA_ERROR |
| 70 | } rf24_pa_dbm_e; |
| 71 | |
| 72 | /** |
| 73 | * @} |
| 74 | * @defgroup Datarate datarate |
| 75 | * How fast data moves through the air. Units are in bits per second (bps). |
| 76 | * @see |
| 77 | * - RF24::setDataRate() |
| 78 | * - RF24::getDataRate() |
| 79 | * @{ |
| 80 | */ |
| 81 | typedef enum |
| 82 | { |
| 83 | /** (0) represents 1 Mbps */ |
| 84 | RF24_1MBPS = 0, |
| 85 | /** (1) represents 2 Mbps */ |
| 86 | RF24_2MBPS, |
| 87 | /** (2) represents 250 kbps */ |
| 88 | RF24_250KBPS |
| 89 | } rf24_datarate_e; |
| 90 | |
| 91 | /** |
| 92 | * @} |
| 93 | * @defgroup CRCLength CRC length |
| 94 | * The length of a CRC checksum that is used (if any). Cyclical Redundancy |
| 95 | * Checking (CRC) is commonly used to ensure data integrity. |
| 96 | * @see |
| 97 | * - RF24::setCRCLength() |
| 98 | * - RF24::getCRCLength() |
| 99 | * - RF24::disableCRC() |
| 100 | * @{ |
| 101 | */ |
| 102 | typedef enum |
| 103 | { |
| 104 | /** (0) represents no CRC checksum is used */ |
| 105 | RF24_CRC_DISABLED = 0, |
| 106 | /** (1) represents CRC 8 bit checksum is used */ |
| 107 | RF24_CRC_8, |
| 108 | /** (2) represents CRC 16 bit checksum is used */ |
| 109 | RF24_CRC_16 |
| 110 | } rf24_crclength_e; |
| 111 | |
| 112 | /** |
| 113 | * @} |
| 114 | * @defgroup fifoState FIFO state |
| 115 | * The state of a single FIFO (RX or TX). |
| 116 | * Remember, each FIFO has a maximum occupancy of 3 payloads. |
| 117 | * @see RF24::isFifo() |
| 118 | * @{ |
| 119 | */ |
| 120 | typedef enum |
| 121 | { |
| 122 | /// @brief The FIFO is not full nor empty, but it is occupied with 1 or 2 payloads. |
| 123 | RF24_FIFO_OCCUPIED, |
| 124 | /// @brief The FIFO is empty. |
| 125 | RF24_FIFO_EMPTY, |
| 126 | /// @brief The FIFO is full. |
| 127 | RF24_FIFO_FULL, |
| 128 | /// @brief Represents corruption of data over SPI (when observed). |
| 129 | RF24_FIFO_INVALID, |
| 130 | } rf24_fifo_state_e; |
| 131 | |
| 132 | /** |
| 133 | * @} |
| 134 | * @defgroup StatusFlags Status flags |
| 135 | * @{ |
| 136 | */ |
| 137 | |
| 138 | /** |
| 139 | * @brief An enumeration of constants used to configure @ref StatusFlags |
| 140 | */ |
| 141 | typedef enum |
| 142 | { |
| 143 | /// An alias of `0` to describe no IRQ events enabled. |
| 144 | RF24_IRQ_NONE = 0, |
| 145 | /// Represents an event where TX Data Failed to send. |
| 146 | RF24_TX_DF = 1 << nRF24L01::MASK_MAX_RT, |
| 147 | /// Represents an event where TX Data Sent successfully. |
| 148 | RF24_TX_DS = 1 << nRF24L01::TX_DS, |
| 149 | /// Represents an event where RX Data is Ready to `RF24::read()`. |
| 150 | RF24_RX_DR = 1 << nRF24L01::RX_DR, |
| 151 | /// Equivalent to `RF24_RX_DR | RF24_TX_DS | RF24_TX_DF`. |
| 152 | RF24_IRQ_ALL = (1 << nRF24L01::MASK_MAX_RT) | (1 << nRF24L01::TX_DS) | (1 << nRF24L01::RX_DR), |
| 153 | } rf24_irq_flags_e; |
| 154 | |
| 155 | /** |
| 156 | * @} |
| 157 | * @brief Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver |
| 158 | */ |
| 159 | class RF24 |
| 160 | { |
| 161 | private: |
| 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) |
| 174 | |
| 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 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. */ |
| 189 | |
| 190 | protected: |
| 191 | /** |
| 192 | * SPI transactions |
| 193 | * |
| 194 | * Common code for SPI transactions including CSN toggle |
| 195 | * |
| 196 | */ |
| 197 | inline void beginTransaction(); |
| 198 | |
| 199 | inline void endTransaction(); |
| 200 | |
| 201 | /** Whether ack payloads are enabled. */ |
| 202 | bool ack_payloads_enabled; |
| 203 | /** The address width to use (3, 4 or 5 bytes). */ |
| 204 | uint8_t addr_width; |
| 205 | /** Whether dynamic payloads are enabled. */ |
| 206 | bool dynamic_payloads_enabled; |
| 207 | |
| 208 | /** |
| 209 | * Read a chunk of data in from a register |
| 210 | * |
| 211 | * @param reg Which register. Use constants from nRF24L01.h |
| 212 | * @param[out] buf Where to put the data |
| 213 | * @param len How many bytes of data to transfer |
| 214 | * @note This returns nothing. Older versions of this function returned the status |
| 215 | * byte, but that it now saved to a private member on all SPI transactions. |
| 216 | */ |
| 217 | void read_register(uint8_t reg, uint8_t* buf, uint8_t len); |
| 218 | |
| 219 | /** |
| 220 | * Read single byte from a register |
| 221 | * |
| 222 | * @param reg Which register. Use constants from nRF24L01.h |
| 223 | * @return Current value of register @p reg |
| 224 | */ |
| 225 | uint8_t read_register(uint8_t reg); |
| 226 | |
| 227 | public: |
| 228 | /** |
| 229 | * @name Primary public interface |
| 230 | * |
| 231 | * These are the main methods you need to operate the chip |
| 232 | */ |
| 233 | /**@{*/ |
| 234 | |
| 235 | /** |
| 236 | * RF24 Constructor |
| 237 | * |
| 238 | * Creates a new instance of this driver. Before using, you create an instance |
| 239 | * and send in the unique pins that this chip is connected to. |
| 240 | * |
| 241 | * See [Related Pages](pages.html) for device specific information |
| 242 | * |
| 243 | * @param _cepin The pin attached to Chip Enable on the RF module. |
| 244 | * Review our [Linux general](rpi_general.md) doc for details about selecting pin numbers on Linux systems. |
| 245 | * @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module. |
| 246 | * - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI) |
| 247 | * 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 |
| 248 | * the radio's CSN pin. |
| 249 | * @param _spi_speed The SPI speed in Hz ie: 1000000 == 1Mhz |
| 250 | * - Users can specify default SPI speed by modifying @ref RF24_SPI_SPEED in @ref RF24_config.h |
| 251 | * - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS |
| 252 | * - Older/Unsupported Arduino devices will use a default clock divider & settings configuration |
| 253 | * - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7 |
| 254 | */ |
| 255 | RF24(rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin, uint32_t _spi_speed = RF24_SPI_SPEED); |
| 256 | |
| 257 | /** |
| 258 | * A constructor for initializing the radio's hardware dynamically |
| 259 | * @warning You MUST use begin(rf24_gpio_pin_t, rf24_gpio_pin_t) or begin(_SPI*, rf24_gpio_pin_t, rf24_gpio_pin_t) to pass both the |
| 260 | * digital output pin numbers connected to the radio's CE and CSN pins. |
| 261 | * @param _spi_speed The SPI speed in Hz ie: 1000000 == 1Mhz |
| 262 | * - Users can specify default SPI speed by modifying @ref RF24_SPI_SPEED in @ref RF24_config.h |
| 263 | * - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS |
| 264 | * - Older/Unsupported Arduino devices will use a default clock divider & settings configuration |
| 265 | * - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7 |
| 266 | */ |
| 267 | RF24(uint32_t _spi_speed = RF24_SPI_SPEED); |
| 268 | |
| 269 | #if defined(RF24_LINUX) |
| 270 | virtual ~RF24() {}; |
| 271 | #endif |
| 272 | |
| 273 | /** |
| 274 | * Begin operation of the chip |
| 275 | * |
| 276 | * Call this in setup(), before calling any other methods. |
| 277 | * @code |
| 278 | * if (!radio.begin()) { |
| 279 | * Serial.println(F("radio hardware not responding!")); |
| 280 | * while (1) {} // hold program in infinite loop to prevent subsequent errors |
| 281 | * } |
| 282 | * @endcode |
| 283 | * @return |
| 284 | * - `true` if the radio was successfully initialized |
| 285 | * - `false` if the MCU failed to communicate with the radio hardware |
| 286 | */ |
| 287 | bool begin(void); |
| 288 | |
| 289 | #if defined(RF24_SPI_PTR) || defined(DOXYGEN_FORCED) |
| 290 | /** |
| 291 | * Same as begin(), but allows specifying a non-default SPI bus to use. |
| 292 | * |
| 293 | * @note This function assumes the `SPI::begin()` method was called before to |
| 294 | * calling this function. |
| 295 | * |
| 296 | * @warning This function is for the Arduino platforms only |
| 297 | * |
| 298 | * @param spiBus A pointer or reference to an instantiated SPI bus object. |
| 299 | * The `_SPI` datatype is a "wrapped" definition that will represent |
| 300 | * various SPI implementations based on the specified platform. |
| 301 | * @see Review the [Arduino support page](arduino.md). |
| 302 | * |
| 303 | * @return same result as begin() |
| 304 | */ |
| 305 | bool begin(_SPI* spiBus); |
| 306 | |
| 307 | /** |
| 308 | * Same as begin(), but allows dynamically specifying a SPI bus, CE pin, |
| 309 | * and CSN pin to use. |
| 310 | * |
| 311 | * @note This function assumes the `SPI::begin()` method was called before to |
| 312 | * calling this function. |
| 313 | * |
| 314 | * @warning This function is for the Arduino platforms only |
| 315 | * |
| 316 | * @param spiBus A pointer or reference to an instantiated SPI bus object. |
| 317 | * The `_SPI` datatype is a "wrapped" definition that will represent |
| 318 | * various SPI implementations based on the specified platform. |
| 319 | * @param _cepin The pin attached to Chip Enable on the RF module. |
| 320 | * Review our [Linux general](rpi_general.md) doc for details about selecting pin numbers on Linux systems. |
| 321 | * @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module. |
| 322 | * - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI) |
| 323 | * 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. |
| 324 | * |
| 325 | * @see Review the [Arduino support page](arduino.md). |
| 326 | * |
| 327 | * @return same result as begin() |
| 328 | */ |
| 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 | |
| 332 | /** |
| 333 | * Same as begin(), but allows dynamically specifying a CE pin |
| 334 | * and CSN pin to use. |
| 335 | * @param _cepin The pin attached to Chip Enable on the RF module |
| 336 | * @param _cspin The pin attached to Chip Select (often labeled CSN) on the radio module. |
| 337 | * - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI) |
| 338 | * 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. |
| 339 | * @return same result as begin() |
| 340 | */ |
| 341 | bool begin(rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin); |
| 342 | |
| 343 | /** |
| 344 | * Checks if the chip is connected to the SPI bus |
| 345 | */ |
| 346 | bool isChipConnected(); |
| 347 | |
| 348 | /** |
| 349 | * Start listening on the pipes opened for reading. |
| 350 | * |
| 351 | * 1. Be sure to call openReadingPipe() first. |
| 352 | * 2. Do not call write() while in this mode, without first calling stopListening(). |
| 353 | * 3. Call available() to check for incoming traffic, and read() to get it. |
| 354 | * |
| 355 | * Open reading pipe 1 using address `0xCCCECCCECC` |
| 356 | * @code |
| 357 | * byte address[] = {0xCC, 0xCE, 0xCC, 0xCE, 0xCC}; |
| 358 | * radio.openReadingPipe(1,address); |
| 359 | * radio.startListening(); |
| 360 | * @endcode |
| 361 | * |
| 362 | * @note If there was a call to openReadingPipe() about pipe 0 prior to |
| 363 | * calling this function, then this function will re-write the address |
| 364 | * that was last set to reading pipe 0. This is because openWritingPipe() |
| 365 | * will overwrite the address to reading pipe 0 for proper auto-ack |
| 366 | * functionality. |
| 367 | */ |
| 368 | void startListening(void); |
| 369 | |
| 370 | /** |
| 371 | * Stop listening for incoming messages, and switch to transmit mode. |
| 372 | * |
| 373 | * Do this before calling write(). |
| 374 | * @code |
| 375 | * radio.stopListening(); |
| 376 | * radio.write(&data, sizeof(data)); |
| 377 | * @endcode |
| 378 | * |
| 379 | * @warning When the ACK payloads feature is enabled, the TX FIFO buffers are |
| 380 | * flushed when calling this function. This is meant to discard any ACK |
| 381 | * payloads that were not appended to acknowledgment packets. |
| 382 | */ |
| 383 | void stopListening(void); |
| 384 | |
| 385 | /** |
| 386 | * @brief Similar to startListening(void) but changes the TX address. |
| 387 | * @param txAddress The new TX address. |
| 388 | * This value will be cached for auto-ack purposes. |
| 389 | */ |
| 390 | void stopListening(const uint8_t* txAddress); |
| 391 | |
| 392 | /** |
| 393 | * Check whether there are bytes available to be read |
| 394 | * @code |
| 395 | * if(radio.available()){ |
| 396 | * radio.read(&data,sizeof(data)); |
| 397 | * } |
| 398 | * @endcode |
| 399 | * |
| 400 | * @see available(uint8_t*) |
| 401 | * |
| 402 | * @return True if there is a payload available, false if none is |
| 403 | * |
| 404 | * @warning This function relies on the information about the pipe number |
| 405 | * that received the next available payload. According to the datasheet, |
| 406 | * the data about the pipe number that received the next available payload |
| 407 | * is "unreliable" during a FALLING transition on the IRQ pin. This means |
| 408 | * you should call clearStatusFlags() before calling this function |
| 409 | * during an ISR (Interrupt Service Routine). For example: |
| 410 | * @code |
| 411 | * void isrCallbackFunction() { |
| 412 | * bool tx_ds, tx_df, rx_dr; |
| 413 | * uint8_t flags = radio.clearStatusFlags(); // resets the IRQ pin to HIGH |
| 414 | * radio.available(); // returned data should now be reliable |
| 415 | * } |
| 416 | * |
| 417 | * void setup() { |
| 418 | * pinMode(IRQ_PIN, INPUT); |
| 419 | * attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING); |
| 420 | * } |
| 421 | * @endcode |
| 422 | */ |
| 423 | bool available(void); |
| 424 | |
| 425 | /** |
| 426 | * Read payload data from the RX FIFO buffer(s). |
| 427 | * |
| 428 | * The length of data read is usually the next available payload's length |
| 429 | * @see |
| 430 | * - getPayloadSize() |
| 431 | * - getDynamicPayloadSize() |
| 432 | * |
| 433 | * @note I specifically chose `void*` as a data type to make it easier |
| 434 | * for beginners to use. No casting needed. |
| 435 | * |
| 436 | * @param buf Pointer to a buffer where the data should be written |
| 437 | * @param len Maximum number of bytes to read into the buffer. This |
| 438 | * value should match the length of the object referenced using the |
| 439 | * `buf` parameter. The absolute maximum number of bytes that can be read |
| 440 | * in one call is 32 (for dynamic payload lengths) or whatever number was |
| 441 | * previously passed to setPayloadSize() (for static payload lengths). |
| 442 | * @remark |
| 443 | * @parblock |
| 444 | * Remember that each call to read() fetches data from the |
| 445 | * RX FIFO beginning with the first byte from the first available |
| 446 | * payload. A payload is not removed from the RX FIFO until it's |
| 447 | * entire length (or more) is fetched using read(). |
| 448 | * |
| 449 | * - If `len` parameter's value is less than the available payload's |
| 450 | * length, then the payload remains in the RX FIFO. |
| 451 | * - If `len` parameter's value is greater than the first of multiple |
| 452 | * available payloads, then the data saved to the `buf` |
| 453 | * parameter's object will be supplemented with data from the next |
| 454 | * available payload. |
| 455 | * - If `len` parameter's value is greater than the last available |
| 456 | * payload's length, then the last byte in the payload is used as |
| 457 | * padding for the data saved to the `buf` parameter's object. |
| 458 | * The nRF24L01 will repeatedly use the last byte from the last |
| 459 | * payload even when read() is called with an empty RX FIFO. |
| 460 | * @endparblock |
| 461 | * @note To use this function in the python wrapper, remember that |
| 462 | * only the `len` parameter is required because this function (in the |
| 463 | * python wrapper) returns the payload data as a buffer protocol object |
| 464 | * (bytearray object). |
| 465 | * @code{.py} |
| 466 | * # let `radio` be the instantiated RF24 object |
| 467 | * if radio.available(): |
| 468 | * length = radio.getDynamicPayloadSize() # or radio.getPayloadSize() for static payload sizes |
| 469 | * received_payload = radio.read(length) |
| 470 | * @endcode |
| 471 | * |
| 472 | * @note This function no longer returns a boolean. Use available to |
| 473 | * determine if packets are available. The `RX_DR` Interrupt flag is now |
| 474 | * cleared with this function instead of when calling available(). |
| 475 | * @code |
| 476 | * if(radio.available()) { |
| 477 | * radio.read(&data, sizeof(data)); |
| 478 | * } |
| 479 | * @endcode |
| 480 | */ |
| 481 | void read(void* buf, uint8_t len); |
| 482 | |
| 483 | /** |
| 484 | * Be sure to call openWritingPipe() first to set the destination |
| 485 | * of where to write to. |
| 486 | * |
| 487 | * This blocks until the message is successfully acknowledged by |
| 488 | * the receiver or the timeout/retransmit maxima are reached. In |
| 489 | * the current configuration, the max delay here is 60-70ms. |
| 490 | * |
| 491 | * The maximum size of data written is the fixed payload size, see |
| 492 | * getPayloadSize(). However, you can write less, and the remainder |
| 493 | * will just be filled with zeroes. |
| 494 | * |
| 495 | * TX/RX/RT interrupt flags will be cleared every time write is called |
| 496 | * |
| 497 | * @param buf Pointer to the data to be sent |
| 498 | * @param len Number of bytes to be sent |
| 499 | * |
| 500 | * @code |
| 501 | * radio.stopListening(); |
| 502 | * radio.write(&data,sizeof(data)); |
| 503 | * @endcode |
| 504 | * |
| 505 | * @note The `len` parameter must be omitted when using the python |
| 506 | * wrapper because the length of the payload is determined automatically. |
| 507 | * To use this function in the python wrapper: |
| 508 | * @code{.py} |
| 509 | * # let `radio` be the instantiated RF24 object |
| 510 | * buffer = b"Hello World" # a `bytes` object |
| 511 | * radio.write(buffer) |
| 512 | * @endcode |
| 513 | * |
| 514 | * @return |
| 515 | * - `true` if the payload was delivered successfully and an acknowledgement |
| 516 | * (ACK packet) was received. If auto-ack is disabled, then any attempt |
| 517 | * to transmit will also return true (even if the payload was not |
| 518 | * received). |
| 519 | * - `false` if the payload was sent but was not acknowledged with an ACK |
| 520 | * packet. This condition can only be reported if the auto-ack feature |
| 521 | * is on. |
| 522 | */ |
| 523 | bool write(const void* buf, uint8_t len); |
| 524 | |
| 525 | /** |
| 526 | * New: Open a pipe for writing via byte array. Old addressing format retained |
| 527 | * for compatibility. |
| 528 | * |
| 529 | * @deprecated Use `RF24::stopListening(uint8_t*)` instead. |
| 530 | * |
| 531 | * Only one writing pipe can be opened at once, but this function changes |
| 532 | * the address that is used to transmit (ACK payloads/packets do not apply |
| 533 | * here). Be sure to call stopListening() prior to calling this function. |
| 534 | * |
| 535 | * Addresses are assigned via a byte array, default is 5 byte address length |
| 536 | * |
| 537 | * @code |
| 538 | * uint8_t addresses[][6] = {"1Node", "2Node"}; |
| 539 | * radio.openWritingPipe(addresses[0]); |
| 540 | * @endcode |
| 541 | * @code |
| 542 | * uint8_t address[] = { 0xCC, 0xCE, 0xCC, 0xCE, 0xCC }; |
| 543 | * radio.openWritingPipe(address); |
| 544 | * address[0] = 0x33; |
| 545 | * radio.openReadingPipe(1, address); |
| 546 | * @endcode |
| 547 | * |
| 548 | * @warning This function will overwrite the address set to reading pipe 0 |
| 549 | * as stipulated by the datasheet for proper auto-ack functionality in TX |
| 550 | * mode. Use this function to ensure proper transmission acknowledgement |
| 551 | * when the address set to reading pipe 0 (via openReadingPipe()) does not |
| 552 | * match the address passed to this function. If the auto-ack feature is |
| 553 | * disabled, then this function will still overwrite the address for |
| 554 | * reading pipe 0 regardless. |
| 555 | * |
| 556 | * @see |
| 557 | * - setAddressWidth() |
| 558 | * - startListening() |
| 559 | * - stopListening() |
| 560 | * |
| 561 | * @param address The address to be used for outgoing transmissions (uses |
| 562 | * pipe 0). Coordinate this address amongst other receiving nodes (the |
| 563 | * pipe numbers don't need to match). This address is cached to ensure proper |
| 564 | * auto-ack behavior; stopListening() will always restore the latest cached TX |
| 565 | * address. |
| 566 | * |
| 567 | * @remark There is no address length parameter because this function will |
| 568 | * always write the number of bytes that the radio addresses are configured |
| 569 | * to use (set with setAddressWidth()). |
| 570 | */ |
| 571 | |
| 572 | void openWritingPipe(const uint8_t* address); |
| 573 | |
| 574 | /** |
| 575 | * Open a pipe for reading |
| 576 | * |
| 577 | * Up to 6 pipes can be open for reading at once. Open all the required |
| 578 | * reading pipes, and then call startListening(). |
| 579 | * |
| 580 | * @see |
| 581 | * - openWritingPipe() |
| 582 | * - setAddressWidth() |
| 583 | * |
| 584 | * @note Pipes 0 and 1 will store a full 5-byte address. Pipes 2-5 will technically |
| 585 | * only store a single byte, borrowing up to 4 additional bytes from pipe 1 per the |
| 586 | * assigned address width. |
| 587 | * Pipes 1-5 should share the same address, except the first byte. |
| 588 | * Only the first byte in the array should be unique, e.g. |
| 589 | * @code |
| 590 | * uint8_t addresses[][6] = {"Prime", "2Node", "3xxxx", "4xxxx"}; |
| 591 | * openReadingPipe(0, addresses[0]); // address used is "Prime" |
| 592 | * openReadingPipe(1, addresses[1]); // address used is "2Node" |
| 593 | * openReadingPipe(2, addresses[2]); // address used is "3Node" |
| 594 | * openReadingPipe(3, addresses[3]); // address used is "4Node" |
| 595 | * @endcode |
| 596 | * |
| 597 | * @warning |
| 598 | * @parblock |
| 599 | * If the reading pipe 0 is opened by this function, the address |
| 600 | * passed to this function (for pipe 0) will be restored at every call to |
| 601 | * startListening(). |
| 602 | * |
| 603 | * Read |
| 604 | * http://maniacalbits.blogspot.com/2013/04/rf24-addressing-nrf24l01-radios-require.html |
| 605 | * to understand how to avoid using malformed addresses. This address |
| 606 | * restoration is implemented because of the underlying necessary |
| 607 | * functionality of openWritingPipe(). |
| 608 | * @endparblock |
| 609 | * |
| 610 | * @param number Which pipe to open. Only pipe numbers 0-5 are available, |
| 611 | * an address assigned to any pipe number not in that range will be ignored. |
| 612 | * @param address The 24, 32 or 40 bit address of the pipe to open. |
| 613 | * |
| 614 | * There is no address length parameter because this function will |
| 615 | * always write the number of bytes (for pipes 0 and 1) that the radio |
| 616 | * addresses are configured to use (set with setAddressWidth()). |
| 617 | */ |
| 618 | void openReadingPipe(uint8_t number, const uint8_t* address); |
| 619 | |
| 620 | /**@}*/ |
| 621 | /** |
| 622 | * @name Advanced Operation |
| 623 | * |
| 624 | * Methods you can use to drive the chip in more advanced ways |
| 625 | */ |
| 626 | /**@{*/ |
| 627 | |
| 628 | /** |
| 629 | * Set radio's CE (Chip Enable) pin state. |
| 630 | * |
| 631 | * @warning Please see the datasheet for a much more detailed description of this pin. |
| 632 | * |
| 633 | * @note This is only publicly exposed for advanced use cases such as complex networking or |
| 634 | * streaming consecutive payloads without robust error handling. |
| 635 | * Typical uses are satisfied by simply using `startListening()` for RX mode or |
| 636 | * `stopListening()` and `write()` for TX mode. |
| 637 | * |
| 638 | * @param level In RX mode, `HIGH` causes the radio to begin actively listening. |
| 639 | * In TX mode, `HIGH` (+ 130 microsecond delay) causes the radio to begin transmitting. |
| 640 | * Setting this to `LOW` will cause the radio to stop transmitting or receiving in any mode. |
| 641 | */ |
| 642 | void ce(bool level); |
| 643 | |
| 644 | /** |
| 645 | * Print a giant block of debugging information to stdout |
| 646 | * |
| 647 | * @warning Does nothing if stdout is not defined. See fdevopen in stdio.h |
| 648 | * The printf.h file is included with the library for Arduino. |
| 649 | * @code |
| 650 | * #include <printf.h> |
| 651 | * setup() { |
| 652 | * Serial.begin(115200); |
| 653 | * printf_begin(); |
| 654 | * // ... |
| 655 | * } |
| 656 | * @endcode |
| 657 | */ |
| 658 | void printDetails(void); |
| 659 | |
| 660 | /** |
| 661 | * Decode and print the given STATUS byte to stdout. |
| 662 | * |
| 663 | * @param flags The STATUS byte to print. |
| 664 | * This value is fetched with update() or getStatusFlags(). |
| 665 | * |
| 666 | * @warning Does nothing if stdout is not defined. See fdevopen in stdio.h |
| 667 | */ |
| 668 | void printStatus(uint8_t flags); |
| 669 | |
| 670 | /** |
| 671 | * Print a giant block of debugging information to stdout. This function |
| 672 | * differs from printDetails() because it makes the information more |
| 673 | * understandable without having to look up the datasheet or convert |
| 674 | * hexadecimal to binary. Only use this function if your application can |
| 675 | * spare extra bytes of memory. |
| 676 | * |
| 677 | * @warning Does nothing if stdout is not defined. See fdevopen in stdio.h |
| 678 | * The printf.h file is included with the library for Arduino. |
| 679 | * @code |
| 680 | * #include <printf.h> |
| 681 | * setup() { |
| 682 | * Serial.begin(115200); |
| 683 | * printf_begin(); |
| 684 | * // ... |
| 685 | * } |
| 686 | * @endcode |
| 687 | * |
| 688 | * @note If the automatic acknowledgements feature is configured differently |
| 689 | * for each pipe, then a binary representation is used in which bits 0-5 |
| 690 | * represent pipes 0-5 respectively. A `0` means the feature is disabled, and |
| 691 | * a `1` means the feature is enabled. |
| 692 | */ |
| 693 | void printPrettyDetails(void); |
| 694 | |
| 695 | /** |
| 696 | * Put a giant block of debugging information in a char array. This function |
| 697 | * differs from printPrettyDetails() because it uses `sprintf()` and does not use |
| 698 | * a predefined output stream (like `Serial` or stdout). Only use this function if |
| 699 | * your application can spare extra bytes of memory. This can also be used for boards that |
| 700 | * do not support `printf()` (which is required for printDetails() and printPrettyDetails()). |
| 701 | * |
| 702 | * @remark |
| 703 | * The C standard function [sprintf()](http://www.cplusplus.com/reference/cstdio/sprintf) |
| 704 | * formats a C-string in the exact same way as `printf()` but outputs (by reference) |
| 705 | * into a char array. The formatted string literal for sprintf() is stored |
| 706 | * in nonvolatile program memory. |
| 707 | * |
| 708 | * @warning Use a buffer of sufficient size for the `debugging_information`. Start |
| 709 | * with a char array that has at least 870 elements. There is no overflow protection when using |
| 710 | * sprintf(), so the output buffer must be sized correctly or the resulting behavior will |
| 711 | * be undefined. |
| 712 | * @code |
| 713 | * char buffer[870] = {'\0'}; |
| 714 | * uint16_t used_chars = radio.sprintfPrettyDetails(buffer); |
| 715 | * Serial.println(buffer); |
| 716 | * Serial.print(F("strlen = ")); |
| 717 | * Serial.println(used_chars + 1); // +1 for c-strings' null terminating byte |
| 718 | * @endcode |
| 719 | * |
| 720 | * @param debugging_information The c-string buffer that the debugging |
| 721 | * information is stored to. This must be allocated to a minimum of 870 bytes of memory. |
| 722 | * @returns The number of characters altered in the given buffer. Remember that, |
| 723 | * like `sprintf()`, this returned number does not include the null terminating byte. |
| 724 | * |
| 725 | * This function is available in the python wrapper, but it accepts no parameters and |
| 726 | * returns a string. It does not return the number of characters in the string. |
| 727 | * @code{.py} |
| 728 | * debug_info = radio.sprintfPrettyDetails() |
| 729 | * print(debug_info) |
| 730 | * print("str_len =", len(debug_info)) |
| 731 | * @endcode |
| 732 | * |
| 733 | * @note If the automatic acknowledgements feature is configured differently |
| 734 | * for each pipe, then a binary representation is used in which bits 0-5 |
| 735 | * represent pipes 0-5 respectively. A `0` means the feature is disabled, and |
| 736 | * a `1` means the feature is enabled. |
| 737 | */ |
| 738 | uint16_t sprintfPrettyDetails(char* debugging_information); |
| 739 | |
| 740 | /** |
| 741 | * Encode radio debugging information into an array of uint8_t. This function |
| 742 | * differs from other debug output methods because the debug information can |
| 743 | * be decoded by an external program. |
| 744 | * |
| 745 | * This function is not available in the python wrapper because it is intended for |
| 746 | * use on processors with very limited available resources. |
| 747 | * |
| 748 | * @remark |
| 749 | * This function uses much less ram than other `*print*Details()` methods. |
| 750 | * |
| 751 | * @code |
| 752 | * uint8_t encoded_details[43] = {0}; |
| 753 | * radio.encodeRadioDetails(encoded_details); |
| 754 | * @endcode |
| 755 | * |
| 756 | * @param encoded_status The uint8_t array that RF24 radio details are |
| 757 | * encoded into. This array must be at least 43 bytes in length; any less would surely |
| 758 | * cause undefined behavior. |
| 759 | * |
| 760 | * Registers names and/or data corresponding to the index of the `encoded_details` array: |
| 761 | * | index | register/data | |
| 762 | * |------:|:--------------| |
| 763 | * | 0 | CONFIG | |
| 764 | * | 1 | EN_AA | |
| 765 | * | 2 | EN_RXADDR | |
| 766 | * | 3 | SETUP_AW | |
| 767 | * | 4 | SETUP_RETR | |
| 768 | * | 5 | RF_CH | |
| 769 | * | 6 | RF_SETUP | |
| 770 | * | 7 | STATUS | |
| 771 | * | 8 | OBSERVE_TX | |
| 772 | * | 9 | CD (aka RPD) | |
| 773 | * | 10-14 | RX_ADDR_P0 | |
| 774 | * | 15-19 | RX_ADDR_P1 | |
| 775 | * | 20 | RX_ADDR_P2 | |
| 776 | * | 21 | RX_ADDR_P3 | |
| 777 | * | 22 | RX_ADDR_P4 | |
| 778 | * | 23 | RX_ADDR_P5 | |
| 779 | * | 24-28 | TX_ADDR | |
| 780 | * | 29 | RX_PW_P0 | |
| 781 | * | 30 | RX_PW_P1 | |
| 782 | * | 31 | RX_PW_P2 | |
| 783 | * | 32 | RX_PW_P3 | |
| 784 | * | 33 | RX_PW_P4 | |
| 785 | * | 34 | RX_PW_P5 | |
| 786 | * | 35 | FIFO_STATUS | |
| 787 | * | 36 | DYNPD | |
| 788 | * | 37 | FEATURE | |
| 789 | * | 38-39 | ce_pin | |
| 790 | * | 40-41 | csn_pin | |
| 791 | * | 42 | SPI speed (in MHz) or'd with (isPlusVariant << 4) | |
| 792 | */ |
| 793 | void encodeRadioDetails(uint8_t* encoded_status); |
| 794 | |
| 795 | /** |
| 796 | * Test whether there are bytes available to be read from the |
| 797 | * FIFO buffers. |
| 798 | * |
| 799 | * @note This function is named `available_pipe()` in the python wrapper. |
| 800 | * @parblock |
| 801 | * Additionally, the `available_pipe()` function (which |
| 802 | * takes no arguments) returns a 2 item tuple containing (ordered by |
| 803 | * tuple's indices): |
| 804 | * - A boolean describing if there is a payload available to read from |
| 805 | * the RX FIFO buffers. |
| 806 | * - The pipe number that received the next available payload in the RX |
| 807 | * FIFO buffers. If the item at the tuple's index 0 is `False`, then |
| 808 | * this pipe number is invalid. |
| 809 | * |
| 810 | * To use this function in python: |
| 811 | * @code{.py} |
| 812 | * # let `radio` be the instantiated RF24 object |
| 813 | * has_payload, pipe_number = radio.available_pipe() # expand the tuple to 2 variables |
| 814 | * if has_payload: |
| 815 | * print("Received a payload with pipe", pipe_number) |
| 816 | * @endcode |
| 817 | * @endparblock |
| 818 | * |
| 819 | * @param[out] pipe_num Which pipe has the payload available |
| 820 | * @code |
| 821 | * uint8_t pipeNum; |
| 822 | * if(radio.available(&pipeNum)){ |
| 823 | * radio.read(&data, sizeof(data)); |
| 824 | * Serial.print("Received data on pipe "); |
| 825 | * Serial.println(pipeNum); |
| 826 | * } |
| 827 | * @endcode |
| 828 | * |
| 829 | * @warning According to the datasheet, the data saved to `pipe_num` is |
| 830 | * "unreliable" during a FALLING transition on the IRQ pin. This means you |
| 831 | * should call clearStatusFlags() before calling this function during |
| 832 | * an ISR (Interrupt Service Routine). For example: |
| 833 | * @code |
| 834 | * void isrCallbackFunction() { |
| 835 | * radio.clearStatusFlags(); // resets the IRQ pin to inactive HIGH |
| 836 | * uint8_t pipe = 7; // initialize pipe data |
| 837 | * radio.available(&pipe); // pipe data should now be reliable |
| 838 | * } |
| 839 | * |
| 840 | * void setup() { |
| 841 | * pinMode(IRQ_PIN, INPUT); |
| 842 | * attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING); |
| 843 | * } |
| 844 | * @endcode |
| 845 | * |
| 846 | * @return |
| 847 | * - `true` if there is a payload available in the top (first out) |
| 848 | * level RX FIFO. |
| 849 | * - `false` if there is nothing available in the RX FIFO because it is |
| 850 | * empty. |
| 851 | */ |
| 852 | bool available(uint8_t* pipe_num); |
| 853 | |
| 854 | /** |
| 855 | * Use this function to check if the radio's RX FIFO levels are all |
| 856 | * occupied. This can be used to prevent data loss because any incoming |
| 857 | * transmissions are rejected if there is no unoccupied levels in the RX |
| 858 | * FIFO to store the incoming payload. Remember that each level can hold |
| 859 | * up to a maximum of 32 bytes. |
| 860 | * @return |
| 861 | * - `true` if all three 3 levels of the RX FIFO buffers are occupied. |
| 862 | * - `false` if there is one or more levels available in the RX FIFO |
| 863 | * buffers. Remember that this does not always mean that the RX FIFO |
| 864 | * buffers are empty; use available() to see if the RX FIFO buffers are |
| 865 | * empty or not. |
| 866 | */ |
| 867 | bool rxFifoFull(); |
| 868 | |
| 869 | /** |
| 870 | * @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO |
| 871 | * @return |
| 872 | * - @ref RF24_FIFO_OCCUPIED (`0`) if the specified FIFO is neither full nor empty. |
| 873 | * - @ref RF24_FIFO_EMPTY (`1`) if the specified FIFO is empty. |
| 874 | * - @ref RF24_FIFO_FULL (`2`) if the specified FIFO is full. |
| 875 | * - @ref RF24_FIFO_INVALID (`3`) if the data fetched over SPI was malformed. |
| 876 | */ |
| 877 | rf24_fifo_state_e isFifo(bool about_tx); |
| 878 | |
| 879 | /** |
| 880 | * @deprecated Use RF24::isFifo(bool about_tx) instead. |
| 881 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 882 | * |
| 883 | * @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO |
| 884 | * @param check_empty |
| 885 | * - `true` checks if the specified FIFO is empty |
| 886 | * - `false` checks is the specified FIFO is full. |
| 887 | * @return A boolean answer to the question "is the [TX/RX] FIFO [empty/full]?" |
| 888 | */ |
| 889 | bool isFifo(bool about_tx, bool check_empty); |
| 890 | |
| 891 | /** |
| 892 | * Enter low-power mode |
| 893 | * |
| 894 | * To return to normal power mode, call powerUp(). |
| 895 | * |
| 896 | * @note After calling startListening(), a basic radio will consume about 13.5mA |
| 897 | * at max PA level. |
| 898 | * During active transmission, the radio will consume about 11.5mA, but this will |
| 899 | * be reduced to 26uA (.026mA) between sending. |
| 900 | * In full powerDown mode, the radio will consume approximately 900nA (.0009mA) |
| 901 | * |
| 902 | * @code |
| 903 | * radio.powerDown(); |
| 904 | * avr_enter_sleep_mode(); // Custom function to sleep the device |
| 905 | * radio.powerUp(); |
| 906 | * @endcode |
| 907 | */ |
| 908 | void powerDown(void); |
| 909 | |
| 910 | /** |
| 911 | * Leave low-power mode - required for normal radio operation after calling powerDown() |
| 912 | * |
| 913 | * To return to low power mode, call powerDown(). |
| 914 | * @note This will take up to 5ms for maximum compatibility |
| 915 | */ |
| 916 | void powerUp(void); |
| 917 | |
| 918 | /** |
| 919 | * Write for single NOACK writes. Optionally disable |
| 920 | * acknowledgements/auto-retries for a single payload using the |
| 921 | * multicast parameter set to true. |
| 922 | * |
| 923 | * Can be used with enableAckPayload() to request a response |
| 924 | * @see |
| 925 | * - setAutoAck() |
| 926 | * - write() |
| 927 | * |
| 928 | * @param buf Pointer to the data to be sent |
| 929 | * @param len Number of bytes to be sent |
| 930 | * @param multicast Request ACK response (false), or no ACK response |
| 931 | * (true). Be sure to have called enableDynamicAck() at least once before |
| 932 | * setting this parameter. |
| 933 | * @return |
| 934 | * - `true` if the payload was delivered successfully and an acknowledgement |
| 935 | * (ACK packet) was received. If auto-ack is disabled, then any attempt |
| 936 | * to transmit will also return true (even if the payload was not |
| 937 | * received). |
| 938 | * - `false` if the payload was sent but was not acknowledged with an ACK |
| 939 | * packet. This condition can only be reported if the auto-ack feature |
| 940 | * is on. |
| 941 | * |
| 942 | * @note The `len` parameter must be omitted when using the python |
| 943 | * wrapper because the length of the payload is determined automatically. |
| 944 | * To use this function in the python wrapper: |
| 945 | * @code{.py} |
| 946 | * # let `radio` be the instantiated RF24 object |
| 947 | * buffer = b"Hello World" # a `bytes` object |
| 948 | * radio.write(buffer, False) # False = the multicast parameter |
| 949 | * @endcode |
| 950 | */ |
| 951 | bool write(const void* buf, uint8_t len, const bool multicast); |
| 952 | |
| 953 | /** |
| 954 | * This will not block until the 3 FIFO buffers are filled with data. |
| 955 | * Once the FIFOs are full, writeFast() will simply wait for a buffer to |
| 956 | * become available or a transmission failure (returning `true` or `false` |
| 957 | * respectively). |
| 958 | * |
| 959 | * @warning |
| 960 | * @parblock |
| 961 | * It is important to never keep the nRF24L01 in TX mode and FIFO full for more than 4ms at a time. If the auto |
| 962 | * retransmit is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO |
| 963 | * to clear by issuing txStandBy() or ensure appropriate time between transmissions. |
| 964 | * |
| 965 | * Use txStandBy() when this function returns `false`. |
| 966 | * |
| 967 | * Example (Partial blocking): |
| 968 | * @code |
| 969 | * radio.writeFast(&buf,32); // Writes 1 payload to the buffers |
| 970 | * txStandBy(); // Returns 0 if failed. 1 if success. Blocks only until MAX_RT timeout or success. Data flushed on fail. |
| 971 | * |
| 972 | * radio.writeFast(&buf,32); // Writes 1 payload to the buffers |
| 973 | * txStandBy(1000); // Using extended timeouts, returns 1 if success. Retries failed payloads for 1 seconds before returning 0. |
| 974 | * @endcode |
| 975 | * @endparblock |
| 976 | * |
| 977 | * @see |
| 978 | * - setAutoAck() |
| 979 | * - txStandBy() |
| 980 | * - write() |
| 981 | * - writeBlocking() |
| 982 | * |
| 983 | * @param buf Pointer to the data to be sent |
| 984 | * @param len Number of bytes to be sent |
| 985 | * @return |
| 986 | * - `true` if the payload passed to `buf` was loaded in the TX FIFO. |
| 987 | * - `false` if the payload passed to `buf` was not loaded in the TX FIFO |
| 988 | * because a previous payload already in the TX FIFO failed to |
| 989 | * transmit. This condition can only be reported if the auto-ack feature |
| 990 | * is on. |
| 991 | * |
| 992 | * @note The `len` parameter must be omitted when using the python |
| 993 | * wrapper because the length of the payload is determined automatically. |
| 994 | * To use this function in the python wrapper: |
| 995 | * @code{.py} |
| 996 | * # let `radio` be the instantiated RF24 object |
| 997 | * buffer = b"Hello World" # a `bytes` object |
| 998 | * radio.writeFast(buffer) |
| 999 | * @endcode |
| 1000 | */ |
| 1001 | bool writeFast(const void* buf, uint8_t len); |
| 1002 | |
| 1003 | /** |
| 1004 | * Similar to writeFast(const void*, uint8_t) but allows for single NOACK writes. |
| 1005 | * Optionally disable acknowledgements/auto-retries for a single payload using the |
| 1006 | * multicast parameter set to `true`. |
| 1007 | * |
| 1008 | * @warning If the auto-ack feature is enabled, then it is strongly encouraged to call |
| 1009 | * txStandBy() when this function returns `false`. |
| 1010 | * |
| 1011 | * @see |
| 1012 | * - setAutoAck() |
| 1013 | * - txStandBy() |
| 1014 | * - write() |
| 1015 | * - writeBlocking() |
| 1016 | * |
| 1017 | * @param buf Pointer to the data to be sent |
| 1018 | * @param len Number of bytes to be sent |
| 1019 | * @param multicast Request ACK response (false), or no ACK response |
| 1020 | * (true). Be sure to have called enableDynamicAck() at least once before |
| 1021 | * setting this parameter. |
| 1022 | * @return |
| 1023 | * - `true` if the payload passed to `buf` was loaded in the TX FIFO. |
| 1024 | * - `false` if the payload passed to `buf` was not loaded in the TX FIFO |
| 1025 | * because a previous payload already in the TX FIFO failed to |
| 1026 | * transmit. This condition can only be reported if the auto-ack feature |
| 1027 | * is on (and the multicast parameter is set to false). |
| 1028 | * |
| 1029 | * @note The `len` parameter must be omitted when using the python |
| 1030 | * wrapper because the length of the payload is determined automatically. |
| 1031 | * To use this function in the python wrapper: |
| 1032 | * @code{.py} |
| 1033 | * # let `radio` be the instantiated RF24 object |
| 1034 | * buffer = b"Hello World" # a `bytes` object |
| 1035 | * radio.writeFast(buffer, False) # False = the multicast parameter |
| 1036 | * @endcode |
| 1037 | */ |
| 1038 | bool writeFast(const void* buf, uint8_t len, const bool multicast); |
| 1039 | |
| 1040 | /** |
| 1041 | * This function extends the auto-retry mechanism to any specified duration. |
| 1042 | * It will not block until the 3 FIFO buffers are filled with data. |
| 1043 | * If so the library will auto retry until a new payload is written |
| 1044 | * or the user specified timeout period is reached. |
| 1045 | * @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 |
| 1046 | * retransmit is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO |
| 1047 | * to clear by issuing txStandBy() or ensure appropriate time between transmissions. |
| 1048 | * |
| 1049 | * Example (Full blocking): |
| 1050 | * @code |
| 1051 | * radio.writeBlocking(&buf, sizeof(buf), 1000); // Wait up to 1 second to write 1 payload to the buffers |
| 1052 | * radio.txStandBy(1000); // Wait up to 1 second for the payload to send. Return 1 if ok, 0 if failed. |
| 1053 | * // Blocks only until user timeout or success. Data flushed on fail. |
| 1054 | * @endcode |
| 1055 | * @note If used from within an interrupt, the interrupt should be disabled until completion, and sei(); called to enable millis(). |
| 1056 | * @see |
| 1057 | * - txStandBy() |
| 1058 | * - write() |
| 1059 | * - writeFast() |
| 1060 | * |
| 1061 | * @param buf Pointer to the data to be sent |
| 1062 | * @param len Number of bytes to be sent |
| 1063 | * @param timeout User defined timeout in milliseconds. |
| 1064 | * |
| 1065 | * @note The `len` parameter must be omitted when using the python |
| 1066 | * wrapper because the length of the payload is determined automatically. |
| 1067 | * To use this function in the python wrapper: |
| 1068 | * @code{.py} |
| 1069 | * # let `radio` be the instantiated RF24 object |
| 1070 | * buffer = b"Hello World" # a `bytes` object |
| 1071 | * radio.writeBlocking(buffer, 1000) # 1000 means wait at most 1 second |
| 1072 | * @endcode |
| 1073 | * |
| 1074 | * @return |
| 1075 | * - `true` if the payload passed to `buf` was loaded in the TX FIFO. |
| 1076 | * - `false` if the payload passed to `buf` was not loaded in the TX FIFO |
| 1077 | * because a previous payload already in the TX FIFO failed to |
| 1078 | * transmit. This condition can only be reported if the auto-ack feature |
| 1079 | * is on. |
| 1080 | */ |
| 1081 | bool writeBlocking(const void* buf, uint8_t len, uint32_t timeout); |
| 1082 | |
| 1083 | /** |
| 1084 | * This function should be called as soon as transmission is finished to |
| 1085 | * drop the radio back to STANDBY-I mode. If not issued, the radio will |
| 1086 | * remain in STANDBY-II mode which, per the data sheet, is not a recommended |
| 1087 | * operating mode. |
| 1088 | * |
| 1089 | * @note When transmitting data in rapid succession, it is still recommended by |
| 1090 | * the manufacturer to drop the radio out of TX or STANDBY-II mode if there is |
| 1091 | * time enough between sends for the FIFOs to empty. This is not required if auto-ack |
| 1092 | * is enabled. |
| 1093 | * |
| 1094 | * Relies on built-in auto retry functionality. |
| 1095 | * |
| 1096 | * Example (Partial blocking): |
| 1097 | * @code |
| 1098 | * radio.writeFast(&buf, 32); |
| 1099 | * radio.writeFast(&buf, 32); |
| 1100 | * radio.writeFast(&buf, 32); //Fills the FIFO buffers up |
| 1101 | * bool ok = radio.txStandBy(); //Returns 0 if failed. 1 if success. |
| 1102 | * //Blocks only until MAX_RT timeout or success. Data flushed on fail. |
| 1103 | * @endcode |
| 1104 | * @see txStandBy(uint32_t timeout, bool startTx) |
| 1105 | * @return |
| 1106 | * - `true` if all payloads in the TX FIFO were delivered successfully and |
| 1107 | * an acknowledgement (ACK packet) was received for each. If auto-ack is |
| 1108 | * disabled, then any attempt to transmit will also return true (even if |
| 1109 | * the payload was not received). |
| 1110 | * - `false` if a payload was sent but was not acknowledged with an ACK |
| 1111 | * packet. This condition can only be reported if the auto-ack feature |
| 1112 | * is on. |
| 1113 | */ |
| 1114 | bool txStandBy(); |
| 1115 | |
| 1116 | /** |
| 1117 | * This function allows extended blocking and auto-retries per a user defined timeout |
| 1118 | * |
| 1119 | * Fully Blocking Example: |
| 1120 | * @code |
| 1121 | * radio.writeFast(&buf, 32); |
| 1122 | * radio.writeFast(&buf, 32); |
| 1123 | * radio.writeFast(&buf, 32); //Fills the FIFO buffers up |
| 1124 | * bool ok = radio.txStandBy(1000); //Returns 0 if failed after 1 second of retries. 1 if success. |
| 1125 | * //Blocks only until user defined timeout or success. Data flushed on fail. |
| 1126 | * @endcode |
| 1127 | * @note If used from within an interrupt, the interrupt should be disabled until completion, and sei(); called to enable millis(). |
| 1128 | * @param timeout Number of milliseconds to retry failed payloads |
| 1129 | * @param startTx If this is set to `true`, then this function puts the nRF24L01 |
| 1130 | * in TX Mode. `false` leaves the primary mode (TX or RX) as it is, which can |
| 1131 | * prevent the mandatory wait time to change modes. |
| 1132 | * @return |
| 1133 | * - `true` if all payloads in the TX FIFO were delivered successfully and |
| 1134 | * an acknowledgement (ACK packet) was received for each. If auto-ack is |
| 1135 | * disabled, then any attempt to transmit will also return true (even if |
| 1136 | * the payload was not received). |
| 1137 | * - `false` if a payload was sent but was not acknowledged with an ACK |
| 1138 | * packet. This condition can only be reported if the auto-ack feature |
| 1139 | * is on. |
| 1140 | */ |
| 1141 | bool txStandBy(uint32_t timeout, bool startTx = 0); |
| 1142 | |
| 1143 | /** |
| 1144 | * Write an acknowledgement (ACK) payload for the specified pipe |
| 1145 | * |
| 1146 | * The next time a message is received on a specified `pipe`, the data in |
| 1147 | * `buf` will be sent back in the ACK payload. |
| 1148 | * |
| 1149 | * @see |
| 1150 | * - enableAckPayload() |
| 1151 | * - enableDynamicPayloads() |
| 1152 | * |
| 1153 | * @note ACK payloads are handled automatically by the radio chip when a |
| 1154 | * regular payload is received. It is important to discard regular payloads |
| 1155 | * in the TX FIFO (using flush_tx()) before loading the first ACK payload |
| 1156 | * into the TX FIFO. This function can be called before and after calling |
| 1157 | * startListening(). |
| 1158 | * |
| 1159 | * @warning Only three of these can be pending at any time as there are |
| 1160 | * only 3 FIFO buffers. Dynamic payloads must be enabled. |
| 1161 | * |
| 1162 | * @note ACK payloads are dynamic payloads. Calling enableAckPayload() |
| 1163 | * will automatically enable dynamic payloads on pipe 0 (required for TX |
| 1164 | * mode when expecting ACK payloads) & pipe 1. To use ACK payloads on any other |
| 1165 | * pipe in RX mode, call enableDynamicPayloads(). |
| 1166 | * |
| 1167 | * @param pipe Which pipe# (typically 1-5) will get this response. |
| 1168 | * @param buf Pointer to data that is sent |
| 1169 | * @param len Length of the data to send, up to 32 bytes max. Not affected |
| 1170 | * by the static payload size set by setPayloadSize(). |
| 1171 | * |
| 1172 | * @note The `len` parameter must be omitted when using the python |
| 1173 | * wrapper because the length of the payload is determined automatically. |
| 1174 | * To use this function in the python wrapper: |
| 1175 | * @code{.py} |
| 1176 | * # let `radio` be the instantiated RF24 object |
| 1177 | * buffer = b"Hello World" # a `bytes` object |
| 1178 | * radio.writeAckPayload(1, buffer) # load an ACK payload for response on pipe 1 |
| 1179 | * @endcode |
| 1180 | * |
| 1181 | * @return |
| 1182 | * - `true` if the payload was loaded into the TX FIFO. |
| 1183 | * - `false` if the payload wasn't loaded into the TX FIFO because it is |
| 1184 | * already full or the ACK payload feature is not enabled using |
| 1185 | * enableAckPayload(). |
| 1186 | */ |
| 1187 | bool writeAckPayload(uint8_t pipe, const void* buf, uint8_t len); |
| 1188 | |
| 1189 | /** |
| 1190 | * Clear the Status flags that caused an interrupt event. |
| 1191 | * |
| 1192 | * @remark This function is similar to `whatHappened()` because it also returns the |
| 1193 | * Status flags that caused the interrupt event. However, this function returns |
| 1194 | * a STATUS byte instead of bit-banging into 3 1-byte booleans |
| 1195 | * passed by reference. |
| 1196 | * |
| 1197 | * @note When used in an ISR (Interrupt Service routine), there is a chance that the |
| 1198 | * returned bits 0b1110 (rx_pipe number) is inaccurate. See available(uint8_t*) (or the |
| 1199 | * datasheet) for more detail. |
| 1200 | * |
| 1201 | * @param flags The IRQ flags to clear. Default value is all of them (`RF24_IRQ_ALL`). |
| 1202 | * Multiple flags can be cleared by OR-ing rf24_irq_flags_e values together. |
| 1203 | * |
| 1204 | * @returns The STATUS byte from the radio's register before it was modified. Use |
| 1205 | * enumerations of rf24_irq_flags_e as masks to interpret the STATUS byte's meaning(s). |
| 1206 | * |
| 1207 | * @ingroup StatusFlags |
| 1208 | */ |
| 1209 | uint8_t clearStatusFlags(uint8_t flags = RF24_IRQ_ALL); |
| 1210 | |
| 1211 | /** |
| 1212 | * Set which flags shall be reflected on the radio's IRQ pin. |
| 1213 | * |
| 1214 | * @remarks This function is similar to maskIRQ() but with less confusing parameters. |
| 1215 | * |
| 1216 | * @param flags A value of rf24_irq_flags_e to influence the radio's IRQ pin. |
| 1217 | * The default value (`RF24_IRQ_NONE`) will disable the radio's IRQ pin. |
| 1218 | * Multiple events can be enabled by OR-ing rf24_irq_flags_e values together. |
| 1219 | * ```cpp |
| 1220 | * radio.setStatusFlags(RF24_IRQ_ALL); |
| 1221 | * // is equivalent to |
| 1222 | * radio.setStatusFlags(RF24_RX_DR | RF24_TX_DS | RF24_TX_DF); |
| 1223 | * ``` |
| 1224 | * |
| 1225 | * @ingroup StatusFlags |
| 1226 | */ |
| 1227 | void setStatusFlags(uint8_t flags = RF24_IRQ_NONE); |
| 1228 | |
| 1229 | /** |
| 1230 | * Get the latest STATUS byte returned from the last SPI transaction. |
| 1231 | * |
| 1232 | * @note This does not actually perform any SPI transaction with the radio. |
| 1233 | * Use `RF24::update()` instead to get a fresh copy of the Status flags at |
| 1234 | * the slight cost of performance. |
| 1235 | * |
| 1236 | * @returns The STATUS byte from the radio's register as the latest SPI transaction. Use |
| 1237 | * enumerations of rf24_irq_flags_e as masks to interpret the STATUS byte's meaning(s). |
| 1238 | * |
| 1239 | * @ingroup StatusFlags |
| 1240 | */ |
| 1241 | uint8_t getStatusFlags(); |
| 1242 | |
| 1243 | /** |
| 1244 | * Get an updated STATUS byte from the radio. |
| 1245 | * |
| 1246 | * @returns The STATUS byte fetched from the radio's register. Use enumerations of |
| 1247 | * rf24_irq_flags_e as masks to interpret the STATUS byte's meaning(s). |
| 1248 | * |
| 1249 | * @ingroup StatusFlags |
| 1250 | */ |
| 1251 | uint8_t update(); |
| 1252 | |
| 1253 | /** |
| 1254 | * Non-blocking write to the open writing pipe used for buffered writes |
| 1255 | * |
| 1256 | * @note Optimization: This function now leaves the CE pin high, so the radio |
| 1257 | * will remain in TX or STANDBY-II Mode until a txStandBy() command is issued. Can be used as an alternative to startWrite() |
| 1258 | * if writing multiple payloads at once. |
| 1259 | * @warning It is important to never keep the nRF24L01 in TX mode with FIFO full for more than 4ms at a time. If the auto |
| 1260 | * retransmit/autoAck is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO |
| 1261 | * to clear by issuing txStandBy() or ensure appropriate time between transmissions. |
| 1262 | * |
| 1263 | * @see |
| 1264 | * - write() |
| 1265 | * - writeFast() |
| 1266 | * - startWrite() |
| 1267 | * - writeBlocking() |
| 1268 | * - setAutoAck() (for single noAck writes) |
| 1269 | * |
| 1270 | * @param buf Pointer to the data to be sent |
| 1271 | * @param len Number of bytes to be sent |
| 1272 | * @param multicast Request ACK response (false), or no ACK response |
| 1273 | * (true). Be sure to have called enableDynamicAck() at least once before |
| 1274 | * setting this parameter. |
| 1275 | * @param startTx If this is set to `true`, then this function sets the |
| 1276 | * nRF24L01's CE pin to active (enabling TX transmissions). `false` has no |
| 1277 | * effect on the nRF24L01's CE pin and simply loads the payload into the |
| 1278 | * TX FIFO. |
| 1279 | * |
| 1280 | * @note The `len` parameter must be omitted when using the python |
| 1281 | * wrapper because the length of the payload is determined automatically. |
| 1282 | * To use this function in the python wrapper: |
| 1283 | * @code{.py} |
| 1284 | * # let `radio` be the instantiated RF24 object |
| 1285 | * buffer = b"Hello World" # a `bytes` object |
| 1286 | * radio.startFastWrite(buffer, False, True) # 3rd parameter is optional |
| 1287 | * # False means expecting ACK response (multicast parameter) |
| 1288 | * # True means initiate transmission (startTx parameter) |
| 1289 | * @endcode |
| 1290 | */ |
| 1291 | void startFastWrite(const void* buf, uint8_t len, const bool multicast, bool startTx = 1); |
| 1292 | |
| 1293 | /** |
| 1294 | * Non-blocking write to the open writing pipe |
| 1295 | * |
| 1296 | * Just like write(), but it returns immediately. To find out what happened |
| 1297 | * to the send, catch the IRQ and then call clearStatusFlags() or update(). |
| 1298 | * |
| 1299 | * @see |
| 1300 | * - write() |
| 1301 | * - writeFast() |
| 1302 | * - startFastWrite() |
| 1303 | * - clearStatusFlags() |
| 1304 | * - setAutoAck() (for single noAck writes) |
| 1305 | * |
| 1306 | * @param buf Pointer to the data to be sent |
| 1307 | * @param len Number of bytes to be sent |
| 1308 | * @param multicast Request ACK response (false), or no ACK response |
| 1309 | * (true). Be sure to have called enableDynamicAck() at least once before |
| 1310 | * setting this parameter. |
| 1311 | * |
| 1312 | * @return |
| 1313 | * - `true` if payload was written to the TX FIFO buffers and the |
| 1314 | * transmission was started. |
| 1315 | * - `false` if the TX FIFO is full and the payload could not be written. In |
| 1316 | * this condition, the transmission process is restarted. |
| 1317 | * @note The `len` parameter must be omitted when using the python |
| 1318 | * wrapper because the length of the payload is determined automatically. |
| 1319 | * To use this function in the python wrapper: |
| 1320 | * @code{.py} |
| 1321 | * # let `radio` be the instantiated RF24 object |
| 1322 | * buffer = b"Hello World" # a `bytes` object |
| 1323 | * radio.startWrite(buffer, False) # False = the multicast parameter |
| 1324 | * @endcode |
| 1325 | */ |
| 1326 | bool startWrite(const void* buf, uint8_t len, const bool multicast); |
| 1327 | |
| 1328 | /** |
| 1329 | * The function will instruct the radio to re-use the payload in the |
| 1330 | * top level (first out) of the TX FIFO buffers. This is used internally |
| 1331 | * by writeBlocking() to initiate retries when a TX failure |
| 1332 | * occurs. Retries are automatically initiated except with the standard |
| 1333 | * write(). This way, data is not flushed from the buffer until calling |
| 1334 | * flush_tx(). If the TX FIFO has only the one payload (in the top level), |
| 1335 | * the re-used payload can be overwritten by using write(), writeFast(), |
| 1336 | * writeBlocking(), startWrite(), or startFastWrite(). If the TX FIFO has |
| 1337 | * other payloads enqueued, then the aforementioned functions will attempt |
| 1338 | * to enqueue the a new payload in the TX FIFO (does not overwrite the top |
| 1339 | * level of the TX FIFO). Currently, stopListening() also calls flush_tx() |
| 1340 | * when ACK payloads are enabled (via enableAckPayload()). |
| 1341 | * |
| 1342 | * Upon exiting, this function will set the CE pin HIGH to initiate the |
| 1343 | * re-transmission process. If only 1 re-transmission is desired, then the |
| 1344 | * CE pin should be set to LOW after the mandatory minumum pulse duration |
| 1345 | * of 10 microseconds. |
| 1346 | * |
| 1347 | * @remark This function only applies when taking advantage of the |
| 1348 | * auto-retry feature. See setAutoAck() and setRetries() to configure the |
| 1349 | * auto-retry feature. |
| 1350 | * |
| 1351 | * @note This is to be used AFTER auto-retry fails if wanting to resend |
| 1352 | * using the built-in payload reuse feature. After issuing reUseTX(), it |
| 1353 | * will keep resending the same payload until a transmission failure |
| 1354 | * occurs or the CE pin is set to LOW (whichever comes first). In the |
| 1355 | * event of a re-transmission failure, simply call this function again to |
| 1356 | * resume re-transmission of the same payload. |
| 1357 | */ |
| 1358 | void reUseTX(); |
| 1359 | |
| 1360 | /** |
| 1361 | * Empty all 3 of the TX (transmit) FIFO buffers. This is automatically |
| 1362 | * called by stopListening() if ACK payloads are enabled. However, |
| 1363 | * startListening() does not call this function. |
| 1364 | * |
| 1365 | * @return Current value of status register |
| 1366 | */ |
| 1367 | uint8_t flush_tx(void); |
| 1368 | |
| 1369 | /** |
| 1370 | * Empty all 3 of the RX (receive) FIFO buffers. |
| 1371 | * |
| 1372 | * @return Current value of status register |
| 1373 | */ |
| 1374 | uint8_t flush_rx(void); |
| 1375 | |
| 1376 | /** |
| 1377 | * Test whether there was a carrier on the line for the |
| 1378 | * previous listening period. |
| 1379 | * |
| 1380 | * Useful to check for interference on the current channel. |
| 1381 | * |
| 1382 | * @return true if was carrier, false if not |
| 1383 | */ |
| 1384 | bool testCarrier(void); |
| 1385 | |
| 1386 | /** |
| 1387 | * Test whether a signal (carrier or otherwise) greater than |
| 1388 | * or equal to -64dBm is present on the channel. Valid only |
| 1389 | * on nRF24L01P (+) hardware. On nRF24L01, use testCarrier(). |
| 1390 | * |
| 1391 | * Useful to check for interference on the current channel and |
| 1392 | * channel hopping strategies. |
| 1393 | * |
| 1394 | * @code |
| 1395 | * bool goodSignal = radio.testRPD(); |
| 1396 | * if(radio.available()){ |
| 1397 | * Serial.println(goodSignal ? "Strong signal > -64dBm" : "Weak signal < -64dBm" ); |
| 1398 | * radio.read(&payload,sizeof(payload)); |
| 1399 | * } |
| 1400 | * @endcode |
| 1401 | * @return true if a signal greater than or equal to -64dBm was detected, |
| 1402 | * false if not. |
| 1403 | */ |
| 1404 | bool testRPD(void); |
| 1405 | |
| 1406 | /** |
| 1407 | * Test whether this is a real radio, or a mock shim for |
| 1408 | * debugging. Setting either pin to 0xff is the way to |
| 1409 | * indicate that this is not a real radio. |
| 1410 | * |
| 1411 | * @return true if this is a legitimate radio |
| 1412 | */ |
| 1413 | bool isValid(); |
| 1414 | |
| 1415 | /** |
| 1416 | * Close a pipe after it has been previously opened. |
| 1417 | * Can be safely called without having previously opened a pipe. |
| 1418 | * @param pipe Which pipe number to close, any integer not in range [0, 5] |
| 1419 | * is ignored. |
| 1420 | */ |
| 1421 | void closeReadingPipe(uint8_t pipe); |
| 1422 | |
| 1423 | #if defined(FAILURE_HANDLING) |
| 1424 | /** |
| 1425 | * |
| 1426 | * If a failure has been detected, it usually indicates a hardware issue. By default the library |
| 1427 | * will cease operation when a failure is detected. |
| 1428 | * This should allow advanced users to detect and resolve intermittent hardware issues. |
| 1429 | * |
| 1430 | * In most cases, the radio must be re-enabled via radio.begin(); and the appropriate settings |
| 1431 | * applied after a failure occurs, if wanting to re-enable the device immediately. |
| 1432 | * |
| 1433 | * The three main failure modes of the radio include: |
| 1434 | * |
| 1435 | * 1. Writing to radio: Radio unresponsive |
| 1436 | * - Fixed internally by adding a timeout to the internal write functions in RF24 (failure handling) |
| 1437 | * 2. Reading from radio: Available returns true always |
| 1438 | * - Fixed by adding a timeout to available functions by the user. This is implemented internally in RF24Network. |
| 1439 | * 3. Radio configuration settings are lost |
| 1440 | * - Fixed by monitoring a value that is different from the default, and re-configuring the radio if this setting reverts to the default. |
| 1441 | * |
| 1442 | * See the included example, GettingStarted_HandlingFailures |
| 1443 | * |
| 1444 | * @code |
| 1445 | * if(radio.failureDetected) { |
| 1446 | * radio.begin(); // Attempt to re-configure the radio with defaults |
| 1447 | * radio.failureDetected = 0; // Reset the detection value |
| 1448 | * radio.openWritingPipe(addresses[1]); // Re-configure pipe addresses |
| 1449 | * radio.openReadingPipe(1, addresses[0]); |
| 1450 | * report_failure(); // Blink LEDs, send a message, etc. to indicate failure |
| 1451 | * } |
| 1452 | * @endcode |
| 1453 | */ |
| 1454 | bool failureDetected; |
| 1455 | uint16_t failureRecoveryAttempts; |
| 1456 | |
| 1457 | #endif // defined (FAILURE_HANDLING) |
| 1458 | |
| 1459 | /**@}*/ |
| 1460 | /** |
| 1461 | * @name Optional Configurators |
| 1462 | * |
| 1463 | * Methods you can use to get or set the configuration of the chip. |
| 1464 | * None are required. Calling begin() sets up a reasonable set of |
| 1465 | * defaults. |
| 1466 | */ |
| 1467 | /**@{*/ |
| 1468 | |
| 1469 | /** |
| 1470 | * Set the address width from 3 to 5 bytes (24, 32 or 40 bit) |
| 1471 | * |
| 1472 | * @param a_width The address width (in bytes) to use; this can be 3, 4 or |
| 1473 | * 5. |
| 1474 | */ |
| 1475 | void setAddressWidth(uint8_t a_width); |
| 1476 | |
| 1477 | /** |
| 1478 | * Set the number of retry attempts and delay between retry attempts when |
| 1479 | * transmitting a payload. The radio is waiting for an acknowledgement |
| 1480 | * (ACK) packet during the delay between retry attempts. |
| 1481 | * |
| 1482 | * @param delay How long to wait between each retry, in multiples of |
| 1483 | * 250 us. The minimum of 0 means 250 us, and the maximum of 15 means |
| 1484 | * 4000 us. The default value of 5 means 1500us (5 * 250 + 250). |
| 1485 | * @param count How many retries before giving up. The default/maximum is 15. Use |
| 1486 | * 0 to disable the auto-retry feature all together. |
| 1487 | * |
| 1488 | * @note Disable the auto-retry feature on a transmitter still uses the |
| 1489 | * auto-ack feature (if enabled), except it will not retry to transmit if |
| 1490 | * the payload was not acknowledged on the first attempt. |
| 1491 | */ |
| 1492 | void setRetries(uint8_t delay, uint8_t count); |
| 1493 | |
| 1494 | /** |
| 1495 | * Set RF communication channel. The frequency used by a channel is |
| 1496 | * calculated as: |
| 1497 | * @verbatim 2400 MHz + <channel number> @endverbatim |
| 1498 | * Meaning the default channel of 76 uses the approximate frequency of |
| 1499 | * 2476 MHz. |
| 1500 | * |
| 1501 | * @note In the python wrapper, this function is the setter of the |
| 1502 | * `channel` attribute.To use this function in the python wrapper: |
| 1503 | * @code{.py} |
| 1504 | * # let `radio` be the instantiated RF24 object |
| 1505 | * radio.channel = 2 # set the channel to 2 (2402 MHz) |
| 1506 | * @endcode |
| 1507 | * |
| 1508 | * @param channel Which RF channel to communicate on, 0-125 |
| 1509 | */ |
| 1510 | void setChannel(uint8_t channel); |
| 1511 | |
| 1512 | /** |
| 1513 | * Get RF communication channel |
| 1514 | * |
| 1515 | * @note In the python wrapper, this function is the getter of the |
| 1516 | * `channel` attribute.To use this function in the python wrapper: |
| 1517 | * @code{.py} |
| 1518 | * # let `radio` be the instantiated RF24 object |
| 1519 | * chn = radio.channel # get the channel |
| 1520 | * @endcode |
| 1521 | * |
| 1522 | * @return The currently configured RF Channel |
| 1523 | */ |
| 1524 | uint8_t getChannel(void); |
| 1525 | |
| 1526 | /** |
| 1527 | * Set Static Payload Size |
| 1528 | * |
| 1529 | * This implementation uses a pre-established fixed payload size for all |
| 1530 | * transmissions. If this method is never called, the driver will always |
| 1531 | * transmit the maximum payload size (32 bytes), no matter how much |
| 1532 | * was sent to write(). |
| 1533 | * |
| 1534 | * @note In the python wrapper, this function is the setter of the |
| 1535 | * `payloadSize` attribute.To use this function in the python wrapper: |
| 1536 | * @code{.py} |
| 1537 | * # let `radio` be the instantiated RF24 object |
| 1538 | * radio.payloadSize = 16 # set the static payload size to 16 bytes |
| 1539 | * @endcode |
| 1540 | * |
| 1541 | * @param size The number of bytes in the payload |
| 1542 | */ |
| 1543 | void setPayloadSize(uint8_t size); |
| 1544 | |
| 1545 | /** |
| 1546 | * Get Static Payload Size |
| 1547 | * |
| 1548 | * @note In the python wrapper, this function is the getter of the |
| 1549 | * `payloadSize` attribute.To use this function in the python wrapper: |
| 1550 | * @code{.py} |
| 1551 | * # let `radio` be the instantiated RF24 object |
| 1552 | * pl_size = radio.payloadSize # get the static payload size |
| 1553 | * @endcode |
| 1554 | * |
| 1555 | * @see setPayloadSize() |
| 1556 | * |
| 1557 | * @return The number of bytes in the payload |
| 1558 | */ |
| 1559 | uint8_t getPayloadSize(void); |
| 1560 | |
| 1561 | /** |
| 1562 | * Get Dynamic Payload Size |
| 1563 | * |
| 1564 | * For dynamic payloads, this pulls the size of the payload off |
| 1565 | * the chip |
| 1566 | * |
| 1567 | * @note Corrupt packets are now detected and flushed per the |
| 1568 | * manufacturer. |
| 1569 | * @code |
| 1570 | * if(radio.available()){ |
| 1571 | * if(radio.getDynamicPayloadSize() < 1){ |
| 1572 | * // Corrupt payload has been flushed |
| 1573 | * return; |
| 1574 | * } |
| 1575 | * radio.read(&data,sizeof(data)); |
| 1576 | * } |
| 1577 | * @endcode |
| 1578 | * |
| 1579 | * @return Payload length of last-received dynamic payload |
| 1580 | */ |
| 1581 | uint8_t getDynamicPayloadSize(void); |
| 1582 | |
| 1583 | /** |
| 1584 | * Enable custom payloads in the acknowledge packets |
| 1585 | * |
| 1586 | * ACK payloads are a handy way to return data back to senders without |
| 1587 | * manually changing the radio modes on both units. |
| 1588 | * |
| 1589 | * @remarks The ACK payload feature requires the auto-ack feature to be |
| 1590 | * enabled for any pipe using ACK payloads. This function does not |
| 1591 | * automatically enable the auto-ack feature on pipe 0 since the auto-ack |
| 1592 | * feature is enabled for all pipes by default. |
| 1593 | * |
| 1594 | * @see setAutoAck() |
| 1595 | * |
| 1596 | * @note ACK payloads are dynamic payloads. This function automatically |
| 1597 | * enables dynamic payloads on pipes 0 & 1 by default. Call |
| 1598 | * enableDynamicPayloads() to enable on all pipes (especially for RX nodes |
| 1599 | * that use pipes other than pipe 0 to receive transmissions expecting |
| 1600 | * responses with ACK payloads). |
| 1601 | */ |
| 1602 | void enableAckPayload(void); |
| 1603 | |
| 1604 | /** |
| 1605 | * Disable custom payloads on the acknowledge packets |
| 1606 | * |
| 1607 | * @see enableAckPayload() |
| 1608 | */ |
| 1609 | void disableAckPayload(void); |
| 1610 | |
| 1611 | /** |
| 1612 | * Enable dynamically-sized payloads |
| 1613 | * |
| 1614 | * This way you don't always have to send large packets just to send them |
| 1615 | * once in a while. This enables dynamic payloads on ALL pipes. |
| 1616 | * |
| 1617 | */ |
| 1618 | void enableDynamicPayloads(void); |
| 1619 | |
| 1620 | /** |
| 1621 | * Disable dynamically-sized payloads |
| 1622 | * |
| 1623 | * This disables dynamic payloads on ALL pipes. Since Ack Payloads |
| 1624 | * requires Dynamic Payloads, Ack Payloads are also disabled. |
| 1625 | * If dynamic payloads are later re-enabled and ack payloads are desired |
| 1626 | * then enableAckPayload() must be called again as well. |
| 1627 | * |
| 1628 | */ |
| 1629 | void disableDynamicPayloads(void); |
| 1630 | |
| 1631 | /** |
| 1632 | * Enable dynamic ACKs (single write multicast or unicast) for chosen |
| 1633 | * messages. |
| 1634 | * |
| 1635 | * @note This function must be called once before using the multicast |
| 1636 | * parameter for any functions that offer it. To use multicast behavior |
| 1637 | * about all outgoing payloads (using pipe 0) or incoming payloads |
| 1638 | * (concerning all RX pipes), use setAutoAck() |
| 1639 | * |
| 1640 | * @see |
| 1641 | * - setAutoAck() for all pipes |
| 1642 | * - setAutoAck(uint8_t, bool) for individual pipes |
| 1643 | * |
| 1644 | * @code |
| 1645 | * radio.write(&data, 32, 1); // Sends a payload with no acknowledgement requested |
| 1646 | * radio.write(&data, 32, 0); // Sends a payload using auto-retry/autoACK |
| 1647 | * @endcode |
| 1648 | */ |
| 1649 | void enableDynamicAck(); |
| 1650 | |
| 1651 | /** |
| 1652 | * Determine whether the hardware is an nRF24L01+ or not. |
| 1653 | * |
| 1654 | * @return true if the hardware is nRF24L01+ (or compatible) and false |
| 1655 | * if its not. |
| 1656 | */ |
| 1657 | bool isPVariant(void); |
| 1658 | |
| 1659 | /** |
| 1660 | * Enable or disable the auto-acknowledgement feature for all pipes. This |
| 1661 | * feature is enabled by default. Auto-acknowledgement responds to every |
| 1662 | * received payload with an empty ACK packet. These ACK packets get sent |
| 1663 | * from the receiving radio back to the transmitting radio. To attach an |
| 1664 | * ACK payload to a ACK packet, use writeAckPayload(). |
| 1665 | * |
| 1666 | * If this feature is disabled on a transmitting radio, then the |
| 1667 | * transmitting radio will always report that the payload was received |
| 1668 | * (even if it was not). Please remember that this feature's configuration |
| 1669 | * needs to match for transmitting and receiving radios. |
| 1670 | * |
| 1671 | * @warning When using the `multicast` parameter to write(), this feature |
| 1672 | * can be disabled for an individual payload. However, if this feature is |
| 1673 | * disabled, then the `multicast` parameter will have no effect. |
| 1674 | * |
| 1675 | * @note If disabling auto-acknowledgment packets, the ACK payloads |
| 1676 | * feature is also disabled as this feature is required to send ACK |
| 1677 | * payloads. |
| 1678 | * |
| 1679 | * @see |
| 1680 | * - write() |
| 1681 | * - writeFast() |
| 1682 | * - startFastWrite() |
| 1683 | * - startWrite() |
| 1684 | * - writeAckPayload() |
| 1685 | * |
| 1686 | * @param enable Whether to enable (true) or disable (false) the |
| 1687 | * auto-acknowledgment feature for all pipes |
| 1688 | */ |
| 1689 | void setAutoAck(bool enable); |
| 1690 | |
| 1691 | /** |
| 1692 | * Enable or disable the auto-acknowledgement feature for a specific pipe. |
| 1693 | * This feature is enabled by default for all pipes. Auto-acknowledgement |
| 1694 | * responds to every received payload with an empty ACK packet. These ACK |
| 1695 | * packets get sent from the receiving radio back to the transmitting |
| 1696 | * radio. To attach an ACK payload to a ACK packet, use writeAckPayload(). |
| 1697 | * |
| 1698 | * Pipe 0 is used for TX operations, which include sending ACK packets. If |
| 1699 | * using this feature on both TX & RX nodes, then pipe 0 must have this |
| 1700 | * feature enabled for the RX & TX operations. If this feature is disabled |
| 1701 | * on a transmitting radio's pipe 0, then the transmitting radio will |
| 1702 | * always report that the payload was received (even if it was not). |
| 1703 | * Remember to also enable this feature for any pipe that is openly |
| 1704 | * listening to a transmitting radio with this feature enabled. |
| 1705 | * |
| 1706 | * @warning If this feature is enabled for pipe 0, then the `multicast` |
| 1707 | * parameter to write() can be used to disable this feature for an |
| 1708 | * individual payload. However, if this feature is disabled for pipe 0, |
| 1709 | * then the `multicast` parameter will have no effect. |
| 1710 | * |
| 1711 | * @note If disabling auto-acknowledgment packets on pipe 0, the ACK |
| 1712 | * payloads feature is also disabled as this feature is required on pipe 0 |
| 1713 | * to send ACK payloads. |
| 1714 | * |
| 1715 | * @see |
| 1716 | * - write() |
| 1717 | * - writeFast() |
| 1718 | * - startFastWrite() |
| 1719 | * - startWrite() |
| 1720 | * - writeAckPayload() |
| 1721 | * - enableAckPayload() |
| 1722 | * - disableAckPayload() |
| 1723 | * |
| 1724 | * @param pipe Which pipe to configure. This number should be in range |
| 1725 | * [0, 5]. |
| 1726 | * @param enable Whether to enable (true) or disable (false) the |
| 1727 | * auto-acknowledgment feature for the specified pipe |
| 1728 | */ |
| 1729 | void setAutoAck(uint8_t pipe, bool enable); |
| 1730 | |
| 1731 | /** |
| 1732 | * Set Power Amplifier (PA) level and Low Noise Amplifier (LNA) state |
| 1733 | * |
| 1734 | * @param level The desired @ref PALevel as defined by @ref rf24_pa_dbm_e. |
| 1735 | * @param lnaEnable Enable or Disable the LNA (Low Noise Amplifier) Gain. |
| 1736 | * See table for Si24R1 modules below. @p lnaEnable only affects |
| 1737 | * nRF24L01 modules with an LNA chip. |
| 1738 | * |
| 1739 | * | @p level (enum value) | nRF24L01<br>description | Si24R1<br>description when<br> @p lnaEnable = 1 | Si24R1<br>description when<br> @p lnaEnable = 0 | |
| 1740 | * |:---------------------:|:-------:|:--------:|:-------:| |
| 1741 | * | @ref RF24_PA_MIN (0) | -18 dBm | -6 dBm | -12 dBm | |
| 1742 | * | @ref RF24_PA_LOW (1) | -12 dBm | -0 dBm | -4 dBm | |
| 1743 | * | @ref RF24_PA_HIGH (2) | -6 dBm | 3 dBm | 1 dBm | |
| 1744 | * | @ref RF24_PA_MAX (3) | 0 dBm | 7 dBm | 4 dBm | |
| 1745 | * |
| 1746 | * @note The getPALevel() function does not care what was passed @p lnaEnable parameter. |
| 1747 | */ |
| 1748 | void setPALevel(uint8_t level, bool lnaEnable = 1); |
| 1749 | |
| 1750 | /** |
| 1751 | * Fetches the current @ref PALevel. |
| 1752 | * |
| 1753 | * @return One of the values defined by @ref rf24_pa_dbm_e. |
| 1754 | * See tables in @ref rf24_pa_dbm_e or setPALevel() |
| 1755 | */ |
| 1756 | uint8_t getPALevel(void); |
| 1757 | |
| 1758 | /** |
| 1759 | * Returns automatic retransmission count (ARC_CNT) |
| 1760 | * |
| 1761 | * Value resets with each new transmission. Allows roughly estimating signal strength. |
| 1762 | * |
| 1763 | * @return Returns values from 0 to 15. |
| 1764 | */ |
| 1765 | uint8_t getARC(void); |
| 1766 | |
| 1767 | /** |
| 1768 | * Set the transmission @ref Datarate |
| 1769 | * |
| 1770 | * @warning setting @ref RF24_250KBPS will fail for non-plus modules (when |
| 1771 | * isPVariant() returns false). |
| 1772 | * |
| 1773 | * @param speed Specify one of the following values (as defined by |
| 1774 | * @ref rf24_datarate_e): |
| 1775 | * | @p speed (enum value) | description | |
| 1776 | * |:---------------------:|:------------:| |
| 1777 | * | @ref RF24_1MBPS (0) | for 1 Mbps | |
| 1778 | * | @ref RF24_2MBPS (1) | for 2 Mbps | |
| 1779 | * | @ref RF24_250KBPS (2) | for 250 kbps | |
| 1780 | * |
| 1781 | * @return true if the change was successful |
| 1782 | */ |
| 1783 | bool setDataRate(rf24_datarate_e speed); |
| 1784 | |
| 1785 | /** |
| 1786 | * Fetches the currently configured transmission @ref Datarate |
| 1787 | * |
| 1788 | * @return One of the values defined by @ref rf24_datarate_e. |
| 1789 | * See table in @ref rf24_datarate_e or setDataRate() |
| 1790 | */ |
| 1791 | rf24_datarate_e getDataRate(void); |
| 1792 | |
| 1793 | /** |
| 1794 | * Set the @ref CRCLength (in bits) |
| 1795 | * |
| 1796 | * CRC cannot be disabled if auto-ack is enabled |
| 1797 | * @param length Specify one of the values (as defined by @ref rf24_crclength_e) |
| 1798 | * | @p length (enum value) | description | |
| 1799 | * |:--------------------------:|:------------------------------:| |
| 1800 | * | @ref RF24_CRC_DISABLED (0) | to disable using CRC checksums | |
| 1801 | * | @ref RF24_CRC_8 (1) | to use 8-bit checksums | |
| 1802 | * | @ref RF24_CRC_16 (2) | to use 16-bit checksums | |
| 1803 | */ |
| 1804 | void setCRCLength(rf24_crclength_e length); |
| 1805 | |
| 1806 | /** |
| 1807 | * Get the @ref CRCLength (in bits) |
| 1808 | * |
| 1809 | * CRC checking cannot be disabled if auto-ack is enabled |
| 1810 | * @return One of the values defined by @ref rf24_crclength_e. |
| 1811 | * See table in @ref rf24_crclength_e or setCRCLength() |
| 1812 | */ |
| 1813 | rf24_crclength_e getCRCLength(void); |
| 1814 | |
| 1815 | /** |
| 1816 | * Disable CRC validation |
| 1817 | * |
| 1818 | * @warning CRC cannot be disabled if auto-ack/ESB is enabled. |
| 1819 | */ |
| 1820 | void disableCRC(void); |
| 1821 | |
| 1822 | /** |
| 1823 | * |
| 1824 | * The driver will delay for this duration when stopListening() is called |
| 1825 | * |
| 1826 | * When responding to payloads, faster devices like ARM(RPi) are much faster than Arduino: |
| 1827 | * 1. Arduino sends data to RPi, switches to RX mode |
| 1828 | * 2. The RPi receives the data, switches to TX mode and sends before the Arduino radio is in RX mode |
| 1829 | * 3. If AutoACK is disabled, this can be set as low as 0. If AA/ESB enabled, set to 100uS minimum on RPi |
| 1830 | * |
| 1831 | * @warning If set to 0, ensure 130uS delay after stopListening() and before any sends |
| 1832 | */ |
| 1833 | uint32_t txDelay; |
| 1834 | |
| 1835 | /** |
| 1836 | * |
| 1837 | * On all devices but Linux and ATTiny, a small delay is added to the CSN toggling function |
| 1838 | * |
| 1839 | * This is intended to minimize the speed of SPI polling due to radio commands |
| 1840 | * |
| 1841 | * If using interrupts or timed requests, this can be set to 0 Default:5 |
| 1842 | */ |
| 1843 | uint32_t csDelay; |
| 1844 | |
| 1845 | /** |
| 1846 | * Transmission of constant carrier wave with defined frequency and output power |
| 1847 | * |
| 1848 | * @param level Output power to use |
| 1849 | * @param channel The channel to use |
| 1850 | * |
| 1851 | * @warning If isPVariant() returns true, then this function takes extra |
| 1852 | * measures that alter some settings. These settings alterations include: |
| 1853 | * - setAutoAck() to false (for all pipes) |
| 1854 | * - setRetries() to retry `0` times with a delay of 250 microseconds |
| 1855 | * - set the TX address to 5 bytes of `0xFF` |
| 1856 | * - flush_tx() |
| 1857 | * - load a 32 byte payload of `0xFF` into the TX FIFO's top level |
| 1858 | * - disableCRC() |
| 1859 | */ |
| 1860 | void startConstCarrier(rf24_pa_dbm_e level, uint8_t channel); |
| 1861 | |
| 1862 | /** |
| 1863 | * Stop transmission of constant wave and reset PLL and CONT registers |
| 1864 | * |
| 1865 | * @warning this function will powerDown() the radio per recommendation of |
| 1866 | * datasheet. |
| 1867 | * @note If isPVariant() returns true, please remember to re-configure the radio's settings |
| 1868 | * @code |
| 1869 | * // re-establish default settings |
| 1870 | * setCRCLength(RF24_CRC_16); |
| 1871 | * setAutoAck(true); |
| 1872 | * setRetries(5, 15); |
| 1873 | * @endcode |
| 1874 | * @see startConstCarrier() |
| 1875 | */ |
| 1876 | void stopConstCarrier(void); |
| 1877 | |
| 1878 | /** |
| 1879 | * @brief Open or close all data pipes. |
| 1880 | * |
| 1881 | * This function does not alter the addresses assigned to pipes. It is simply a |
| 1882 | * convenience function that allows controlling all pipes at once. |
| 1883 | * @param isEnabled `true` opens all pipes; `false` closes all pipes. |
| 1884 | */ |
| 1885 | void toggleAllPipes(bool isEnabled); |
| 1886 | |
| 1887 | /** |
| 1888 | * @brief configure the RF_SETUP register in 1 transaction |
| 1889 | * @param level This parameter is the same input as setPALevel()'s `level` parameter. |
| 1890 | * See @ref rf24_pa_dbm_e enum for accepted values. |
| 1891 | * @param speed This parameter is the same input as setDataRate()'s `speed` parameter. |
| 1892 | * See @ref rf24_datarate_e enum for accepted values. |
| 1893 | * @param lnaEnable This optional parameter is the same as setPALevel()'s `lnaEnable` |
| 1894 | * optional parameter. Defaults to `true` (meaning LNA feature is enabled) when not specified. |
| 1895 | */ |
| 1896 | void setRadiation(uint8_t level, rf24_datarate_e speed, bool lnaEnable = true); |
| 1897 | |
| 1898 | /**@}*/ |
| 1899 | /** |
| 1900 | * @name Deprecated |
| 1901 | * |
| 1902 | * Methods provided for backwards compatibility. |
| 1903 | */ |
| 1904 | /**@{*/ |
| 1905 | |
| 1906 | /** |
| 1907 | * Open a pipe for reading |
| 1908 | * @deprecated For compatibility with old code only, see newer function |
| 1909 | * openReadingPipe(). |
| 1910 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 1911 | * |
| 1912 | * @note Pipes 1-5 should share the first 32 bits. |
| 1913 | * Only the least significant byte should be unique, e.g. |
| 1914 | * @code |
| 1915 | * openReadingPipe(1, 0xF0F0F0F0AA); |
| 1916 | * openReadingPipe(2, 0xF0F0F0F066); |
| 1917 | * @endcode |
| 1918 | * |
| 1919 | * @warning |
| 1920 | * @parblock |
| 1921 | * Pipe 0 is also used by the writing pipe so should typically be avoided as a reading pipe. |
| 1922 | * If used, the reading pipe 0 address needs to be restored at every call to startListening(). |
| 1923 | * |
| 1924 | * See http://maniacalbits.blogspot.com/2013/04/rf24-addressing-nrf24l01-radios-require.html |
| 1925 | * @endparblock |
| 1926 | * |
| 1927 | * @param number Which pipe# to open, 0-5. |
| 1928 | * @param address The 40-bit address of the pipe to open. |
| 1929 | */ |
| 1930 | void openReadingPipe(uint8_t number, uint64_t address); |
| 1931 | |
| 1932 | /** |
| 1933 | * Open a pipe for writing |
| 1934 | * @deprecated For compatibility with old code only, see newer function |
| 1935 | * openWritingPipe(). |
| 1936 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 1937 | * |
| 1938 | * Addresses are 40-bit hex values, e.g.: |
| 1939 | * |
| 1940 | * @code |
| 1941 | * openWritingPipe(0xF0F0F0F0F0); |
| 1942 | * @endcode |
| 1943 | * |
| 1944 | * @param address The 40-bit address of the pipe to open. |
| 1945 | */ |
| 1946 | void openWritingPipe(uint64_t address); |
| 1947 | |
| 1948 | /** |
| 1949 | * Determine if an ack payload was received in the most recent call to |
| 1950 | * write(). The regular available() can also be used. |
| 1951 | * |
| 1952 | * @deprecated For compatibility with old code only, see synonymous function available(). |
| 1953 | * Use read() to retrieve the ack payload and getDynamicPayloadSize() to get the ACK payload size. |
| 1954 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 1955 | * |
| 1956 | * @return True if an ack payload is available. |
| 1957 | */ |
| 1958 | bool isAckPayloadAvailable(void); |
| 1959 | |
| 1960 | /** |
| 1961 | * This function is used to configure what events will trigger the Interrupt |
| 1962 | * Request (IRQ) pin active LOW. |
| 1963 | * |
| 1964 | * @deprecated Use setStatusFlags() instead. |
| 1965 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 1966 | * |
| 1967 | * The following events can be configured: |
| 1968 | * 1. "data sent": This does not mean that the data transmitted was |
| 1969 | * received, only that the attempt to send it was complete. |
| 1970 | * 2. "data failed": This means the data being sent was not received. This |
| 1971 | * event is only triggered when the auto-ack feature is enabled. |
| 1972 | * 3. "data received": This means that data from a receiving payload has |
| 1973 | * been loaded into the RX FIFO buffers. Remember that there are only 3 |
| 1974 | * levels available in the RX FIFO buffers. |
| 1975 | * |
| 1976 | * By default, all events are configured to trigger the IRQ pin active LOW. |
| 1977 | * When the IRQ pin is active, use clearStatusFlags() or getStatusFlags() to |
| 1978 | * determine what events triggered it. |
| 1979 | * Remember that calling clearStatusFlags() also clears these |
| 1980 | * events' status, and the IRQ pin will then be reset to inactive HIGH. |
| 1981 | * |
| 1982 | * The following code configures the IRQ pin to only reflect the "data received" |
| 1983 | * event: |
| 1984 | * @code |
| 1985 | * radio.maskIRQ(1, 1, 0); |
| 1986 | * @endcode |
| 1987 | * |
| 1988 | * @param tx_ok `true` ignores the "data sent" event, `false` reflects the |
| 1989 | * "data sent" event on the IRQ pin. |
| 1990 | * @param tx_fail `true` ignores the "data failed" event, `false` reflects the |
| 1991 | * "data failed" event on the IRQ pin. |
| 1992 | * @param rx_ready `true` ignores the "data received" event, `false` reflects the |
| 1993 | * "data received" event on the IRQ pin. |
| 1994 | */ |
| 1995 | void maskIRQ(bool tx_ok, bool tx_fail, bool rx_ready); |
| 1996 | |
| 1997 | /** |
| 1998 | * Call this when you get an Interrupt Request (IRQ) to find out why |
| 1999 | * |
| 2000 | * This function describes what event triggered the IRQ pin to go active |
| 2001 | * LOW and clears the status of all events. |
| 2002 | * |
| 2003 | * @deprecated Use clearStatusFlags() instead. |
| 2004 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 2005 | * |
| 2006 | * @see setStatusFlags() |
| 2007 | * |
| 2008 | * @param[out] tx_ok The transmission attempt completed (TX_DS). This does |
| 2009 | * not imply that the transmitted data was received by another radio, rather |
| 2010 | * this only reports if the attempt to send was completed. This will |
| 2011 | * always be `true` when the auto-ack feature is disabled. |
| 2012 | * @param[out] tx_fail The transmission failed to be acknowledged, meaning |
| 2013 | * too many retries (MAX_RT) were made while expecting an ACK packet. This |
| 2014 | * event is only triggered when auto-ack feature is enabled. |
| 2015 | * @param[out] rx_ready There is a newly received payload (RX_DR) saved to |
| 2016 | * RX FIFO buffers. Remember that the RX FIFO can only hold up to 3 |
| 2017 | * payloads. Once the RX FIFO is full, all further received transmissions |
| 2018 | * are rejected until there is space to save new data in the RX FIFO |
| 2019 | * buffers. |
| 2020 | * |
| 2021 | * @note This function expects no parameters in the python wrapper. |
| 2022 | * Instead, this function returns a 3 item tuple describing the IRQ |
| 2023 | * events' status. To use this function in the python wrapper: |
| 2024 | * @code{.py} |
| 2025 | * # let`radio` be the instantiated RF24 object |
| 2026 | * tx_ds, tx_df, rx_dr = radio.whatHappened() # get IRQ status flags |
| 2027 | * print("tx_ds: {}, tx_df: {}, rx_dr: {}".format(tx_ds, tx_df, rx_dr)) |
| 2028 | * @endcode |
| 2029 | */ |
| 2030 | void whatHappened(bool& tx_ok, bool& tx_fail, bool& rx_ready); |
| 2031 | |
| 2032 | /** |
| 2033 | * Similar to startListening(void) but changes the TX address. |
| 2034 | * |
| 2035 | * @deprecated Use stopListening(const uint8_t*) instead. |
| 2036 | * See our [migration guide](migration.md) to understand what you should update in your code. |
| 2037 | * |
| 2038 | * @param txAddress The new TX address. |
| 2039 | * This value will be cached for auto-ack purposes. |
| 2040 | */ |
| 2041 | void stopListening(const uint64_t txAddress); |
| 2042 | |
| 2043 | private: |
| 2044 | /**@}*/ |
| 2045 | /** |
| 2046 | * @name Low-level internal interface. |
| 2047 | * |
| 2048 | * Protected methods that address the chip directly. Regular users cannot |
| 2049 | * ever call these. They are documented for completeness and for developers who |
| 2050 | * may want to extend this class. |
| 2051 | */ |
| 2052 | /**@{*/ |
| 2053 | |
| 2054 | /** |
| 2055 | * initializing function specific to all constructors |
| 2056 | * (regardless of constructor parameters) |
| 2057 | */ |
| 2058 | void _init_obj(); |
| 2059 | |
| 2060 | /** |
| 2061 | * initialize radio by performing a soft reset. |
| 2062 | * @warning This function assumes the SPI bus object's begin() method has been |
| 2063 | * previously called. |
| 2064 | */ |
| 2065 | bool _init_radio(); |
| 2066 | |
| 2067 | /** |
| 2068 | * initialize the GPIO pins |
| 2069 | */ |
| 2070 | bool _init_pins(); |
| 2071 | |
| 2072 | /** |
| 2073 | * Set chip select pin |
| 2074 | * |
| 2075 | * Running SPI bus at PI_CLOCK_DIV2 so we don't waste time transferring data |
| 2076 | * and best of all, we make use of the radio's FIFO buffers. A lower speed |
| 2077 | * means we're less likely to effectively leverage our FIFOs and pay a higher |
| 2078 | * AVR runtime cost as toll. |
| 2079 | * |
| 2080 | * @param mode HIGH to take this unit off the SPI bus, LOW to put it on |
| 2081 | */ |
| 2082 | void csn(bool mode); |
| 2083 | |
| 2084 | /** |
| 2085 | * Write a chunk of data to a register |
| 2086 | * |
| 2087 | * @param reg Which register. Use constants from nRF24L01.h |
| 2088 | * @param buf Where to get the data |
| 2089 | * @param len How many bytes of data to transfer |
| 2090 | * @return Nothing. Older versions of this function returned the status |
| 2091 | * byte, but that it now saved to a private member on all SPI transactions. |
| 2092 | */ |
| 2093 | void write_register(uint8_t reg, const uint8_t* buf, uint8_t len); |
| 2094 | |
| 2095 | /** |
| 2096 | * Write a single byte to a register |
| 2097 | * |
| 2098 | * @param reg Which register. Use constants from nRF24L01.h |
| 2099 | * @param value The new value to write |
| 2100 | * @return Nothing. Older versions of this function returned the status |
| 2101 | * byte, but that it now saved to a private member on all SPI transactions. |
| 2102 | */ |
| 2103 | void write_register(uint8_t reg, uint8_t value); |
| 2104 | |
| 2105 | /** |
| 2106 | * Write the transmit payload |
| 2107 | * |
| 2108 | * The size of data written is the fixed payload size, see getPayloadSize() |
| 2109 | * |
| 2110 | * @param buf Where to get the data |
| 2111 | * @param len Number of bytes to be sent |
| 2112 | * @param writeType Specify if individual payload should be acknowledged |
| 2113 | * @return Nothing. Older versions of this function returned the status |
| 2114 | * byte, but that it now saved to a private member on all SPI transactions. |
| 2115 | */ |
| 2116 | void write_payload(const void* buf, uint8_t len, const uint8_t writeType); |
| 2117 | |
| 2118 | /** |
| 2119 | * Read the receive payload |
| 2120 | * |
| 2121 | * The size of data read is the fixed payload size, see getPayloadSize() |
| 2122 | * |
| 2123 | * @param buf Where to put the data |
| 2124 | * @param len Maximum number of bytes to read |
| 2125 | * @return Nothing. Older versions of this function returned the status |
| 2126 | * byte, but that it now saved to a private member on all SPI transactions. |
| 2127 | */ |
| 2128 | void read_payload(void* buf, uint8_t len); |
| 2129 | |
| 2130 | #if !defined(MINIMAL) |
| 2131 | |
| 2132 | /** |
| 2133 | * Decode and print the given 'observe_tx' value to stdout |
| 2134 | * |
| 2135 | * @param value The observe_tx value to print |
| 2136 | * |
| 2137 | * @warning Does nothing if stdout is not defined. See fdevopen in stdio.h |
| 2138 | */ |
| 2139 | void print_observe_tx(uint8_t value); |
| 2140 | |
| 2141 | /** |
| 2142 | * Print the name and value of an 8-bit register to stdout |
| 2143 | * |
| 2144 | * Optionally it can print some quantity of successive |
| 2145 | * registers on the same line. This is useful for printing a group |
| 2146 | * of related registers on one line. |
| 2147 | * |
| 2148 | * @param name Name of the register |
| 2149 | * @param reg Which register. Use constants from nRF24L01.h |
| 2150 | * @param qty How many successive registers to print |
| 2151 | */ |
| 2152 | void print_byte_register(const char* name, uint8_t reg, uint8_t qty = 1); |
| 2153 | |
| 2154 | /** |
| 2155 | * Print the name and value of a 40-bit address register to stdout |
| 2156 | * |
| 2157 | * Optionally it can print some quantity of successive |
| 2158 | * registers on the same line. This is useful for printing a group |
| 2159 | * of related registers on one line. |
| 2160 | * |
| 2161 | * @param name Name of the register |
| 2162 | * @param reg Which register. Use constants from nRF24L01.h |
| 2163 | * @param qty How many successive registers to print |
| 2164 | */ |
| 2165 | void print_address_register(const char* name, uint8_t reg, uint8_t qty = 1); |
| 2166 | |
| 2167 | /** |
| 2168 | * Put the value of a 40-bit address register into a char array |
| 2169 | * |
| 2170 | * Optionally it can print some quantity of successive |
| 2171 | * registers on the same line. This is useful for printing a group |
| 2172 | * of related registers on one line. |
| 2173 | * |
| 2174 | * @param out_buffer Output buffer, char array |
| 2175 | * @param reg Which register. Use constants from nRF24L01.h |
| 2176 | * @param qty How many successive registers to print |
| 2177 | * @return The total number of characters written to the given buffer. |
| 2178 | */ |
| 2179 | uint8_t sprintf_address_register(char* out_buffer, uint8_t reg, uint8_t qty = 1); |
| 2180 | #endif |
| 2181 | |
| 2182 | /** |
| 2183 | * Turn on or off the special features of the chip |
| 2184 | * |
| 2185 | * The chip has certain 'features' which are only available when the 'features' |
| 2186 | * are enabled. See the datasheet for details. |
| 2187 | */ |
| 2188 | void toggle_features(void); |
| 2189 | |
| 2190 | #if defined(FAILURE_HANDLING) || defined(RF24_LINUX) |
| 2191 | |
| 2192 | void errNotify(void); |
| 2193 | inline int8_t errHandler(bool* doRecovery); |
| 2194 | inline void errHandler(); |
| 2195 | |
| 2196 | bool failureFlushed; |
| 2197 | #endif |
| 2198 | |
| 2199 | /** |
| 2200 | * @brief Manipulate the @ref Datarate and txDelay |
| 2201 | * |
| 2202 | * This is a helper function to setRadiation() and setDataRate() |
| 2203 | * @param speed The desired data rate. |
| 2204 | */ |
| 2205 | inline uint8_t _data_rate_reg_value(rf24_datarate_e speed); |
| 2206 | |
| 2207 | /** |
| 2208 | * @brief Manipulate the @ref PALevel |
| 2209 | * |
| 2210 | * This is a helper function to setRadiation() and setPALevel() |
| 2211 | * @param level The desired @ref PALevel. |
| 2212 | * @param lnaEnable Toggle the LNA feature. |
| 2213 | */ |
| 2214 | inline uint8_t _pa_level_reg_value(uint8_t level, bool lnaEnable); |
| 2215 | |
| 2216 | /**@}*/ |
| 2217 | }; |
| 2218 | |
| 2219 | /** |
| 2220 | * @example{lineno} examples/GettingStarted/GettingStarted.ino |
| 2221 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2222 | * |
| 2223 | * A simple example of sending data from 1 nRF24L01 transceiver to another. |
| 2224 | * |
| 2225 | * This example was written to be used on 2 devices acting as "nodes". |
| 2226 | * Use the Serial Monitor to change each node's behavior. |
| 2227 | */ |
| 2228 | |
| 2229 | /** |
| 2230 | * @example{lineno} examples/AcknowledgementPayloads/AcknowledgementPayloads.ino |
| 2231 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2232 | * |
| 2233 | * A simple example of sending data from 1 nRF24L01 transceiver to another |
| 2234 | * with Acknowledgement (ACK) payloads attached to ACK packets. |
| 2235 | * |
| 2236 | * This example was written to be used on 2 devices acting as "nodes". |
| 2237 | * Use the Serial Monitor to change each node's behavior. |
| 2238 | */ |
| 2239 | |
| 2240 | /** |
| 2241 | * @example{lineno} examples/ManualAcknowledgements/ManualAcknowledgements.ino |
| 2242 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2243 | * |
| 2244 | * A simple example of sending data from 1 nRF24L01 transceiver to another |
| 2245 | * with manually transmitted (non-automatic) Acknowledgement (ACK) payloads. |
| 2246 | * This example still uses ACK packets, but they have no payloads. Instead the |
| 2247 | * acknowledging response is sent with `write()`. This tactic allows for more |
| 2248 | * updated acknowledgement payload data, where actual ACK payloads' data are |
| 2249 | * outdated by 1 transmission because they have to loaded before receiving a |
| 2250 | * transmission. |
| 2251 | * |
| 2252 | * This example was written to be used on 2 devices acting as "nodes". |
| 2253 | * Use the Serial Monitor to change each node's behavior. |
| 2254 | */ |
| 2255 | |
| 2256 | /** |
| 2257 | * @example{lineno} examples/StreamingData/StreamingData.ino |
| 2258 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2259 | * |
| 2260 | * A simple example of streaming data from 1 nRF24L01 transceiver to another. |
| 2261 | * |
| 2262 | * This example was written to be used on 2 devices acting as "nodes". |
| 2263 | * Use the Serial Monitor to change each node's behavior. |
| 2264 | */ |
| 2265 | |
| 2266 | /** |
| 2267 | * @example{lineno} examples/MulticeiverDemo/MulticeiverDemo.ino |
| 2268 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2269 | * |
| 2270 | * A simple example of sending data from as many as 6 nRF24L01 transceivers to |
| 2271 | * 1 receiving transceiver. This technique is trademarked by |
| 2272 | * Nordic Semiconductors as "MultiCeiver". |
| 2273 | * |
| 2274 | * This example was written to be used on up to 6 devices acting as TX nodes & |
| 2275 | * only 1 device acting as the RX node (that's a maximum of 7 devices). |
| 2276 | * Use the Serial Monitor to change each node's behavior. |
| 2277 | */ |
| 2278 | |
| 2279 | /** |
| 2280 | * @example{lineno} examples/InterruptConfigure/InterruptConfigure.ino |
| 2281 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2282 | * |
| 2283 | * This example uses Acknowledgement (ACK) payloads attached to ACK packets to |
| 2284 | * demonstrate how the nRF24L01's IRQ (Interrupt Request) pin can be |
| 2285 | * configured to detect when data is received, or when data has transmitted |
| 2286 | * successfully, or when data has failed to transmit. |
| 2287 | * |
| 2288 | * This example was written to be used on 2 devices acting as "nodes". |
| 2289 | * Use the Serial Monitor to change each node's behavior. |
| 2290 | */ |
| 2291 | |
| 2292 | /** |
| 2293 | * @example{lineno} examples/old_backups/GettingStarted_HandlingFailures/GettingStarted_HandlingFailures.ino |
| 2294 | * Written by [TMRh20](http://github.com/TMRh20) in 2019 |
| 2295 | * |
| 2296 | * This example demonstrates the basic getting started functionality, but with |
| 2297 | * failure handling for the radio chip. Addresses random radio failures etc, |
| 2298 | * potentially due to loose wiring on breadboards etc. |
| 2299 | */ |
| 2300 | |
| 2301 | /** |
| 2302 | * @example{lineno} examples/old_backups/TransferTimeouts/TransferTimeouts.ino |
| 2303 | * Written by [TMRh20](https://github.com/TMRh20) |
| 2304 | * |
| 2305 | * This example demonstrates the use of and extended timeout period and |
| 2306 | * auto-retries/auto-reUse to increase reliability in noisy or low signal scenarios. |
| 2307 | * |
| 2308 | * Write this sketch to two different nodes. Put one of the nodes into 'transmit' |
| 2309 | * mode by connecting with the serial monitor and sending a 'T'. The data <br> |
| 2310 | * transfer will begin, with the receiver displaying the payload count and the |
| 2311 | * data transfer rate. |
| 2312 | */ |
| 2313 | |
| 2314 | /** |
| 2315 | * @example{lineno} examples/old_backups/pingpair_irq/pingpair_irq.ino |
| 2316 | * Updated by [TMRh20](https://github.com/TMRh20) |
| 2317 | * |
| 2318 | * This is an example of how to user interrupts to interact with the radio, and a demonstration |
| 2319 | * of how to use them to sleep when receiving, and not miss any payloads.<br> |
| 2320 | * The pingpair_sleepy example expands on sleep functionality with a timed sleep option for the transmitter. |
| 2321 | * Sleep functionality is built directly into my fork of the RF24Network library<br> |
| 2322 | */ |
| 2323 | |
| 2324 | /** |
| 2325 | * @example{lineno} examples/old_backups/pingpair_sleepy/pingpair_sleepy.ino |
| 2326 | * Updated by [TMRh20](https://github.com/TMRh20) |
| 2327 | * |
| 2328 | * This is an example of how to use the RF24 class to create a battery- |
| 2329 | * efficient system. It is just like the GettingStarted_CallResponse example, but the<br> |
| 2330 | * ping node powers down the radio and sleeps the MCU after every |
| 2331 | * ping/pong cycle, and the receiver sleeps between payloads. <br> |
| 2332 | */ |
| 2333 | |
| 2334 | /** |
| 2335 | * @example{lineno} examples/rf24_ATTiny/rf24ping85/rf24ping85.ino |
| 2336 | * <b>2014 Contribution by [tong67](https://github.com/tong67)</b><br> |
| 2337 | * Updated 2020 by [2bndy5](http://github.com/2bndy5) for the |
| 2338 | * [SpenceKonde ATTinyCore](https://github.com/SpenceKonde/ATTinyCore)<br> |
| 2339 | * The RF24 library uses the [ATTinyCore by |
| 2340 | * SpenceKonde](https://github.com/SpenceKonde/ATTinyCore) |
| 2341 | * |
| 2342 | * This sketch is a duplicate of the ManualAcknowledgements.ino example |
| 2343 | * (without all the Serial input/output code), and it demonstrates |
| 2344 | * a ATTiny25/45/85 or ATTiny24/44/84 driving the nRF24L01 transceiver using |
| 2345 | * the RF24 class to communicate with another node. |
| 2346 | * |
| 2347 | * A simple example of sending data from 1 nRF24L01 transceiver to another |
| 2348 | * with manually transmitted (non-automatic) Acknowledgement (ACK) payloads. |
| 2349 | * This example still uses ACK packets, but they have no payloads. Instead the |
| 2350 | * acknowledging response is sent with `write()`. This tactic allows for more |
| 2351 | * updated acknowledgement payload data, where actual ACK payloads' data are |
| 2352 | * outdated by 1 transmission because they have to loaded before receiving a |
| 2353 | * transmission. |
| 2354 | * |
| 2355 | * This example was written to be used on 2 devices acting as "nodes". |
| 2356 | */ |
| 2357 | |
| 2358 | /** |
| 2359 | * @example{lineno} examples/rf24_ATTiny/timingSearch3pin/timingSearch3pin.ino |
| 2360 | * <b>2014 Contribution by [tong67](https://github.com/tong67)</b><br> |
| 2361 | * Updated 2020 by [2bndy5](http://github.com/2bndy5) for the |
| 2362 | * [SpenceKonde ATTinyCore](https://github.com/SpenceKonde/ATTinyCore)<br> |
| 2363 | * The RF24 library uses the [ATTinyCore by |
| 2364 | * SpenceKonde](https://github.com/SpenceKonde/ATTinyCore) |
| 2365 | * |
| 2366 | * This sketch can be used to determine the best settle time values to use for |
| 2367 | * RF24::csDelay in RF24::csn() (private function). |
| 2368 | * @see RF24::csDelay |
| 2369 | * |
| 2370 | * The settle time values used here are 100/20. However, these values depend |
| 2371 | * on the actual used RC combination and voltage drop by LED. The |
| 2372 | * intermediate results are written to TX (PB3, pin 2 -- using Serial). |
| 2373 | * |
| 2374 | * For schematic details, see introductory comment block in the rf24ping85.ino sketch. |
| 2375 | */ |
| 2376 | |
| 2377 | /** |
| 2378 | * @example{lineno} examples/old_backups/pingpair_dyn/pingpair_dyn.ino |
| 2379 | * |
| 2380 | * This is an example of how to use payloads of a varying (dynamic) size on Arduino. |
| 2381 | */ |
| 2382 | |
| 2383 | /** |
| 2384 | * @example{lineno} examples_linux/getting_started.py |
| 2385 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2386 | * |
| 2387 | * This is a simple example of using the RF24 class on a Raspberry Pi. |
| 2388 | * |
| 2389 | * Remember to install the [Python wrapper](python_wrapper.md), then |
| 2390 | * navigate to the "RF24/examples_linux" folder. |
| 2391 | * <br>To run this example, enter |
| 2392 | * @code{.sh}python3 getting_started.py @endcode and follow the prompts. |
| 2393 | * |
| 2394 | * @note this example requires python v3.7 or newer because it measures |
| 2395 | * transmission time with `time.monotonic_ns()`. |
| 2396 | */ |
| 2397 | |
| 2398 | /** |
| 2399 | * @example{lineno} examples_linux/acknowledgement_payloads.py |
| 2400 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2401 | * |
| 2402 | * This is a simple example of using the RF24 class on a Raspberry Pi to |
| 2403 | * transmit and retrieve custom automatic acknowledgment payloads. |
| 2404 | * |
| 2405 | * Remember to install the [Python wrapper](python_wrapper.md), then |
| 2406 | * navigate to the "RF24/examples_linux" folder. |
| 2407 | * <br>To run this example, enter |
| 2408 | * @code{.sh}python3 acknowledgement_payloads.py @endcode and follow the prompts. |
| 2409 | * |
| 2410 | * @note this example requires python v3.7 or newer because it measures |
| 2411 | * transmission time with `time.monotonic_ns()`. |
| 2412 | */ |
| 2413 | |
| 2414 | /** |
| 2415 | * @example{lineno} examples_linux/manual_acknowledgements.py |
| 2416 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2417 | * |
| 2418 | * This is a simple example of using the RF24 class on a Raspberry Pi to |
| 2419 | * transmit and respond with acknowledgment (ACK) transmissions. Notice that |
| 2420 | * the auto-ack feature is enabled, but this example doesn't use automatic ACK |
| 2421 | * payloads because automatic ACK payloads' data will always be outdated by 1 |
| 2422 | * transmission. Instead, this example uses a call and response paradigm. |
| 2423 | * |
| 2424 | * Remember to install the [Python wrapper](python_wrapper.md), then |
| 2425 | * navigate to the "RF24/examples_linux" folder. |
| 2426 | * <br>To run this example, enter |
| 2427 | * @code{.sh}python3 manual_acknowledgements.py @endcode and follow the prompts. |
| 2428 | * |
| 2429 | * @note this example requires python v3.7 or newer because it measures |
| 2430 | * transmission time with `time.monotonic_ns()`. |
| 2431 | */ |
| 2432 | |
| 2433 | /** |
| 2434 | * @example{lineno} examples_linux/streaming_data.py |
| 2435 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2436 | * |
| 2437 | * This is a simple example of using the RF24 class on a Raspberry Pi for |
| 2438 | * streaming multiple payloads. |
| 2439 | * |
| 2440 | * Remember to install the [Python wrapper](python_wrapper.md), then |
| 2441 | * navigate to the "RF24/examples_linux" folder. |
| 2442 | * <br>To run this example, enter |
| 2443 | * @code{.sh}python3 streaming_data.py @endcode and follow the prompts. |
| 2444 | * |
| 2445 | * @note this example requires python v3.7 or newer because it measures |
| 2446 | * transmission time with `time.monotonic_ns()`. |
| 2447 | */ |
| 2448 | |
| 2449 | /** |
| 2450 | * @example{lineno} examples_linux/interrupt_configure.py |
| 2451 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2452 | * |
| 2453 | * This is a simple example of using the RF24 class on a Raspberry Pi to |
| 2454 | * detecting (and verifying) the IRQ (interrupt) pin on the nRF24L01. |
| 2455 | * |
| 2456 | * Remember to install the [Python wrapper](python_wrapper.md), then |
| 2457 | * navigate to the "RF24/examples_linux" folder. |
| 2458 | * <br>To run this example, enter |
| 2459 | * @code{.sh}python3 interrupt_configure.py @endcode and follow the prompts. |
| 2460 | * |
| 2461 | * @note this example requires python v3.7 or newer because it measures |
| 2462 | * transmission time with `time.monotonic_ns()`. |
| 2463 | */ |
| 2464 | |
| 2465 | /** |
| 2466 | * @example{lineno} examples_linux/multiceiver_demo.py |
| 2467 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2468 | * |
| 2469 | * This is a simple example of using the RF24 class on a Raspberry Pi for |
| 2470 | * using 1 nRF24L01 to receive data from up to 6 other transceivers. This |
| 2471 | * technique is called "multiceiver" in the datasheet. |
| 2472 | * |
| 2473 | * Remember to install the [Python wrapper](python_wrapper.md), then |
| 2474 | * navigate to the "RF24/examples_linux" folder. |
| 2475 | * <br>To run this example, enter |
| 2476 | * @code{.sh}python3 multiceiver_demo.py @endcode and follow the prompts. |
| 2477 | * |
| 2478 | * @note this example requires python v3.7 or newer because it measures |
| 2479 | * transmission time with `time.monotonic_ns()`. |
| 2480 | */ |
| 2481 | |
| 2482 | /** |
| 2483 | * @example{lineno} examples_linux/scanner.cpp |
| 2484 | * |
| 2485 | * Example to detect interference on the various channels available. |
| 2486 | * This is a good diagnostic tool to check whether you're picking a |
| 2487 | * good channel for your application. |
| 2488 | * |
| 2489 | * Inspired by cpixip. |
| 2490 | * See http://arduino.cc/forum/index.php/topic,54795.0.html |
| 2491 | * |
| 2492 | * Use ctrl+C to exit |
| 2493 | */ |
| 2494 | |
| 2495 | /** |
| 2496 | * @example{lineno} examples/scanner/scanner.ino |
| 2497 | * |
| 2498 | * Example to detect interference on the various channels available. |
| 2499 | * This is a good diagnostic tool to check whether you're picking a |
| 2500 | * good channel for your application. |
| 2501 | * |
| 2502 | * Inspired by cpixip. |
| 2503 | * See http://arduino.cc/forum/index.php/topic,54795.0.html |
| 2504 | */ |
| 2505 | |
| 2506 | /** |
| 2507 | * @example{lineno} examples_linux/gettingstarted.cpp |
| 2508 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2509 | * |
| 2510 | * A simple example of sending data from 1 nRF24L01 transceiver to another. |
| 2511 | * |
| 2512 | * This example was written * This example was written to be used on up to 6 devices acting as TX nodes & |
| 2513 | * only 1 device acting as the RX node (that's a maximum of 7 devices). |
| 2514 | acting as "nodes". |
| 2515 | * Use `ctrl+c` to quit at any time. |
| 2516 | */ |
| 2517 | |
| 2518 | /** |
| 2519 | * @example{lineno} examples_linux/acknowledgementPayloads.cpp |
| 2520 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2521 | * |
| 2522 | * A simple example of sending data from 1 nRF24L01 transceiver to another |
| 2523 | * with Acknowledgement (ACK) payloads attached to ACK packets. |
| 2524 | * |
| 2525 | * This example was written to be used on 2 devices acting as "nodes". |
| 2526 | * Use `ctrl+c` to quit at any time. |
| 2527 | */ |
| 2528 | |
| 2529 | /** |
| 2530 | * @example{lineno} examples_linux/manualAcknowledgements.cpp |
| 2531 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2532 | * |
| 2533 | * A simple example of sending data from 1 nRF24L01 transceiver to another |
| 2534 | * with manually transmitted (non-automatic) Acknowledgement (ACK) payloads. |
| 2535 | * This example still uses ACK packets, but they have no payloads. Instead the |
| 2536 | * acknowledging response is sent with `write()`. This tactic allows for more |
| 2537 | * updated acknowledgement payload data, where actual ACK payloads' data are |
| 2538 | * outdated by 1 transmission because they have to loaded before receiving a |
| 2539 | * transmission. |
| 2540 | * |
| 2541 | * This example was written to be used on 2 devices acting as "nodes". |
| 2542 | * Use `ctrl+c` to quit at any time. |
| 2543 | */ |
| 2544 | |
| 2545 | /** |
| 2546 | * @example{lineno} examples_linux/streamingData.cpp |
| 2547 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2548 | * |
| 2549 | * A simple example of sending data from 1 nRF24L01 transceiver to another. |
| 2550 | * |
| 2551 | * This example was written to be used on 2 devices acting as "nodes". |
| 2552 | * Use `ctrl+c` to quit at any time. |
| 2553 | */ |
| 2554 | |
| 2555 | /** |
| 2556 | * @example{lineno} examples_linux/multiceiverDemo.cpp |
| 2557 | * Written by [2bndy5](http://github.com/2bndy5) in 2020 |
| 2558 | * |
| 2559 | * A simple example of sending data from as many as 6 nRF24L01 transceivers to |
| 2560 | * 1 receiving transceiver. This technique is trademarked by |
| 2561 | * Nordic Semiconductors as "MultiCeiver". |
| 2562 | * |
| 2563 | * This example was written to be used on up to 6 devices acting as TX nodes & |
| 2564 | * only 1 device acting as the RX node (that's a maximum of 7 devices). |
| 2565 | * Use `ctrl+c` to quit at any time. |
| 2566 | */ |
| 2567 | |
| 2568 | #endif // RF24_H_ |