Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver.
More...
#include <RF24.h>
|
|
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) |
|
void | stopListening (const uint8_t *txAddress) |
| Similar to startListening(void) but changes the TX address.
|
|
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) |
|
|
Methods provided for backwards compatibility.
|
void | openReadingPipe (uint8_t number, uint64_t address) |
|
void | openWritingPipe (uint64_t address) |
|
bool | isAckPayloadAvailable (void) |
|
void | maskIRQ (bool tx_ok, bool tx_fail, bool rx_ready) |
|
void | whatHappened (bool &tx_ok, bool &tx_fail, bool &rx_ready) |
|
void | stopListening (const uint64_t txAddress) |
|
|
Methods you can use to drive the chip in more advanced ways
|
bool | failureDetected |
|
void | ce (bool level) |
|
void | printDetails (void) |
|
void | printStatus (uint8_t flags) |
|
void | printPrettyDetails (void) |
|
uint16_t | sprintfPrettyDetails (char *debugging_information) |
|
void | encodeRadioDetails (uint8_t *encoded_status) |
|
bool | available (uint8_t *pipe_num) |
|
bool | rxFifoFull () |
|
rf24_fifo_state_e | 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) |
|
uint8_t | clearStatusFlags (uint8_t flags=RF24_IRQ_ALL) |
|
void | setStatusFlags (uint8_t flags=RF24_IRQ_NONE) |
|
uint8_t | getStatusFlags () |
|
uint8_t | update () |
|
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) |
|
Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver.
- Examples
- examples/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 159 of file RF24.h.
◆ RF24() [1/2]
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
-
_cepin | The pin attached to Chip Enable on the RF module. Review our Linux general doc for details about selecting pin numbers on Linux systems. |
_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 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 560 of file RF24.cpp.
◆ RF24() [2/2]
A constructor for initializing the radio's hardware dynamically
- Warning
- You 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_speed | The 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 579 of file RF24.cpp.
◆ 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 |
◆ read_register() [1/2]
void RF24::read_register |
( |
uint8_t | reg, |
|
|
uint8_t * | buf, |
|
|
uint8_t | len ) |
|
protected |
Read a chunk of data in from a register
- Parameters
-
| reg | Which register. Use constants from nRF24L01.h |
[out] | buf | Where to put the data |
| len | How many bytes of data to transfer |
- Note
- This 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_t | reg | ) |
|
|
protected |
Read single byte from a register
- Parameters
-
- Returns
- Current 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) {}
}
- Returns
true
if the radio was successfully initialized
false
if the MCU failed to communicate with the radio hardware
Definition at line 973 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.
- Note
- This function assumes the
SPI::begin()
method was called before to calling this function.
- Warning
- This function is for the Arduino platforms only
- Parameters
-
spiBus | A 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 also
- Review the Arduino support page.
- Returns
- same result as begin()
Definition at line 945 of file RF24.cpp.
◆ begin() [3/4]
Same as begin(), but allows dynamically specifying a SPI bus, CE pin, and CSN pin to use.
- Note
- This function assumes the
SPI::begin()
method was called before to calling this function.
- Warning
- This function is for the Arduino platforms only
- Parameters
-
spiBus | A 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. |
_cepin | The pin attached to Chip Enable on the RF module. Review our Linux general doc for details about selecting pin numbers on Linux systems. |
_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.
|
- See also
- Review the Arduino support page.
- Returns
- same result as begin()
Definition at line 953 of file RF24.cpp.
◆ begin() [4/4]
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 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()
Definition at line 964 of file RF24.cpp.
◆ isChipConnected()
bool RF24::isChipConnected |
( |
| ) |
|
Checks if the chip is connected to the SPI bus
Definition at line 1130 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();
- 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.
Definition at line 1144 of file RF24.cpp.
◆ stopListening() [1/3]
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));
- Warning
- 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.
Definition at line 1168 of file RF24.cpp.
◆ stopListening() [2/3]
void RF24::stopListening |
( |
const uint8_t * | txAddress | ) |
|
Similar to startListening(void) but changes the TX address.
- Parameters
-
txAddress | The new TX address. This value will be cached for auto-ack purposes. |
Definition at line 1203 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 also
- available(uint8_t*)
- Returns
- True if there is a payload available, false if none is
- 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 clearStatusFlags() before calling this function during an ISR (Interrupt Service Routine). For example:
void isrCallbackFunction() {
bool tx_ds, tx_df, rx_dr;
uint8_t flags = radio.clearStatusFlags();
radio.available();
}
void setup() {
attachInterrupt(digitalPinToInterrupt(IRQ_PIN), isrCallbackFunction, FALLING);
}
#define pinMode(pin, direction)
Definition at line 1532 of file RF24.cpp.
◆ read()
void RF24::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
- See also
-
- Note
- I specifically chose
void*
as a data type to make it easier for beginners to use. No casting needed.
- Parameters
-
buf | Pointer to a buffer where the data should be written |
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 32 (for dynamic payload lengths) or whatever number was previously passed to setPayloadSize() (for static payload lengths). |
- Note
- To 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).
if radio.available():
length = radio.getDynamicPayloadSize()
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 1550 of file RF24.cpp.
◆ write() [1/2]
bool RF24::write |
( |
const void * | buf, |
|
|
uint8_t | len ) |
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
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
radio.stopListening();
radio.write(&data,sizeof(data));
- Note
- The
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:
buffer = b"Hello World"
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 1291 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.
- Deprecated
- Use
RF24::stopListening(uint8_t*)
instead.
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);
- 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.
- See also
-
- 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). This address is cached to ensure proper auto-ack behavior; stopListening() will always restore the latest cached TX address. |
Definition at line 1620 of file RF24.cpp.
◆ openReadingPipe() [1/2]
void RF24::openReadingPipe |
( |
uint8_t | number, |
|
|
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
-
- 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"};
void openReadingPipe(uint8_t number, const uint8_t *address)
- 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().
- 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 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 1679 of file RF24.cpp.
◆ ce()
void RF24::ce |
( |
bool | level | ) |
|
Set radio's CE (Chip Enable) pin state.
- Warning
- Please see the datasheet for a much more detailed description of this pin.
- Note
- This is only publicly exposed for advanced use cases such as complex networking or streaming consecutive payloads without robust error handling. Typical uses are satisfied by simply using
startListening()
for RX mode or stopListening()
and write()
for TX mode.
- Parameters
-
level | In RX mode, HIGH causes the radio to begin actively listening. In TX mode, HIGH (+ 130 microsecond delay) causes the radio to begin transmitting. Setting this to LOW will cause the radio to stop transmitting or receiving in any mode. |
Definition at line 103 of file RF24.cpp.
◆ printDetails()
void RF24::printDetails |
( |
void | | ) |
|
Print a giant block of debugging information to stdout
- Warning
- Does nothing if stdout is not defined. See fdevopen in stdio.h The printf.h file is included with the library for Arduino.
setup() {
Serial.begin(115200);
}
Definition at line 693 of file RF24.cpp.
◆ printStatus()
void RF24::printStatus |
( |
uint8_t | flags | ) |
|
Decode and print the given STATUS byte to stdout.
- Parameters
-
- Warning
- Does nothing if stdout is not defined. See fdevopen in stdio.h
Definition at line 488 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.
- Warning
- Does nothing if stdout is not defined. See fdevopen in stdio.h The printf.h file is included with the library for Arduino.
setup() {
Serial.begin(115200);
}
- Note
- If 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 739 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()).
- Warning
- Use 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);
- Parameters
-
debugging_information | The c-string buffer that the debugging information is stored to. This must be allocated to a minimum of 870 bytes of memory. |
- Returns
- The 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))
- Note
- If 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 836 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.
uint8_t encoded_details[43] = {0};
radio.encodeRadioDetails(encoded_details);
- Parameters
-
encoded_status | The 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:
index | register/data |
0 | NRF_CONFIG |
1 | EN_AA |
2 | EN_RXADDR |
3 | SETUP_AW |
4 | SETUP_RETR |
5 | RF_CH |
6 | RF_SETUP |
7 | NRF_STATUS |
8 | OBSERVE_TX |
9 | CD (aka RPD) |
10-14 | RX_ADDR_P0 |
15-19 | RX_ADDR_P1 |
20 | RX_ADDR_P2 |
21 | RX_ADDR_P3 |
22 | RX_ADDR_P4 |
23 | RX_ADDR_P5 |
24-28 | TX_ADDR |
29 | RX_PW_P0 |
30 | RX_PW_P1 |
31 | RX_PW_P2 |
32 | RX_PW_P3 |
33 | RX_PW_P4 |
34 | RX_PW_P5 |
35 | FIFO_STATUS |
36 | DYNPD |
37 | FEATURE |
38-39 | ce_pin |
40-41 | csn_pin |
42 | SPI speed (in MHz) or'd with (isPlusVariant << 4) |
Definition at line 919 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.
- Note
- This 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:
has_payload, pipe_number = radio.available_pipe()
if has_payload:
print("Received a payload with pipe", pipe_number)
- Parameters
-
[out] | pipe_num | Which 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);
}
|
- Warning
- According to the datasheet, the data saved to
pipe_num
is "unreliable" during a FALLING transition on the IRQ pin. This means you should call clearStatusFlags() before calling this function during an ISR (Interrupt Service Routine). For example: void isrCallbackFunction() {
radio.clearStatusFlags();
uint8_t pipe = 7;
radio.available(&pipe);
}
void setup() {
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 1539 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 1421 of file RF24.cpp.
◆ isFifo() [1/2]
- Parameters
-
about_tx | true focuses on the TX FIFO, false focuses on the RX FIFO |
- Returns
-
Definition at line 1428 of file RF24.cpp.
◆ isFifo() [2/2]
bool RF24::isFifo |
( |
bool | about_tx, |
|
|
bool | check_empty ) |
- Deprecated
- Use RF24::isFifo(bool about_tx) instead. See our migration guide to understand what you should update in your code.
- Parameters
-
about_tx | true focuses on the TX FIFO, false focuses on the RX FIFO |
check_empty |
true checks if the specified FIFO is empty
false checks is the specified FIFO is full.
|
- Returns
- A boolean answer to the question "is the [TX/RX] FIFO [empty/full]?"
Definition at line 1436 of file RF24.cpp.
◆ powerDown()
void RF24::powerDown |
( |
void | | ) |
|
Enter low-power mode
To return to normal power mode, call 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)
radio.powerDown();
avr_enter_sleep_mode();
radio.powerUp();
Definition at line 1212 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().
- Note
- This will take up to 5ms for maximum compatibility
Definition at line 1222 of file RF24.cpp.
◆ write() [2/2]
bool RF24::write |
( |
const void * | buf, |
|
|
uint8_t | len, |
|
|
const bool | multicast ) |
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
-
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
multicast | Request ACK response (false), or no ACK response (true). Be sure to have called enableDynamicAck() 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.
- Note
- The
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:
buffer = b"Hello World"
radio.write(buffer, False)
Definition at line 1255 of file RF24.cpp.
◆ writeFast() [1/2]
bool RF24::writeFast |
( |
const void * | buf, |
|
|
uint8_t | len ) |
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);
radio.writeFast(&buf,32);
- See also
-
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
- Returns
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.
- Note
- The
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:
buffer = b"Hello World"
radio.writeFast(buffer)
Definition at line 1376 of file RF24.cpp.
◆ writeFast() [2/2]
bool RF24::writeFast |
( |
const void * | buf, |
|
|
uint8_t | len, |
|
|
const bool | multicast ) |
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
.
- Warning
- If the auto-ack feature is enabled, then it is strongly encouraged to call txStandBy() when this function returns
false
.
- See also
-
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
multicast | Request ACK response (false), or no ACK response (true). Be sure to have called enableDynamicAck() at least once before setting this parameter. |
- Returns
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 (and the multicast parameter is set to false).
- Note
- The
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:
buffer = b"Hello World"
radio.writeFast(buffer, False)
Definition at line 1345 of file RF24.cpp.
◆ writeBlocking()
bool RF24::writeBlocking |
( |
const void * | buf, |
|
|
uint8_t | len, |
|
|
uint32_t | timeout ) |
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.
- 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.
Example (Full blocking):
radio.writeBlocking(&buf, sizeof(buf), 1000);
radio.txStandBy(1000);
- Note
- If used from within an interrupt, the interrupt should be disabled until completion, and sei(); called to enable millis().
- See also
-
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
timeout | User defined timeout in milliseconds. |
- Note
- The
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:
buffer = b"Hello World"
radio.writeBlocking(buffer, 1000)
- Returns
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.
Definition at line 1299 of file RF24.cpp.
◆ txStandBy() [1/2]
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.
- Note
- When 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);
radio.writeFast(&buf, 32);
bool ok = radio.txStandBy();
- See also
- txStandBy(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 1443 of file RF24.cpp.
◆ txStandBy() [2/2]
bool RF24::txStandBy |
( |
uint32_t | timeout, |
|
|
bool | startTx = 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);
radio.writeFast(&buf, 32);
bool ok = radio.txStandBy(1000);
- Note
- If used from within an interrupt, the interrupt should be disabled until completion, and sei(); called to enable millis().
- Parameters
-
timeout | Number of milliseconds to retry failed payloads |
startTx | If 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
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 1472 of file RF24.cpp.
◆ writeAckPayload()
bool RF24::writeAckPayload |
( |
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.
- See also
-
- Note
- 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 flush_tx()) before loading the first ACK payload into the TX FIFO. This function can be called before and after calling startListening().
- Warning
- Only three of these can be pending at any time as there are only 3 FIFO buffers. Dynamic payloads must be enabled.
- Note
- ACK 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().
- 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 size set by setPayloadSize(). |
- Note
- The
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:
buffer = b"Hello World"
radio.writeAckPayload(1, buffer)
- 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 1820 of file RF24.cpp.
◆ startFastWrite()
void RF24::startFastWrite |
( |
const void * | buf, |
|
|
uint8_t | len, |
|
|
const bool | multicast, |
|
|
bool | startTx = 1 ) |
Non-blocking write to the open writing pipe used for buffered writes
- Note
- Optimization: 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.
- 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 issuing txStandBy() or ensure appropriate time between transmissions.
- See also
-
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
multicast | Request ACK response (false), or no ACK response (true). Be sure to have called enableDynamicAck() at least once before setting this parameter. |
startTx | If 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. |
- Note
- The
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:
buffer = b"Hello World"
radio.startFastWrite(buffer, False, True)
Definition at line 1388 of file RF24.cpp.
◆ startWrite()
bool RF24::startWrite |
( |
const void * | buf, |
|
|
uint8_t | len, |
|
|
const bool | multicast ) |
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 clearStatusFlags() or update().
- See also
-
- Parameters
-
buf | Pointer to the data to be sent |
len | Number of bytes to be sent |
multicast | Request ACK response (false), or no ACK response (true). Be sure to have called enableDynamicAck() at least once before setting this parameter. |
- Returns
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.
- Note
- The
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:
buffer = b"Hello World"
radio.startWrite(buffer, False)
Definition at line 1401 of file RF24.cpp.
◆ 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.
- Note
- This 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 1334 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.
- Returns
- Current 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.
- Returns
- Current 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.
- Returns
- true if was carrier, false if not
Definition at line 1882 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));
}
- Returns
- true if a signal greater than or equal to -64dBm was detected, false if not.
Definition at line 1889 of file RF24.cpp.
◆ 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.
- Returns
- true if this is a legitimate radio
Definition at line 1137 of file RF24.cpp.
◆ closeReadingPipe()
void RF24::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. |
Definition at line 1708 of file RF24.cpp.
◆ setAddressWidth()
void RF24::setAddressWidth |
( |
uint8_t | a_width | ) |
|
Set the address width from 3 to 5 bytes (24, 32 or 40 bit)
- Parameters
-
a_width | The address width (in bytes) to use; this can be 3, 4 or 5. |
Definition at line 1664 of file RF24.cpp.
◆ setRetries()
void RF24::setRetries |
( |
uint8_t | delay, |
|
|
uint8_t | count ) |
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.
- Parameters
-
delay | How 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). |
count | How many retries before giving up. The default/maximum is 15. Use 0 to disable the auto-retry feature all together. |
- Note
- Disable 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 2010 of file RF24.cpp.
◆ setChannel()
void RF24::setChannel |
( |
uint8_t | channel | ) |
|
Set RF communication channel. The frequency used by a channel is calculated as:
2400 MHz + <channel number>
Meaning the default channel of 76 uses the approximate frequency of 2476 MHz.
- Note
- In the python wrapper, this function is the setter of the
channel
attribute.To use this function in the python wrapper:
- Parameters
-
channel | Which RF channel to communicate on, 0-125 |
Definition at line 613 of file RF24.cpp.
◆ getChannel()
uint8_t RF24::getChannel |
( |
void | | ) |
|
Get RF communication channel
- Note
- In the python wrapper, this function is the getter of the
channel
attribute.To use this function in the python wrapper:
- Returns
- The currently configured RF Channel
Definition at line 619 of file RF24.cpp.
◆ setPayloadSize()
void RF24::setPayloadSize |
( |
uint8_t | size | ) |
|
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().
- Note
- In the python wrapper, this function is the setter of the
payloadSize
attribute.To use this function in the python wrapper:
- Parameters
-
size | The number of bytes in the payload |
Definition at line 626 of file RF24.cpp.
◆ getPayloadSize()
uint8_t RF24::getPayloadSize |
( |
void | | ) |
|
Get Static Payload Size
- Note
- In the python wrapper, this function is the getter of the
payloadSize
attribute.To use this function in the python wrapper:
pl_size = radio.payloadSize
- See also
- setPayloadSize()
- Returns
- The number of bytes in the payload
Definition at line 639 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
- Note
- Corrupt packets are now detected and flushed per the manufacturer.
if(radio.available()){
if(radio.getDynamicPayloadSize() < 1){
return;
}
radio.read(&data,sizeof(data));
}
- Returns
- Payload length of last-received dynamic payload
Definition at line 1519 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.
- See also
- setAutoAck()
- Note
- ACK 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 1775 of file RF24.cpp.
◆ disableAckPayload()
void RF24::disableAckPayload |
( |
void | | ) |
|
◆ enableDynamicPayloads()
void RF24::enableDynamicPayloads |
( |
void | | ) |
|
Enable dynamically-sized payloads
This way you don't always have to send large packets just to send them once in a while. This enables dynamic payloads on ALL pipes.
Definition at line 1734 of file RF24.cpp.
◆ disableDynamicPayloads()
void RF24::disableDynamicPayloads |
( |
void | | ) |
|
Disable dynamically-sized payloads
This disables dynamic payloads on ALL pipes. Since Ack Payloads requires Dynamic Payloads, Ack Payloads are also disabled. If dynamic payloads are later re-enabled and ack payloads are desired then enableAckPayload() must be called again as well.
Definition at line 1754 of file RF24.cpp.
◆ enableDynamicAck()
void RF24::enableDynamicAck |
( |
void | | ) |
|
Enable dynamic ACKs (single write multicast or unicast) for chosen messages.
- Note
- This function must be called once before using the multicast parameter for any functions that offer it. To use multicast behavior about all outgoing payloads (using pipe 0) or incoming payloads (concerning all RX pipes), use setAutoAck()
- See also
-
radio.write(&data, 32, 1);
radio.write(&data, 32, 0);
Definition at line 1807 of file RF24.cpp.
◆ isPVariant()
bool RF24::isPVariant |
( |
void | | ) |
|
Determine whether the hardware is an nRF24L01+ or not.
- Returns
- true if the hardware is nRF24L01+ (or compatible) and false if its not.
Definition at line 1840 of file RF24.cpp.
◆ setAutoAck() [1/2]
void RF24::setAutoAck |
( |
bool | enable | ) |
|
Enable or disable the auto-acknowledgement feature for all pipes. This feature is enabled by default. Auto-acknowledgement responds to every received payload with an empty ACK packet. These ACK packets get sent from the receiving radio back to the transmitting radio. To attach an ACK payload to a ACK packet, use writeAckPayload().
If this feature is disabled on a transmitting radio, then the transmitting radio will always report that the payload was received (even if it was not). Please remember that this feature's configuration needs to match for transmitting and receiving radios.
- Warning
- When using the
multicast
parameter to write(), this feature can be disabled for an individual payload. However, if this feature is disabled, then the multicast
parameter will have no effect.
- Note
- If disabling auto-acknowledgment packets, the ACK payloads feature is also disabled as this feature is required to send ACK payloads.
- See also
-
- Parameters
-
enable | Whether to enable (true) or disable (false) the auto-acknowledgment feature for all pipes |
Definition at line 1847 of file RF24.cpp.
◆ setAutoAck() [2/2]
void RF24::setAutoAck |
( |
uint8_t | pipe, |
|
|
bool | enable ) |
Enable or disable the auto-acknowledgement feature for a specific pipe. This feature is enabled by default for all pipes. Auto-acknowledgement responds to every received payload with an empty ACK packet. These ACK packets get sent from the receiving radio back to the transmitting radio. To attach an ACK payload to a ACK packet, use writeAckPayload().
Pipe 0 is used for TX operations, which include sending ACK packets. If using this feature on both TX & RX nodes, then pipe 0 must have this feature enabled for the RX & TX operations. If this feature is disabled on a transmitting radio's pipe 0, then the transmitting radio will always report that the payload was received (even if it was not). Remember to also enable this feature for any pipe that is openly listening to a transmitting radio with this feature enabled.
- Warning
- If this feature is enabled for pipe 0, then the
multicast
parameter to write() can be used to disable this feature for an individual payload. However, if this feature is disabled for pipe 0, then the multicast
parameter will have no effect.
- Note
- If disabling auto-acknowledgment packets on pipe 0, the ACK payloads feature is also disabled as this feature is required on pipe 0 to send ACK payloads.
- See also
-
- Parameters
-
pipe | Which pipe to configure. This number should be in range [0, 5]. |
enable | Whether to enable (true) or disable (false) the auto-acknowledgment feature for the specified pipe |
Definition at line 1863 of file RF24.cpp.
◆ setPALevel()
void RF24::setPALevel |
( |
uint8_t | level, |
|
|
bool | lnaEnable = 1 ) |
Set Power Amplifier (PA) level and Low Noise Amplifier (LNA) state
- Parameters
-
level | The desired Power Amplifier level as defined by rf24_pa_dbm_e. |
lnaEnable | Enable or Disable the LNA (Low Noise Amplifier) Gain. See table for Si24R1 modules below. lnaEnable only affects nRF24L01 modules with an LNA chip. |
level (enum value) | nRF24L01
description | Si24R1
description when
lnaEnable = 1 | Si24R1
description when
lnaEnable = 0 |
RF24_PA_MIN (0) | -18 dBm | -6 dBm | -12 dBm |
RF24_PA_LOW (1) | -12 dBm | -0 dBm | -4 dBm |
RF24_PA_HIGH (2) | -6 dBm | 3 dBm | 1 dBm |
RF24_PA_MAX (3) | 0 dBm | 7 dBm | 4 dBm |
- Note
- The getPALevel() function does not care what was passed
lnaEnable
parameter.
Definition at line 1896 of file RF24.cpp.
◆ getPALevel()
uint8_t RF24::getPALevel |
( |
void | | ) |
|
◆ getARC()
uint8_t RF24::getARC |
( |
void | | ) |
|
Returns automatic retransmission count (ARC_CNT)
Value resets with each new transmission. Allows roughly estimating signal strength.
- Returns
- Returns values from 0 to 15.
Definition at line 1912 of file RF24.cpp.
◆ setDataRate()
◆ getDataRate()
◆ setCRCLength()
Set the CRC length (in bits)
CRC cannot be disabled if auto-ack is enabled
- Parameters
-
Definition at line 1963 of file RF24.cpp.
◆ getCRCLength()
◆ disableCRC()
void RF24::disableCRC |
( |
void | | ) |
|
Disable CRC validation
- Warning
- CRC cannot be disabled if auto-ack/ESB is enabled.
Definition at line 2003 of file RF24.cpp.
◆ startConstCarrier()
void RF24::startConstCarrier |
( |
rf24_pa_dbm_e | level, |
|
|
uint8_t | channel ) |
Transmission of constant carrier wave with defined frequency and output power
- Parameters
-
level | Output power to use |
channel | The channel to use |
- Warning
- If isPVariant() returns true, then this function takes extra measures that alter some settings. These settings alterations include:
Definition at line 2016 of file RF24.cpp.
◆ stopConstCarrier()
void RF24::stopConstCarrier |
( |
void | | ) |
|
Stop transmission of constant wave and reset PLL and CONT registers
- Warning
- this function will powerDown() the radio per recommendation of datasheet.
- Note
- If isPVariant() returns true, please remember to re-configure the radio's settings
void setRetries(uint8_t delay, uint8_t count)
void setCRCLength(rf24_crclength_e length)
void setAutoAck(bool enable)
- See also
- startConstCarrier()
Definition at line 2050 of file RF24.cpp.
◆ toggleAllPipes()
void RF24::toggleAllPipes |
( |
bool | isEnabled | ) |
|
Open or close all data pipes.
This function does not alter the addresses assigned to pipes. It is simply a convenience function that allows controlling all pipes at once.
- Parameters
-
isEnabled | true opens all pipes; false closes all pipes. |
Definition at line 2070 of file RF24.cpp.
◆ setRadiation()
void RF24::setRadiation |
( |
uint8_t | level, |
|
|
rf24_datarate_e | speed, |
|
|
bool | lnaEnable = true ) |
configure the RF_SETUP register in 1 transaction
- Parameters
-
level | This parameter is the same input as setPALevel()'s level parameter. See rf24_pa_dbm_e enum for accepted values. |
speed | This parameter is the same input as setDataRate()'s speed parameter. See rf24_datarate_e enum for accepted values. |
lnaEnable | This optional parameter is the same as setPALevel()'s lnaEnable optional parameter. Defaults to true (meaning LNA feature is enabled) when not specified. |
Definition at line 2120 of file RF24.cpp.
◆ openReadingPipe() [2/2]
void RF24::openReadingPipe |
( |
uint8_t | number, |
|
|
uint64_t | address ) |
◆ openWritingPipe() [2/2]
void RF24::openWritingPipe |
( |
uint64_t | address | ) |
|
Open a pipe for writing
- Deprecated
- For compatibility with old code only, see newer function openWritingPipe(). See our migration guide to understand what you should update in your code.
Addresses are 40-bit hex values, e.g.:
void openWritingPipe(const uint8_t *address)
- Parameters
-
address | The 40-bit address of the pipe to open. |
Definition at line 1608 of file RF24.cpp.
◆ isAckPayloadAvailable()
bool RF24::isAckPayloadAvailable |
( |
void | | ) |
|
◆ maskIRQ()
void RF24::maskIRQ |
( |
bool | tx_ok, |
|
|
bool | tx_fail, |
|
|
bool | rx_ready ) |
This function is used to configure what events will trigger the Interrupt Request (IRQ) pin active LOW.
- Deprecated
- Use setStatusFlags() instead. See our migration guide to understand what you should update in your code.
The following events can be configured:
- "data sent": This does not mean that the data transmitted was received, only that the attempt to send it was complete.
- "data failed": This means the data being sent was not received. This event is only triggered when the auto-ack feature is enabled.
- "data received": This means that data from a receiving payload has been loaded into the RX FIFO buffers. Remember that there are only 3 levels available in the RX FIFO buffers.
By default, all events are configured to trigger the IRQ pin active LOW. When the IRQ pin is active, use clearStatusFlags() or getStatusFlags() to determine what events triggered it. Remember that calling clearStatusFlags() also clears these events' status, and the IRQ pin will then be reset to inactive HIGH.
The following code configures the IRQ pin to only reflect the "data received" event:
- Parameters
-
tx_ok | true ignores the "data sent" event, false reflects the "data sent" event on the IRQ pin. |
tx_fail | true ignores the "data failed" event, false reflects the "data failed" event on the IRQ pin. |
rx_ready | true ignores the "data received" event, false reflects the "data received" event on the IRQ pin. |
Definition at line 1508 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.
- Deprecated
- Use clearStatusFlags() instead. See our migration guide to understand what you should update in your code.
- See also
- setStatusFlags()
- Parameters
-
[out] | tx_ok | 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. |
[out] | tx_fail | 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. |
[out] | rx_ready | 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. |
- Note
- This 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:
tx_ds, tx_df, rx_dr = radio.whatHappened()
print("tx_ds: {}, tx_df: {}, rx_dr: {}".format(tx_ds, tx_df, rx_dr))
Definition at line 1562 of file RF24.cpp.
◆ stopListening() [3/3]
void RF24::stopListening |
( |
const uint64_t | txAddress | ) |
|
◆ ack_payloads_enabled
bool RF24::ack_payloads_enabled |
|
protected |
Whether ack payloads are enabled.
Definition at line 202 of file RF24.h.
◆ addr_width
The address width to use (3, 4 or 5 bytes).
Definition at line 204 of file RF24.h.
◆ dynamic_payloads_enabled
bool RF24::dynamic_payloads_enabled |
|
protected |
Whether dynamic payloads are enabled.
Definition at line 206 of file RF24.h.
◆ failureDetected
bool RF24::failureDetected |
If a failure has been detected, it usually indicates a hardware issue. By default the library will cease operation when a failure is detected. This should allow advanced users to detect and resolve intermittent hardware issues.
In most cases, the radio must be re-enabled via radio.begin(); and the appropriate settings applied after a failure occurs, if wanting to re-enable the device immediately.
The three main failure modes of the radio include:
- Writing to radio: Radio unresponsive
- Fixed internally by adding a timeout to the internal write functions in RF24 (failure handling)
- Reading from radio: Available returns true always
- Fixed by adding a timeout to available functions by the user. This is implemented internally in RF24Network.
- Radio configuration settings are lost
- Fixed by monitoring a value that is different from the default, and re-configuring the radio if this setting reverts to the default.
See the included example, GettingStarted_HandlingFailures
if(radio.failureDetected) {
radio.begin();
radio.failureDetected = 0;
radio.openWritingPipe(addresses[1]);
radio.openReadingPipe(1, addresses[0]);
report_failure();
}
Definition at line 1454 of file RF24.h.
◆ txDelay
The driver will delay for this duration when stopListening() is called
When responding to payloads, faster devices like ARM(RPi) are much faster than Arduino:
- Arduino sends data to RPi, switches to RX mode
- The RPi receives the data, switches to TX mode and sends before the Arduino radio is in RX mode
- If AutoACK is disabled, this can be set as low as 0. If AA/ESB enabled, set to 100uS minimum on RPi
- Warning
- If set to 0, ensure 130uS delay after stopListening() and before any sends
Definition at line 1831 of file RF24.h.
◆ csDelay
On all devices but Linux and ATTiny, a small delay is added to the CSN toggling function
This is intended to minimize the speed of SPI polling due to radio commands
If using interrupts or timed requests, this can be set to 0 Default:5
Definition at line 1841 of file RF24.h.
The documentation for this class was generated from the following files: