# Migration guide @tableofcontents This is a collection of snippets that highlight preferred API over the deprecated original API. ## isAckPayloadAvailable() > **Deprecated since v1.4.2** This function is equivalent to `RF24::available()`. Any use of `RF24::isAckPayloadAvailable()` is interchangeable with `RF24::available()`.
Old New (supported)
```cpp if radio.isAckPayloadAvailable() { /* .. */ } ``` ```cpp if radio.available() { /* .. */ } ```
## 64-bit integer addresses Any function that accept an address in the form of `uint64_t` is discouraged. This includes - `RF24::openReadingPipe(uint8_t, uint64_t)` > **Deprecated since v1.3.11** - `RF24::openWritingPipe(uint64_t)` > **Deprecated since v1.3.11** - `RF24::stopListening(const uint64_t)` > **Deprecated since v1.5** These functions' address parameter use a 64-bit unsigned integer (`uint64_t`). The nRF24L01 can only use up to 40 bit addresses. Thus, there is an unused 24 bits being allocated for addresses using these functions. There are overloaded functions that use a buffer instead: - `RF24::openReadingPipe(uint8_t, const uint8_t*)` - `RF24::openWritingPipe(const uint8_t*)` - `RF24::stopListening(const uint8_t*)` These eliminate the unnecessary 24 bits by only using the length of the buffer (`uint8_t*`) specified by `RF24::setAddressWidth()`. @see The `RF24::openWritingPipe(const uint8_t*)` is now deprecated in favor of the overloaded `RF24::stopListening(const uint8_t*)` function. See the section below for more detail. > [!CAUTION] > The endianness (byte order) of a buffer is reversed compared to a 64-bit integer. > ```c > uint64_t address = 0xB3B4B5B6C2; > // is the same address as > uint8_t address[5] = {0xC2, 0xB6, 0xB5, 0xB4, 0xB3}; > ``` > Notice the MSB (Most Significant Byte) `0xC2` is last in the integer but first in the buffer.
Old New (supported)
```cpp uint64_t address = 0xB3B4B5B6C2; radio.openReadingPipe(1, address); ``` ```cpp uint8_t address[5] = {0xC2, 0xB6, 0xB5, 0xB4, 0xB3}; radio.openReadingPipe(1, address); ```
> [!NOTE] > Our examples actually use a C-string casted as an array of 6 bytes. > That's because a C-string (`char*`) must be NULL terminated (`\0` at the end) in memory. > ```c > uint8_t address[][6] = { "1Node", "2Node" }; > // is equivalent to > uint8_t address[][6] = { { '1', 'N', 'o', 'd', 'e', '\0' }, > { '2', 'N', 'o', 'd', 'e', '\0' } }; > ``` ## isFifo(bool, bool) > **Deprecated since v1.4.11** Introduced as a compliment to `RF24::isFifo(bool)` in v1.4.3, this function was supposed to provide a specific detail about a specified radio's FIFO. However, it was discovered that the function may not highlight binary corruption (`RF24_FIFO_INVALID`) observed in the SPI bus' MISO line. A fix was introduced using enumerated values of `rf24_fifo_state_e`. Since then, `RF24::isFifo(bool)` is now preferred as it accurately describes the result.
Old New (supported)
```cpp bool rxFifoEmpty = radio.isFifo(false, true); ``` ```cpp bool rxFifoEmpty = radio.isFifo(false) == RF24_FIFO_EMPTY; ```
## maskIRQ() > **Deprecated since v1.5** Originally `RF24::maskIRQ()` was the only function provided to influence the radio's IRQ pin. However, the 3 required boolean parameters made this prone to bugs in user code. The parameters' meaning was confusingly reversed, and they were easily misplaced in the wrong order. A better approach was introduced with `RF24::setStatusFlags()`. It's 1 parameter accepts values defined by the `rf24_irq_flags_e` enumerated constants. These constant values specify individual events; they can also be OR'd together to specify multiple events.
Old New (supported)
```cpp // IRQ pin only activated by "RX Data Ready" event radio.maskIRQ(1, 1, 0); // IRQ pin activated by "TX Data Sent" and TX Data Failed" events radio.maskIRQ(0, 0, 1); // IRQ pin activated by all events radio.maskIRQ(0, 0, 0); // IRQ pin disabled radio.maskIRQ(1, 1, 1); ``` ```cpp // IRQ pin only activated by "RX Data Ready" event radio.setStatusFlags(RF24_RX_DR); // IRQ pin activated by "TX Data Sent" and TX Data Failed" events radio.setStatusFlags(RF24_TX_DS | RF24_TX_DF); // IRQ pin activated by all events radio.setStatusFlags(RF24_IRQ_ALL); // IRQ pin disabled radio.setStatusFlags(RF24_IRQ_NONE); // or equivalently radio.setStatusFlags(); ```
## whatHappened() > **Deprecated since v1.5** Originally, `RF24::whatHappened()` was the only way to clear the events that triggered the IRQ pin. Like `maskIRQ()`, this was also prone to bugs because of the 3 required boolean parameters (passed by reference). The aptly named `RF24::clearStatusFlags()` is designed to be a replacement for `RF24::whatHappened()`. Like `RF24::clearStatusFlags()`, `RF24::setStatusFlags()` takes 1 parameter whose value is defined by the `rf24_irq_flags_e` enumerated constants. These constant values specify individual flags; they can also be OR'd together to specify multiple flags. Additionally, `RF24::clearStatusFlags()` returns the STATUS byte containing the flags that caused the IRQ pin to go active LOW. This allows the user code to allocate less memory when diagnosing the IRQ pin's meaning.
Old New (supported)
```cpp bool tx_ds, tx_df, rx_dr; radio.whatHappened(tx_ds, tx_df, rx_dr); ``` ```cpp uint8_t flags = radio.clearStatusFlags(); // or equivalently uint8_t flags = radio.clearStatusFlags(RF24_IRQ_ALL); // focus on the events you care about if (flags & RF24_TX_DS) { /* TX data sent */ } if (flags & RF24_TX_DF) { /* TX data failed to send */ } if (flags & RF24_RX_DR) { /* RX data is in the RX FIFO */ } // only clear the "TX Data Sent" and TX Data Failed" events radio.clearStatusFlags(RF24_TX_DS | RF24_TX_DF); // only clear the "RX Data Ready" event radio.clearStatusFlags(RF24_RX_DR); ```
## openWritingPipe(const uint8_t*) > Deprecated since v1.5 Originally, `RF24::openWritingPipe(const uint8_t*)` was just a compliment to `RF24::openReadingPipe()`. It changes the address on pipe 0 because that is the only pipe that can be used for transmitting. Unfortunately, there was a bug that prevented the given TX address from being persistent on pipe 0 if the user code also set an RX address to pipe 0. This bug would surface when switching between RX mode and TX mode (via `RF24::startListening()` and `RF24::stopListening()` respectively) or after `RF24::stopConstCarrier()` (if `RF24::isPVariant()` returns `true`). The solution is to cache the TX address on the `RF24` instance. Consequently, this solution did not fit well with the traditional order of functions used to set up the radio's TX or RX mode. By overloading `RF24::stopListening(const uint8_t*)`, we are able to ensure proper radio setup without requiring certain functions are called in a certain order. - Use `RF24::stopListening(const uint8_t*)` to set the TX address and enter inactive TX mode. `RF24::openReadingPipe()` can now (as of v1.5) be used in TX mode without consequence. - Use `RF24::stopListening()` to enter inactive TX mode without changing the TX address. > [!warning] > Avoid using pipe 0 for RX operations to improve performance and reliability. > > For implementation detail, see the source for `RF24::openReadingPipe()` and > `RF24::stopListening()`. Ultimately, the datasheet's Appendix A has a detailed > example outlining the order of a proper radio setup.
Old New (supported)
```cpp // set TX address (pipe 0) radio.openWritingPipe(tx_address); // set RX address (pipe 1) radio.openReadingPipe(1, rx_address); // idle radio using inactive TX mode radio.stopListening(); ``` ```cpp // set TX address (pipe 0) radio.stopListening(tx_address); // enters inactive TX mode // set RX address (pipe 1) radio.openReadingPipe(1, rx_address); ```