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
or1
enables nRF24L01’s dynamic payload length feature for all data pipes. Thepayload_length
attribute is ignored when this feature is enabled for all respective data pipes.False
or0
disables nRF24L01’s dynamic payload length feature for all data pipes. Be sure to adjust thepayload_length
attribute accordingly when this feature is disabled for any respective data pipes.- A
list
ortuple
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 theauto_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 thedynamic_payloads
attribute is enabled for a certain data pipe, this attribute has no affect on that data pipe. Whendynamic_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 aValueError
exception is thrown. - A
list
ortuple
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 is0
, 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.
- an
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
or1
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 alsocrc
attribute).False
or0
disables transmitting automatic acknowledgment packets for all data pipes. Thecrc
attribute will remain unaffected when disabling this attribute for any data pipes.- A
list
ortuple
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. Theauto_ack
attribute must be enabled on the receiving nRF24L01 respective data pipe, otherwise this attribute will makesend()
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 of0
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 thearc
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, theard
must be 500µS or more. In 250kbps data rate (even when there is no custom ACK payload) theard
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 isFalse
.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
andauto_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 theauto_ack
anddynamic_payloads
features on all applicable pipes. Disabling this feature does not disable theauto_ack
anddynamic_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 isTrue
- data_sent (bool) – If this is
True
, then IRQ pin goes active when a payload from TX buffer is successfully transmit. Default setting isTrue
- 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. Ifarc
attribute is disabled, then this IRQ event is not used. Default setting isTrue
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:- retreive the payload from RX FIFO using
recv()
- clear
irq_dr
status flag (taken care of by usingrecv()
in previous step) - read FIFO_STATUS register to check if there are more payloads available in RX FIFO
buffer. A call to
pipe
(may requireupdate()
to be called beforehand),any()
or even(False, True)
as parameters tofifo()
will get this result. - if there is more data in RX FIFO, repeat from step 1
- data_recv (bool) – If this is
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 Mbps2
sets the frequency data rate to 2 Mbps250
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
isTrue
will throw aNotImplementedError
.
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 aValueError
exception is thrown. Default is76
(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 dBm0
sets the nRF24L01’s power amplifier to 0 dBm (highest)
If this attribute is set to a
list
ortuple
, then the list/tuple must contain the desired power amplifier level (from list above) at index 0 and abool
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. Seepa_level
attribute about how to set this. Default is always enabled, but this feature is specific to non-plus variants of nRF24L01 transceivers. Ifis_plus_variant
attribute isTrue
, then setting feature in any way has no affect.