From 3120783000d0025b183b0397acaa8b769499eb38 Mon Sep 17 00:00:00 2001 From: krolyxon Date: Mon, 8 Jun 2026 23:10:46 +0530 Subject: Initial gh-pages firmware hosting --- .pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md | 287 +++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 .pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md (limited to '.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md') diff --git a/.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md b/.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md new file mode 100644 index 0000000..b4d3782 --- /dev/null +++ b/.pio/libdeps/esp32-s3-n16r8/RF24/docs/migration.md @@ -0,0 +1,287 @@ +# 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()`. + + + + +
OldNew (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. + + + + +
OldNew (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. + + + + +
OldNew (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. + + + + +
OldNew (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. + + + + +
OldNew (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. + + + + +
OldNew (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); +``` + +
-- cgit v1.2.3