Configuration API

CSN_DELAY

circuitpython_nrf24l01.rf24.CSN_DELAY = 0.005

The delay time (in seconds) used to let the CSN pin settle, allowing a clean SPI transaction.

dynamic_payloads

RF24.dynamic_payloads

This bool attribute controls the nRF24L01’s dynamic payload length feature for each pipe. Default setting is enabled on all pipes.

  • True or 1 enables nRF24L01’s dynamic payload length feature for all data pipes. The payload_length attribute is ignored when this feature is enabled for all respective data pipes.
  • False or 0 disables nRF24L01’s dynamic payload length feature for all data pipes. Be sure to adjust the payload_length attribute accordingly when this feature is disabled for any respective 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.

Note

This attribute mostly relates to RX operations, but data pipe 0 applies to TX operations also. The auto_ack attribute is automatically enabled by this attribute for any data pipes that have this feature enabled. Disabling this feature for any data pipe will not affect the auto_ack feature for the corresponding data pipes.

payload_length

RF24.payload_length

This int attribute specifies the length (in bytes) of static payloads for each pipe. If the dynamic_payloads attribute is enabled for a certain data pipe, this attribute has no affect on that data pipe. When dynamic_payloads is disabled for a certain data pipe, this attribute is used to specify the payload length on that data pipe.

A valid input value must be:

  • an int in range [1, 32]. Otherwise a ValueError exception is thrown.
  • 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 0, then the existing setting will persist (not be changed).

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

Note

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

auto_ack

RF24.auto_ack

This bool attribute controls the nRF24L01’s automatic acknowledgment feature during the process of receiving a packet. Default setting is enabled on all data pipes.

  • True or 1 enables transmitting automatic acknowledgment packets for all data pipes. 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).
  • False or 0 disables transmitting automatic acknowledgment packets for all data pipes. The crc attribute will remain unaffected when disabling this attribute for any 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.

Note

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

arc

RF24.arc

This int attribute specifies the nRF24L01’s number of attempts to re-transmit TX payload when acknowledgment packet is not received. The auto_ack attribute must be enabled on the receiving nRF24L01 respective data pipe, otherwise this attribute will make send() seem like it failed.

A valid input value must be in range [0, 15]. Otherwise a ValueError exception is thrown. Default is set to 3. A value of 0 disables the automatic re-transmit feature and considers all payload transmissions a success.

ard

RF24.ard

This int attribute specifies the nRF24L01’s delay (in microseconds) between attempts to automatically re-transmit the TX payload when an expected acknowledgement (ACK) packet is not received. During this time, the nRF24L01 is listening for the ACK packet. If the arc attribute is disabled, this attribute is not applied.

A valid input value must be in range [250, 4000]. Otherwise a ValueError exception is thrown. 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.

ack

RF24.ack

This bool attribute represents the status of the nRF24L01’s capability to use custom payloads as part of the automatic acknowledgment (ACK) packet. Use this attribute to set/check if the custom ACK payloads feature is enabled. Default setting is False.

  • True enables the use of custom ACK payloads in the ACK packet when responding to receiving transmissions.
  • False disables the use of custom ACK payloads in the ACK packet when responding to receiving transmissions.

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.

interrupt_config()

RF24.interrupt_config(data_recv=True, data_sent=True, data_fail=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) – 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) – 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) – If this is True, then IRQ pin goes active when the maximum number of attempts to re-transmit the packet have been reached. If arc attribute is disabled, 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. retreive the payload from RX FIFO using recv()
  2. clear irq_dr status flag (taken care of by using recv() 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

data_rate

RF24.data_rate

This int attribute specifies the nRF24L01’s frequency data rate for OTA (over the air) transmissions. 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 the non-plus variants of the nRF24L01 transceivers. Trying to set the data rate to 250 kpbs when is_plus_variant is True will throw a NotImplementedError.

channel

RF24.channel

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

crc

RF24.crc

This int attribute specifies the nRF24L01’s CRC (cyclic redundancy checking) encoding scheme in terms of byte length. CRC 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 throws a ValueError exception. 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.

pa_level

RF24.pa_level

This int attribute specifies the nRF24L01’s 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.

is_lna_enabled

RF24.is_lna_enabled

A read-only bool attribute about the LNA (Low Noise Amplifier) gain feature. 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.