Basic API¶

Constructors¶

class RF24Revamped¶

Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver.

Subclassed by RF24

Public Functions

RF24Revamped(uint16_t _cepin, uint16_t _cspin, uint32_t _spi_speed = RF24_SPI_SPEED)¶

Creates a new instance of this driver.

RF24 Constructor Before using, you create an instance and send in the unique pins that this chip is connected to.

See also

Arduino, ATTiny, Linux, Pico SDK pages for device specific information.

Parameters

_cepin – The pin attached to Chip Enable on the radio module
_cspin – The pin attached to Chip Select (often labeled CSN) on the radio module. For the Arduino Due board, the Arduino Due extended SPI feature 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.
_spi_speed – The SPI speed in Hz ie: 1000000 == 1Mhz. Users can specify default SPI speed by modifying #define RF24_SPI_SPEED in RF24_config.h
- For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
- Older/Unsupported Arduino devices will use a default clock divider & settings configuration
- For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

RF24Revamped(uint32_t _spi_speed = RF24_SPI_SPEED)¶

A constructor for initializing the radio’s hardware dynamically

See also

Arduino, ATTiny, Linux, Pico SDK pages for device specific information.

Warning

You MUST use begin(uint16_t, uint16_t)_ or begin(_SPI*, uint16_t, uint16_t)_ to pass both the digital output pin numbers connected to the radio’s CE and CSN pins.

Parameters

_spi_speed – The SPI speed in Hz ie: 1000000 == 1Mhz. Users can specify default SPI speed by modifying #define RF24_SPI_SPEED in RF24_config.h

For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
Older/Unsupported Arduino devices will use a default clock divider & settings configuration
For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

begin()¶

bool RF24Revamped::begin(void)¶

Begin operation of the chip

Call this in setup(), before calling any other methods.

Important

Use this function to determine if there is a hardware problem before continuing application.

if (!radio.begin()) { // if the radio is unresponsive?
    while (1) {}      // hold in infinite loop
}

Returns

true if the radio is not responding to SPI transactions
false if the radio is responsive to SPI transactions

begin(_SPI*)¶

bool RF24Revamped::begin(_SPI *spiBus)¶

Same as begin(), but allows specifying a non-default SPI bus to use.

See also

Review the Arduino support page.

Important

This function assumes the SPI.begin() method was called before to calling this function.

Warning

This function is for the Arduino platform only, but is not supported on the following boards/architecture:

Arduino Due
Any ATTiny device
LittleWire
SPI_UART implementation

Parameters

spiBus – A pointer or reference to an instantiated SPI bus object.

Hint

The _SPI datatype is a “wrapped” definition that will represent various SPI implementations based on the specified platform (or SoftSPI).

Returns

same result as begin()

begin(uint16_t, uint16_t)¶

bool RF24Revamped::begin(uint16_t _cepin, uint16_t _cspin)¶

Same as begin(), but allows dynamically specifying a CE pin and CSN pin to use.

Parameters

_cepin – The pin attached to Chip Enable on the radio module
_cspin – The pin attached to Chip Select (often labeled CSN) on the radio module. For the Arduino Due board, the Arduino Due extended SPI feature 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.

Returns

same result as begin()

begin(_SPI*, uint16_t, uint16_t)¶

bool RF24Revamped::begin(_SPI *spiBus, uint16_t _cepin, uint16_t _cspin)¶

Same as begin(), but allows dynamically specifying a SPI bus, CE pin, and CSN pin to use.

See also

Review the Arduino support page.

Important

This function assumes the SPI.begin() method was called before to calling this function.

Warning

This function is for the Arduino platform only, but is not supported on the following boards/architecture:

Arduino Due
Any ATTiny device
LittleWire
SPI_UART implementation

Parameters

spiBus – A pointer or reference to an instantiated SPI bus object.

Hint

The _SPI datatype is a “wrapped” definition that will represent various SPI implementations based on the specified platform (or SoftSPI).
_cepin – The pin attached to Chip Enable on the RF module
_cspin – The pin attached to Chip Select (often labeled CSN) on the radio module. For the Arduino Due board, the Arduino Due extended SPI feature 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.

Returns

same result as begin()

openReadingPipe()¶

void RF24Revamped::openReadingPipe(uint8_t number, const uint8_t *address)¶

Open a pipe for reading with an array of bytes as an address. Use OpenReadingPipe(uint8_t, uint64_t) for passing a 64-bit integer as an address.

Up to 6 pipes can be open for simultaneous listening. Open all the required reading pipes, and then call startListening().

Note

Pipes 0 and 1 will store a full 5-byte address. Pipes 2-5 will technically only store a single byte, borrowing up to 4 additional bytes from pipe 1 per the assigned address width.

Pipes 1-5 should share the same address, except the first byte. Only the first byte in the array should be unique, e.g.

uint8_t addresses[][6] = {"Prime", "2Node", "3xxxx", "4xxxx"};
openReadingPipe(0, addresses[0]); // address used is "Prime"
openReadingPipe(1, addresses[1]); // address used is "2Node"
openReadingPipe(2, addresses[2]); // address used is "3Node"
openReadingPipe(3, addresses[3]); // address used is "4Node"

Note

There is no address length parameter because this function will always write the number of bytes (for pipes 0 and 1) that the radio addresses are configured to use (set with setAddressLength()).

Warning

If the reading pipe 0 is opened by this function, the address passed to this function (for pipe 0) will be restored at every call to startListening(), but the address for pipe 0 is ONLY restored if the LSB is a non-zero value.

Read this article to understand how to avoid using malformed addresses. This address restoration is implemented because of the underlying neccessary functionality of openWritingPipe().

Parameters

number – Which pipe to open. Only pipe numbers 0-5 are available, an address assigned to any pipe number not in that range will be ignored.
address – The 3, 4, or 5 byte address to assign to an RX pipe.

void RF24Revamped::openReadingPipe(uint8_t number, uint64_t address)¶

Open a pipe for reading with a 64-but integer as an address. Use openReadingPipe(uint8_t, const uint8_t*) for passing an array of bytes as an address.

Important

Pipes 1-5 should share the first 32 bits. Only the least significant byte should be unique, e.g.

openReadingPipe(1, 0xF0F0F0F0AA);
openReadingPipe(2, 0xF0F0F0F066);

Warning

Pipe 0 is also used by the writing pipe so should typically be avoided as a reading pipe.

If used, the reading pipe 0 address needs to be restored at avery call to startListening(), and the address is ONLY restored if the LSB is a non-zero value.

Read this article to understand how to avoid using malformed addresses.

Parameters

number – Which pipe number to open, should be in range [0, 5].
address – The 40-bit address of the pipe to open.

closeReadingPipe()¶

void RF24Revamped::closeReadingPipe(uint8_t pipe)¶

Close a pipe after it has been previously opened. Can be safely called without having previously opened a pipe.

Parameters: pipe – Which pipe number to close, any integer not in range [0, 5] is ignored.

openWritingPipe()¶

void RF24Revamped::openWritingPipe(const uint8_t *address)¶

Open a pipe for writing with an array of bytes as an address. Use openWritingPipe(uint64_t) for passing a 64-bit integer as an address.

Only one writing pipe can be opened at once, but this function changes the address that is used to transmit (ACK payloads/packets do not apply here). Be sure to call stopListening() prior to calling this function.

Addresses are assigned via a byte array, default is 5 byte address length

uint8_t addresses[][6] = {"1Node", "2Node"};
radio.openWritingPipe(addresses[0]);

uint8_t address[] = {0xCC, 0xCE, 0xCC, 0xCE, 0xCC};
radio.openWritingPipe(address);
address[0] = 0x33;
radio.openReadingPipe(1, address);

Note

There is no address length parameter because this function will always write the number of bytes that the radio addresses are configured to use (set with setAddressLength()).

Warning

This function will overwrite the address set to reading pipe 0 as stipulated by the datasheet for proper auto-ack functionality in TX mode. Use this function to ensure proper transmission acknowledgement when the address set to reading pipe 0 (via openReadingPipe()) does not match the address passed to this function. If the auto-ack feature is disabled, then this function will still overwrite the address for reading pipe 0 regardless.

Parameters: address – The address to be used for outgoing transmissions (uses pipe 0). Coordinate this address amongst other receiving nodes (the pipe numbers don’t need to match).

void RF24Revamped::openWritingPipe(uint64_t address)¶

Open a pipe for writing using a 64-but integer as an address. Use openWritingPipe(const uint8_t*) for passing an array of bytes.

Addresses are 40-bit hex values, e.g.:

openWritingPipe(0xF0F0F0F0F0);

Parameters: address – The 40-bit address of the pipe to open.

startListening()¶

void RF24Revamped::startListening(void)¶

Start listening on the pipes opened for reading.

Be sure to call openReadingPipe() first.
Do not call send() while in this mode, without first calling stopListening().
Call available() to check for incoming traffic, and read() to get it.

Open reading pipe 1 using address 0xCCCECCCECC

byte address[] = {0xCC, 0xCE, 0xCC, 0xCE, 0xCC};
radio.openReadingPipe(1,address);
radio.startListening();

Note

If there was a call to openReadingPipe() about pipe 0 prior to calling this function, then this function will re-write the address that was last set to reading pipe 0. This is because openWritingPipe() will overwrite the address to reading pipe 0 for proper auto-ack functionality.

stopListening()¶

void RF24Revamped::stopListening(void)¶

Stop listening for incoming messages, and switch to transmit mode.

Do this before calling send().

radio.stopListening();
radio.send(&data, sizeof(data));

Note

When the ACK payloads feature is enabled, the TX FIFO buffers are flushed when calling this function. This is meant to discard any ACK payloads that were not appended to acknowledgment packets.

any()¶

uint8_t RF24Revamped::any(void)¶

Get next available payload length in bytes. This function is compatible with static or dynamic payloads.

Returns: Payload length in bytes of next available payload in the RX FIFO. If no payload is available then this function returns 0.

available()¶

bool RF24Revamped::available(void)¶

Check whether there are bytes available to be read

if(radio.available()){
  radio.read(&data, sizeof(data));
}

See also

any()

Warning

This function relies on the information about the pipe number that received the next available payload. According to the datasheet, the data about the pipe number that received the next available payload is “unreliable” during a FALLING transition on the IRQ pin. This means you should call update() then any() instead of calling this function during an ISR (Interrupt Service Routine).

For example:

void isrCallbackFunction() {
  radio.update();                  // allow time for the IRQ pin to settle
  uint8_t bytes = radio.any();     // any() is slightly slower than available()
                                   // but more reliable in this case
  if (bytes) {
    radio.read(&buffer, bytes);    // event is related to RX operation
  } else {
    radio.clearStatusFlags(false); // event is related to TX operation
    if (radio.irqDf()) {
      // do some TX failure handling here
    }
  }
}

void setup() {
  pinMode(IRQ_PIN, INPUT);
  attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING);
}

Return

true if there is a payload available in the RX FIFO buffers
false if there is no payload available in the RX FIFO buffers

read()¶

void RF24Revamped::read(void *buf, uint8_t len)¶

Read payload data from the RX FIFO buffer(s).

The length of data read is usually the next available payload’s length

Parameters

buf – [out] Pointer to a buffer where the data should be written

Note

void* was chosen specifically as a data type to make it easier for beginners to use (no casting needed).
len – Maximum number of bytes to read into the buffer. This value should match the length of the object referenced using the buf parameter. The absolute maximum number of bytes that can be read in one call is 96.
Hint

Remember that each call to read() fetches data from the RX FIFO beginning with the first byte from the first available payload. A payload is not removed from the RX FIFO until it’s entire length (or more) is fetched using read().
- If len parameter’s value is less than the available payload’s length, then the payload remains in the RX FIFO.
- If len parameter’s value is greater than the first of multiple available payloads, then the data saved to the buf parameter’s object will be supplemented with data from the next available payload.
- If len parameter’s value is greater than the last available payload’s length, then the last byte in the payload is used as padding for the data saved to the buf parameter’s object. The nRF24L01 will repeatedly use the last byte from the last payload even when read() is called with an empty RX FIFO.
See also

any(), available()

send()¶

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

This blocks until the message is successfully acknowledged by the receiver or the timeout/retransmit maxima are reached.

Be sure to call openWritingPipe() first to set the destination of the paylooad.

The irqDs() and irqDf() interrupt flags will be cleared upon entering this function

See also

the Auto-ACK feature

Parameters

buf – Pointer to the data to be sent
len – Number of bytes to be sent. The maximum size of data from buf is 32 bytes (for dynamic payload lengths) or the static payload length specified by setPayloadLength(). If this parameter is less than what getPayloadLength() returns (about pipe 0), then the remainder will be padded with zeroes.
multicast – Request ACK response (false), or no ACK response (true). Be sure to have called allowMulticast() at least once before setting this parameter.

Returns

true if the payload was delivered successfully and an acknowledgement (ACK packet) was received. If auto-ack is disabled, then any attempt to transmit will also return true (even if the payload was not received).
false if the payload was sent but was not acknowledged with an ACK packet. This condition can only be reported if the auto-ack feature is on.