diff options
Diffstat (limited to '.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md')
| -rw-r--r-- | .pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md b/.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md deleted file mode 100644 index b4d3782..0000000 --- a/.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md +++ /dev/null @@ -1,287 +0,0 @@ -# Migration guide - -@tableofcontents - -<!-- markdownlint-disable MD033 MD031 --> - -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()`. - -<table><tr> -<th>Old</th> -<th>New (supported)</th> -</tr><tr><td> - -```cpp -if radio.isAckPayloadAvailable() { /* .. */ } -``` - -</td><td> - -```cpp -if radio.available() { /* .. */ } -``` - -</td></tr></table> - -## 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. - -<table><tr> -<th>Old</th> -<th>New (supported)</th> -</tr><tr><td> - -```cpp -uint64_t address = 0xB3B4B5B6C2; -radio.openReadingPipe(1, address); -``` - -</td><td> - -```cpp -uint8_t address[5] = {0xC2, 0xB6, 0xB5, 0xB4, 0xB3}; -radio.openReadingPipe(1, address); -``` - -</td></tr></table> - -> [!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. - -<table><tr> -<th>Old</th> -<th>New (supported)</th> -</tr><tr><td> - -```cpp -bool rxFifoEmpty = radio.isFifo(false, true); -``` - -</td><td> - -```cpp -bool rxFifoEmpty = radio.isFifo(false) == RF24_FIFO_EMPTY; -``` - -</td></tr></table> - -## 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. - -<table><tr> -<th>Old</th> -<th>New (supported)</th> -</tr><tr><td> - -```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); -``` - -</td><td> - -```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(); -``` - -</td></tr></table> - -## 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. - -<table><tr> -<th>Old</th> -<th>New (supported)</th> -</tr><tr><td> - -```cpp -bool tx_ds, tx_df, rx_dr; -radio.whatHappened(tx_ds, tx_df, rx_dr); -``` - -</td><td> - -```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); -``` - -</td></tr></table> - -## 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. - -<table><tr> -<th>Old</th> -<th>New (supported)</th> -</tr><tr><td> - -```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(); -``` - -</td><td> - -```cpp -// set TX address (pipe 0) -radio.stopListening(tx_address); // enters inactive TX mode - -// set RX address (pipe 1) -radio.openReadingPipe(1, rx_address); -``` - -</td></tr></table> |