Configurable RF24 API¶
dynamic_payloads¶
Note
This attribute mostly relates to RX operations, but data pipe 0 applies to TX operations also.
-
RF24.
dynamic_payloads
¶ This
int
attribute controls the nRF24L01’s dynamic payload length feature for any or 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
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.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
set_dynamic_payloads()¶
-
RF24.
set_dynamic_payloads
(enable, pipe_number=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) – The specific data pipe number in range [0, 5] to apply the
enable
parameter. If this parameter is not specified theenable
parameter is applied to all data pipes. If this parameter is not in range [0, 5], then aIndexError
exception is thrown.
New in version 2.0.0.
get_dynamic_payloads()¶
-
RF24.
get_dynamic_payloads
(pipe_number=0)[source]¶ Returns a
bool
describing the setting of the dynamic payload feature about a specific data pipe.- Parameters
pipe_number (int) – 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.
-
RF24.
payload_length
¶ This
int
attribute specifies the length (in bytes) of static payloads for any or 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 disabledA 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 singleint
configures all 6 data pipes.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 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:
The settings could be changed improperly in a way that was not written to the nRF24L01 registers.
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.
set_payload_length()¶
-
RF24.
set_payload_length
(length, pipe_number=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) – The specific data pipe number in range [0, 5] to apply the
length
parameter. If this parameter is not specified thelength
parameter is applied to all data pipes. If this parameter is not in range [0, 5], then aIndexError
exception is thrown.
New in version 2.0.0.
get_payload_length()¶
-
RF24.
get_payload_length
(pipe_number=0)[source]¶ Returns an
int
describing the current setting of a specified data pipe’s expected 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) – 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.
New in version 2.0.0.
auto_ack¶
Note
- This attribute mostly relates to RX operations, but data pipe 0 applies to TX operations also. This attribute will intuitively:
enable the automatic acknowledgement feature for pipe 0 if any other data pipe is configured to use the automatic acknowledgement feature.
disable the acknowledgement payload feature (
ack
attribute) when the automatic acknowledgement feature is disabled for data pipe 0.
-
RF24.
auto_ack
¶ This
int
attribute controls the nRF24L01’s automatic acknowledgment feature for any or 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
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.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). Thecrc
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 a integer instead of a boolean
accepts an integer for binary control of the automatic acknowledgement feature per pipe
set_auto_ack()¶
-
RF24.
set_auto_ack
(enable, pipe_number=None)[source]¶ Control the automatic acknowledgement 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 theenable
parameter is applied to all data pipes. If this parameter is not in range [0, 5], then aIndexError
exception is thrown.
New in version 2.0.0.
get_auto_ack()¶
-
RF24.
get_auto_ack
(pipe_number=0)[source]¶ Returns a
bool
describing the automatic acknowledgement feature setting about a specific 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.
New in version 2.0.0.
Auto-Retry feature¶
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’s pipe 0 & the RX data pipe and the transmitting nRF24L01’s pipe 0 to properly use this attribute. Ifauto_ack
is disabled on the transmitting nRF24L01’s pipe 0, then this attribute is ignored when callingsend()
.A valid input value will be clamped to range [0, 15]. Default is set to 3. A value of
0
disables the automatic re-transmit feature, but the sending nRF24L01 will still wait the number of microseconds specified byard
for an Acknowledgement (ACK) packet response (assumingauto_ack
is enabled).Changed in version 2.0.0: invalid input values are clamped to proper range instead of throwing a
ValueError
exception.
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
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, 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.Changed in version 2.0.0: invalid input values are clamped to proper range instead of throwing a
ValueError
exception.
set_auto_retries()¶
get_auto_retries()¶
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 (
True
) or disabled (False
). Default setting isFalse
.Note
This attribute differs from the
auto_ack
attribute because theauto_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.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.
allow_ask_no_ack¶
-
RF24.
allow_ask_no_ack
¶ Allow or disallow the use of
ask_no_ack
parameter tosend()
&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.
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. Ifauto_ack
attribute is disabled for pipe 0, 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
read()
clear
irq_dr
status flag (taken care of by usingread()
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_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 a
ValueError
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 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.
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.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. Ifis_plus_variant
attribute isTrue
, then setting feature in any way has no affect.