|
Optimized high speed nRF24L01+ driver class documentation v1.5.0
TMRh20 2020 - Optimized fork of the nRF24L01+ driver
|
Loading...
Searching...
No Matches
|
Optimized high speed nRF24L01+ driver class documentation v1.5.0
TMRh20 2020 - Optimized fork of the nRF24L01+ driver
|
Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver. More...
#include <RF24.h>
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) |
| 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) |
Deprecated | |
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) |
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 | 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) |
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 | 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 | |
Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver.
| 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
| _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.
|
| _spi_speed | The SPI speed in Hz ie: 1000000 == 1Mhz
|
| RF24::RF24 | ( | uint32_t | _spi_speed = RF24_SPI_SPEED | ) |
A constructor for initializing the radio's hardware dynamically
| _spi_speed | The SPI speed in Hz ie: 1000000 == 1Mhz
|
|
inlineprotected |
|
protected |
Read a chunk of data in from a register
| reg | Which register. Use constants from nRF24L01.h | |
| [out] | buf | Where to put the data |
| len | How many bytes of data to transfer |
|
protected |
Read single byte from a register
| reg | Which register. Use constants from nRF24L01.h |
reg | bool RF24::begin | ( | void | ) |
Begin operation of the chip
Call this in setup(), before calling any other methods.
true if the radio was successfully initializedfalse if the MCU failed to communicate with the radio hardware | bool RF24::begin | ( | _SPI * | spiBus | ) |
Same as begin(), but allows specifying a non-default SPI bus to use.
SPI::begin() method was called before to calling this function.| 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. |
| 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.
SPI::begin() method was called before to calling this function.| 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.
|
| 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.
| _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.
|
| bool RF24::isChipConnected | ( | ) |
| void RF24::startListening | ( | void | ) |
Start listening on the pipes opened for reading.
Open reading pipe 1 using address 0xCCCECCCECC
| void RF24::stopListening | ( | void | ) |
Stop listening for incoming messages, and switch to transmit mode.
Do this before calling write().
| void RF24::stopListening | ( | const uint8_t * | txAddress | ) |
Similar to startListening(void) but changes the TX address.
| txAddress | The new TX address. This value will be cached for auto-ack purposes. |
| bool RF24::available | ( | void | ) |
Check whether there are bytes available to be 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
void* as a data type to make it easier for beginners to use. No casting needed.| 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). |
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().
len parameter's value is less than the available payload's length, then the payload remains in the RX FIFO.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.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. len parameter is required because this function (in the python wrapper) returns the payload data as a buffer protocol object (bytearray object). RX_DR Interrupt flag is now cleared with this function instead of when calling available(). | 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
| buf | Pointer to the data to be sent |
| len | Number of bytes to be sent |
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: 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. | void RF24::openWritingPipe | ( | const uint8_t * | address | ) |
New: Open a pipe for writing via byte array. Old addressing format retained for compatibility.
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
| 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. |
| 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().
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().
| 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()).
| void RF24::ce | ( | bool | level | ) |
Set radio's CE (Chip Enable) pin state.
startListening() for RX mode or stopListening() and write() for TX mode.| 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. |
| void RF24::printDetails | ( | void | ) |
Print a giant block of debugging information to stdout
| void RF24::printStatus | ( | uint8_t | flags | ) |
Decode and print the given STATUS byte to stdout.
| flags | The STATUS byte to print. This value is fetched with update() or getStatusFlags(). |
| 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.
0 means the feature is disabled, and a 1 means the feature is enabled. | 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()).
printf() but outputs (by reference) into a char array. The formatted string literal for sprintf() is stored in nonvolatile program memory.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. | 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. |
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.
0 means the feature is disabled, and a 1 means the feature is enabled. | 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.
*print*Details() methods.| 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) |
| bool RF24::available | ( | uint8_t * | pipe_num | ) |
Test whether there are bytes available to be read from the FIFO buffers.
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):
False, then this pipe number is invalid.To use this function in python:
| [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);
}
|
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: 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. | 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.
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. | rf24_fifo_state_e RF24::isFifo | ( | bool | about_tx | ) |
| about_tx | true focuses on the TX FIFO, false focuses on the RX FIFO |
0) if the specified FIFO is neither full nor empty.1) if the specified FIFO is empty.2) if the specified FIFO is full.3) if the data fetched over SPI was malformed. | bool RF24::isFifo | ( | bool | about_tx, |
| bool | check_empty ) |
| about_tx | true focuses on the TX FIFO, false focuses on the RX FIFO |
| check_empty |
|
| void RF24::powerDown | ( | void | ) |
Enter low-power mode
To return to normal power mode, call 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().
| 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
| 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. |
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.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: | 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).
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):
| buf | Pointer to the data to be sent |
| len | Number of bytes to be sent |
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.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: | 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.
false.| 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. |
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).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: | 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.
Example (Full blocking):
| buf | Pointer to the data to be sent |
| len | Number of bytes to be sent |
| timeout | User defined timeout in milliseconds. |
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: 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. | 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.
Relies on built-in auto retry functionality.
Example (Partial blocking):
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. | 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:
| 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. |
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. | 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.
| 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(). |
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: 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(). | 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
| 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. |
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: | 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().
| 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. |
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. 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: | 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.
| 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.
| uint8_t RF24::flush_rx | ( | void | ) |
| bool RF24::testCarrier | ( | void | ) |
| 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 RF24::isValid | ( | ) |
| void RF24::closeReadingPipe | ( | uint8_t | pipe | ) |
| void RF24::setAddressWidth | ( | uint8_t | a_width | ) |
| 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.
| 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. |
| 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.
channel attribute.To use this function in the python wrapper: | channel | Which RF channel to communicate on, 0-125 |
| uint8_t RF24::getChannel | ( | void | ) |
Get RF communication channel
channel attribute.To use this function in the python wrapper: | 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().
payloadSize attribute.To use this function in the python wrapper: | size | The number of bytes in the payload |
| uint8_t RF24::getPayloadSize | ( | void | ) |
Get Static Payload Size
payloadSize attribute.To use this function in the python wrapper: | uint8_t RF24::getDynamicPayloadSize | ( | void | ) |
Get Dynamic Payload Size
For dynamic payloads, this pulls the size of the payload off the chip
| 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.
| void RF24::disableAckPayload | ( | void | ) |
Disable custom payloads on the acknowledge packets
| void RF24::enableDynamicPayloads | ( | void | ) |
| 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.
| void RF24::enableDynamicAck | ( | void | ) |
Enable dynamic ACKs (single write multicast or unicast) for chosen messages.
| bool RF24::isPVariant | ( | void | ) |
| 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.
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.| enable | Whether to enable (true) or disable (false) the auto-acknowledgment feature for all pipes |
| 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.
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.| 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 |
| void RF24::setPALevel | ( | uint8_t | level, |
| bool | lnaEnable = 1 ) |
Set Power Amplifier (PA) level and Low Noise Amplifier (LNA) state
| 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 |
lnaEnable parameter. | uint8_t RF24::getPALevel | ( | void | ) |
Fetches the current Power Amplifier level.
| uint8_t RF24::getARC | ( | void | ) |
| bool RF24::setDataRate | ( | rf24_datarate_e | speed | ) |
Set the transmission datarate
| speed | Specify one of the following values (as defined by rf24_datarate_e):
|
| rf24_datarate_e RF24::getDataRate | ( | void | ) |
Fetches the currently configured transmission datarate
| void RF24::setCRCLength | ( | rf24_crclength_e | length | ) |
Set the CRC length (in bits)
CRC cannot be disabled if auto-ack is enabled
| length | Specify one of the values (as defined by rf24_crclength_e)
|
| rf24_crclength_e RF24::getCRCLength | ( | void | ) |
Get the CRC length (in bits)
CRC checking cannot be disabled if auto-ack is enabled
| void RF24::disableCRC | ( | void | ) |
| void RF24::startConstCarrier | ( | rf24_pa_dbm_e | level, |
| uint8_t | channel ) |
Transmission of constant carrier wave with defined frequency and output power
| level | Output power to use |
| channel | The channel to use |
0 times with a delay of 250 microseconds0xFF0xFF into the TX FIFO's top level| void RF24::stopConstCarrier | ( | void | ) |
Stop transmission of constant wave and reset PLL and CONT registers
| void RF24::toggleAllPipes | ( | bool | isEnabled | ) |
| void RF24::setRadiation | ( | uint8_t | level, |
| rf24_datarate_e | speed, | ||
| bool | lnaEnable = true ) |
configure the RF_SETUP register in 1 transaction
| 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. |
| void RF24::openReadingPipe | ( | uint8_t | number, |
| uint64_t | address ) |
Open a pipe for reading
Pipe 0 is also used by the writing pipe so should typically be avoided as a reading pipe. If used, the reading pipe 0 address needs to be restored at every call to startListening().
See http://maniacalbits.blogspot.com/2013/04/rf24-addressing-nrf24l01-radios-require.html
| number | Which pipe# to open, 0-5. |
| address | The 40-bit address of the pipe to open. |
| void RF24::openWritingPipe | ( | uint64_t | address | ) |
Open a pipe for writing
Addresses are 40-bit hex values, e.g.:
| address | The 40-bit address of the pipe to open. |
| bool RF24::isAckPayloadAvailable | ( | void | ) |
Determine if an ack payload was received in the most recent call to write(). The regular available() can also be used.
| 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.
The following events can be configured:
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:
| 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. |
| 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.
| [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. |
| void RF24::stopListening | ( | const uint64_t | txAddress | ) |
Similar to startListening(void) but changes the TX address.
| txAddress | The new TX address. This value will be cached for auto-ack purposes. |
|
protected |
|
protected |
|
protected |
| 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:
See the included example, GettingStarted_HandlingFailures
| uint32_t RF24::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:
| uint32_t RF24::csDelay |
1.13.2