RF24 class¶

Important

The nRF24L01 has 3 key features that can be interdependent of each other. Their priority of dependence is as follows:

dynamic_payloads feature allowing either TX/RX nRF24L01 to be able to send/receive payloads with their size written into the payloads’ packet. With this disabled, both RX/TX nRF24L01 must use matching payload_length attributes.
auto_ack feature provides transmission verification by using the RX nRF24L01 to automatically and imediatedly send an acknowledgment (ACK) packet in response to freshly received payloads. auto_ack does not require dynamic_payloads to be enabled.
ack feature allows the MCU to append a payload to the ACK packet, thus instant bi-directional communication. A transmitting ACK payload must be loaded into the nRF24L01’s TX FIFO buffer (done using load_ack()) BEFORE receiving the payload that is to be acknowledged. Once transmitted, the payload is released from the TX FIFO buffer. This feature requires the auto_ack and dynamic_payloads features enabled.

Remeber that the nRF24L01’s FIFO (first-in,first-out) buffer has 3 levels. This means that there can be up to 3 payloads waiting to be read (RX) and up to 3 payloads waiting to be transmit (TX).

With the auto_ack feature enabled you get:

cycle redundancy checking (crc) automatically enabled

to change amount of automatic re-transmit attempts and the delay time between them. See the arc and ard attributes.

Note

A word on pipes vs addresses vs channels.

You should think of the data pipes as a vehicle that you (the payload) get into. Continuing the analogy, the specified address is not the address of an nRF24L01 radio, rather it is more like a route that connects the endpoints. There are only six data pipes on the nRF24L01, thus it can simultaneously listen to a maximum of 6 other nRF24L01 radios (can only talk to 1 at a time). When assigning addresses to a data pipe, you can use any 5 byte long address you can think of (as long as the last byte is unique among simultaneously broadcasting addresses), so you’re not limited to communicating to the same 6 radios (more on this when we support “Multiciever” mode). Also the radio’s channel is not be confused with the radio’s pipes. Channel selection is a way of specifying a certain radio frequency (frequency = [2400 + channel] MHz). Channel defaults to 76 (like the arduino library), but options range from 0 to 125 – that’s 2.4 GHz to 2.525 GHz. The channel can be tweaked to find a less occupied frequency amongst (Bluetooth & WiFi) ambient signals.

Warning

For successful transmissions, most of the endpoint trasceivers’ settings/features must match. These settings/features include:

The RX pipe’s address on the receiving nRF24L01 MUST match the TX pipe’s address on the transmitting nRF24L01
address_length
channel
data_rate
dynamic_payloads
payload_length only when dynamic_payloads is disabled
auto_ack
custom ack payloads
crc

In fact the only attributes that aren’t required to match on both endpoint transceivers would be the identifying data pipe number (passed to open_rx_pipe()), pa_level, arc, & ard attributes. The ask_no_ack feature can be used despite the settings/features configuration (see send() & write() function parameters for more details).

Basic API¶

class circuitpython_nrf24l01.rf24.RF24(spi, csn, ce, channel=76, payload_length=32, address_length=5, ard=1500, arc=3, crc=2, data_rate=1, pa_level=0, dynamic_payloads=True, auto_ack=True, ask_no_ack=True, ack=False, irq_DR=True, irq_DS=True, irq_DF=True)[source]¶

A driver class for the nRF24L01(+) transceiver radios. This class aims to be compatible with other devices in the nRF24xxx product line that implement the Nordic proprietary Enhanced ShockBurst Protocol (and/or the legacy ShockBurst Protocol), but officially only supports (through testing) the nRF24L01 and nRF24L01+ devices.

Parameters:

spi (SPI) –
The object for the SPI bus that the nRF24L01 is connected to.

Tip

This object is meant to be shared amongst other driver classes (like adafruit_mcp3xxx.mcp3008 for example) that use the same SPI bus. Otherwise, multiple devices on the same SPI bus with different spi objects may produce errors or undesirable behavior.
csn (DigitalInOut) – The digital output pin that is connected to the nRF24L01’s CSN (Chip Select Not) pin. This is required.
ce (DigitalInOut) – The digital output pin that is connected to the nRF24L01’s CE (Chip Enable) pin. This is required.
channel (int) – This is used to specify a certain radio frequency that the nRF24L01 uses. Defaults to 76 and can be changed at any time by using the channel attribute.
payload_length (int) – This is the length (in bytes) of a single payload to be transmitted or received. This is ignored if the dynamic_payloads attribute is enabled. Defaults to 32 and must be in range [1,32]. This can be changed at any time by using the payload_length attribute.
address_length (int) – This is the length (in bytes) of the addresses that are assigned to the data pipes for transmitting/receiving. Defaults to 5 and must be in range [3,5]. This can be changed at any time by using the address_length attribute.
ard (int) – This specifies the delay time (in µs) between attempts to automatically re-transmit. This can be changed at any time by using the ard attribute. This parameter must be a multiple of 250 in the range [250,4000]. Defualts to 1500 µs.
arc (int) – This specifies the automatic re-transmit count (maximum number of automatically attempts to re-transmit). This can be changed at any time by using the arc attribute. This parameter must be in the range [0,15]. Defaults to 3.
crc (int) – This parameter controls the CRC setting of transmitted packets. Options are 0 (off), 1 or 2 (byte long CRC enabled). This can be changed at any time by using the crc attribute. Defaults to 2.
data_rate (int) – This parameter controls the RF data rate setting of transmissions. Options are 1 (Mbps), 2 (Mbps), or 250 (Kbps). This can be changed at any time by using the data_rate attribute. Defaults to 1.
pa_level (int) – This parameter controls the RF power amplifier setting of transmissions. Options are 0 (dBm), -6 (dBm), -12 (dBm), or -18 (dBm). This can be changed at any time by using the pa_level attribute. Defaults to 0.
dynamic_payloads (bool) – This parameter enables/disables the dynamic payload length feature of the nRF24L01. Defaults to enabled. This can be changed at any time by using the dynamic_payloads attribute.
auto_ack (bool) – This parameter enables/disables the automatic acknowledgment (ACK) feature of the nRF24L01. Defaults to enabled if dynamic_payloads is enabled. This can be changed at any time by using the auto_ack attribute.
ask_no_ack (bool) – This represents a special flag that has to be thrown to enable a feature specific to individual payloads. Setting this parameter only enables access to this feature; it does not invoke it (see parameters for send() or write() functions). Enabling/Disabling this does not affect auto_ack attribute.
ack (bool) – This represents a special flag that has to be thrown to enable a feature allowing custom response payloads appended to the ACK packets. Enabling this also requires the auto_ack attribute enabled. This can be changed at any time by using the ack attribute.
irq_DR (bool) – When “Data is Ready”, this configures the interrupt (IRQ) trigger of the nRF24L01’s IRQ pin (active low). Defaults to enabled. This can be changed at any time by using the interrupt_config() function.
irq_DS (bool) – When “Data is Sent”, this configures the interrupt (IRQ) trigger of the nRF24L01’s IRQ pin (active low). Defaults to enabled. This can be changed at any time by using the interrupt_config() function.
irq_DF (bool) – When “max retry attempts are reached” (specified by the arc attribute), this configures the interrupt (IRQ) trigger of the nRF24L01’s IRQ pin (active low) and represents transmission failure. Defaults to enabled. This can be changed at any time by using the interrupt_config() function.

address_length¶

This int attribute specifies the length (in bytes) of addresses to be used for RX/TX pipes. The addresses assigned to the data pipes must have byte length equal to the value set for this attribute.

A valid input value must be an int in range [3,5]. Otherwise a ValueError exception is thrown. Default is set to the nRF24L01’s maximum of 5.

open_tx_pipe(address)[source]¶

This function is used to open a data pipe for OTA (over the air) TX transmissions.

Parameters:	address (bytearray) – The virtual address of the receiving nRF24L01. This must have a length equal to the `address_length` attribute (see `address_length` attribute). Otherwise a `ValueError` exception is thrown. The address specified here must match the address set to one of the RX data pipes of the receiving nRF24L01.

Note

There is no option to specify which data pipe to use because the nRF24L01 only uses data pipe 0 in TX mode. Additionally, the nRF24L01 uses the same data pipe (pipe 0) for receiving acknowledgement (ACK) packets in TX mode when the auto_ack attribute is enabled. Thus, RX pipe 0 is appropriated with the TX address (specified here) when auto_ack is set to True.

close_rx_pipe(pipe_number, reset=True)[source]¶

This function is used to close a specific data pipe from OTA (over the air) RX transmissions.

Parameters:

pipe_number (int) – The data pipe to use for RX transactions. This must be in range [0,5]. Otherwise a ValueError exception is thrown.
reset (bool) – True resets the address for the specified pipe_number to the factory address (different for each pipe). False leaves the address on the specified pipe_number alone. Be aware that the addresses will remain despite loss of power.

open_rx_pipe(pipe_number, address)[source]¶

This function is used to open a specific data pipe for OTA (over the air) RX transmissions. If dynamic_payloads attribute is False, then the payload_length attribute is used to specify the expected length of the RX payload on the specified data pipe.

Parameters:

pipe_number (int) – The data pipe to use for RX transactions. This must be in range [0,5]. Otherwise a ValueError exception is thrown.
address (bytearray) – The virtual address to the receiving nRF24L01. This must have a byte length equal to the address_length attribute. Otherwise a ValueError exception is thrown. If using a pipe_number greater than 1, then only the MSByte of the address is written, so make sure MSByte (first character) is unique among other simultaneously receiving addresses).

Note

The nRF24L01 shares the addresses’ LSBytes (address[1:5]) on data pipes 2 through 5. These shared LSBytes are determined by the address set to pipe 1.

listen¶

An attribute to represent the nRF24L01 primary role as a radio.

Setting this attribute incorporates the proper transitioning to/from RX mode as it involves playing with the power attribute and the nRF24L01’s CE pin. This attribute does not power down the nRF24L01, but will power it up when needed; use power attribute set to False to put the nRF24L01 to sleep.

A valid input value is a bool in which:

True enables RX mode. Additionally, per Appendix B of the nRF24L01+ Specifications Sheet, this attribute flushes the RX FIFO, clears the irq_DR status flag, and puts nRF24L01 in power up mode. Notice the CE pin is be held HIGH during RX mode.

False disables RX mode. As mentioned in above link, this puts nRF24L01’s power in Standby-I (CE pin is LOW meaning low current & no transmissions) mode which is ideal for post-reception work. Disabing RX mode doesn’t flush the RX/TX FIFO buffers, so remember to flush your 3-level FIFO buffers when appropriate using flush_tx() or flush_rx() (see also the recv() function).

any()[source]¶

This function checks if the nRF24L01 has received any data at all. Internally, this function uses pipe() then reports the next available payload’s length (in bytes) – if there is any.

Returns:	`int` of the size (in bytes) of an available RX payload (if any). `0` if there is no payload in the RX FIFO buffer.

recv()[source]¶

This function is used to retrieve the next available payload in the RX FIFO buffer, then clears the irq_DR status flag. This function also serves as a helper function to read_ack() in TX mode to aquire any custom payload in the automatic acknowledgement (ACK) packet – only when the ack attribute is enabled.

Returns:	A `bytearray` of the RX payload data If the `dynamic_payloads` attribute is disabled, then the returned bytearray’s length is equal to the user defined `payload_length` attribute (which defaults to 32). If the `dynamic_payloads` attribute is enabled, then the returned bytearray’s length is equal to the payload’s length

Tip

Call the any() function before calling recv() to verify that there is data to fetch. If there’s no data to fetch, then the nRF24L01 returns bogus data and should not regarded as a valid payload.

send(buf, ask_no_ack=False)[source]¶

This blocking function is used to transmit payload(s).

Returns:

list if a list or tuple of payloads was passed as the buf parameter. Each item in the returned list will contain the returned status for each corresponding payload in the list/tuple that was passed. The return statuses will be in one of the following forms:
False if transmission fails.
True if transmission succeeds.
bytearray when the ack attribute is True, the payload expects a responding custom ACK payload; the response is returned (upon successful transmission) as a bytearray. Empty ACK payloads (upon successful transmission) when the ack attribute is set True are replaced with an error message b'NO ACK RETURNED'.
None if transmission times out meaning nRF24L01 has malfunctioned. This condition is very rare. The allowed time for transmission is calculated using table 18 in the nRF24L01 specification sheet

Parameters:

buf (bytearray,list,tuple) –
The payload to transmit. This bytearray must have a length greater than 0 and less than 32, otherwise a ValueError exception is thrown. This can also be a list or tuple of payloads (bytearray); in which case, all items in the list/tuple are processed for consecutive transmissions.
- If the dynamic_payloads attribute is disabled and this bytearray’s length is less than the payload_length attribute, then this bytearray is padded with zeros until its length is equal to the payload_length attribute.
- If the dynamic_payloads attribute is disabled and this bytearray’s length is greater than payload_length attribute, then this bytearray’s length is truncated to equal the payload_length attribute.
ask_no_ack (bool) –
Pass this parameter as True to tell the nRF24L01 not to wait for an acknowledgment from the receiving nRF24L01. This parameter directly controls a NO_ACK flag in the transmission’s Packet Control Field (9 bits of information about the payload). Therefore, it takes advantage of an nRF24L01 feature specific to individual payloads, and its value is not saved anywhere. You do not need to specify this for every payload if the auto_ack attribute is disabled, however this parameter should work despite the auto_ack attribute’s setting.

Note

Each transmission is in the form of a packet. This packet contains sections of data around and including the payload. See Chapter 7.3 in the nRF24L01 Specifications Sheet for more details.

Tip

It is highly recommended that auto_ack attribute is enabled when sending multiple payloads. Test results with the auto_ack attribute disabled were very poor (much < 50% received). This same advice applies to the ask_no_ack parameter (leave it as False for multiple payloads).

Warning

The nRF24L01 will block usage of the TX FIFO buffer upon failed transmissions. Failed transmission’s payloads stay in TX FIFO buffer until the MCU calls flush_tx() and clear_status_flags(). Therefore, this function will discard failed transmissions’ payloads when sending a list or tuple of payloads, so it can continue to process through the list/tuple even if any payload fails to be acknowledged.

Note

We’ve tried very hard to keep nRF24L01s driven by CircuitPython devices compliant with nRF24L01s driven by the Raspberry Pi. But due to the Raspberry Pi’s seemingly slower SPI speeds, we’ve had to resort to internally deploying resend() twice (at most when needed) for payloads that failed during multi-payload processing. This tactic is meant to slow down CircuitPython devices just enough for the Raspberry Pi to catch up. Transmission failures are less possible this way.

Advanced API¶

class circuitpython_nrf24l01.rf24.RF24¶

RF24.what_happened(dump_pipes=False)¶

This debuggung function aggregates and outputs all status/condition related information from the nRF24L01. Some information may be irrelevant depending on nRF24L01’s state/condition.

Prints:

Channel The current setting of the channel attribute
RF Data Rate The current setting of the RF data_rate attribute.
RF Power Amplifier The current setting of the pa_level attribute.
CRC bytes The current setting of the crc attribute
Address length The current setting of the address_length attribute
Payload lengths The current setting of the payload_length attribute
Auto retry delay The current setting of the ard attribute
Auto retry attempts The current setting of the arc attribute
Packets Lost Total amount of packets lost (transmission failures)
Retry Attempts Made Maximum amount of attempts to re-transmit during last transmission (resets per payload)
IRQ - Data Ready The current setting of the IRQ pin on “Data Ready” event
IRQ - Data Sent The current setting of the IRQ pin on “Data Sent” event
IRQ - Data Fail The current setting of the IRQ pin on “Data Fail” event
Data Ready Is there RX data ready to be read? (state of the irq_DR flag)
Data Sent Has the TX data been sent? (state of the irq_DS flag)
Data Failed Has the maximum attempts to re-transmit been reached? (state of the irq_DF flag)
TX FIFO full Is the TX FIFO buffer full? (state of the tx_full flag)
TX FIFO empty Is the TX FIFO buffer empty?
RX FIFO full Is the RX FIFO buffer full?
RX FIFO empty Is the RX FIFO buffer empty?
Custom ACK payload Is the nRF24L01 setup to use an extra (user defined) payload attached to the acknowledgment packet? (state of the ack attribute)
Ask no ACK Is the nRF24L01 setup to transmit individual packets that don’t require acknowledgment?
Automatic Acknowledgment Is the auto_ack attribute enabled?
Dynamic Payloads Is the dynamic_payloads attribute enabled?
Primary Mode The current mode (RX or TX) of communication of the nRF24L01 device.
Power Mode The power state can be Off, Standby-I, Standby-II, or On.

Parameters:

dump_pipes (bool) –

True appends the output and prints:

the current address used for TX transmissions
Pipe [#] ([open/closed]) bound: [address] where # represent the pipe number, the open/closed status is relative to the pipe’s RX status, and address is read directly from the nRF24L01 registers.
if the pipe is open, then the output also prints expecting [X] byte static payloads where X is the payload_length (in bytes) the pipe is setup to receive when dynamic_payloads is disabled.

Default is False and skips this extra information.

RF24.dynamic_payloads¶

This bool attribute controls the nRF24L01’s dynamic payload length feature.

True enables nRF24L01’s dynamic payload length feature. The payload_length attribute is ignored when this feature is enabled.
False disables nRF24L01’s dynamic payload length feature. Be sure to adjust the payload_length attribute accordingly when dynamic_payloads feature is disabled.

RF24.payload_length¶

This int attribute specifies the length (in bytes) of payload that is regarded, meaning “how big of a payload should the radio care about?” If the dynamic_payloads attribute is enabled, this attribute has no affect. When dynamic_payloads is disabled, this attribute is used to specify the payload length when entering RX mode.

A valid input value must be an int in range [1,32]. Otherwise a ValueError exception is thrown. Default is set to the nRF24L01’s maximum of 32.

Note

When dynamic_payloads is disabled during transmissions:

Payloads’ size of greater than this attribute’s value will be truncated to match.
Payloads’ size of less than this attribute’s value will be padded with zeros to match.

RF24.auto_ack¶

This bool attribute controls the nRF24L01’s automatic acknowledgment feature.

True enables automatic acknowledgment packets. The CRC (cyclic redundancy checking) is enabled automatically by the nRF24L01 if the auto_ack attribute is enabled (see also crc attribute).
False disables automatic acknowledgment packets. The crc attribute will remain unaffected (remains enabled) when disabling the auto_ack attribute.

RF24.irq_DR¶

A bool that represents the “Data Ready” interrupted flag. (read-only)

True represents Data is in the RX FIFO buffer
False represents anything depending on context (state/condition of FIFO buffers) – usually this means the flag’s been reset.

Pass dataReady parameter as True to clear_status_flags() and reset this. As this is a virtual representation of the interrupt event, this attribute will always be updated despite what the actual IRQ pin is configured to do about this event.

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed.

RF24.irq_DF¶

A bool that represents the “Data Failed” interrupted flag. (read-only)

True signifies the nRF24L01 attemped all configured retries
False represents anything depending on context (state/condition) – usually this means the flag’s been reset.

Pass dataFail parameter as True to clear_status_flags() to reset this. As this is a virtual representation of the interrupt event, this attribute will always be updated despite what the actual IRQ pin is configured to do about this event.see also the arc and ard attributes.

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed.

RF24.irq_DS¶

A bool that represents the “Data Sent” interrupted flag. (read-only)

True represents a successful transmission
False represents anything depending on context (state/condition of FIFO buffers) – usually this means the flag’s been reset.

Pass dataSent parameter as True to clear_status_flags() to reset this. As this is a virtual representation of the interrupt event, this attribute will always be updated despite what the actual IRQ pin is configured to do about this event.

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any other SPI transactions. Use the update() function to manually refresh this data when needed.

RF24.clear_status_flags(data_recv=True, data_sent=True, data_fail=True)¶

This clears the interrupt flags in the status register. Internally, this is automatically called by send(), write(), recv(), and when listen changes from False to True.

Parameters:	data_recv (bool) – specifies wheather to clear the “RX Data Ready” flag. data_sent (bool) – specifies wheather to clear the “TX Data Sent” flag. data_fail (bool) – specifies wheather to clear the “Max Re-transmit reached” flag.

Note

Clearing the data_fail flag is necessary for continued transmissions from the nRF24L01 (locks the TX FIFO buffer when irq_DF is True) despite wheather or not the MCU is taking advantage of the interrupt (IRQ) pin. Call this function only when there is an antiquated status flag (after you’ve dealt with the specific payload related to the staus flags that were set), otherwise it can cause payloads to be ignored and occupy the RX/TX FIFO buffers. See Appendix A of the nRF24L01+ Specifications Sheet for an outline of proper behavior.

RF24.interrupt_config(data_recv=True, data_sent=True, data_fail=True)¶

Sets the configuration of the nRF24L01’s IRQ (interrupt) pin. The signal from the nRF24L01’s IRQ pin is active LOW. (write-only)

Parameters:

data_recv (bool) – If this is True, then IRQ pin goes active when there is new data to read in the RX FIFO buffer.
data_sent (bool) – If this is True, then IRQ pin goes active when a payload from TX buffer is successfully transmit.
data_fail (bool) – If this is True, then IRQ pin goes active when maximum number of attempts to re-transmit the packet have been reached. If auto_ack attribute is disabled, then this IRQ event is not used.

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 data_recv IRQ should be:

read payload through recv()
clear dataReady status flag (taken care of by using recv() in previous step)
read FIFO_STATUS register to check if there are more payloads available in RX FIFO buffer. (a call to pipe(), any() or even (False,True) as parameters to fifo() will get this result)
if there is more data in RX FIFO, repeat from step 1

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 enables the use of custom ACK payloads in the ACK packet when responding to receiving transmissions. As dynamic_payloads and auto_ack attributes are required for this feature to work, they are automatically enabled as needed.
False disables the use of custom ACK payloads. Disabling this feature does not disable the auto_ack and dynamic_payloads attributes (they work just fine without this feature).

RF24.load_ack(buf, pipe_number)¶

This allows the MCU to specify a payload to be allocated into the TX FIFO buffer for use on a specific data pipe. This payload will then be appended to the automatic acknowledgment (ACK) packet that is sent when fresh data is received on the specified pipe. See read_ack() on how to fetch a received custom ACK payloads.

Parameters:

buf (bytearray) – This will be the data attached to an automatic ACK packet on the incoming transmission about the specified pipe_number parameter. This must have a length in range [1,32] bytes, otherwise a ValueError exception is thrown. Any ACK payloads will remain in the TX FIFO buffer until transmitted successfully or flush_tx() is called.
pipe_number (int) – This will be the pipe number to use for deciding which transmissions get a response with the specified buf parameter’s data. This number must be in range [0,5], otherwise a ValueError exception is thrown.

Returns:

True if payload was successfully loaded onto the TX FIFO buffer. False if it wasn’t because TX FIFO buffer is full.

Note

this function takes advantage of a special feature on the nRF24L01 and needs to be called for every time a customized ACK payload is to be used (not for every automatic ACK packet – this just appends a payload to the ACK packet). The ack, auto_ack, and dynamic_payloads attributes are also automatically enabled by this function when necessary.

Tip

The ACK payload must be set prior to receiving a transmission. It is also worth noting that the nRF24L01 can hold up to 3 ACK payloads pending transmission. Using this function does not over-write existing ACK payloads pending; it only adds to the queue (TX FIFO buffer) if it can. Use flush_tx() to discard unused ACK payloads when done listening.

RF24.read_ack()¶: Allows user to read the automatic acknowledgement (ACK) payload (if any) when nRF24L01 is in TX mode. This function is called from a blocking send() call if the ack attribute is enabled. Alternatively, this function can be called directly in case of calling the non-blocking write() function during asychronous applications.

Warning

In the case of asychronous applications, this function will do nothing if the status flags are cleared after calling write() and before calling this function. See also the ack, dynamic_payloads, and auto_ack attributes as they must be enabled to use custom ACK payloads.

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

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

Warning

250 Kbps is be buggy on the non-plus models of the nRF24L01 product line. If you use 250 Kbps data rate, and some transmissions report failed by the transmitting nRF24L01, even though the same packet in question actually reports received by the receiving nRF24L01, then try a higher data rate. CAUTION: Higher data rates mean less maximum distance between nRF24L01 transceivers (and vise versa).

RF24.channel¶

This int attribute specifies the nRF24L01’s frequency (in 2400 + channel MHz).

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.

RF24.crc¶

This int attribute specifies the nRF24L01’s CRC (cyclic redundancy checking) encoding scheme in terms of byte length.

A valid input value is in range [0,2]:

0 disables CRC
1 enables CRC encoding scheme using 1 byte
2 enables CRC encoding scheme using 2 bytes

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

RF24.power¶

This bool attribute controls the power state of the nRF24L01. This is exposed for asynchronous applications and user preference.

False basically puts the nRF24L01 to sleep (AKA power down mode) with ultra-low current consumption. No transmissions are executed when sleeping, but the nRF24L01 can still be accessed through SPI. Upon instantiation, this driver class puts the nRF24L01 to sleep until the MCU invokes RX/TX transmissions. This driver class doesn’t power down the nRF24L01 after RX/TX transmissions are complete (avoiding the required power up/down 130 µs wait time), that preference is left to the user.
True powers up the nRF24L01. This is the first step towards entering RX/TX modes (see also listen attribute). Powering up is automatically handled by the listen attribute as well as the send() and write() functions.

Note

This attribute needs to be True if you want to put radio on Standby-II (highest current consumption) or Standby-I (moderate current consumption) modes. TX transmissions are only executed during Standby-II by calling send() or write(). RX transmissions are received during Standby-II by setting listen attribute to True (see Chapter 6.1.2-7 of the nRF24L01+ Specifications Sheet). After using send() or setting listen to False, the nRF24L01 is left in Standby-I mode (see also notes on the write() function).

RF24.arc¶

“This int attribute specifies the nRF24L01’s number of attempts to re-transmit TX payload when acknowledgment packet is not received. The nRF24L01 does not attempt to re-transmit if auto_ack attribute is disabled.

A valid input value must be in range [0,15]. Otherwise a ValueError exception is thrown. Default is set to 3.

RF24.ard¶

This int attribute specifies the nRF24L01’s delay (in µs) 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, this attribute is not applied.

A valid input value must be a multiple of 250 in range [250,4000]. Otherwise a ValueError exception is thrown. Default is 1500 for reliability.

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.

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)

Any invalid input throws a ValueError exception. Default is 0 dBm.

RF24.tx_full¶

An attribute to represent the nRF24L01’s status flag signaling that the TX FIFO buffer is full. (read-only)

Calling this does not execute an SPI transaction. It only exposes that latest data contained in the STATUS byte that’s always returned from any SPI transactions with the nRF24L01. Use the update() function to manually refresh this data when needed.

Returns:	`True` for TX FIFO buffer is full `False` for TX FIFO buffer is not full. This doesn’t mean the TX FIFO buffer is empty.

RF24.update()¶: This function is only used to get an updated status byte over SPI from the nRF24L01 and is exposed to the MCU for asynchronous applications. Refreshing the status byte is vital to checking status of the interrupts, RX pipe number related to current RX payload, and if the TX FIFO buffer is full. This function returns nothing, but internally updates the irq_DR, irq_DS, irq_DF, and tx_full attributes. Internally this is a helper function to pipe(), send(), and resend() functions

RF24.resend()¶: Use this function to maunally re-send the previously failed-to-transmit payload in the top level (first out) of the TX FIFO buffer.

Note

The nRF24L01 normally removes a payload from the TX FIFO buffer after successful transmission, but not when this function is called. The payload (successfully transmitted or not) will remain in the TX FIFO buffer until flush_tx() is called to remove them. Alternatively, using this function also allows the failed payload to be over-written by using send() or write() to load a new payload.

RF24.write(buf=None, ask_no_ack=False)¶

This non-blocking function (when used as alternative to send()) is meant for asynchronous applications and can only handle one payload at a time as it is a helper function to send().

Parameters:

buf (bytearray) –
The payload to transmit. This bytearray must have a length greater than 0 and less than 32 bytes, otherwise a ValueError exception is thrown.
- If the dynamic_payloads attribute is disabled and this bytearray’s length is less than the payload_length attribute, then this bytearray is padded with zeros until its length is equal to the payload_length attribute.
- If the dynamic_payloads attribute is disabled and this bytearray’s length is greater than payload_length attribute, then this bytearray’s length is truncated to equal the payload_length attribute.
ask_no_ack (bool) –
Pass this parameter as True to tell the nRF24L01 not to wait for an acknowledgment from the receiving nRF24L01. This parameter directly controls a NO_ACK flag in the transmission’s Packet Control Field (9 bits of information about the payload). Therefore, it takes advantage of an nRF24L01 feature specific to individual payloads, and its value is not saved anywhere. You do not need to specify this for every payload if the auto_ack attribute is disabled, however this parameter should work despite the auto_ack attribute’s setting.

Note

Each transmission is in the form of a packet. This packet contains sections of data around and including the payload. See Chapter 7.3 in the nRF24L01 Specifications Sheet for more details.

This function isn’t completely non-blocking as we still need to wait just under 5 ms for the CSN pin to settle (allowing a clean SPI transaction).

Note

The nRF24L01 doesn’t initiate sending until a mandatory minimum 10 µs pulse on the CE pin is acheived. That pulse is initiated before this function exits. However, we have left that 10 µs wait time to be managed by the MCU in cases of asychronous application, or it is managed by using send() instead of this function. If the CE pin remains HIGH for longer than 10 µs, then the nRF24L01 will continue to transmit all payloads found in the TX FIFO buffer.

Warning

A note paraphrased from the nRF24L01+ Specifications Sheet:

It is important to NEVER to keep the nRF24L01+ in TX mode for more than 4 ms at a time. If the [auto_ack and dynamic_payloads] features are enabled, nRF24L01+ is never in TX mode longer than 4 ms.

Tip

Use this function at your own risk. Because of the underlying “Enhanced ShockBurst Protocol”, disobeying the 4 ms rule is easily avoided if you enable the dynamic_payloads and auto_ack attributes. Alternatively, you MUST use interrupt flags or IRQ pin with user defined timer(s) to AVOID breaking the 4 ms rule. If the nRF24L01+ Specifications Sheet explicitly states this, we have to assume radio damage or misbehavior as a result of disobeying the 4 ms rule. See also table 18 in the nRF24L01 specification sheet for calculating necessary transmission time (these calculations are used in the send() function).

RF24.flush_rx()¶: A helper function to flush the nRF24L01’s internal RX FIFO buffer. (write-only)

Note

The nRF24L01 RX FIFO is 3 level stack that holds payload data. This means that there can be up to 3 received payloads (each of a maximum length equal to 32 bytes) waiting to be read (and popped from the stack) by recv() or read_ack(). This function clears all 3 levels.

RF24.flush_tx()¶: A helper function to flush the nRF24L01’s internal TX FIFO buffer. (write-only)

Note

The nRF24L01 TX FIFO is 3 level stack that holds payload data. This means that there can be up to 3 payloads (each of a maximum length equal to 32 bytes) waiting to be transmit by send(), resend() or write(). This function clears all 3 levels. It is worth noting that the payload data is only popped from the TX FIFO stack upon successful transmission (see also resend() as the handling of failed transmissions can be altered).

RF24.fifo(tx=False, empty=None)¶

This provides some precision determining the status of the TX/RX FIFO buffers. (read-only)

Parameters:

tx (bool) –
- True means information returned is about the TX FIFO buffer.
- False means information returned is about the RX FIFO buffer. This parameter defaults to False when not specified.
empty (bool) –
- True tests if the specified FIFO buffer is empty.
- False tests if the specified FIFO buffer is full.
- None (when not specified) returns a 2 bit number representing both empty (bit 1) & full (bit 0) tests related to the FIFO buffer specified using the tx parameter.

Returns:

A bool answer to the question: “Is the [TX/RX]:[True/False] FIFO buffer [empty/full]:[True/False]?
If the empty parameter is not specified: an int in range [0,2] for which:
- 1 means the specified FIFO buffer is full
- 2 means the specified FIFO buffer is empty
- 0 means the specified FIFO buffer is neither full nor empty

RF24.pipe()¶

This function returns information about the data pipe that received the next available payload in the RX FIFO buffer.

Returns:	`None` if there is no payload in RX FIFO. The `int` identifying pipe number [0,5] that received the next available payload in the RX FIFO buffer.