RF24 API¶

A Python module that wraps all RF24 C++ library’s API

Enum classes¶

class pyrf24.rf24.rf24_crclength_e¶

Members:

RF24_CRC_DISABLED: to disable using CRC checksums
RF24_CRC_8: to use 8-bit checksums
RF24_CRC_16: to use 16-bit checksums

class pyrf24.rf24.rf24_datarate_e¶

Members:

RF24_1MBPS: for 1 Mbps
RF24_2MBPS: for 2 Mbps
RF24_250KBPS: for 250 kbps

class pyrf24.rf24.rf24_pa_dbm_e¶

Members:

RF24_PA_MIN

nRF24L01 description	Si24R1 description when LNA enabled	Si24R1 description when LNA disabled
-18 dBm	6 dBm	-12 dBm

RF24_PA_LOW

nRF24L01 description	Si24R1 description when LNA enabled	Si24R1 description when LNA disabled
-12 dBm	0 dBm	-4 dBm

RF24_PA_HIGH

nRF24L01 description	Si24R1 description when LNA enabled	Si24R1 description when LNA disabled
-6 dBm	3 dBm	1 dBm

RF24_PA_MAX

nRF24L01 description	Si24R1 description when LNA enabled	Si24R1 description when LNA disabled
0 dBm	7 dBm	4 dBm

RF24 class¶

class pyrf24.rf24.RF24¶

Basic RF24 API¶

__init__(ce_pin: int, csn_pin: int, spi_speed: int = 10000000)¶

__init__(spi_speed: int = 10000000)

Create a RF24 object.

Parameters:

ce_pin : int¶: The pin number connected to the radio’s CE pin.
csn_pin : int¶: The pin number connected to the radio’s CSN pin.
spi_speed : int¶: The SPI bus speed (in Hz). Defaults to 10 MHz when not specified.

If it is desirable to create a RF24 object in which the pin numbers are dynamically configured, the ce_pin and csn_pin parameters can be omitted.

Important

If dynamically configuring the pin numbers, then they must be set using the overloaded begin() function.

begin() → bool¶

begin(ce_pin: int, csn_pin: int) → bool

Initialize the radio’s hardware.

If configuring the radio’s CE & CSN pins dynamically, then the respective pin numbers must be passed to this function.

Parameters:

ce_pin : int¶: The pin number connected to the radio’s CE pin.
csn_pin : int¶: The pin number connected to the radio’s CSN pin.

Returns:

True if the radio was configured successfully, otherwise False.

listen¶

This bool attribute represents the radio’s primary mode (RX/TX).

Hint

Be sure to call open_rx_pipe() before setting listen to True.
Do not call write() while in RX mode, without first setting listen to False.
Call available() to check for incoming traffic, and use read() to get it.

Important

If there was a call to open_rx_pipe() about pipe 0 prior to setting this attribute to False, then this attribute will re-write the address that was last set to RX pipe 0. This is because open_tx_pipe() will overwrite the address to RX pipe 0 for proper auto-ack functionality.

Note

When the ACK payloads feature is enabled, the TX FIFO buffers are flushed when changing this attribute to True (RX mode). This is meant to discard any ACK payloads that were not appended to acknowledgment packets during TX mode.

available() → bool¶

Check if there is an available payload in the radio’s RX FIFO.

Returns:: True if there is a payload in the radio’s RX FIFO, otherwise False.

See Also

Use available_pipe() to get the pipe number that received the next available payload.

read(length: int) → bytearray¶

Fetch data from the radio’s RX FIFO.

Parameters:

length : int¶

The number of bytes to fetch from the radio’s RX FIFO. If this parameter is not specified, then the length of the next available payload is used. The maximum number of bytes that can be fetched at once is 32 bytes.

If the value specified by this parameter is less than the length of the next available payload, then the payload will remain in the RX FIFO.
If the value specified by this parameter is greater than the length of the next available payload, then the data from the next level of the RX FIFO is returned (if any).
If the value specified by this parameter is greater than the length of the last available payload, then the payload’s last byte is returned repeatedly until the length value is fulfilled.

Returns:

A bytearray of the specified length containing the data from the payload in the RX FIFO.

See Also

payload_size
get_dynamic_payload_size()
available()

write(buf: bytearray | bytes, multicast: bool = False) → bool¶

Transmit a single payload.

Parameters:

buf : bytes,bytearray¶

The payload to load into the TX FIFO.

multicast : bool¶

Set this parameter to True to flag the payload for no acknowledgement. This parameter makes use of the radio’s NO_ACK flag for the individual payload. Defaults to False.

Important

This parameter requires that the enable_dynamic_ack() function is called at least once prior to calling this function.

Returns:

True if the payload was successfully transmitted, otherwise False.

open_tx_pipe(address: bytearray | bytes | int)¶

Open data pipe 0 for transmitting to a specified address.

Parameters:

address : bytes,bytearray,int¶: The address assigned to data pipe 0 for outgoing transmissions.

For backward compatibility, this function’s address parameter can also take a 64-bit integer.

open_rx_pipe(pipe_number: int, address: bytearray | bytes | int)¶

Open a data pipe for receiving.

Parameters:

pipe_number : int¶: The pipe number to use for receiving transmissions. This value should be in range [0, 5].
address : bytes,bytearray,int¶: The address assigned to the specified data pipe for receiving transmissions.

For backward compatibility, this function’s address parameter can also take a 64-bit integer.

Advanced RF24 API¶

toggle_all_pipes(enable: bool)¶

Open or close all pipes with 1 SPI transaction. This does not alter the addresses assigned to the data pipes (using open_rx_pipe() or open_tx_pipe()).

Parameters:

enable : bool¶: True opens all data pipes for RX operation. False closes all data pipes for RX operation.

is_valid¶: This read-only attribute represents if the radio’s CE & CSN pins are configured properly.

is_chip_connected¶: Check if the SPI bus is working with the radio. This read-only bool attribute assumes that begin() returned True.

is_plus_variant¶: This read-only bool attribute represents if the detected radio is a nRF24L01+ model.

what_happened() → tuple[bool, bool, bool]¶

Call this function when the radio’s IRQ pin is active LOW.

Returns:

a 3-tuple of boolean values in which

index 0 represents a “data sent” event
index 1 represents a “data failed” event
index 2 represents a “data ready” event

Note

Calling this function also clears all status flags and resets the IRQ pin to inactive high.

See Also

mask_irq()

Debugging Helpers¶

failure_detected¶: The number of accumulative transmission failures specific to the life cycle of the RF24 object.

print_details()¶: Print out details about the radio’s configuration.

print_pretty_details()¶: Print out details about the radio’s configuration. This function differs from print_details() as the output for this function is more human-friendly/readable.

sprintf_pretty_details() → str¶

Put details about the radio’s configuration into a string. This function differs from print_pretty_details() as it does not use stdout output stream.

Returns:: A string that describes the radio’s details.

get_arc() → int¶

Returns automatic retransmission count (ARC_CNT)

Value resets with each new transmission. Allows roughly estimating signal strength.

Returns:: Returned values range from 0 to 15.

Advanced Transmission¶

write_ack_payload(pipe: int, buf: bytearray | bytes) → bool¶

Load a payload into the TX FIFO to be used in the ACK packet of automatic acknowledgements.

Parameters:

pipe : int¶

The pipe number to use for the acknowledging payload.

See Also

Set the pipe’s assigned address using open_rx_pipe()

buf : bytes,bytearray¶

The payload to load into the TX FIFO.

Returns:

True if the payload was loaded into the radio’s TX FIFO, otherwise False.

write_fast(buf: bytearray | bytes, multicast: bool = False) → bool¶

Simply load a payload into the radio’s TX FIFO and assert the radio’s CE pin to activate transmission.

See Also

Use tx_standby() to ensure the radio has had time to transmit the payload(s) from the TX FIFO.

Parameters:

buf : bytes,bytearray¶

The payload to load into the TX FIFO.

multicast : bool¶

Set this parameter to True to flag the payload for no acknowledgement. This parameter makes use of the radio’s NO_ACK flag for the individual payload. Defaults to False.

Important

This parameter requires that the enable_dynamic_ack() function is called at least once prior to calling this function.

Returns:

True if the payload was loaded into the radio’s TX FIFO, otherwise False.

reuse_tx()¶: Re-use the 1^st level of the radio’s TX FIFO.

write_blocking(buf: bytearray | bytes, timeout: int) → bool¶

A blocking function to load a payload into the radio’s TX FIFO. If there is no un-occupied level of the TX FIFO, this function waits until a level becomes available or the specified timeout is reached.

Parameters:

buf : bytes,bytearray¶: The payload to load into the TX FIFO.
timeout : int¶: The amount of time (in milliseconds) to wait while there is no available level in the TX FIFO.

Returns:

True if the payload was loaded into the radio’s TX FIFO, otherwise False.

start_fast_write(buf: bytearray | bytes, multicast: bool = False, start_tx: bool = True) → None¶

Write a payload to the radio’s TX FIFO.

See Also

Use tx_standby() to ensure the radio has had time to transmit the payload(s) from the TX FIFO.

Parameters:

buf : bytes,bytearray¶

The payload to load into the TX FIFO.

multicast : bool¶

Set this parameter to True to flag the payload for no acknowledgement. This parameter makes use of the radio’s NO_ACK flag for the individual payload. Defaults to False.

Important

This parameter requires that the enable_dynamic_ack() function is called at least once prior to calling this function.

start_tx : bool¶

Set this parameter to True to activate transmission. By default this parameter is set to True. Notice this parameter controls the radio’s CE pin as required. Setting this parameter to False will only leave the radio’s CE pin unchanged.

start_write(buf: bytearray | bytes, multicast: bool = False) → bool¶

For backward compatibility, this function is similar to start_fast_write().

Parameters:

buf : bytes,bytearray¶

The payload to load into the TX FIFO.

multicast : bool¶

Set this parameter to True to flag the payload for no acknowledgement. This parameter makes use of the radio’s NO_ACK flag for the individual payload. Defaults to False.

Important

This parameter requires that the enable_dynamic_ack() function is called at least once prior to calling this function.

Returns:

True if the payload was loaded into the radio’s TX FIFO, otherwise False.

tx_standby() → bool¶

tx_standby(timeout: int, start_tx: bool = True) → bool

When using write_fast() to fill the radio’s TX FIFO, call this blocking function to allow the radio time to transmit.

The default timeout value is 95 milliseconds. Any failed transmissions will be re-attempted until successfully transmitted or timeout occurs.

Optionally, a timeout value can be supplied to augment how long the function will block during transmission.

Parameters:

timeout : int¶: The maximum time (in milliseconds) to allow for transmission. This value is added to the default 95 milliseconds.
start_tx : bool¶: Set this parameter to False if the radio’s CE pin is already active. This parameter is optional.

Power Management¶

power¶: This bool attribute represents the radio’s power status. False means the radio is powered down.

FIFO Management¶

rx_fifo_full¶: This bool attribute represents if all 3 levels of the radio’s RX FIFO are occupied.

flush_tx()¶: Flush all 3 levels of the radio’s TX FIFO.

flush_rx()¶: Flush all 3 levels of the radio’s RX FIFO.

is_fifo(about_tx: bool, check_empty: bool) → bool¶

is_fifo(about_tx: bool) → int

Get information about a specified FIFO buffers.

Parameters:

about_tx : bool¶: Ensure the returned data is about the TX FIFO. Set this to False to make returned data describe the RX FIFO.
check_empty : bool¶: Check if the specified FIFO is empty. Set this to False to check if the specified FIFO is full.

Returns:

A bool describing if the specified FIFO is empty or full.
An int if the check_empty parameter was unspecified. In which case, the return integer is
- 0 if the specified FIFO is neither full nor empty.
- 1 if the specified FIFO is empty.
- 2 if the specified FIFO is full.

Ambiguous Signal Detection¶

rpd¶: This read-only bool attribute represents if the radio detected a signal above -64 dbm in RX mode.

Hint

RPD stands for “Received Power Detection”. Non-plus variants of nRF24L01 call this attribute CD (short for “Carrier Detection”) because this feature was originally made available for government mandated hardware tests.

start_const_carrier(level: rf24_pa_dbm_e, channel: int)¶

Start a constant carrier wave. This is used (in conjunction with rpd) to test the radio’s hardware.

Parameters:

level : rf24_pa_dbm_e¶: The value used to configure Power Amplitude level. Accepted values are pre-defined in the rf24_pa_dbm_e enum struct.
channel : int¶: The channel to broadcast on.

stop_const_carrier()¶: End transmitting a constant carrier wave. This function also sets the power to False as recommended by the datasheet.

available_pipe() → tuple[bool, int]¶

Similar to available(), but additionally returns the pipe number that received the next available payload.

Returns:

A 2-tuple in which

index 0 is the bool value indicating if there is a available payload in the radio’s RX FIFO.
index 1 is the int value indicating the pipe number that received the next available in the radio’s RX FIFO. If there is no payload received, then this number is set to an invalid value of 7.

close_rx_pipe(pipe: int)¶

Close a data pipe for receiving.

Parameters:

pipe : int¶: The identifying data pipe number to close. Remember there are only 6 data pipes (identified by the numbers 0-5).

Configurable RF24 API¶

address_width¶: This int attribute represents length of addresses used on the radio’s data pipes. Accepted values range [2, 5].

Warning

Using an address width of 2 bytes is not officially supported by the nRF24L01. This ability is exposed for advanced reverse engineering purposes.

set_retries(delay: int, count: int)¶

Configure the radio’s auto-retries feature.

Parameters:

delay : int¶: A number in the range [0, 15] used as a multiple of 250. This controls the amount of time (in microseconds) the radio waits for an auto-acknowledgment.
count : int¶: A number in range [0, 15]. This is the amount of automatic retries that the radio attempts when an automatic acknowledgment is not received.

mask_irq(tx_ok: bool, tx_fail: bool, rx_ready: bool)¶

Configure the radio’s IRQ pin to go active on certain events.

Important

The IRQ pin is only active when LOW.

Parameters:

tx_ok : bool¶: True ignores the “data sent” event, False reflects the “data sent” event on the IRQ pin.
tx_fail : bool¶: True ignores the “data failed” event, False reflects the “data failed” event on the IRQ pin.
rx_ready : bool¶: True ignores the “data ready” event, False reflects the “data ready” event on the IRQ pin.

Channel (Frequency)¶

channel¶: This int attribute represents the radio’s configured channel (AKA frequency). This roughly translates to frequency (in Hz). So, channel 76 (the default setting) is

2400 MHz + 76 = 2.4076 GHz

Dynamic Delays¶

tx_delay¶

The driver will delay for this duration (int in microseconds) when listen is set to False.

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 AutoACK enabled, set to 100uS minimum on RPi

Warning

If set to 0, ensure 130uS delay after listen is set to False before any transmitting.

Payload Sizes¶

payload_size¶: This int attribute represents the radio’s static payload lengths. Maximum length is 32 bytes; minimum is 1 byte.

Note

This attribute is only used when the radio’s dynamic_payloads feature is disabled (which is disabled by default).

dynamic_payloads¶: This bool attribute represents the radio’s dynamic payload length feature for all data pipes.

Note

Since ack_payloads requires Dynamic Payload lengths, ack_payloads are also disabled when setting this attribute is set to False.

get_dynamic_payload_size() → int¶: Get the Dynamic Payload Size of the next available payload in the radio’s RX FIFO.

Auto-Acknowledgement¶

set_auto_ack(enable: bool)¶

set_auto_ack(pipe_number: int, enable: bool) → None

Configure the radio’s automatic acknowledgement feature for all data pipes or a specific data pipe.

Parameters:

enable : bool¶: Enable/disable (True/False) the radio’s auto-ack feature for all data pipes or for the specified pipe_number.
pipe_number : int¶: The pipe number for which the enable parameter is about. This value must be in range [0, 5].

ack_payloads¶: This bool attribute represents the status of the radio’s acknowledgement payload feature for appending data to automatic acknowledgement packets.

Important

To use acknowledgement payloads, the dynamic_payloads and auto-ack features must be enabled.

This attribute does not automatically enable the auto-ack feature on pipe 0 because the auto-ack feature is enabled for all pipes by default.

See Also

Review write_ack_payload() and set_auto_ack(). Use available() and read() to fetch a received acknowledgement payload.

enable_dynamic_ack()¶

Enable the radio’s Dynamic Ack feature.

By default the multicast parameter to write() is ineffective unless this function is called. This design decision was made for compatibility with the cheap chinese Si24R1 clones.

Radiation Options¶

set_pa_level(level: rf24_pa_dbm_e, lna_enable: bool = True)¶

Configure the radio’s Power Amplitude Level.

Parameters:

level : rf24_pa_dbm_e¶: The value used to configure Power Amplitude level. Accepted values are pre-defined in the rf24_pa_dbm_e enum struct.
lna_enable : bool¶: This parameter configures the LNA (Low Noise Amplifier) feature of the radio. This feature can only be configured on non-plus models of the nRF24L01 (or the Si24R1 clone).

pa_level¶: This attribute represents the radio’s configured Power Amplitude level.

See Also

Accepted values are defined in the rf24_pa_dbm_e enum struct.

data_rate¶: This attribute represents the radio’s OTA data rate.

Hint

The units “BPS” stand for “Bits Per Second” (not Bytes per second).

See Also

Accepted values are pre-defined in the rf24_datarate_e enum struct.

set_radiation(level: rf24_pa_dbm_e, speed: rf24_datarate_e, lna_enable: bool = True)¶

Configure the RF_SETUP register in 1 SPI transaction.

Parameters:

level : rf24_pa_dbm_e¶: The desired Power Amplitude level. Options are defined in the rf24_pa_dbm_e enum.
speed : rf24_datarate_e¶: The desired RF data rate. Options are defined in the rf24_datarate_e enum.
lna_enable : bool¶: A toggle for radio’s that support controlling the Low Noise Amplifier feature. This is always enabled by default and when not specified.

See Also

set_pa_level()
pa_level
data_rate

CRC Lengths¶

crc_length¶: This attribute represents the radio’s CRC checksum length (in bits).

See Also

Accepted values are predefined in the rf24_crclength_e enum struct.

Note

The radio automatically uses CRC checksums when the auto-ack feature is enabled. This attribute may not reflect this situation if CRC is disabled when auto-ack is enabled.