Advanced API¶

what_happened()¶

RF24.what_happened(dump_pipes=False)[source]¶

This debuggung function aggregates and outputs all status/condition related information from the nRF24L01.

Some information may be irrelevant depending on nRF24L01’s state/condition.

Prints:

Is a plus variant True means the transceiver is a nRF24L01+. False means the transceiver is a nRF24L01 (not a plus variant).
Channel The current setting of the channel attribute
RF Data Rate The current setting of the RF data_rate attribute.
RF Power Amplifier The current setting of the pa_level attribute.
CRC bytes The current setting of the crc attribute
Address length The current setting of the address_length attribute
TX Payload lengths The current setting of the payload_length attribute for TX operations (concerning data pipe 0)
Auto retry delay The current setting of the ard attribute
Auto retry attempts The current setting of the arc attribute
Re-use TX FIFO Are payloads in the TX FIFO to be re-used for subsequent transmissions (triggered by calling resend())
Packets lost on current channel Total amount of packets lost (transmission failures). This only resets when the channel is changed. This count will only go up to 15.
Retry attempts made for last transmission Amount of attempts to re-transmit during last transmission (resets per payload)
IRQ - Data Ready The current setting of the IRQ pin on “Data Ready” event
IRQ - Data Sent The current setting of the IRQ pin on “Data Sent” event
IRQ - Data Fail The current setting of the IRQ pin on “Data Fail” event
Data Ready Is there RX data ready to be read? (state of the irq_dr flag)
Data Sent Has the TX data been sent? (state of the irq_ds flag)
Data Failed Has the maximum attempts to re-transmit been reached? (state of the irq_df flag)
TX FIFO full Is the TX FIFO buffer full? (state of the tx_full flag)
TX FIFO empty Is the TX FIFO buffer empty?
RX FIFO full Is the RX FIFO buffer full?
RX FIFO empty Is the RX FIFO buffer empty?
Custom ACK payload Is the nRF24L01 setup to use an extra (user defined) payload attached to the acknowledgment packet? (state of the ack attribute)
Ask no ACK Is the nRF24L01 setup to transmit individual packets that don’t require acknowledgment?
Automatic Acknowledgment The status of the auto_ack feature. If this value is a binary representation, then each bit represents the feature’s status for each pipe.
Dynamic Payloads The status of the dynamic_payloads feature. If this value is a binary representation, then each bit represents the feature’s status for each pipe.
Primary Mode The current mode (RX or TX) of communication of the nRF24L01 device.
Power Mode The power state can be Off, Standby-I, Standby-II, or On.

Parameters:

dump_pipes (bool) –

True appends the output and prints:

the current address used for TX transmissions. This value is the entire content of the nRF24L01’s register about the TX address (despite what address_length is set to).
Pipe [#] ([open/closed]) bound: [address] where # represent the pipe number, the open/closed status is relative to the pipe’s RX status, and address is the full value stored in the nRF24L01’s RX address registers (despite what address_length is set to.
if the pipe is open, then the output also prints expecting [X] byte static payloads where X is the payload_length (in bytes) the pipe is setup to receive when dynamic_payloads is disabled for that pipe.

This parameter’s default is False and skips this extra information.

is_plus_variant¶

RF24.is_plus_variant¶: A bool attribute to descibe if the nRF24L01 is a plus variant or not (read-only). This information is detirmined upon instantiation.

load_ack()¶

RF24.load_ack(buf, pipe_number)[source]¶

This allows the MCU to specify a payload to be allocated into the TX FIFO buffer for use on a specific data pipe.

This payload will then be appended to the automatic acknowledgment (ACK) packet that is sent when new data is received on the specified pipe. See recv() on how to fetch a received custom ACK payloads.

Parameters:

buf (bytearray,bytes) – This will be the data attached to an automatic ACK packet on the incoming transmission about the specified pipe_number parameter. This must have a length in range [1, 32] bytes, otherwise a ValueError exception is thrown. Any ACK payloads will remain in the TX FIFO buffer until transmitted successfully or flush_tx() is called.
pipe_number (int) – This will be the pipe number to use for deciding which transmissions get a response with the specified buf parameter’s data. This number must be in range [0, 5], otherwise a IndexError exception is thrown.

Returns:

True if payload was successfully loaded onto the TX FIFO buffer. False if it wasn’t because TX FIFO buffer is full.

Note

this function takes advantage of a special feature on the nRF24L01 and needs to be called for every time a customized ACK payload is to be used (not for every automatic ACK packet – this just appends a payload to the ACK packet). The ack, auto_ack, and dynamic_payloads attributes are also automatically enabled (with respect to data pipe 0) by this function when necessary.

Tip

The ACK payload must be set prior to receiving a transmission. It is also worth noting that the nRF24L01 can hold up to 3 ACK payloads pending transmission. Using this function does not over-write existing ACK payloads pending; it only adds to the queue (TX FIFO buffer) if it can. Use flush_tx() to discard unused ACK payloads when done listening.

read_ack()¶

RF24.read_ack()[source]¶

Allows user to read the automatic acknowledgement (ACK) payload (if any).

This function is an alias of recv() and remains for backward compatibility with older versions of this library.

Warning

This function will be deprecated on next major release. Use recv() instead.

irq_dr¶

RF24.irq_dr¶

A bool that represents the “Data Ready” interrupted flag. (read-only) .

Returns:	`True` represents Data is in the RX FIFO buffer `False` represents anything depending on context (state/condition of FIFO buffers); usually this means the flag’s been reset.

Pass data_recv parameter as True to clear_status_flags() and reset this. As this is a virtual representation of the interrupt event, this attribute will always be updated despite what the actual IRQ pin is configured to do about this event.

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed (especially after calling clear_status_flags()).

irq_df¶

RF24.irq_df¶

A bool that represents the “Data Failed” interrupted flag. (read-only) .

Returns:	`True` signifies the nRF24L01 attemped all configured retries `False` represents anything depending on context (state/condition); usually this means the flag’s been reset.

Pass data_fail parameter as True to clear_status_flags() and reset this. As this is a virtual representation of the interrupt event, this attribute will always be updated despite what the actual IRQ pin is configured to do about this event.

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed (especially after calling clear_status_flags()).

irq_ds¶

RF24.irq_ds¶

A bool that represents the “Data Sent” interrupted flag. (read-only) .

Returns:	`True` represents a successful transmission `False` represents anything depending on context (state/condition of FIFO buffers); usually this means the flag’s been reset.

Pass data_sent parameter as True to clear_status_flags() and reset this. As this is a virtual representation of the interrupt event, this attribute will always be updated despite what the actual IRQ pin is configured to do about this event.

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed (especially after calling clear_status_flags()).

clear_status_flags()¶

RF24.clear_status_flags(data_recv=True, data_sent=True, data_fail=True)[source]¶

This clears the interrupt flags in the status register.

Internally, this is automatically called by send(), write(), recv(), and when listen changes from False to True.

Parameters:	data_recv (bool) – specifies wheather to clear the “RX Data Ready” (`irq_dr`) flag. data_sent (bool) – specifies wheather to clear the “TX Data Sent” (`irq_ds`) flag. data_fail (bool) – specifies wheather to clear the “Max Re-transmit reached” (`irq_df`) flag.

Note

Clearing the data_fail flag is necessary for continued transmissions from the nRF24L01 (locks the TX FIFO buffer when irq_df is True) despite wheather or not the MCU is taking advantage of the interrupt (IRQ) pin. Call this function only when there is an antiquated status flag (after you’ve dealt with the specific payload related to the staus flags that were set), otherwise it can cause payloads to be ignored and occupy the RX/TX FIFO buffers. See Appendix A of the nRF24L01+ Specifications Sheet for an outline of proper behavior.

power¶

RF24.power¶

This bool attribute controls the power state of the nRF24L01. This is exposed for convenience.

False basically puts the nRF24L01 to sleep (AKA power down mode) with ultra-low current consumption. No transmissions are executed when sleeping, but the nRF24L01 can still be accessed through SPI. Upon instantiation, this driver class puts the nRF24L01 to sleep until the MCU invokes RX/TX modes. This driver class will only power down the nRF24L01 after exiting a The with statement block.
True powers up the nRF24L01. This is the first step towards entering RX/TX modes (see also listen attribute). Powering up is automatically handled by the listen attribute as well as the send() and write() functions.

Note

This attribute needs to be True if you want to put radio on Standby-II (highest current consumption) or Standby-I (moderate current consumption) modes. The state of the CE pin determines which Standby mode is acheived. See Chapter 6.1.2-7 of the nRF24L01+ Specifications Sheet for more details.

tx_full¶

RF24.tx_full¶

An attribute to represent the nRF24L01’s status flag signaling that the TX FIFO buffer is full. (read-only) .

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed (especially after calling flush_tx()).

Returns:	`True` for TX FIFO buffer is full `False` for TX FIFO buffer is not full. This doesn’t mean the TX FIFO buffer is empty.

update()¶

RF24.update()[source]¶

This function is only used to get an updated status byte over SPI from the nRF24L01.

Refreshing the status byte is vital to checking status of the interrupt flags, RX pipe number related to current RX payload, and if the TX FIFO buffer is full. This function returns nothing, but internally updates the irq_dr, irq_ds, irq_df, pipe, and tx_full attributes. Internally this is a helper function to send(), and resend() functions.

Returns:	`True` for every call. This value is meant to allow this function to be used in `if` statements in conjunction with attributes related to the refreshed status byte. # let ``nrf`` be the instantiated object of the RF24 class # the following if statement is faster than using ``if nrf.any():`` if nrf.update() and nrf.pipe is not None: nrf.recv()

resend()¶

RF24.resend(send_only=False)[source]¶

Use this function to maunally re-send the previous payload in the top level (first out) of the TX FIFO buffer.

This function is meant to be used for payloads that failed to transmit using the send() function. If a payload failed to transmit using the write() function, just call clear_status_flags() and re-start the pulse on the nRF24L01’s CE pin.

Returns: Data returned from this function follows the same pattern that send() returns with the added condition that this function will return False if the TX FIFO buffer is empty.

Parameters: send_only (bool) – This parameter only applies when the ack attribute is set to True. Pass this parameter as True if the RX FIFO is not to be manipulated. Many other libraries’ behave as though this parameter is True (e.g. The popular TMRh20 Arduino RF24 library). This parameter defaults to False. Use recv() to get the ACK payload (if there is any) from the RX FIFO. Remember that the RX FIFO can only hold up to 3 payloads at once.

Note

The nRF24L01 normally removes a payload from the TX FIFO buffer after successful transmission, but not when this function is called. The payload (successfully transmitted or not) will remain in the TX FIFO buffer until flush_tx() is called to remove them. Alternatively, using this function also allows the failed payload to be over-written by using send() or write() to load a new payload into the TX FIFO buffer.

write()¶

RF24.write(buf, ask_no_ack=False, write_only=False)[source]¶

This non-blocking function (when used as alternative to send()) is meant for asynchronous applications and can only handle one payload at a time as it is a helper function to send().

This function isn’t completely non-blocking as we still need to wait 5 ms (CSN_DELAY) for the CSN pin to settle (allowing an accurate SPI write transaction). Example usage of this function can be seen in the IRQ pin example and in the Stream example’s “master_fifo()” function

Returns:

True if the payload was added to the TX FIFO buffer. False if the TX FIFO buffer is already full, and no payload could be added to it.

Parameters:

buf (bytearray) –
The payload to transmit. This bytearray must have a length greater than 0 and less than 32 bytes, otherwise a ValueError exception is thrown.
- If the dynamic_payloads attribute is disabled for data pipe 0 and this bytearray’s length is less than the payload_length attribute for data pipe 0, then this bytearray is padded with zeros until its length is equal to the payload_length attribute for data pipe 0.
- If the dynamic_payloads attribute is disabled for data pipe 0 and this bytearray’s length is greater than payload_length attribute for data pipe 0, then this bytearray’s length is truncated to equal the payload_length attribute for data pipe 0.
ask_no_ack (bool) –
Pass this parameter as True to tell the nRF24L01 not to wait for an acknowledgment from the receiving nRF24L01. This parameter directly controls a NO_ACK flag in the transmission’s Packet Control Field (9 bits of information about the payload). Therefore, it takes advantage of an nRF24L01 feature specific to individual payloads, and its value is not saved anywhere. You do not need to specify this for every payload if the arc attribute is disabled, however setting this parameter to True will work despite the arc attribute’s setting.

Note

Each transmission is in the form of a packet. This packet contains sections of data around and including the payload. See Chapter 7.3 in the nRF24L01 Specifications Sheet for more details.
write_only (bool) –
This function will not manipulate the nRF24L01’s CE pin if this parameter is True. The default value of False will ensure that the CE pin is HIGH upon exiting this function. This function does not set the CE pin LOW at any time. Use this parameter as True to fill the TX FIFO buffer before beginning transmissions.

Note

The nRF24L01 doesn’t initiate sending until a mandatory minimum 10 µs pulse on the CE pin is acheived. If the write_only parameter is False, then that pulse is initiated before this function exits. However, we have left that 10 µs wait time to be managed by the MCU in cases of asychronous application, or it is managed by using send() instead of this function. According to the Specification sheet, if the CE pin remains HIGH for longer than 10 µs, then the nRF24L01 will continue to transmit all payloads found in the TX FIFO buffer.

Warning

A note paraphrased from the nRF24L01+ Specifications Sheet:

It is important to NEVER to keep the nRF24L01+ in TX mode for more than 4 ms at a time. If the [arc attribute is] enabled, nRF24L01+ is never in TX mode longer than 4 ms.

Tip

Use this function at your own risk. Because of the underlying “Enhanced ShockBurst Protocol”, disobeying the 4 ms rule is easily avoided if the arc attribute is greater than 0. Alternatively, you MUST use nRF24L01’s IRQ pin and/or user-defined timer(s) to AVOID breaking the 4 ms rule. If the nRF24L01+ Specifications Sheet explicitly states this, we have to assume radio damage or misbehavior as a result of disobeying the 4 ms rule. See also table 18 in the nRF24L01 specification sheet for calculating an adequate transmission timeout sentinal.

flush_rx()¶

RF24.flush_rx()[source]¶: A helper function to flush the nRF24L01’s RX FIFO buffer.

Note

The nRF24L01 RX FIFO is 3 level stack that holds payload data. This means that there can be up to 3 received payloads (each of a maximum length equal to 32 bytes) waiting to be read (and removed from the stack) by recv() or read_ack(). This function clears all 3 levels.

flush_tx()¶

RF24.flush_tx()[source]¶: A helper function to flush the nRF24L01’s TX FIFO buffer.

Note

The nRF24L01 TX FIFO is 3 level stack that holds payload data. This means that there can be up to 3 payloads (each of a maximum length equal to 32 bytes) waiting to be transmit by send(), resend() or write(). This function clears all 3 levels. It is worth noting that the payload data is only removed from the TX FIFO stack upon successful transmission (see also resend() as the handling of failed transmissions can be altered).

fifo()¶

RF24.fifo(about_tx=False, check_empty=None)[source]¶

This provides some precision determining the status of the TX/RX FIFO buffers. (read-only)

Parameters:

about_tx (bool) –
- True means the information returned is about the TX FIFO buffer.
- False means the information returned is about the RX FIFO buffer. This parameter defaults to False when not specified.
check_empty (bool) –
- True tests if the specified FIFO buffer is empty.
- False tests if the specified FIFO buffer is full.
- None (when not specified) returns a 2 bit number representing both empty (bit 1) & full (bit 0) tests related to the FIFO buffer specified using the about_tx parameter.

Returns:

A bool answer to the question:

”Is the [TX/RX](about_tx) FIFO buffer [empty/full](check_empty)?
If the check_empty parameter is not specified: an int in range [0,2] for which:
- 1 means the specified FIFO buffer is empty
- 2 means the specified FIFO buffer is full
- 0 means the specified FIFO buffer is neither full nor empty

pipe¶

RF24.pipe¶

The identifying number of the data pipe that received the next available payload in the RX FIFO buffer. (read only) .

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed (especially after calling flush_rx()).

Returns:	`None` if there is no payload in RX FIFO. The `int` identifying pipe number [0,5] that received the next available payload in the RX FIFO buffer.

address_length¶

RF24.address_length¶: This int attribute specifies the length (in bytes) of addresses to be used for RX/TX pipes. A valid input value must be an int in range [3, 5]. Otherwise a ValueError exception is thrown. Default is set to the nRF24L01’s maximum of 5.

address()¶

RF24.address(index=-1)[source]¶

Returns the current address set to a specified data pipe or the TX address. (read-only)

This function returns the full content of the nRF24L01’s registers about RX/TX addresses despite what address_length is set to.

Parameters:	index (int) – the number of the data pipe whose address is to be returned. A valid index ranges [0,5] for RX addresses or any negative number for the TX address. Otherwise an `IndexError` is thown. This parameter defaults to `-1`.

rpd¶

RF24.rpd¶

This read-only attribute returns True if RPD (Received Power Detector) is triggered or False if not triggered. The RPD flag is triggered in the following cases:

During RX mode (when listen is True) and an arbitrary RF transmission with a gain above -64 dBm threshold is/was present.

When a packet is received (instigated by the nRF24L01 used to detect/”listen” for incoming packets).

Note

See also section 6.4 of the Specification Sheet concerning the RPD flag. Ambient temperature affects the -64 dBm threshold. The latching of this flag happens differently under certain conditions.

start_carrier_wave()¶

RF24.start_carrier_wave()[source]¶

Starts a continuous carrier wave test.

This is a basic test of the nRF24L01’s TX output. It is a commonly required test for telecommunication regulations. Calling this function may introduce interference with other transceivers that use frequencies in range [2.4, 2.525] GHz. To verify that this test is working properly, use the following code on a seperate nRF24L01 transceiver:

# declare objects for SPI bus and CSN pin and CE pin
nrf. = RF24(spi, csn, ce)
# set nrf.pa_level, nrf.channel, & nrf.data_rate values to
# match the corresponding attributes on the device that is
# transmitting the carrier wave
nrf.listen = True
if nrf.rpd:
    print("carrier wave detected")

The pa_level, channel & data_rate attributes are vital factors to the success of this test. Be sure these attributes are set to the desired test conditions before calling this function. See also the rpd attribute.

Note

To preserve backward compatibility with non-plus variants of the nRF24L01, this function will also change certain settings if is_plus_variant is False. These settings changes include disabling crc, disabling auto_ack, disabling arc, setting ard to 250 microseconds, changing the TX address to b"\xFF\xFF\xFF\xFF\xFF", and loading a 32-byte payload (each byte is 0xFF) into the TX FIFO buffer while continuously behaving like resend() to establish the constant carrier wave. If is_plus_variant is True, then none of these changes are needed nor applied.

stop_carrier_wave()¶

RF24.stop_carrier_wave()[source]¶

Stops a continuous carrier wave test.

See start_carrier_wave() for more details.

Note

Calling this function puts the nRF24L01 to sleep (AKA power down mode).