Optimized high speed nRF24L01+ driver class documentation v1.4.10

TMRh20 2020 - Optimized fork of the nRF24L01+ driver

Main Page

Topics

Classes

Files

Examples

Class List

Class Index

Class Members

Protected Member Functions | Protected Attributes | List of all members

RF24 Class Reference

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

include

Public Member Functions

Primary public interface

These are the main methods you need to operate the chip

RF24 (rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin, uint32_t _spi_speed=RF24_SPI_SPEED) RF24 (uint32_t _spi_speed=RF24_SPI_SPEED) bool begin (void) bool begin (_SPI spiBus) bool begin (_SPI spiBus, rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin) bool begin (rf24_gpio_pin_t _cepin, rf24_gpio_pin_t _cspin) bool isChipConnected () void startListening (void) void stopListening (void) bool available (void) void read (void buf, uint8_t len) bool write (const void buf, uint8_t len) void openWritingPipe (const uint8_t address) void openReadingPipe (uint8_t number, const uint8_t address)

Deprecated

Methods provided for backwards compatibility.

void openReadingPipe (uint8_t number, uint64_t address) void openWritingPipe (uint64_t address) bool isAckPayloadAvailable (void)

Protected Member Functions

void beginTransaction () void endTransaction () void read_register (uint8_t reg, uint8_t *buf, uint8_t len) uint8_t read_register (uint8_t reg)

Protected Attributes

bool ack_payloads_enabled uint8_t addr_width bool dynamic_payloads_enabled

Advanced Operation

Methods you can use to drive the chip in more advanced ways

bool failureDetected void printDetails (void) void printPrettyDetails (void) uint16_t sprintfPrettyDetails (char debugging_information) void encodeRadioDetails (uint8_t encoded_status) bool available (uint8_t pipe_num) bool rxFifoFull () uint8_t isFifo (bool about_tx) bool isFifo (bool about_tx, bool check_empty) void powerDown (void) void powerUp (void) bool write (const void buf, uint8_t len, const bool multicast) bool writeFast (const void buf, uint8_t len) bool writeFast (const void buf, uint8_t len, const bool multicast) bool writeBlocking (const void buf, uint8_t len, uint32_t timeout) bool txStandBy () bool txStandBy (uint32_t timeout, bool startTx=0) bool writeAckPayload (uint8_t pipe, const void buf, uint8_t len) void whatHappened (bool &tx_ok, bool &tx_fail, bool &rx_ready) void startFastWrite (const void buf, uint8_t len, const bool multicast, bool startTx=1) bool startWrite (const void buf, uint8_t len, const bool multicast) void reUseTX () uint8_t flush_tx (void) uint8_t flush_rx (void) bool testCarrier (void) bool testRPD (void) bool isValid () void closeReadingPipe (uint8_t pipe)

Optional Configurators

Methods you can use to get or set the configuration of the chip. None are required. Calling begin() sets up a reasonable set of defaults.

uint32_t txDelay uint32_t csDelay void setAddressWidth (uint8_t a_width) void setRetries (uint8_t delay, uint8_t count) void setChannel (uint8_t channel) uint8_t getChannel (void) void setPayloadSize (uint8_t size) uint8_t getPayloadSize (void) uint8_t getDynamicPayloadSize (void) void enableAckPayload (void) void disableAckPayload (void) void enableDynamicPayloads (void) void disableDynamicPayloads (void) void enableDynamicAck () bool isPVariant (void) void setAutoAck (bool enable) void setAutoAck (uint8_t pipe, bool enable) void setPALevel (uint8_t level, bool lnaEnable=1) uint8_t getPALevel (void) uint8_t getARC (void) bool setDataRate (rf24_datarate_e speed) rf24_datarate_e getDataRate (void) void setCRCLength (rf24_crclength_e length) rf24_crclength_e getCRCLength (void) void disableCRC (void) void maskIRQ (bool tx_ok, bool tx_fail, bool rx_ready) void startConstCarrier (rf24_pa_dbm_e level, uint8_t channel) void stopConstCarrier (void) void toggleAllPipes (bool isEnabled) Open or close all data pipes. void setRadiation (uint8_t level, rf24_datarate_e speed, bool lnaEnable=true) configure the RF_SETUP register in 1 transaction

Detailed Description

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

Examplesexamples/AcknowledgementPayloads/AcknowledgementPayloads.ino, examples/GettingStarted/GettingStarted.ino, examples/InterruptConfigure/InterruptConfigure.ino, examples/ManualAcknowledgements/ManualAcknowledgements.ino, examples/MulticeiverDemo/MulticeiverDemo.ino, examples/StreamingData/StreamingData.ino, examples/old_backups/GettingStarted_HandlingFailures/GettingStarted_HandlingFailures.ino, examples/old_backups/TransferTimeouts/TransferTimeouts.ino, examples/old_backups/pingpair_dyn/pingpair_dyn.ino, examples/old_backups/pingpair_irq/pingpair_irq.ino, examples/old_backups/pingpair_sleepy/pingpair_sleepy.ino, examples/rf24_ATTiny/rf24ping85/rf24ping85.ino, examples/scanner/scanner.ino, examples_linux/acknowledgementPayloads.cpp, examples_linux/gettingstarted.cpp, examples_linux/manualAcknowledgements.cpp, examples_linux/multiceiverDemo.cpp, examples_linux/scanner.cpp, and examples_linux/streamingData.cpp.

Definition at line 115 of file RF24.h.

Constructor & Destructor Documentation

◆ RF24() [1/2]

RF24::RF24(rf24_gpio_pin_t_cepin,rf24_gpio_pin_t_cspin,uint32_t_spi_speed = RF24_SPI_SPEED )

RF24 Constructor

Creates a new instance of this driver. Before using, you create an instance and send in the unique pins that this chip is connected to.

See Related Pages for device specific information

Parameters_cepinThe pin attached to Chip Enable on the RF module_cspinThe 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_speedThe SPI speed in Hz ie: 1000000 == 1Mhz

Users can specify default SPI speed by modifying 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

Definition at line 564 of file RF24.cpp.

◆ RF24() [2/2]

RF24::RF24(uint32_t_spi_speed = RF24_SPI_SPEED)

A constructor for initializing the radio's hardware dynamically

WarningYou MUST use begin(rf24_gpio_pin_t, rf24_gpio_pin_t) or begin(_SPI*, rf24_gpio_pin_t, rf24_gpio_pin_t) to pass both the digital output pin numbers connected to the radio's CE and CSN pins.Parameters_spi_speedThe SPI speed in Hz ie: 1000000 == 1Mhz

Users can specify default SPI speed by modifying 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

Definition at line 572 of file RF24.cpp.

Member Function Documentation

◆ beginTransaction()

void RF24::beginTransaction()inlineprotected

SPI transactions

Common code for SPI transactions including CSN toggle

Definition at line 117 of file RF24.cpp.

◆ endTransaction()

void RF24::endTransaction()inlineprotected

Definition at line 135 of file RF24.cpp.

◆ read_register() [1/2]

void RF24::read_register(uint8_treg,uint8_t *buf,uint8_tlen )protected

Read a chunk of data in from a register

ParametersregWhich register. Use constants from nRF24L01.h[out]bufWhere to put the datalenHow many bytes of data to transferNoteThis returns nothing. Older versions of this function returned the status byte, but that it now saved to a private member on all SPI transactions.

Definition at line 149 of file RF24.cpp.

◆ read_register() [2/2]

uint8_t RF24::read_register(uint8_treg)protected

Read single byte from a register

ParametersregWhich register. Use constants from nRF24L01.hReturnsCurrent value of register reg

Definition at line 200 of file RF24.cpp.

◆ begin() [1/4]

bool RF24::begin(void)

Begin operation of the chip

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

if (!radio.begin()) {

Serial.println(F("radio hardware not responding!"));

while (1) {} // hold program in infinite loop to prevent subsequent errors

}

Returns

true if the radio was successfully initialized

false if the MCU failed to communicate with the radio hardware

Definition at line 954 of file RF24.cpp.

◆ begin() [2/4]

bool RF24::begin(_SPI *spiBus)

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

NoteThis function assumes the SPI::begin() method was called before to calling this function.WarningThis function is for the Arduino platforms onlyParametersspiBusA pointer or reference to an instantiated SPI bus object. The _SPI datatype is a "wrapped" definition that will represent various SPI implementations based on the specified platform.See alsoReview the Arduino support page.Returnssame result as begin()

Definition at line 926 of file RF24.cpp.

◆ begin() [3/4]

bool RF24::begin(_SPI *spiBus,rf24_gpio_pin_t_cepin,rf24_gpio_pin_t_cspin )

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

NoteThis function assumes the SPI::begin() method was called before to calling this function.WarningThis function is for the Arduino platforms onlyParametersspiBusA pointer or reference to an instantiated SPI bus object. The _SPI datatype is a "wrapped" definition that will represent various SPI implementations based on the specified platform._cepinThe pin attached to Chip Enable on the RF module_cspinThe pin attached to Chip Select (often labeled CSN) on the radio module.

See alsoReview the Arduino support page.Returnssame result as begin()

Definition at line 934 of file RF24.cpp.

◆ begin() [4/4]

bool RF24::begin(rf24_gpio_pin_t_cepin,rf24_gpio_pin_t_cspin )

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

Parameters_cepinThe pin attached to Chip Enable on the RF module_cspinThe pin attached to Chip Select (often labeled CSN) on the radio module.

Returnssame result as begin()

Definition at line 945 of file RF24.cpp.

◆ isChipConnected()

bool RF24::isChipConnected()

Checks if the chip is connected to the SPI bus

Definition at line 1111 of file RF24.cpp.

◆ startListening()

void RF24::startListening(void)

Start listening on the pipes opened for reading.

Be sure to call openReadingPipe() first.

Do not call write() 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();

NoteIf 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.

Definition at line 1125 of file RF24.cpp.

◆ stopListening()

void RF24::stopListening(void)

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

Do this before calling write().

radio.stopListening();

radio.write(&data, sizeof(data));

NoteWhen 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.

Definition at line 1149 of file RF24.cpp.

◆ available() [1/2]

bool RF24::available(void)

Check whether there are bytes available to be read

if(radio.available()){

radio.read(&data,sizeof(data));

}

See alsoavailable(uint8_t*)ReturnsTrue if there is a payload available, false if none isWarningThis 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 whatHappened() before calling this function during an ISR (Interrupt Service Routine). For example:

void isrCallbackFunction() {

bool tx_ds, tx_df, rx_dr;

radio.whatHappened(tx_ds, tx_df, rx_dr); // resets the IRQ pin to HIGH

radio.available(); // returned data should now be reliable

}

void setup() {

pinMode(IRQ_PIN, INPUT);

attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING);

}

Definition at line 1489 of file RF24.cpp.

◆ read()

void RF24::read(void *buf,uint8_tlen )

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

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

See also

getPayloadSize()

getDynamicPayloadSize()

NoteI specifically chose void* as a data type to make it easier for beginners to use. No casting needed.ParametersbufPointer to a buffer where the data should be writtenlenMaximum 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 32 (for dynamic payload lengths) or whatever number was previously passed to setPayloadSize() (for static payload lengths).Remarks

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.

NoteTo use this function in the python wrapper, remember that only the len parameter is required because this function (in the python wrapper) returns the payload data as a buffer protocol object (bytearray object).

let radio be the instantiated RF24 object

if radio.available():

length = radio.getDynamicPayloadSize() # or radio.getPayloadSize() for static payload sizes

received_payload = radio.read(length)

This function no longer returns a boolean. Use available to determine if packets are available. The RX_DR Interrupt flag is now cleared with this function instead of when calling available().

if(radio.available()) {

radio.read(&data, sizeof(data));

}

Definition at line 1512 of file RF24.cpp.

◆ write() [1/2]

bool RF24::write(const void *buf,uint8_tlen )

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

This blocks until the message is successfully acknowledged by the receiver or the timeout/retransmit maxima are reached. In the current configuration, the max delay here is 60-70ms.

The maximum size of data written is the fixed payload size, see getPayloadSize(). However, you can write less, and the remainder will just be filled with zeroes.

TX/RX/RT interrupt flags will be cleared every time write is called

ParametersbufPointer to the data to be sentlenNumber of bytes to be sent

radio.stopListening();

radio.write(&data,sizeof(data));

NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.write(buffer)

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.

Definition at line 1253 of file RF24.cpp.

◆ openWritingPipe() [1/2]

void RF24::openWritingPipe(const uint8_t *address)

New: Open a pipe for writing via byte array. Old addressing format retained for compatibility.

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);

WarningThis 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.See also

setAddressWidth()

startListening()

ParametersaddressThe 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).RemarksThere 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 setAddressWidth()).

Definition at line 1549 of file RF24.cpp.

◆ openReadingPipe() [1/2]

void RF24::openReadingPipe(uint8_tnumber,const uint8_t *address )

Open a pipe for reading

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

See also

openWritingPipe()

setAddressWidth()

NotePipes 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"

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().

Read http://maniacalbits.blogspot.com/2013/04/rf24-addressing-nrf24l01-radios-require.html to understand how to avoid using malformed addresses. This address restoration is implemented because of the underlying necessary functionality of openWritingPipe().

ParametersnumberWhich pipe to open. Only pipe numbers 0-5 are available, an address assigned to any pipe number not in that range will be ignored.addressThe 24, 32 or 40 bit address of the pipe to open.

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 setAddressWidth()).

Definition at line 1605 of file RF24.cpp.

◆ printDetails()

void RF24::printDetails(void)

Print a giant block of debugging information to stdout

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

include

setup(){

Serial.begin(115200);

printf_begin();

...

}

Definition at line 676 of file RF24.cpp.

◆ printPrettyDetails()

void RF24::printPrettyDetails(void)

Print a giant block of debugging information to stdout. This function differs from printDetails() because it makes the information more understandable without having to look up the datasheet or convert hexadecimal to binary. Only use this function if your application can spare extra bytes of memory.

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

include

setup(){

Serial.begin(115200);

printf_begin();

// ...

}

NoteIf the automatic acknowledgements 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.

Definition at line 720 of file RF24.cpp.

◆ sprintfPrettyDetails()

uint16_t RF24::sprintfPrettyDetails(char *debugging_information)

Put a giant block of debugging information in a char array. This function differs from printPrettyDetails() because it uses sprintf() and does not use a predefined output stream (like Serial or stdout). Only use this function if your application can spare extra bytes of memory. This can also be used for boards that do not support printf() (which is required for printDetails() and printPrettyDetails()).

RemarksThe C standard function sprintf() formats a C-string in the exact same way as printf() but outputs (by reference) into a char array. The formatted string literal for sprintf() is stored in nonvolatile program memory.WarningUse a buffer of sufficient size for the debugging_information. Start with a char array that has at least 870 elements. There is no overflow protection when using sprintf(), so the output buffer must be sized correctly or the resulting behavior will be undefined.

char buffer[870] = {'\0'};

uint16_t used_chars = radio.sprintfPrettyDetails(buffer);

Serial.println(buffer);

Serial.print(F("strlen = "));

Serial.println(used_chars + 1); // +1 for c-strings' null terminating byte

Parametersdebugging_informationThe c-string buffer that the debugging information is stored to. This must be allocated to a minimum of 870 bytes of memory.ReturnsThe number of characters altered in the given buffer. Remember that, like sprintf(), this returned number does not include the null terminating byte.

This function is available in the python wrapper, but it accepts no parameters and returns a string. It does not return the number of characters in the string.

debug_info = radio.sprintfPrettyDetails()

print(debug_info)

print("str_len =", len(debug_info))

Definition at line 817 of file RF24.cpp.

◆ encodeRadioDetails()

void RF24::encodeRadioDetails(uint8_t *encoded_status)

Encode radio debugging information into an array of uint8_t. This function differs from other debug output methods because the debug information can be decoded by an external program.

This function is not available in the python wrapper because it is intended for use on processors with very limited available resources.

RemarksThis function uses much less ram than other printDetails() methods.

uint8_t encoded_details[43] = {0};

radio.encodeRadioDetails(encoded_details);

Parametersencoded_statusThe uint8_t array that RF24 radio details are encoded into. This array must be at least 43 bytes in length; any less would surely cause undefined behavior.

Registers names and/or data corresponding to the index of the encoded_details array:

indexregister/data0NRF_CONFIG1EN_AA2EN_RXADDR3SETUP_AW4SETUP_RETR5RF_CH6RF_SETUP7NRF_STATUS8OBSERVE_TX9CD (aka RPD)10-14RX_ADDR_P015-19RX_ADDR_P120RX_ADDR_P221RX_ADDR_P322RX_ADDR_P423RX_ADDR_P524-28TX_ADDR29RX_PW_P030RX_PW_P131RX_PW_P232RX_PW_P333RX_PW_P434RX_PW_P535FIFO_STATUS36DYNPD37FEATURE38-39ce_pin40-41csn_pin42SPI speed (in MHz) or'd with (isPlusVariant << 4)

Definition at line 900 of file RF24.cpp.

◆ available() [2/2]

bool RF24::available(uint8_t *pipe_num)

Test whether there are bytes available to be read from the FIFO buffers.

NoteThis function is named available_pipe() in the python wrapper.

Additionally, the available_pipe() function (which takes no arguments) returns a 2 item tuple containing (ordered by tuple's indices):

A boolean describing if there is a payload available to read from the RX FIFO buffers.

The pipe number that received the next available payload in the RX FIFO buffers. If the item at the tuple's index 0 is False, then this pipe number is invalid.

To use this function in python:

let radio be the instantiated RF24 object

has_payload, pipe_number = radio.available_pipe() # expand the tuple to 2 variables

if has_payload:

print("Received a payload with pipe", pipe_number)

Parameters[out]pipe_numWhich pipe has the payload available

uint8_t pipeNum;

if(radio.available(&pipeNum)){

radio.read(&data, sizeof(data));

Serial.print("Received data on pipe ");

Serial.println(pipeNum);

}

WarningAccording to the datasheet, the data saved to pipe_num is "unreliable" during a FALLING transition on the IRQ pin. This means you should call whatHappened() before calling this function during an ISR (Interrupt Service Routine). For example:

void isrCallbackFunction() {

bool tx_ds, tx_df, rx_dr;

radio.whatHappened(tx_ds, tx_df, rx_dr); // resets the IRQ pin to HIGH

uint8_t pipe; // initialize pipe data

radio.available(&pipe); // pipe data should now be reliable

}

void setup() {

pinMode(IRQ_PIN, INPUT);

attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING);

}

Returns

true if there is a payload available in the top (first out) level RX FIFO.

false if there is nothing available in the RX FIFO because it is empty.

Definition at line 1497 of file RF24.cpp.

◆ rxFifoFull()

bool RF24::rxFifoFull()

Use this function to check if the radio's RX 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.

Returns

true if all three 3 levels of the RX FIFO buffers are occupied.

false if there is one or more levels available in the RX FIFO buffers. Remember that this does not always mean that the RX FIFO buffers are empty; use available() to see if the RX FIFO buffers are empty or not.

Definition at line 1378 of file RF24.cpp.

◆ isFifo() [1/2]

uint8_t RF24::isFifo(boolabout_tx)

Parametersabout_txtrue focuses on the TX FIFO, false focuses on the RX FIFOReturns

0 if the specified FIFO is neither full nor empty.

1 if the specified FIFO is empty.

2 if the specified FIFO is full.

Definition at line 1385 of file RF24.cpp.

◆ isFifo() [2/2]

bool RF24::isFifo(boolabout_tx,boolcheck_empty )

Parametersabout_txtrue focuses on the TX FIFO, false focuses on the RX FIFOcheck_empty

true checks if the specified FIFO is empty

false checks is the specified FIFO is full.

ReturnsA boolean answer to the question "is the [TX/RX] FIFO [empty/full]?"

Definition at line 1392 of file RF24.cpp.

◆ powerDown()

void RF24::powerDown(void)

Enter low-power mode

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

NoteAfter 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)

radio.powerDown();

avr_enter_sleep_mode(); // Custom function to sleep the device

radio.powerUp();

Definition at line 1174 of file RF24.cpp.

◆ powerUp()

void RF24::powerUp(void)

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

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

NoteThis will take up to 5ms for maximum compatibility

Definition at line 1184 of file RF24.cpp.

◆ write() [2/2]

bool RF24::write(const void *buf,uint8_tlen,const boolmulticast )

Write for single NOACK writes. Optionally disable acknowledgements/auto-retries for a single payload using the multicast parameter set to true.

Can be used with enableAckPayload() to request a response

See also

setAutoAck()

write()

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.

NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.write(buffer, False) # False = the multicast parameter

Definition at line 1217 of file RF24.cpp.

◆ writeFast() [1/2]

bool RF24::writeFast(const void *buf,uint8_tlen )

This will not block until the 3 FIFO buffers are filled with data. Once the FIFOs are full, writeFast() will simply wait for a buffer to become available or a transmission failure (returning true or false respectively).

Warning

It is important to never keep the nRF24L01 in TX mode and FIFO full for more than 4ms at a time. If the auto retransmit is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO to clear by issuing txStandBy() or ensure appropriate time between transmissions.

Use txStandBy() when this function returns false.

Example (Partial blocking):

radio.writeFast(&buf,32); // Writes 1 payload to the buffers

txStandBy(); // Returns 0 if failed. 1 if success. Blocks only until MAX_RT timeout or success. Data flushed on fail.

radio.writeFast(&buf,32); // Writes 1 payload to the buffers

txStandBy(1000); // Using extended timeouts, returns 1 if success. Retries failed payloads for 1 seconds before returning 0.

See also

setAutoAck()

txStandBy()

write()

writeBlocking()

ParametersbufPointer to the data to be sentlenNumber of bytes to be sentReturns

true if the payload passed to buf was loaded in the TX FIFO.

false if the payload passed to buf was not loaded in the TX FIFO because a previous payload already in the TX FIFO failed to transmit. This condition can only be reported if the auto-ack feature is on.

NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.writeFast(buffer)

Definition at line 1338 of file RF24.cpp.

◆ writeFast() [2/2]

bool RF24::writeFast(const void *buf,uint8_tlen,const boolmulticast )

Similar to writeFast(const void*, uint8_t) but allows for single NOACK writes. Optionally disable acknowledgements/auto-retries for a single payload using the multicast parameter set to true.

WarningIf the auto-ack feature is enabled, then it is strongly encouraged to call txStandBy() when this function returns false.See also

setAutoAck()

txStandBy()

write()

writeBlocking()

true if the payload passed to buf was loaded in the TX FIFO.

NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.writeFast(buffer, False) # False = the multicast parameter

Definition at line 1307 of file RF24.cpp.

◆ writeBlocking()

bool RF24::writeBlocking(const void *buf,uint8_tlen,uint32_ttimeout )

This function extends the auto-retry mechanism to any specified duration. It will not block until the 3 FIFO buffers are filled with data. If so the library will auto retry until a new payload is written or the user specified timeout period is reached.

WarningIt is important to never keep the nRF24L01 in TX mode and FIFO full for more than 4ms at a time. If the auto retransmit is enabled, the nRF24L01 is never in TX mode long enough to disobey this rule. Allow the FIFO to clear by issuing txStandBy() or ensure appropriate time between transmissions.

Example (Full blocking):

radio.writeBlocking(&buf, sizeof(buf), 1000); // Wait up to 1 second to write 1 payload to the buffers

radio.txStandBy(1000); // Wait up to 1 second for the payload to send. Return 1 if ok, 0 if failed.

// Blocks only until user timeout or success. Data flushed on fail.

NoteIf used from within an interrupt, the interrupt should be disabled until completion, and sei(); called to enable millis().See also

txStandBy()

write()

writeFast()

ParametersbufPointer to the data to be sentlenNumber of bytes to be senttimeoutUser defined timeout in milliseconds.NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.writeBlocking(buffer, 1000) # 1000 means wait at most 1 second

Returns

true if the payload passed to buf was loaded in the TX FIFO.

Definition at line 1261 of file RF24.cpp.

◆ txStandBy() [1/2]

bool RF24::txStandBy()

This function should be called as soon as transmission is finished to drop the radio back to STANDBY-I mode. If not issued, the radio will remain in STANDBY-II mode which, per the data sheet, is not a recommended operating mode.

NoteWhen transmitting data in rapid succession, it is still recommended by the manufacturer to drop the radio out of TX or STANDBY-II mode if there is time enough between sends for the FIFOs to empty. This is not required if auto-ack is enabled.

Relies on built-in auto retry functionality.

Example (Partial blocking):

radio.writeFast(&buf, 32);

radio.writeFast(&buf, 32); //Fills the FIFO buffers up

bool ok = radio.txStandBy(); //Returns 0 if failed. 1 if success.

//Blocks only until MAX_RT timeout or success. Data flushed on fail.

See alsotxStandBy(uint32_t timeout, bool startTx)Returns

true if all payloads in the TX FIFO were delivered successfully and an acknowledgement (ACK packet) was received for each. If auto-ack is disabled, then any attempt to transmit will also return true (even if the payload was not received).

false if a payload was sent but was not acknowledged with an ACK packet. This condition can only be reported if the auto-ack feature is on.

Definition at line 1399 of file RF24.cpp.

◆ txStandBy() [2/2]

bool RF24::txStandBy(uint32_ttimeout,boolstartTx = 0 )

This function allows extended blocking and auto-retries per a user defined timeout

Fully Blocking Example:

radio.writeFast(&buf, 32);

radio.writeFast(&buf, 32); //Fills the FIFO buffers up

bool ok = radio.txStandBy(1000); //Returns 0 if failed after 1 second of retries. 1 if success.

//Blocks only until user defined timeout or success. Data flushed on fail.

NoteIf used from within an interrupt, the interrupt should be disabled until completion, and sei(); called to enable millis().ParameterstimeoutNumber of milliseconds to retry failed payloadsstartTxIf this is set to true, then this function puts the nRF24L01 in TX Mode. false leaves the primary mode (TX or RX) as it is, which can prevent the mandatory wait time to change modes.Returns

false if a payload was sent but was not acknowledged with an ACK packet. This condition can only be reported if the auto-ack feature is on.

Definition at line 1428 of file RF24.cpp.

◆ writeAckPayload()

bool RF24::writeAckPayload(uint8_tpipe,const void *buf,uint8_tlen )

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.

See also

enableAckPayload()

enableDynamicPayloads()

NoteACK 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 flush_tx()) before loading the first ACK payload into the TX FIFO. This function can be called before and after calling startListening().WarningOnly three of these can be pending at any time as there are only 3 FIFO buffers. Dynamic payloads must be enabled.NoteACK payloads are dynamic payloads. Calling enableAckPayload() will automatically enable dynamic payloads on pipe 0 (required for TX mode when expecting ACK payloads) & pipe 1. To use ACK payloads on any other pipe in RX mode, call enableDynamicPayloads().ParameterspipeWhich pipe# (typically 1-5) will get this response.bufPointer to data that is sentlenLength of the data to send, up to 32 bytes max. Not affected by the static payload size set by setPayloadSize().NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.writeAckPayload(1, buffer) # load an ACK payload for response on pipe 1

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().

Definition at line 1744 of file RF24.cpp.

◆ whatHappened()

void RF24::whatHappened(bool &tx_ok,bool &tx_fail,bool &rx_ready )

Call this when you get an Interrupt Request (IRQ) to find out why

This function describes what event triggered the IRQ pin to go active LOW and clears the status of all events.

See alsomaskIRQ()Parameters[out]tx_okThe 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.[out]tx_failThe 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.[out]rx_readyThere 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.NoteThis function expects no parameters in the python wrapper. Instead, this function returns a 3 item tuple describing the IRQ events' status. To use this function in the python wrapper:

letradio be the instantiated RF24 object

tx_ds, tx_df, rx_dr = radio.whatHappened() # get IRQ status flags

print("tx_ds: {}, tx_df: {}, rx_dr: {}".format(tx_ds, tx_df, rx_dr))

Definition at line 1524 of file RF24.cpp.

◆ startFastWrite()

void RF24::startFastWrite(const void *buf,uint8_tlen,const boolmulticast,boolstartTx = 1 )

Non-blocking write to the open writing pipe used for buffered writes

NoteOptimization: This function now leaves the CE pin high, so the radio will remain in TX or STANDBY-II Mode until a txStandBy() command is issued. Can be used as an alternative to startWrite() if writing multiple payloads at once.WarningIt 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 issuing txStandBy() or ensure appropriate time between transmissions.See also

write()

writeFast()

startWrite()

writeBlocking()

setAutoAck() (for single noAck writes)

ParametersbufPointer to the data to be sentlenNumber of bytes to be sentmulticastRequest ACK response (false), or no ACK response (true). Be sure to have called enableDynamicAck() at least once before setting this parameter.startTxIf this is set to true, then this function sets the nRF24L01's CE pin to active (enabling TX transmissions). false has no effect on the nRF24L01's CE pin and simply loads the payload into the TX FIFO.NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.startFastWrite(buffer, False, True) # 3rd parameter is optional

False means expecting ACK response (multicast parameter)

True means initiate transmission (startTx parameter)

Definition at line 1350 of file RF24.cpp.

◆ startWrite()

bool RF24::startWrite(const void *buf,uint8_tlen,const boolmulticast )

Non-blocking write to the open writing pipe

Just like write(), but it returns immediately. To find out what happened to the send, catch the IRQ and then call whatHappened().

See also

write()

writeFast()

startFastWrite()

whatHappened()

setAutoAck() (for single noAck writes)

true if payload was written to the TX FIFO buffers and the transmission was started.

false if the TX FIFO is full and the payload could not be written. In this condition, the transmission process is restarted.

NoteThe len parameter must be omitted when using the python wrapper because the length of the payload is determined automatically. To use this function in the python wrapper:

let radio be the instantiated RF24 object

buffer = b"Hello World" # a bytes object

radio.startWrite(buffer, False) # False = the multicast parameter

Definition at line 1363 of file RF24.cpp.

◆ reUseTX()

void RF24::reUseTX()

The function will instruct the radio to re-use the payload in the top level (first out) of the TX FIFO buffers. This is used internally by writeBlocking() to initiate retries when a TX failure occurs. Retries are automatically initiated except with the standard write(). This way, data is not flushed from the buffer until calling flush_tx(). If the TX FIFO has only the one payload (in the top level), the re-used payload can be overwritten by using write(), writeFast(), writeBlocking(), startWrite(), or startFastWrite(). If the TX FIFO has other payloads enqueued, then the aforementioned functions will attempt to enqueue the a new payload in the TX FIFO (does not overwrite the top level of the TX FIFO). Currently, stopListening() also calls flush_tx() when ACK payloads are enabled (via enableAckPayload()).

Upon exiting, this function will set the CE pin HIGH to initiate the re-transmission process. If only 1 re-transmission is desired, then the CE pin should be set to LOW after the mandatory minumum pulse duration of 10 microseconds.

RemarksThis function only applies when taking advantage of the auto-retry feature. See setAutoAck() and setRetries() to configure the auto-retry feature.NoteThis is to be used AFTER auto-retry fails if wanting to resend using the built-in payload reuse feature. After issuing reUseTX(), it will keep resending the same payload until a transmission failure occurs or the CE pin is set to LOW (whichever comes first). In the event of a re-transmission failure, simply call this function again to resume re-transmission of the same payload.

Definition at line 1296 of file RF24.cpp.

◆ flush_tx()

uint8_t RF24::flush_tx(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.

ReturnsCurrent value of status register

Definition at line 478 of file RF24.cpp.

◆ flush_rx()

uint8_t RF24::flush_rx(void)

Empty all 3 of the RX (receive) FIFO buffers.

ReturnsCurrent value of status register

Definition at line 469 of file RF24.cpp.

◆ testCarrier()

bool RF24::testCarrier(void)

Test whether there was a carrier on the line for the previous listening period.

Useful to check for interference on the current channel.

Returnstrue if was carrier, false if not

Definition at line 1807 of file RF24.cpp.

◆ testRPD()

bool RF24::testRPD(void)

Test whether a signal (carrier or otherwise) greater than or equal to -64dBm is present on the channel. Valid only on nRF24L01P (+) hardware. On nRF24L01, use testCarrier().

Useful 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(&payload,sizeof(payload));

}

Returnstrue if a signal greater than or equal to -64dBm was detected, false if not.

Definition at line 1814 of file RF24.cpp.

◆ isValid()

bool RF24::isValid()

Test whether this is a real radio, or a mock shim for debugging. Setting either pin to 0xff is the way to indicate that this is not a real radio.

Returnstrue if this is a legitimate radio

Definition at line 1118 of file RF24.cpp.

◆ closeReadingPipe()

void RF24::closeReadingPipe(uint8_tpipe)

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

ParameterspipeWhich pipe number to close, any integer not in range [0, 5] is ignored.

Definition at line 1632 of file RF24.cpp.

◆ setAddressWidth()

void RF24::setAddressWidth(uint8_ta_width)

Set the address width from 3 to 5 bytes (24, 32 or 40 bit)

Parametersa_widthThe address width (in bytes) to use; this can be 3, 4 or 5.

Definition at line 1590 of file RF24.cpp.

◆ setRetries()

void RF24::setRetries(uint8_tdelay,uint8_tcount )

Set the number of retry attempts and delay between retry attempts when transmitting a payload. The radio is waiting for an acknowledgement (ACK) packet during the delay between retry attempts.

ParametersdelayHow long to wait between each retry, in multiples of 250 us. The minimum of 0 means 250 us, and the maximum of 15 means 4000 us. The default value of 5 means 1500us (5 * 250 + 250).countHow many retries before giving up. The default/maximum is 15. Use 0 to disable the auto-retry feature all together.NoteDisable the auto-retry feature on a transmitter still uses the auto-ack feature (if enabled), except it will not retry to transmit if the payload was not acknowledged on the first attempt.

Definition at line 1935 of file RF24.cpp.

◆ setChannel()

void RF24::setChannel(uint8_tchannel)

Set RF communication channel. The frequency used by a channel is calculated as:

2400 MHz +

Meaning the default channel of 76 uses the approximate frequency of 2476 MHz.

NoteIn the python wrapper, this function is the setter of the channel attribute.To use this function in the python wrapper:

let radio be the instantiated RF24 object

radio.channel = 2 # set the channel to 2 (2402 MHz)

ParameterschannelWhich RF channel to communicate on, 0-125

Definition at line 596 of file RF24.cpp.

◆ getChannel()

uint8_t RF24::getChannel(void)

Get RF communication channel

NoteIn the python wrapper, this function is the getter of the channel attribute.To use this function in the python wrapper:

let radio be the instantiated RF24 object

chn = radio.channel # get the channel

ReturnsThe currently configured RF Channel

Definition at line 602 of file RF24.cpp.

◆ setPayloadSize()

void RF24::setPayloadSize(uint8_tsize)

Set Static Payload Size

This implementation uses a pre-established fixed payload size for all transmissions. If this method is never called, the driver will always transmit the maximum payload size (32 bytes), no matter how much was sent to write().

NoteIn the python wrapper, this function is the setter of the payloadSize attribute.To use this function in the python wrapper:

let radio be the instantiated RF24 object

radio.payloadSize = 16 # set the static payload size to 16 bytes

ParameterssizeThe number of bytes in the payload

Definition at line 609 of file RF24.cpp.

◆ getPayloadSize()

uint8_t RF24::getPayloadSize(void)

Get Static Payload Size

NoteIn the python wrapper, this function is the getter of the payloadSize attribute.To use this function in the python wrapper:

let radio be the instantiated RF24 object

pl_size = radio.payloadSize # get the static payload size

See alsosetPayloadSize()ReturnsThe number of bytes in the payload

Definition at line 622 of file RF24.cpp.

◆ getDynamicPayloadSize()

uint8_t RF24::getDynamicPayloadSize(void)

Get Dynamic Payload Size

For dynamic payloads, this pulls the size of the payload off the chip

NoteCorrupt packets are now detected and flushed per the manufacturer.

if(radio.available()){

if(radio.getDynamicPayloadSize() < 1){

// Corrupt payload has been flushed

return;

}

radio.read(&data,sizeof(data));

}

ReturnsPayload length of last-received dynamic payload

Definition at line 1475 of file RF24.cpp.

◆ enableAckPayload()

void RF24::enableAckPayload(void)

Enable custom payloads in the acknowledge packets

ACK payloads are a handy way to return data back to senders without manually changing the radio modes on both units.

RemarksThe ACK payload feature requires the auto-ack feature to be enabled for any pipe using ACK payloads. This function does not automatically enable the auto-ack feature on pipe 0 since the auto-ack feature is enabled for all pipes by default.See alsosetAutoAck()NoteACK payloads are dynamic payloads. This function automatically enables dynamic payloads on pipes 0 & 1 by default. Call enableDynamicPayloads() to enable on all pipes (especially for RX nodes that use pipes other than pipe 0 to receive transmissions expecting responses with ACK payloads).

Definition at line 1699 of file RF24.cpp.

◆ disableAckPayload()

void RF24::disableAckPayload(void)

Disable custom payloads on the acknowledge packets

HACKDRES2 / virus-link

Extraer en mi entordor #14

include

include

include