RF24 API

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

rf24.RF24_DRIVER = 'SPIDEV'

This str describes the backend driver used to build the pyrf24 package. If installed from pypi, then this value should be "SPIDEV".

All other drivers imply that the pyrf24 package was built from source Using a specific RF24 driver.

Hint

Use this attribute to determine programmatically which pin numbers to use. Drivers like wiringPi and MRAA use their own pin numbering scheme.

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

  1. Be sure to call open_rx_pipe() before setting listen to True.

  2. Do not call write() while in RX mode, without first setting listen to False.

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

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 1st 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:

  1. Arduino sends data to RPi, switches to RX mode

  2. The RPi receives the data, switches to TX mode and sends before the Arduino radio is in RX mode

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

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.