Configurable RF24 API

property RF24.ack : bool

Represents use of custom payloads as part of the ACK packet.

Use this attribute to set/check if the custom ACK payloads feature is enabled (True) or disabled (False). Default setting is False.

Note

This attribute differs from the auto_ack attribute because the auto_ack attribute enables or disables the use of automatic ACK packets. By default, ACK packets have no payload. This attribute enables or disables attaching payloads to the ACK packets.

See Also

Use load_ack() attach ACK payloads.

Use read(), send(), resend() to retrieve ACK payloads.

Important

As dynamic_payloads and auto_ack attributes are required for this feature to work, they are automatically enabled (on data pipe 0) as needed. However, it is required to enable the auto_ack and dynamic_payloads features on all applicable pipes. Disabling this feature does not disable the auto_ack and dynamic_payloads attributes for any data pipe; they work just fine without this feature.

property RF24.allow_ask_no_ack : bool

Allow or disable ask_no_ack parameter to send() & write().

This attribute is enabled by default, and it only exists to provide support for the Si24R1. The designers of the Si24R1 (a cheap chinese clone of the nRF24L01) happened to clone a typo from the first version of the nRF24L01 specification sheet. Disable this attribute for the Si24R1.

RF24.interrupt_config(data_recv: bool = True, data_sent: bool = True, data_fail: bool = True)[source]

Sets the configuration of the nRF24L01’s IRQ pin. (write-only)

The digital signal from the nRF24L01’s IRQ (Interrupt ReQuest) pin is active LOW.

Parameters:
data_recv: bool = True

If this is True, then IRQ pin goes active when new data is put into the RX FIFO buffer. Default setting is True

data_sent: bool = True

If this is True, then IRQ pin goes active when a payload from TX buffer is successfully transmit. Default setting is True

data_fail: bool = True

If this is True, then IRQ pin goes active when the maximum number of attempts to re-transmit the packet have been reached. If auto_ack attribute is disabled for pipe 0, then this IRQ event is not used. Default setting is True

Note

To fetch the status (not configuration) of these IRQ flags, use the irq_df, irq_ds, irq_dr attributes respectively.

Tip

Paraphrased from nRF24L01+ Specification Sheet:

The procedure for handling irq_dr IRQ should be:

  1. retrieve the payload from RX FIFO using read()

  2. clear irq_dr status flag (taken care of by using read() in previous step)

  3. read FIFO_STATUS register to check if there are more payloads available in RX FIFO buffer. A call to pipe (may require update() to be called beforehand), any() or even (False, True) as parameters to fifo() will get this result.

  4. if there is more data in RX FIFO, repeat from step 1

property RF24.data_rate : int

This int attribute specifies the RF data rate.

A valid input value is:

  • 1 sets the frequency data rate to 1 Mbps

  • 2 sets the frequency data rate to 2 Mbps

  • 250 sets the frequency data rate to 250 kbps (see warning below)

Any invalid input throws a ValueError exception. Default is 1 Mbps.

Warning

250 kbps is not available for all variants of transceivers based on the nRF24L01. This library will assume that the transceiver being used does support 250 kbps, but there is no way to determine (via software) if that is actually the case. Please refer to your transceiver’s manufacturer information to determine if 250 kbps is supposed to be supported.

Hint

You can perform a carrier wave test on 250 kbps to see if your transceiver hardware does support that data rate. See start_carrier_wave(), stop_carrier_wave(), and rpd to execute a hardware test.

Changed in version 2.2.0: Blindly allow configuring the radio for 250 kbps

Support for 250 kbps is dependent on the hardware being used, and there’s no agnostic way to detect such support.

property RF24.channel : int

This int attribute specifies the nRF24L01’s frequency.

A valid input value must be in range [0, 125] (that means [2.4, 2.525] GHz). Otherwise a ValueError exception is thrown. Default is 76 (2.476 GHz).

property RF24.crc : int

This int attribute specifies the CRC checksum length in bytes.

CRC (cyclic redundancy checking) is a way of making sure that the transmission didn’t get corrupted over the air.

A valid input value must be:

  • 0 disables CRC (no anti-corruption of data)

  • 1 enables CRC encoding scheme using 1 byte (weak anti-corruption of data)

  • 2 enables CRC encoding scheme using 2 bytes (better anti-corruption of data)

Any invalid input will be clamped to range [0, 2]. Default is enabled using 2 bytes.

Note

The nRF24L01 automatically enables CRC if automatic acknowledgment feature is enabled (see auto_ack attribute) for any data pipe.

Changed in version 2.0.0: Invalid input values are clamped to proper range instead of throwing a ValueError exception.

property RF24.pa_level : int

This int is the power amplifier level (in dBm).

Higher levels mean the transmission will cover a longer distance. Use this attribute to tweak the nRF24L01 current consumption on projects that don’t span large areas.

A valid input value is:

  • -18 sets the nRF24L01’s power amplifier to -18 dBm (lowest)

  • -12 sets the nRF24L01’s power amplifier to -12 dBm

  • -6 sets the nRF24L01’s power amplifier to -6 dBm

  • 0 sets the nRF24L01’s power amplifier to 0 dBm (highest)

If this attribute is set to a list or tuple, then the list/tuple must contain the desired power amplifier level (from list above) at index 0 and a bool to control the Low Noise Amplifier (LNA) feature at index 1. All other indices will be discarded.

Note

The LNA feature setting only applies to the nRF24L01 (non-plus variant).

Any invalid input will invoke the default of 0 dBm with LNA enabled.

property RF24.is_lna_enabled : bool

A read-only bool attribute about the LNA gain feature.

LNA stands for Low Noise Amplifier. See pa_level attribute about how to set this. Default is always enabled, but this feature is specific to non-plus variants of nRF24L01 transceivers. If is_plus_variant attribute is True, then setting feature in any way has no affect.

dynamic_payloads

Note

This attribute mostly relates to RX operations, but data pipe 0 applies to TX operations also.

property RF24.dynamic_payloads : int

This int attribute is the dynamic payload length feature for any/all pipes.

Default setting is enabled on all pipes. A valid input is:

  • A bool to enable (True) or disable (False) the dynamic payload length feature for all data pipes.

  • A list or tuple containing booleans or integers can be used control this feature per data pipe. Index 0 controls this feature on data pipe 0. Indices greater than 5 will be ignored since there are only 6 data pipes. If any index’s value is less than 0 (a negative value), then the pipe corresponding to that index will remain unaffected.

  • An int where each bit in the integer represents the dynamic payload feature per pipe. Bit position 0 controls this feature for data pipe 0, and bit position 5 controls this feature for data pipe 5. All bits in positions greater than 5 are ignored.

Note

  • The payload_length attribute is ignored when this feature is enabled for any respective data pipes.

  • Be sure to adjust the payload_length attribute accordingly when this feature is disabled for any respective data pipes.

Returns:

An int (1 unsigned byte) where each bit in the integer represents the dynamic payload length feature per pipe.

Changed in version 1.2.0: Accepts a list or tuple for control of the dynamic payload length feature per pipe.

Changed in version 2.0.0:

  • Returns a integer instead of a boolean

  • Accepts an integer for binary control of the dynamic payload length feature per pipe

RF24.set_dynamic_payloads(enable: bool, pipe_number: int | None = None)[source]

Control the dynamic payload feature for a specific data pipe.

Parameters:
enable: bool

The state of the dynamic payload feature about a specified data pipe.

pipe_number: int | None = None

The specific data pipe number in range [0, 5] to apply the enable parameter. If this parameter is not specified the enable parameter is applied to all data pipes. If this parameter is not in range [0, 5], then a IndexError exception is thrown.

Added in version 2.0.0.

RF24.get_dynamic_payloads(pipe_number: int = 0) → bool[source]

Returns a bool describing the dynamic payload feature about a pipe.

Parameters:
pipe_number: int = 0

The specific data pipe number in range [0, 5] concerning the dynamic payload length feature. If this parameter is not in range [0, 5], then a IndexError exception is thrown. If this parameter is not specified, then the data returned is about data pipe 0.

payload_length

Note

This attribute mostly relates to RX operations, but data pipe 0 applies to TX operations also.

property RF24.payload_length : int

This int attribute is the length of static payloads for any/all pipes.

This attribute can be used to specify the static payload length used for all data pipes in which the dynamic_payloads attribute is disabled

A valid input value must be:

  • an int in which the value that will be clamped to the range [1, 32]. Setting this attribute to a single int configures all 6 data pipes.

  • A list or tuple containing integers can be used control this feature per data pipe. Index 0 controls this feature on data pipe 0. Indices greater than 5 will be ignored since there are only 6 data pipes. If any index’s value is less than or equal to``0``, then the existing setting for the corresponding data pipe will persist (not be changed).

Default is set to the nRF24L01’s maximum of 32 (on all data pipes).

Returns:

The current setting of the expected static payload length feature for pipe 0 only.

Changed in version 1.2.0: Return a list of all payload length settings for all pipes.

This implementation introduced a couple bugs:

  1. The settings could be changed improperly in a way that was not written to the nRF24L01 registers.

  2. There was no way to catch an invalid setting if configured improperly via the first bug. This led to errors in using other functions that handle payloads or the length of payloads.

Changed in version 2.0.0: This attribute returns the configuration about static payload length for data pipe 0 only.

Use get_payload_length() to fetch the configuration of the static payload length feature for any data pipe.

RF24.set_payload_length(length: int, pipe_number: int | None = None)[source]

Sets the static payload length feature for each/all data pipes.

This function only affects data pipes for which the dynamic_payloads attribute is disabled.

Parameters:
length: int

The number of bytes in range [1, 32] for to be used for static payload lengths. If this number is not in range [1, 32], then it will be clamped to that range.

pipe_number: int | None = None

The specific data pipe number in range [0, 5] to apply the length parameter. If this parameter is not specified the length parameter is applied to all data pipes. If this parameter is not in range [0, 5], then a IndexError exception is thrown.

Added in version 2.0.0.

RF24.get_payload_length(pipe_number: int = 0) → int[source]

Returns an int describing the specified data pipe’s static payload length.

The data returned by this function is only relevant for data pipes in which the dynamic_payloads attribute is disabled.

Parameters:
pipe_number: int = 0

The specific data pipe number in range [0, 5] to concerning the static payload length feature. If this parameter is not in range [0, 5], then a IndexError exception is thrown. If this parameter is not specified, then the data returned is about data pipe 0.

Added in version 2.0.0.

auto_ack

Important

This attribute mostly relates to RX operations, but data pipe 0 applies to TX operations also.

  • This attribute will intuitively disable the acknowledgement payload feature (ack attribute) when the automatic acknowledgement feature is disabled for data pipe 0.

  • When entering in TX mode, the listen attribute will ensure data pipe 0 is open to receive automatic acknowledgments for outgoing transmissions.

  • Be sure to configure this attribute for data pipe 0 before calling open_tx_pipe() because the RX address for pipe 0 needs to be overwritten for automatic acknowledgments to be received in TX mode. The listen attribute will re-write the RX address for data pipe 0 when entering RX mode if needed.

property RF24.auto_ack : int

This int attribute is the automatic acknowledgment feature for any/all pipes.

Default setting is enabled on all data pipes. A valid input is:

  • A bool to enable (True) or disable (False) transmitting automatic acknowledgment packets for all data pipes.

  • A list or tuple containing booleans or integers can be used control this feature per data pipe. Index 0 controls this feature on data pipe 0. Indices greater than 5 will be ignored since there are only 6 data pipes. If any index’s value is less than 0 (a negative value), then the pipe corresponding to that index will remain unaffected.

  • An int where each bit in the integer represents the automatic acknowledgement feature per pipe. Bit position 0 controls this feature for data pipe 0, and bit position 5 controls this feature for data pipe 5. All bits in positions greater than 5 are ignored.

Note

The CRC (cyclic redundancy checking) is enabled (for all transmissions) automatically by the nRF24L01 if this attribute is enabled for any data pipe (see also crc attribute). The crc attribute will remain unaffected when disabling this attribute for any data pipes.

Returns:

An int (1 unsigned byte) where each bit in the integer represents the automatic acknowledgement feature per pipe.

Changed in version 1.2.0: Accepts a list or tuple for control of the automatic acknowledgement feature per pipe.

Changed in version 2.0.0:

  • Returns an integer instead of a boolean

  • Accepts an integer for binary control of the automatic acknowledgement feature per pipe

RF24.set_auto_ack(enable: bool, pipe_number: int)[source]

Control the auto_ack feature for a specific data pipe.

Parameters:
enable: bool

The state of the automatic acknowledgement feature about a specified data pipe.

pipe_number: int

The specific data pipe number in range [0, 5] to apply the enable parameter. If this parameter is not specified the enable parameter is applied to all data pipes. If this parameter is not in range [0, 5], then a IndexError exception is thrown.

Added in version 2.0.0.

RF24.get_auto_ack(pipe_number: int) → bool[source]

Returns a bool describing the auto_ack feature about a data pipe.

Parameters:
pipe_number: int

The specific data pipe number in range [0, 5] concerning the setting for the automatic acknowledgment feature. If this parameter is not in range [0, 5], then a IndexError exception is thrown. If this parameter is not specified, then the data returned is about data pipe 0.

Added in version 2.0.0.

Auto-Retry feature

property RF24.arc : int

This int attribute specifies the number of attempts to re-transmit TX payload when ACK packet is not received.

The auto_ack attribute must be enabled on the receiving nRF24L01’s pipe 0 & the RX data pipe and the transmitting nRF24L01’s pipe 0 to properly use this attribute. If auto_ack is disabled on the transmitting nRF24L01’s pipe 0, then this attribute is ignored when calling send().

A valid input value will be clamped to range [0, 15]. Default is set to 15. A value of 0 disables the automatic re-transmit feature, but the sending nRF24L01 will still wait the number of microseconds specified by ard for an Acknowledgement (ACK) packet response (assuming auto_ack is enabled).

Changed in version 2.0.0: Invalid input values are clamped to proper range instead of throwing a ValueError exception.

Changed in version 2.2.0: Default value changed from 3 to the maximum 15.

This only affects performance in scenarios that experience unreliable reception.

property RF24.ard : int

This int attribute specifies the delay (in microseconds) between attempts to automatically re-transmit the TX payload when no ACK packet is received.

During this time, the nRF24L01 is listening for the ACK packet. If the auto_ack attribute is disabled for pipe 0, then this attribute is not applied.

A valid input value will be clamped to range [250, 4000]. Default is 1500 for reliability. If this is set to a value that is not multiple of 250, then the highest multiple of 250 that is no greater than the input value is used.

Note

Paraphrased from nRF24L01 specifications sheet:

Please take care when setting this parameter. If the custom ACK payload is more than 15 bytes in 2 Mbps data rate, the ard must be 500µS or more. If the custom ACK payload is more than 5 bytes in 1 Mbps data rate, the ard must be 500µS or more. In 250kbps data rate (even when there is no custom ACK payload) the ard must be 500µS or more.

See data_rate attribute on how to set the data rate of the nRF24L01’s transmissions.

Changed in version 2.0.0: Invalid input values are clamped to proper range instead of throwing a ValueError exception.

RF24.set_auto_retries(delay: int, count: int)[source]

set the ard & arc attributes with 1 function.

Parameters:
delay: int

accepts the same input as the ard attribute.

count: int

accepts the same input as the arc attribute.

RF24.get_auto_retries() → tuple[source]

get the ard & arc attributes with 1 function.

Return:

A tuple containing 2 items; index 0 will be the ard attribute, and index 1 will be the arc attribute.