Basic RF24 API¶
-
class circuitpython_nrf24l01.rf24.RF24(spi: busio.SPI, csn: digitalio.DigitalInOut, ce_pin: digitalio.DigitalInOut, spi_frequency=
10000000
)[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_pin : DigitalInOut¶
The digital output pin that is connected to the nRF24L01’s CE (Chip Enable) pin. This is required.
- spi_frequency=
10000000
¶ Specify which SPI frequency (in Hz) to use on the SPI bus. This parameter only applies to the instantiated
RF24
object and is made persistent viaSPIDevice
.
Changed in version 1.2.0:
new
spi_frequency
parameterremoved all keyword arguments in favor of using the provided corresponding attributes.
- RF24.open_tx_pipe(address: bytes | bytearray) None [source]¶
Open a data pipe for TX transmissions.
- Parameters
- address: bytes | bytearray¶
The virtual address of the receiving nRF24L01. The address specified here must match the address set to one of the RX data pipes of the receiving nRF24L01. The existing address can be altered by writing a bytearray with a length less than 5. The nRF24L01 will use the first
address_length
number of bytes for the RX address on the specified data pipe.
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 1) for receiving acknowledgement (ACK) packets in TX mode when the
auto_ack
attribute is enabled for data pipe 0. Thus, RX pipe 0 is appropriated with the TX address (specified here) whenauto_ack
is enabled for data pipe 0.
- RF24.close_rx_pipe(pipe_number: int) None [source]¶
Close a specific data pipe from RX transmissions.
- Parameters
- pipe_number: int¶
The data pipe to use for RX transactions. This must be in range [0, 5]. Otherwise a
IndexError
exception is thrown.
Changed in version 1.2.0: removed the
reset
parameter. Addresses assigned to pipes will persist until changed or power to the nRF24L01 is discontinued.
- RF24.open_rx_pipe(pipe_number: int, address: bytes | bytearray) None [source]¶
Open a specific data pipe for RX transmissions.
- Parameters
- pipe_number: int¶
The data pipe to use for RX transactions. This must be in range [0, 5]. Otherwise a
IndexError
exception is thrown.- address: bytes | bytearray¶
The virtual address to the receiving nRF24L01. 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. The existing address can be altered by writing a bytearray with a length less than 5. The nRF24L01 will use the firstaddress_length
number of bytes for the RX address on the specified data pipe.
Note
The nRF24L01 shares the addresses’ last 4 LSBytes on data pipes 2 through 5. These shared LSBytes are determined by the address set to data pipe 1.
- RF24.listen : bool¶
This attribute is the 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 if needed; usepower
attribute set toFalse
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, 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 mode (CE pin is LOW meaning low current & no transmissions) which is ideal for post-reception work. Disabling RX mode doesn’t flush the RX FIFO buffers, so remember to flush your 3-level FIFO buffers when appropriate usingflush_tx()
orflush_rx()
(see also theread()
function).
Note
When
ack
payloads are enabled, this attribute flushes the TX FIFO buffers upon exiting RX mode. However, this attribute does not flush the TX FIFO buffers when entering RX mode. This is done to better manage the ACK payloads loaded into the TX FIFO.Changed in version 2.1.0: Prior to v2.1.0 this attribute would clear the status flags when entering RX mode. This was removed to expedite applications that use manually transmitted acknowledgement payloads.
- RF24.any() int [source]¶
This function reports the next available payload’s length (in bytes).
- 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.
- RF24.available() bool [source]¶
A
bool
describing if there is a payload in the RX FIFO.This function is provided for convenience and is synonymous with the following statement:
# let `nrf` be the instantiated RF24 object nrf.update() and nrf.pipe is not None
New in version 2.0.0.
-
RF24.read(length: int | None =
None
) bytearray | None [source]¶ This function is used to retrieve data from the RX FIFO.
The
irq_dr
status flag is reset automatically. This function can also be used to fetch the last ACK packet’s payload ifack
is enabled.- Parameters
- length: int | None =
None
¶ An optional parameter to specify how many bytes to read from the RX FIFO buffer. This parameter is not constrained in any way.
If this parameter is less than the length of the first available payload in the RX FIFO buffer, then the payload will remain in the RX FIFO buffer until the entire payload is fetched by this function.
If this parameter is greater than the next available payload’s length, then additional data from other payload(s) in the RX FIFO buffer are returned.
Note
The nRF24L01 will repeatedly return the last byte fetched from the RX FIFO buffer when there is no data to return (even if the RX FIFO is empty). Be aware that a payload is only removed from the RX FIFO buffer when the entire payload has been fetched by this function. Notice that this function always starts reading data from the first byte of the first available payload (if any) in the RX FIFO buffer. Remember the RX FIFO buffer can hold up to 3 payloads at a maximum of 32 bytes each.
- length: int | None =
- Returns
If the
length
parameter is not specified, then this function returns abytearray
of the RX payload data orNone
if there is no payload. This also depends on the setting ofdynamic_payloads
&payload_length
attributes. Consider the following two scenarios:If the
dynamic_payloads
attribute is disabled, then the returned bytearray’s length is equal to the user definedpayload_length
attribute for the data pipe that received the payload.If the
dynamic_payloads
attribute is enabled, then the returned bytearray’s length is equal to the payload’s length
When the
length
parameter is specified, this function strictly returns abytearray
of that length despite the contents of the RX FIFO.
New in version 1.2.0:
length
parameterChanged in version 2.0.0: renamed this method from
recv()
toread()
because it isn’t doing any actual receiving. Rather, it is only reading data from the RX FIFO that was already received/validated by the radio.
-
RF24.send(buf: bytes | bytearray | Sequence[bytes | bytearray], ask_no_ack: bool =
False
, force_retry: int =0
, send_only: bool =False
) bool | bytearray | list[bool | bytearray] [source]¶ This blocking function is used to transmit payload(s).
- Returns
list
if a list or tuple of payloads was passed as thebuf
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. Transmission failure can only be detected ifauto_ack
is enabled for data pipe 0.True
if transmission succeeds.bytearray
orTrue
when theack
attribute isTrue
. Because the payload expects a responding custom ACK payload, the response is returned (upon successful transmission) as abytearray
(orTrue
if ACK payload is empty). Returning the ACK payload can be bypassed by setting thesend_only
parameter asTrue
.
- Parameters
- buf: bytes | bytearray | Sequence[bytes | bytearray]¶
The payload to transmit. This bytearray must have a length in range [1, 32], otherwise a
ValueError
exception is thrown when thedynamic_payloads
attribute is enabled. 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 for data pipe 0 and this bytearray’s length is less than the
payload_length
attribute for pipe 0, then this bytearray is padded with zeros until its length is equal to thepayload_length
attribute for pipe 0.
- If the
- If the
dynamic_payloads
attribute is disabled for data pipe 0 and this bytearray’s length is greater than
payload_length
attribute for pipe 0, then this bytearray’s length is truncated to equal thepayload_length
attribute for pipe 0.
- If the
- ask_no_ack: bool =
False
¶ Pass this parameter as
True
to tell the nRF24L01 not to wait for an acknowledgment from the receiving nRF24L01. This parameter directly controls aNO_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 theauto_ack
attribute is disabled (for data pipe 0), however setting this parameter toTrue
will work despite theauto_ack
attribute’s setting.Important
If the
allow_ask_no_ack
attribute is disabled (set toFalse
), then this parameter will have no affect at all. By default theallow_ask_no_ack
attribute is enabled.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.
- force_retry: int =
0
¶ The number of brute-force attempts to
resend()
a failed transmission. Default is 0. This parameter has no affect on transmissions ifauto_ack
is disabled or ifask_no_ack
parameter is set toTrue
. Each re-attempt still takes advantage of Auto-Retry feature. During multi-payload processing, this parameter is meant to slow down CircuitPython devices just enough for the Raspberry Pi to catch up (due to the Raspberry Pi’s seemingly slower SPI speeds).- send_only: bool =
False
¶ This parameter only applies when the
ack
attribute is set toTrue
. Pass this parameter asTrue
if the RX FIFO is not to be manipulated. Many other libraries’ behave as though this parameter isTrue
(e.g. The popular TMRh20 Arduino RF24 library). This parameter defaults toFalse
. If this parameter is set toTrue
, then useread()
to get the ACK payload (if there is any) from the RX FIFO. Remember that the RX FIFO can only hold up to 3 payloads at once.
Tip
It is highly recommended that
auto_ack
attribute is enabled when sending multiple payloads. Test results with theauto_ack
attribute disabled were rather poor (less than 79% received by a Raspberry Pi). This same advice applies to theask_no_ack
parameter (leave it asFalse
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()
andclear_status_flags()
. Therefore, this function will discard any payloads in the TX FIFO when called, but failed transmissions’ payloads will remain in the TX FIFO untilsend()
orflush_tx()
is called after failed transmissions.New in version 1.2.0:
send_only
parameter