Skip to content

RF24

rf24_py.RF24 

RF24(
    ce_pin: int,
    cs_pin: int,
    dev_gpio_chip: int = 0,
    dev_spi_bus: int = 0,
    spi_speed: int = 10000000,
)

Construct an object to control the radio.

Parameters:

  • ce_pin (int) –

    The GPIO pin number connected to the radio's CE pin.

  • cs_pin (int) –

    The identifying number for the SPI bus' CS pin; also labeled as "CEx" (where "x" is this parameter's value) on many Raspberry Pi pin diagrams.

Other Parameters:

  • dev_gpio_chip (int) –

    The GPIO chip's identifying number. Consider the path /dev/gpiochipN where N is this parameter's value.

  • dev_spi_bus (int) –

    The SPI bus number. Consider the path /dev/spidevX.Y where X is this parameter's value and Y is the cs_pin parameter's value.

  • spi_speed (int) –

    The SPI bus speed in Hz. Defaults to the radio's maximum supported speed (10 MHz).

Basic API

rf24_py.RF24.begin 

begin() -> None

Initialize the radio on the configured hardware (as specified to RF24 constructor).

This is the same as with_config(RadioConfig()), but this function also - detects if the radio is a plus variant (is_plus_variant) - checks for data corruption across the SPI lines (MOSI, MISO, SCLK)

Raises:

  • RuntimeError –

    If a hardware failure caused problems (includes a message to describe what problem was detected).

rf24_py.RF24.is_rx property 

is_rx: bool

rf24_py.RF24.as_rx 

as_rx() -> None

Put the radio into active RX mode.

Conventionally, this should be called after setting the RX addresses via RF24.open_rx_pipe().

This function will restore the cached RX address set to pipe 0. This is done because the RF24.as_tx() will appropriate the RX address on pipe 0 for auto-ack purposes.

rf24_py.RF24.as_tx 

as_tx(tx_address: bytes | bytearray | None = None) -> None

Puts the radio into an inactive TX mode.

This must be called at least once before calling RF24.send() or RF24.write().

Parameters:

  • tx_address (bytes | bytearray | None, default: None ) –

    If specified, then this buffer will be cached and set as the new TX address.

For auto-ack purposes, this function will also restore the cached tx_address to the RX pipe 0.

The datasheet recommends idling the radio in an inactive TX mode.

Note

This function will also flush the TX FIFO when ACK payloads are enabled (via RF24.ack_payloads).

rf24_py.RF24.open_rx_pipe 

open_rx_pipe(pipe: int, address: bytes | bytearray) -> None

Open a specific pipe for receiving from the given address.

It is highly recommended to avoid using pipe 0 to receive because it is also used to transmit automatic acknowledgements.

Note

Only pipes 0 and 1 actually use up to 5 bytes of the given address. Pipes 2 - 5 only use the first byte of the given address and last 4 bytes of the address set to pipe 1.

Parameters:

  • pipe (int) –

    The pipe number to receive data. This must be in range [0, 5], otherwise this function does nothing.

  • address (bytes | bytearray) –

    The address to receive data from.

rf24_py.RF24.close_rx_pipe 

close_rx_pipe(pipe: int) -> None

Close the specified pipe from receiving transmissions.

Use RF24.open_rx_pipe() to set the address for a specific pipe.

Parameters:

  • pipe (int) –

    The pipe to close. This must be in range [0, 5], otherwise this function does nothing.

rf24_py.RF24.available 

available() -> bool

Is there a payload available in the RX FIFO?

Use RF24.read() to get the payload data.

rf24_py.RF24.available_pipe 

available_pipe() -> tuple[bool, int]

Similar to RF24.available() but also returns the pipe that received the next available payload.

rf24_py.RF24.read 

read(len: int | None = None) -> bytes

Read data from the radio's RX FIFO.

Use RF24.available() to determine if there is data ready to read from the RX FIFO.

Other Parameters:

  • len (int | None) –

    An optional number of bytes to read from the FIFO. This is capped at 32. If not specified, then the length of the next available payload is used (which automatically respects if dynamic payloads are enabled).

See also

RF24.dynamic_payloads for dynamically sized payload or RF24.payload_length for statically sized payloads.

rf24_py.RF24.send 

send(
    buf: bytes | bytearray, ask_no_ack: bool | int = False
) -> bool

Blocking function that loads a given buf into the TX FIFO, waits for a response (if auto-ack is enabled), then returns a Boolean describing success.

Parameters:

Other Parameters:

  • ask_no_ack (bool | int) –

    A flag to disable the auto-ack feature for the given payload in buf. This has no effect if auto-ack is disabled or RF24.allow_ask_no_ack is not enabled.

rf24_py.RF24.resend 

resend() -> bool

A blocking function to resend a failed payload in the TX FIFO.

This is similar to RF24.send() but specifically for failed transmissions.

rf24_py.RF24.channel property writable 

channel: int

Set/get the channel (frequency) that the radio uses to transmit and receive.

This value is clamped to the range [0, 125].

The channel can be roughly translated into a frequency with the formula: 

frequency (in Hz) = channel + 2400

Advanced API

rf24_py.RF24.ce_pin 

ce_pin(value: bool | int) -> None

Set the radio's CE pin HIGH (True) or LOW (False).

This is only exposed for advanced use of TX FIFO during asynchronous TX operations. It is highly encouraged to use as_rx() or as_tx() to ensure proper radio behavior when entering RX or TX mode.

rf24_py.RF24.write_ack_payload 

write_ack_payload(
    pipe: int, buf: bytes | bytearray
) -> bool

Upload a given ACK packet's payload (buf) into the radio's TX FIFO.

This feature requires RF24.ack_payloads to be enabled.

Parameters:

  • pipe (int) –

    The pipe number that (when data is received) will be responded with the given payload (buf).

  • buf (bytes | bytearray) –

    The payload to attach to the auto-ack packet when responding to data received on specified pipe.

Returns:

  • bool –

    A boolean value that describes if the payload was successfully uploaded to the TX FIFO. Remember, the TX FIFO only has 3 levels ("slots").

rf24_py.RF24.write 

write(
    buf: bytes | bytearray,
    ask_no_ack: bool | int = False,
    start_tx: bool | int = True,
) -> bool

A non-blocking function that uploads a given buf to the radio's TX FIFO.

This is a helper function to RF24.send(). Use this in combination with RF24.update() and RF24.get_status_flags() to determine if transmission was successful.

Parameters:

  • buf (bytes | bytearray) –

    The buffer of bytes to load into the TX FIFO.

Other Parameters:

  • ask_no_ack (bool | int) –

    A flag to disable the auto-ack feature for the given payload in buf.

    This has no effect if auto-ack is disabled or [RF24.allow_ask_no_ack] is not enabled.

  • start_tx (bool | int) –

    A flag to assert the radio's CE pin after the given buf is uploaded to the RX FIFO. Setting this to false does not un-assert the radio's CE pin to LOW.

Returns:

  • bool –

    A Boolean that describes if the given buf was successfully loaded into the TX FIFO.

rf24_py.RF24.rewrite 

rewrite() -> None

A non-blocking function to restart a failed transmission.

This is a helper function to RF24.resend(). Use RF24.update() and RF24.get_status_flags() to determine if retransmission was successful.

rf24_py.RF24.get_fifo_state 

get_fifo_state(about_tx: bool | int) -> FifoState

Get the state of the specified FIFO.

Parameters:

  • about_tx (bool | int) –

    True returns data about the TX FIFO. False returns data about the RX FIFO.

rf24_py.RF24.clear_status_flags 

clear_status_flags(
    flags: StatusFlags | None = None,
) -> None

Reset the specified StatusFlags.

Other Parameters:

  • flags (StatusFlags | None) –

    If this value is None, then all flags are reset.

rf24_py.RF24.update 

update() -> None

Update the cached value of Status flags.

Use RF24.get_status_flags() to get the updated values.

rf24_py.RF24.get_status_flags 

get_status_flags() -> StatusFlags

Get the current state of the StatusFlags.

Note

This function simply returns the value of the flags that was cached from the last SPI transaction. It does not actually update the values (from the radio) before returning them.

Use RF24.update() to update them first.

rf24_py.RF24.flush_rx 

flush_rx() -> None

Discard all 3 layers in the radio's RX FIFO.

rf24_py.RF24.flush_tx 

flush_tx() -> None

Discard all 3 layers in the radio's TX FIFO.

rf24_py.RF24.start_carrier_wave 

start_carrier_wave(level: PaLevel, channel: int) -> None

Start a constant carrier wave

This functionality is meant for hardware tests (in conjunction with RF24.rpd). Typically, this behavior is required by government agencies to enforce regional restrictions.

Parameters:

  • level (PaLevel) –

    The Power Amplitude level to use when transmitting.

  • channel (int) –

    The channel (radio's frequency) used to transmit. The channel should not be changed while transmitting because it can cause undefined behavior.

rf24_py.RF24.stop_carrier_wave 

stop_carrier_wave() -> None

Stop the constant carrier wave started via RF24.start_carrier_wave().

This function leaves the radio in a configuration that may be undesired or unexpected because of the setup involved in RF24.start_carrier_wave(). The PaLevel and channel passed to RF24.start_carrier_wave() are still set. If RF24.is_plus_variant returns true, the following features are all disabled:

  • auto-ack
  • CRC
  • auto-retry

rf24_py.RF24.rpd property 

rpd: bool

Was the Received Power Detection (RPD) trigger?

This flag is asserted during an RX session (after a mandatory 130 microseconds duration) if a signal stronger than -64 dBm was detected.

Note that if a payload was placed in RX mode, then that means the signal used to transmit that payload was stronger than either

Sensitivity may vary based of the radio's model and manufacturer. The information above is stated in the nRF24L01+ datasheet.

rf24_py.RF24.get_last_arc 

get_last_arc() -> int

Get the Automatic Retry Count (ARC) of attempts made during the last transmission.

This resets with every new transmission. The returned value is meaningless if the auto-ack feature is disabled.

See also

Use RF24.set_auto_retries to configure the automatic retries feature.

rf24_py.RF24.get_dynamic_payload_length 

get_dynamic_payload_length() -> int

Get the length of the next available payload in the RX FIFO.

If dynamically sized payloads are not enabled (via RF24.dynamic_payloads), then use RF24.payload_length.

Configuration API

rf24_py.RF24.with_config 

with_config(config: RadioConfig)

Reconfigure the radio with a specified RadioConfig.

Warning

It is strongly encouraged to call RF24.begin() after constructing the RF24 object.

Only use this function subsequently to quickly switch between different network settings.

rf24_py.RF24.set_status_flags 

set_status_flags(flags: StatusFlags | None = None) -> None

Configure the IRQ pin to reflect the specified StatusFlags.

Other Parameters:

  • flags (StatusFlags | None) –

    If this value is None, then all flags are reflected by the IRQ pin.

rf24_py.RF24.set_auto_ack 

set_auto_ack(enable: bool | int) -> None

Enable or disable the auto-ack feature for all pipes.

Note

This feature requires CRC to be enabled. See RF24.crc_length for more detail.

Parameters:

  • enable (bool | int) –

    Pass true to enable the auto-ack feature for all pipes.

rf24_py.RF24.set_auto_ack_pipe 

set_auto_ack_pipe(enable: bool | int, pipe: int) -> None

Enable or disable the auto-ack feature for a specified pipe.

Note

This feature requires CRC to be enabled. See RF24.crc_length for more detail.

Parameters:

  • enable (bool | int) –

    Pass true to enable the auto-ack feature for the specified pipe.

  • pipe (int) –

    The pipe about which to control the auto-ack feature.

rf24_py.RF24.set_auto_retries 

set_auto_retries(count: int, delay: int) -> None

Configure the automatic retry feature.

This feature is part of the auto-ack feature, thus the auto-ack feature is required for this function to have any effect.

Parameters:

  • delay (int) –

    This value is clamped to the range [0, 15]. This value is translated to microseconds with the formula

    250 + (delay * 250) = microseconds

    Meaning, the effective range of delay is [250, 4000].

  • count (int) –

    The number of attempt to retransmit when no ACK packet was received (after transmitting). This value is clamped to the range [0, 15].

rf24_py.RF24.dynamic_payloads property writable 

dynamic_payloads: bool

Enable or disable the dynamically sized payloads feature.

If set to true, the statically sized payload length (set via RF24.payload_length) are not used.

rf24_py.RF24.allow_ask_no_ack 

allow_ask_no_ack(enable: bool | int) -> None

Allow disabling the auto-ack feature for individual payloads.

Parameters:

rf24_py.RF24.ack_payloads property writable 

ack_payloads: bool

Enable or disable the custom ACK payloads attached to auto-ack packets.

Important

This feature requires dynamically sized payloads. This attribute will enable dynamic_payloads automatically when needed. This attribute will not disable dynamic_payloads.

rf24_py.RF24.address_length property writable 

address_length: int

Set/get the address length (applied to all pipes).

The address length is only allowed to be in range [2, 5].

rf24_py.RF24.payload_length property writable 

payload_length: int

Set/get the statically sized payload length.

This configuration is not used if dynamic payloads are enabled. Use RF24.get_dynamic_payload_length() instead if dynamically sized payloads are enabled (via RF24.dynamic_payloads).

rf24_py.RF24.data_rate property writable 

data_rate: DataRate

Set the DataRate used for all incoming and outgoing transmissions.

rf24_py.RF24.pa_level property writable 

pa_level: PaLevel

Set/get the Power Amplitude (PA) level used for all transmissions (including auto ack packet).

rf24_py.RF24.set_lna 

set_lna(enable: bool | int) -> None

Enable or disable the LNA feature.

This is enabled by default (regardless of chip variant). See PaLevel for effective behavior.

On nRF24L01+ modules with a builtin antenna, this feature is always enabled. For clone's and module's with a separate PA/LNA circuit (external antenna), this function may not behave exactly as expected. Consult the radio module's manufacturer.

rf24_py.RF24.crc_length property writable 

crc_length: CrcLength

Set/get the CrcLength used for all outgoing and incoming transmissions.

Important

Because CRC is required for the auto-ack feature, the radio's firmware will forcefully enable CRC even if the user explicitly disables it.

rf24_py.RF24.power property writable 

power: bool

Power Up/Down the radio.

No transmissions can be received when the radio is powered down.

See also

Setting this attribute to True is equivalent to calling power_up() (using default delay).

rf24_py.RF24.power_up 

power_up(delay: int | None = None) -> None

Power up the radio.

Parameters:

  • delay (int | None, default: None ) –

    The number of nanoseconds to wait for the radio to finish powering up. If not specified, the default wait time defaults to 5 milliseconds.

rf24_py.RF24.power_down 

power_down() -> None

Power Down the radio.

No transmissions can be received when the radio is powered down.

rf24_py.RF24.tx_delay property writable 

tx_delay: int

The driver will delay for this duration (32 bit unsigned int of microseconds) when as_tx() is called.

If the auto-ack feature is disabled, then this can be set as low as 0. If the auto-ack feature is enabled, then set to 100 microseconds minimum on generally faster devices (like RPi).

This value cannot be negative.

Since this value can be optimized per the radio's data rate, this value is automatically adjusted when changing data_rate. If setting this to a custom value be sure, to set it after changing the radio's data rate.

Warning

If set to 0, then the concurrent outgoing ACK packet (when auto-ack is enabled) may fail to transmit when exiting RX mode with as_tx().

rf24_py.RF24.is_plus_variant property 

is_plus_variant: bool

Is this radio a nRF24L01+ variant?

The bool that this property returns is only valid after calling RF24.begin().