Advanced API¶

resend()¶

The function will instruct the radio to re-use the payload in the top level (first out) of the TX FIFO buffers when a TX failure occurs. The auto-retry feature is applied just like when calling send(). Calling this function prevents succefully sent payloads from being removed from the TX FIFO buffer until calling flushTx(). If the TX FIFO has only the one payload (in the top level), the re-used payload can be overwritten by using send() or write(). If the TX FIFO has other payloads enqueued, then using send() or write() will attempt to enqueue a new payload in the TX FIFO (does not overwrite the top level of the TX FIFO). Currently, stopListening() also calls flushTx() when ACK payloads are enabled (via enableAckPayload()).

This function only applies when taking advantage of the auto-retry feature. See setAutoAck() and setAutoRetry() to configure the auto-retry feature.

Note

This is to be used AFTER auto-retry fails if wanting to resend using the built-in payload reuse feature. In the event of a re-transmission failure, simply call this function again to resume re-transmission of the same payload.

Returns

true if re-transmission was successful.
false if the re-transmission failed or the TX FIFO was already empty.

write()¶

bool RF24Revamped::write(const void *buf, uint8_t len, const bool multicast = 0, bool write_only = 0)¶

Write a payload to the TX FIFO buffers. This function actually serves as a helper to send().

Note

This function leaves the CE pin HIGH, so the radio will remain in TX or StandBy-II Mode until a ce() is called to set the pin LOW (into StandBy-I mode). Can be used as an alternative to send() if using all 3 levels of the TX FIFO to manage multiple payloads at once.

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 retransmit/autoAck is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO to clear by calling ce() to the the CE pin inactive LOW.

Parameters

buf – Pointer to the data to be sent
len – Number of bytes to be sent
multicast – Request ACK packet response (false), or no ACK packet response (true). Be sure to have called allowMulticast() at least once before setting this parameter.
write_only – If this is set to false, then this function sets the CE pin to active (enabling TX transmissions). true has no effect on the CE pin and simply loads the payload into the TX FIFO.

Returns

true if the payload was loaded into the TX FIFO.
false if the payload wasn’t loaded into the TX FIFO because it is already full.

ce()¶

void RF24Revamped::ce(bool level)¶

Set the radio’s CE (Chip Enable) pin. In RX mode, this pin controls weather the radio is actively listening. In TX mode, this pin controls how much data from the TX FIFO buffers is transmitted. Keep in mind that a minimum 10 microseconds pulse will send only 1 payload from the TX FIFO, and the radio requires at least a 130 microsecond pulse to start actively listening in RX mode.

Parameters

level – Use true for active HIGH state. Use false for inactive LOW state.

Important

Please see data sheet for a much more detailed description of this pin’s usage.

writeAck()¶

bool RF24Revamped::writeAck(uint8_t pipe, const void *buf, uint8_t len)¶

Write an acknowledgement (ACK) payload for the specified pipe

The next time a message is received on a specified pipe, the data in buf will be sent back in the ACK payload.

Important

Dynamic payloads must be enabled.

Tip

ACK payloads are handled automatically by the radio chip when a regular payload is received. It is important to discard regular payloads in the TX FIFO (using flushTx()) before loading the first ACK payload into the TX FIFO. This function can be called before and after calling startListening().

Note

ACK payloads are dynamic payloads. Calling enableAckPayload() will automatically enable dynamic payloads on pipe 0 (required for TX mode when expecting ACK payloads). To use ACK payloads on any other pipe in RX mode, call setDynamicPayloads().

Warning

Only 3 of these ACK payloads can be pending at any time because there are only 3 FIFO buffers.

Parameters

pipe – Which pipe# (typically 1-5) will get this response.
buf – Pointer to data that is sent
len – Length of the data to send, up to 32 bytes max. Not affected by the static payload set by setPayloadLength().

Returns

true if the payload was loaded into the TX FIFO.
false if the payload wasn’t loaded into the TX FIFO because it is already full or the ACK payload feature is not enabled using enableAckPayload().

Status Byte¶

Important

Calling most of these status byte related functions do not update the data they return. Use update() to refresh the status byte data as needed.

The status byte data is updated on every SPI transaction. The only functions that don’t execute an SPI transaction are irqDf(), irqDs(), irqDr(), isTxFull(), and pipe().

update()¶

uint8_t RF24Revamped::update(void)¶

Refresh data (from the STATUS register) used by the following functions: irqDf(), irqDs(), irqDr(), isTxFull(), pipe().

Returns: Current value of STATUS register

isTxFull()¶

bool RF24Revamped::isTxFull(void)¶

Returns: A bool flag that describes if all 3 levels of the TX FIFO are occupied with a payload.

pipe()¶

uint8_t RF24Revamped::pipe(void)¶

Warning

According to the datasheet, this data is “unreliable” while the IRQ pin is transitioning from HIGH to LOW (a FALLING transition).

Returns: The pipe number that received the next available payload in the RX FIFO is in range [0, 5]. If there is no payload in the RX FIFO, then the number returned is 255.

irqDr()¶

bool RF24Revamped::irqDr(void)¶

Returns: A bool flag that describes if the “Data Ready” event has occured. Use the data_ready parameter to clearStatusFlags() to reset this event.

irqDf()¶

bool RF24Revamped::irqDf(void)¶

Returns: A bool flag that describes if the “Data Fail” event has occured. Use the data_fail parameter to clearStatusFlags() to reset this event.

irqDs()¶

bool RF24Revamped::irqDs(void)¶

Returns: A bool flag that describes if the “Data Sent” event has occured. Use the data_sent parameter to clearStatusFlags() to reset this event.

clearStatusFlags()¶

void RF24Revamped::clearStatusFlags(bool dataReady = true, bool dataSent = true, bool dataFail = true)¶

Call this to reset an Interrupt Request (IRQ) event flag after the approriate actions have been taken.

Note

After calling this function, the status flags irqDr(), irqDf(), irqDs() will be immediately outdated until another function (that executes an SPI transaction) is called.

Parameters

dataReady – There is a newly received payload (RX_DR) saved to RX FIFO buffers. Remember that the RX FIFO can only hold up to 3 payloads. Once the RX FIFO is full, all further received transmissions are rejected until there is space to save new data in the RX FIFO buffers.
dataSent – The transmission attempt completed (TX_DS). This does not imply that the transmitted data was received by another radio, rather this only reports if the attempt to send was completed. This will always be true when the auto-ack feature is disabled.
dataFail – The transmission failed to be acknowledged, meaning too many retries (MAX_RT) were made while expecting an ACK packet. This event is only triggered when auto-ack feature is enabled.

Power mode¶

powerUp()¶

void RF24Revamped::powerUp(void)¶

Leave low-power mode - required for normal radio operation after calling powerDown()

To return to low power mode, call powerDown().

Note

This will take up to 5ms for maximum compatibility.

powerDown()¶

void RF24Revamped::powerDown(void)¶

Enter low-power mode

To return to normal power mode, call powerUp().

radio.powerDown();
avr_enter_sleep_mode(); // Custom function to sleep the device
radio.powerUp();

Note

After calling startListening(), a basic radio will consume about 13.5mA at max PA level. During active transmission, the radio will consume about 11.5mA, but this will be reduced to 26uA (.026mA) between sending. In full powerDown mode, the radio will consume approximately 900nA (.0009mA)

setPower()¶

void RF24Revamped::setPower(bool is_on)¶

Set the power state of the radio.

See also

ce() because the state of the CE pin has a direct affect on current consumption.

Parameters

is_on –

true ensures the radio is powered up and ready to receive or transmit.
false puts the radio to “powered down” mode which is like “sleep” mode.

isPower()¶

bool RF24Revamped::isPower(void)¶

Get the current power state of the radio.

Returns: true when radio is powered up or false when radio is powered down.

FIFO managment¶

flushRx()¶

void RF24Revamped::flushRx(void)¶: Empty all 3 of the RX (receive) FIFO buffers.

flushTx()¶

void RF24Revamped::flushTx(void)¶: Empty all 3 of the TX (transmit) FIFO buffers. This is automatically called by stopListening() if ACK payloads are enabled. However, startListening() does not call this function.

isFifo()¶

bool RF24Revamped::isFifo(bool about_tx, bool check_empty)¶

Use this function to check if the radio’s RX or TX FIFO levels are all occupied. This can be used to prevent data loss because any incoming transmissions are rejected if there is no unoccupied levels in the RX FIFO to store the incoming payload. Remember that each level can hold up to a maximum of 32 bytes.

Parameters

about_tx – Specify which FIFO the returned data should concern. If this parameter is not specified, then the default value is false.
- true fetches data about the TX FIFO
- false fetches data about the RX FIFO
check_empty – Specify if the data returned about the specified FIFO describes it as empty or full.
- true checks if the specified FIFO is empty
- false checks if the specified FIFO is full

Returns

A boolean that answers the question (according to the parameters)
Is the [TX or RX](about_tx) FIFO [empty or full](check_empty)?
If the check_empty parameter is not specified, then this function returns a number consisting of 2 bits where each bit describes the empty and full state of the specified FIFO buffers.
- 2 means the FIFO is full
- 1 means the FIFO is empty
- 0 means the FIFO is neither full nor empty

lastTxArc()¶

uint8_t RF24Revamped::lastTxArc(void)¶

Returns

The number of auto-retry attempts made for the last transmision. This value ranges from 0 to 15. This value resets with each new transmission.

Note

The maximum limit of this number is controlled via the count parameter to the setAutoRetry() or setArc() functions.

Hint

This function can be used to get a rough estimate of signal strength.

isPlusVariant()¶

bool RF24Revamped::isPlusVariant(void)¶

Returns: true if the hardware is nRF24L01+ (or compatible) or false if it is an older non-plus variant(nRF24L01).

Ambiguous Signal detection¶

The nRF24L01 comes with access to perform hardware specifications testing to ensure the radio is not defective. The constant carrier wave test and Received Power Detection (RPD) are common stipulations mandated by authoritative agencies (i.e. the FCC in the United States).

testRpd()¶

bool RF24Revamped::testRpd(void)¶

Test whether a signal (carrier wave or otherwise) greater than or equal to -64dBm is present on the channel. This can be used to check for interference on the current channel and channel hopping strategies.

bool goodSignal = radio.testRpd();
if(radio.available()){
   Serial.println(goodSignal ? "Strong signal > 64dBm" : "Weak signal < 64dBm" );
   radio.read(0, 0);
}

Returns

This data is reset upon entering RX mode.

true if a signal with an amplitude of greater than or equal to -64dBm was detected.
false if no signal with an amplitude of greater than or equal to -64 dBm was detected.

startCarrierWave()¶

void RF24Revamped::startCarrierWave(void)¶

Transmission of constant carrier wave.

Warning

If isPlusVariant() returns true, then this function takes extra measures that alter some settings. These settings alterations include:

setAutoAck() to false (for all pipes)
setAutoRetry() to retry 0 times with a delay of 250 microseconds
set the TX address to 5 bytes of 0xFF
flushTx()
load a 32 byte payload of 0xFF into the TX FIFO’s top level
setCrc() to 0 (disabling CRC checking).

stopCarrierWave()¶

void RF24Revamped::stopCarrierWave(void)¶

Stop transmission of the constant carrier wave initiated by startCarrierWave()

Important

If isPlusVariant() returns true, please remember to re-configure the radio’s settings

// re-establish default settings
setCrc(RF24_CRC_16);
setAutoAck(true);
setAutoRetry(5, 15);

Warning

this function will powerDown() the radio per recommendation of datasheet.

printDetails()¶

void RF24Revamped::printDetails(bool dump_pipes = false)¶

Print a giant block of debugging information to stdout. Only use this function if your application can spare extra bytes of memory.

Note

If the Auto-Ack feature is configured differently for each pipe, then a binary representation is used in which bits 0-5 represent pipes 0-5 respectively. A 0 means the feature is disabled and a 1 means the feature is enabled.

Warning

Does nothing if stdout is not defined. See fdevopen in stdio.h The printf.h file is included with the library for Arduino.

#include "printf.h"
setup(){
  Serial.begin(115200);
  printf_begin();
  // ...
}

Parameters: dump_pipes – If true, this parameter will append information about the data pipes including addresses (TX and RX), opened/closed status of RX pipes, and expected static payload lengths. If this parameter is not specified, then it defaults to false.