RF24 API¶
-
pyrf24.RF24_DRIVER =
'SPIDEV'
¶ This
str
describes the backend driver used to build the pyrf24 package. If installed from PyPI, then this value should be"SPIDEV"
.All other drivers imply that the pyrf24 package was built from source Using a specific RF24 driver.
Hint
Use this attribute to determine programmatically which pin numbers to use. Drivers like
wiringPi
andMRAA
use their own pin numbering scheme.
Enum classes¶
- class pyrf24.rf24_crclength_e¶
Members:
- RF24_CRC_DISABLED
to disable using CRC checksums
- RF24_CRC_8
to use 8-bit checksums
- RF24_CRC_16
to use 16-bit checksums
- class pyrf24.rf24_datarate_e¶
Members:
- RF24_1MBPS
for 1 Mbps
- RF24_2MBPS
for 2 Mbps
- RF24_250KBPS
for 250 kbps
- class pyrf24.rf24_pa_dbm_e¶
Members:
- RF24_PA_MIN
nRF24L01 description
Si24R1 description when LNA enabled
Si24R1 description when LNA disabled
-18 dBm
6 dBm
-12 dBm
- RF24_PA_LOW
nRF24L01 description
Si24R1 description when LNA enabled
Si24R1 description when LNA disabled
-12 dBm
0 dBm
-4 dBm
- RF24_PA_HIGH
nRF24L01 description
Si24R1 description when LNA enabled
Si24R1 description when LNA disabled
-6 dBm
3 dBm
1 dBm
- RF24_PA_MAX
nRF24L01 description
Si24R1 description when LNA enabled
Si24R1 description when LNA disabled
0 dBm
7 dBm
4 dBm
- class pyrf24.rf24_fifo_state_e¶
Members:
- RF24_FIFO_OCCUPIED
The FIFO is not full nor empty, but it is occupied with 1 or 2 payloads.
- RF24_FIFO_EMPTY
The FIFO is empty.
- RF24_FIFO_FULL
The FIFO is full.
- RF24_FIFO_INVALID
Represents corruption of data over SPI (when observed).
- class pyrf24.rf24_irq_flags_e¶
Members:
- RF24_RX_DR
Represents an event where RX Data is Ready to
RF24.read()
.- RF24_TX_DS
Represents an event where TX Data Sent successfully.
- RF24_TX_DF
Represents an event where TX Data Failed to send.
- RF24_IRQ_ALL
Equivalent to
RF24_RX_DR | RF24_TX_DS | RF24_TX_DF
.- RF24_IRQ_NONE
An alias of
0
to describe no IRQ events enabled.
RF24 class¶
- class pyrf24.RF24¶
Basic RF24 API¶
-
__init__(ce_pin: int, csn_pin: int, spi_speed: int =
10000000
)¶ -
__init__(spi_speed: int =
10000000
) Create a RF24 object.
- Parameters:
If it is desirable to create a RF24 object in which the pin numbers are dynamically configured, the
ce_pin
andcsn_pin
parameters can be omitted.Important
If dynamically configuring the pin numbers, then they must be set using the overloaded
begin()
function.
- begin() bool ¶
- begin(ce_pin: int, csn_pin: int) bool
Initialize the radio’s hardware.
If configuring the radio’s CE & CSN pins dynamically, then the respective pin numbers must be passed to this function.
- listen¶
This
bool
attribute represents the radio’s primary mode (RX/TX).Hint
Be sure to call
open_rx_pipe()
before settinglisten
toTrue
.Do not call
write()
while in RX mode, without first settinglisten
toFalse
.Call
available()
to check for incoming traffic, and useread()
to get it.
Important
If there was a call to
open_rx_pipe()
about pipe 0 prior to setting this attribute toFalse
, then this attribute will re-write the address that was last set to RX pipe 0. This is becauseopen_tx_pipe()
will overwrite the address to RX pipe 0 for proper auto-ack functionality.Note
When the ACK payloads feature is enabled, the TX FIFO buffers are flushed when changing this attribute to
True
(RX mode). This is meant to discard any ACK payloads that were not appended to acknowledgment packets during TX mode.
-
stop_listening(tx_address: bytes | bytearray | int | None =
None
) None ¶ Stop listening for incoming messages, set the TX address, and switch to transmit mode.
Do this to set the TX address (and enter TX mode) before callingRF24.write()
¶radio.stop_listening(b"1Node") radio.write(data)
Warning
When the ACK payloads feature is enabled, the TX FIFO buffers are flushed when calling this function. This is meant to discard any ACK payloads that were not appended to acknowledgment packets.
- start_listening()¶
Start listening on the pipes opened for receiving. This function is equivalent to calling
radio.listen = True
.Hint
Be sure to call
open_rx_pipe()
before calling this function.Do not call
write()
while in RX mode, without first settinglisten
toFalse
(or callingRF24.stop_listening()
).Call
available()
to check for incoming traffic, and useread()
to get it.
Open reading pipe 1 using addressb"\xCC\xCE\xCC\xCE\xCC"
¶address = bytes([0xCC, 0xCE, 0xCC, 0xCE, 0xCC]) radio.open_rx_pipe(1, address) radio.start_listening() # or radio.listen = True
Note
If there was a call to
RF24.open_rx_pipe()
about pipe 0 prior to calling this function, then this function will re-write the address that was last set to reading pipe 0. This is becauseRF24.stop_listening()
(andRF24.open_tx_pipe()
) will overwrite the address to reading pipe 0 for proper auto-ack functionality.
- available() bool ¶
Check if there is an available payload in the radio’s RX FIFO.
See Also
Use
available_pipe()
to get the pipe number that received the next available payload.
- read(length: int) bytearray ¶
Fetch data from the radio’s RX FIFO.
- Parameters:
- length : int¶
The number of bytes to fetch from the radio’s RX FIFO. If this parameter is not specified, then the length of the next available payload is used. The maximum number of bytes that can be fetched at once is 32 bytes.
If the value specified by this parameter is less than the length of the next available payload, then the payload will remain in the RX FIFO.
If the value specified by this parameter is greater than the length of the next available payload, then the data from the next level of the RX FIFO is returned (if any).
If the value specified by this parameter is greater than the length of the last available payload, then the payload’s last byte is returned repeatedly until the length value is fulfilled.
- Returns:
A
bytearray
of the specifiedlength
containing the data from the payload in the RX FIFO.
-
write(buf: bytearray | bytes, multicast: bool =
False
) bool ¶ Transmit a single payload.
- Parameters:
- buf : bytes,bytearray¶
The payload to load into the TX FIFO.
- multicast : bool¶
Set this parameter to
True
to flag the payload for no acknowledgement. This parameter makes use of the radio’sNO_ACK
flag for the individual payload. Defaults toFalse
.Important
This parameter requires that the
enable_dynamic_ack()
function is called at least once prior to calling this function.
- Returns:
True
if the payload was successfully transmitted, otherwiseFalse
.
- open_tx_pipe(address: bytearray | bytes | int)¶
Open data pipe 0 for transmitting to a specified address.
Deprecated since version 0.5.0: Use
RF24.stop_listening()
instead.
Advanced RF24 API¶
- toggle_all_pipes(enable: bool)¶
Open or close all pipes with 1 SPI transaction. This does not alter the addresses assigned to the data pipes (using
open_rx_pipe()
oropen_tx_pipe()
).
- is_valid¶
This read-only attribute represents if the radio’s CE & CSN pins are configured properly.
- is_chip_connected¶
Check if the SPI bus is working with the radio. This read-only
bool
attribute assumes thatbegin()
returnedTrue
.
- is_plus_variant¶
This read-only
bool
attribute represents if the detected radio is a nRF24L01+ model.
- what_happened() tuple[bool, bool, bool] ¶
Call this function when the radio’s IRQ pin is active LOW.
Deprecated since version 0.5.0: Use
clear_status_flags()
instead.- Returns:
a 3-tuple of boolean values in which
index 0 represents a “data sent” event
index 1 represents a “data failed” event
index 2 represents a “data ready” event
Note
Calling this function also clears all status flags and resets the IRQ pin to inactive high.
See Also
- update() int ¶
Get an updated STATUS byte from the radio.
- Returns:
The STATUS byte fetched from the radio’s register. Use enumerations of
rf24_irq_flags_e
as masks to interpret the STATUS byte’s meaning(s).
-
set_status_flags(flags: int =
RF24_IRQ_NONE.value
) None ¶ Set which flags shall be reflected on the radio’s IRQ pin (when active LOW).
Note
This function is similar to
mask_irq()
but with less confusing parameters.- Parameters:
- flags: int =
RF24_IRQ_NONE.value
¶ A value of
rf24_irq_flags_e
to influence the radio’s IRQ pin. The default value (RF24_IRQ_NONE
) will disable the radio’s IRQ pin. Multiple events can be enabled by OR-ingrf24_irq_flags_e
values together.radio.set_status_flags(int(RF24_IRQ_ALL)) # is equivalent to radio.set_status_flags( int(RF24_RX_DR) | int(RF24_TX_DS) | int(RF24_TX_DF) )
- flags: int =
- get_status_flags() int ¶
Get the latest STATUS byte returned from the last SPI transaction.
Note
This does not actually perform any SPI transaction with the radio. Use
RF24.update()
instead to get a fresh copy of the Status flags at the slight cost of performance.- Returns:
The STATUS byte from the radio’s register as the latest SPI transaction. Use enumerations of
rf24_irq_flags_e
as masks to interpret the STATUS byte’s meaning(s).
-
clear_status_flags(flags: int =
RF24_IRQ_ALL.value
) int ¶ Clear the Status flags that caused an interrupt event.
Note
This function is similar to
what_happened()
because it also returns the status flags that caused the interrupt event. However, this function takes a 1-byte integer instead of bit-banging each flag into 3 1-byte booleans.Caution
When used in an ISR (Interrupt Service routine), there is a chance that the returned bits
0b1110
(RX pipe number) is inaccurate. See the datasheet for more detail.- Parameters:
- flags: int =
RF24_IRQ_ALL.value
¶ The IRQ flags to clear. Default value is all of them (
RF24_IRQ_ALL
). Multiple flags can be cleared by OR-ingrf24_irq_flags_e
values together.radio.clear_status_flags() # is equivalent to radio.clear_status_flags(int(RF24_IRQ_ALL)) # is equivalent to radio.clear_status_flags( int(RF24_RX_DR) | int(RF24_TX_DS) | int(RF24_TX_DF) )
- flags: int =
- Returns:
The STATUS byte from the radio’s register before it was modified. Use enumerations of
rf24_irq_flags_e
as masks to interpret the STATUS byte’s meaning(s).
- ce_pin(level: bool) None ¶
Set radio’s CE (Chip Enable) pin state.
Warning
Please see the datasheet for a much more detailed description of this pin.
Note
This is only publicly exposed for advanced use cases such as complex networking or streaming consecutive payloads without robust error handling. Typical uses are satisfied by simply using
RF24.start_listening()
for RX mode orRF24.stop_listening()
andRF24.write()
for TX mode.
Debugging Helpers¶
- failure_detected¶
The number of accumulative transmission failures specific to the life cycle of the
RF24
object.
- print_status(flags: int) None ¶
A convenient function to display the meaning of the STATUS byte returned from
RF24.get_status_flags()
,RF24.update()
, orRF24.clear_status_flags()
.
- print_details()¶
Print out details about the radio’s configuration.
- print_pretty_details()¶
Print out details about the radio’s configuration. This function differs from
print_details()
as the output for this function is more human-friendly/readable.
- sprintf_pretty_details() str ¶
Put details about the radio’s configuration into a string. This function differs from
print_pretty_details()
as it does not use stdout output stream.- Returns:
A string that describes the radio’s details.
- get_arc() int ¶
Returns automatic retransmission count (ARC_CNT)
Value resets with each new transmission. Allows roughly estimating signal strength.
- Returns:
Returned values range from 0 to 15.
Advanced Transmission¶
- write_ack_payload(pipe: int, buf: bytearray | bytes) bool ¶
Load a payload into the TX FIFO to be used in the ACK packet of automatic acknowledgements.
-
write_fast(buf: bytearray | bytes, multicast: bool =
False
) bool ¶ Simply load a payload into the radio’s TX FIFO and assert the radio’s CE pin to activate transmission.
See Also
Use
tx_standby()
to ensure the radio has had time to transmit the payload(s) from the TX FIFO.- Parameters:
- buf : bytes,bytearray¶
The payload to load into the TX FIFO.
- multicast : bool¶
Set this parameter to
True
to flag the payload for no acknowledgement. This parameter makes use of the radio’sNO_ACK
flag for the individual payload. Defaults toFalse
.Important
This parameter requires that the
enable_dynamic_ack()
function is called at least once prior to calling this function.
- Returns:
True
if the payload was loaded into the radio’s TX FIFO, otherwiseFalse
.
- reuse_tx()¶
Re-use the 1st level of the radio’s TX FIFO.
- write_blocking(buf: bytearray | bytes, timeout: int) bool ¶
A blocking function to load a payload into the radio’s TX FIFO. If there is no un-occupied level of the TX FIFO, this function waits until a level becomes available or the specified timeout is reached.
-
start_fast_write(buf: bytearray | bytes, multicast: bool =
False
, start_tx: bool =True
) None ¶ Write a payload to the radio’s TX FIFO.
See Also
Use
tx_standby()
to ensure the radio has had time to transmit the payload(s) from the TX FIFO.- Parameters:
- buf : bytes,bytearray¶
The payload to load into the TX FIFO.
- multicast : bool¶
Set this parameter to
True
to flag the payload for no acknowledgement. This parameter makes use of the radio’sNO_ACK
flag for the individual payload. Defaults toFalse
.Important
This parameter requires that the
enable_dynamic_ack()
function is called at least once prior to calling this function.- start_tx : bool¶
Set this parameter to
True
to activate transmission. By default this parameter is set toTrue
. Notice this parameter controls the radio’s CE pin as required. Setting this parameter toFalse
will only leave the radio’s CE pin unchanged.
-
start_write(buf: bytearray | bytes, multicast: bool =
False
) bool ¶ For backward compatibility, this function is similar to
start_fast_write()
.- Parameters:
- buf : bytes,bytearray¶
The payload to load into the TX FIFO.
- multicast : bool¶
Set this parameter to
True
to flag the payload for no acknowledgement. This parameter makes use of the radio’sNO_ACK
flag for the individual payload. Defaults toFalse
.Important
This parameter requires that the
enable_dynamic_ack()
function is called at least once prior to calling this function.
- Returns:
True
if the payload was loaded into the radio’s TX FIFO, otherwiseFalse
.
- tx_standby() bool ¶
-
tx_standby(timeout: int, start_tx: bool =
True
) bool When using
write_fast()
to fill the radio’s TX FIFO, call this blocking function to allow the radio time to transmit.The default timeout value is 95 milliseconds. Any failed transmissions will be re-attempted until successfully transmitted or timeout occurs.
Optionally, a timeout value can be supplied to augment how long the function will block during transmission.
Power Management¶
- power¶
This
bool
attribute represents the radio’s power status.False
means the radio is powered down.
FIFO Management¶
- flush_tx()¶
Flush all 3 levels of the radio’s TX FIFO.
- flush_rx()¶
Flush all 3 levels of the radio’s RX FIFO.
- is_fifo(about_tx: bool, check_empty: bool) bool ¶
- is_fifo(about_tx: bool) rf24_fifo_state_e
Get information about a specified FIFO buffers.
- Parameters:
- about_tx : bool¶
Ensure the returned data is about the TX FIFO. Set this to
False
to make returned data describe the RX FIFO.- check_empty : bool¶
Check if the specified FIFO is empty. Set this to
False
to check if the specified FIFO is full.Deprecated since version 0.4.4: Use
is_fifo(about_tx: bool)
for better precision.The
is_fifo(about_tx: bool, check_empty: bool)
signature may yield inaccurate information when data suffers corruption over the SPI bus’ MISO line.
- Returns:
A
bool
describing if the specified FIFO is empty or full if thecheck_empty
parameter was specified.An enumeration of
rf24_fifo_state_e
describing the specifed FIFO’s state if thecheck_empty
parameter was unspecified.
Ambiguous Signal Detection¶
- rpd¶
This read-only
bool
attribute represents if the radio detected a signal above -64 dbm in RX mode.Hint
RPD stands for “Received Power Detection”. Non-plus variants of nRF24L01 call this attribute CD (short for “Carrier Detection”) because this feature was originally made available for government mandated hardware tests.
- start_const_carrier(level: rf24_pa_dbm_e, channel: int)¶
Start a constant carrier wave. This is used (in conjunction with
rpd
) to test the radio’s hardware.- Parameters:
- level : rf24_pa_dbm_e¶
The value used to configure Power Amplitude level. Accepted values are pre-defined in the
rf24_pa_dbm_e
enum struct.- channel : int¶
The channel to broadcast on.
- stop_const_carrier()¶
End transmitting a constant carrier wave. This function also sets the
power
toFalse
as recommended by the datasheet.
- available_pipe() tuple[bool, int] ¶
Similar to
available()
, but additionally returns the pipe number that received the next available payload.- Returns:
A 2-tuple in which
Configurable RF24 API¶
- address_width¶
This
int
attribute represents length of addresses used on the radio’s data pipes. Accepted values range [2, 5].Warning
Using an address width of 2 bytes is not officially supported by the nRF24L01. This ability is exposed for advanced reverse engineering purposes.
- set_retries(delay: int, count: int)¶
Configure the radio’s auto-retries feature.
- Parameters:
- delay : int¶
A number in the range [0, 15] used as a multiple of 250. This controls the amount of time (in microseconds) the radio waits for an auto-acknowledgment.
- count : int¶
A number in range [0, 15]. This is the amount of automatic retries that the radio attempts when an automatic acknowledgment is not received.
- mask_irq(tx_ok: bool, tx_fail: bool, rx_ready: bool)¶
Configure the radio’s IRQ pin to go active on certain events.
Deprecated since version 0.5.0: Use
set_status_flags()
instead.Important
The IRQ pin is only active when LOW.
- Parameters:
- tx_ok : bool¶
True
ignores the “data sent” event,False
reflects the “data sent” event on the IRQ pin.- tx_fail : bool¶
True
ignores the “data failed” event,False
reflects the “data failed” event on the IRQ pin.- rx_ready : bool¶
True
ignores the “data ready” event,False
reflects the “data ready” event on the IRQ pin.
Channel (Frequency)¶
- channel¶
This
int
attribute represents the radio’s configured channel (AKA frequency). This roughly translates to frequency (in Hz). So, channel 76 (the default setting) is2400 MHz + 76 = 2.4076 GHz
Dynamic Delays¶
- tx_delay¶
The driver will delay for this duration (
int
in microseconds) whenlisten
is set toFalse
.When responding to payloads, faster devices like ARM(RPi) are much faster than Arduino:
Arduino sends data to RPi, switches to RX mode
The RPi receives the data, switches to TX mode and sends before the Arduino radio is in RX mode
If AutoACK is disabled, this can be set as low as 0. If AutoACK enabled, set to 100uS minimum on RPi
Payload Sizes¶
- payload_size¶
This
int
attribute represents the radio’s static payload lengths. Maximum length is 32 bytes; minimum is 1 byte.Note
This attribute is only used when the radio’s
dynamic_payloads
feature is disabled (which is disabled by default).
- dynamic_payloads¶
This
bool
attribute represents the radio’s dynamic payload length feature for all data pipes.Note
Since
ack_payloads
requires Dynamic Payload lengths,ack_payloads
are also disabled when setting this attribute is set toFalse
.
- get_dynamic_payload_size() int ¶
Get the Dynamic Payload Size of the next available payload in the radio’s RX FIFO.
Auto-Acknowledgement¶
- set_auto_ack(enable: bool)¶
- set_auto_ack(pipe_number: int, enable: bool) None
Configure the radio’s automatic acknowledgement feature for all data pipes or a specific data pipe.
- ack_payloads¶
This
bool
attribute represents the status of the radio’s acknowledgement payload feature for appending data to automatic acknowledgement packets.Important
To use acknowledgement payloads, the
dynamic_payloads
and auto-ack features must be enabled.This attribute does not automatically enable the auto-ack feature on pipe 0 because the auto-ack feature is enabled for all pipes by default.
See Also
Review
write_ack_payload()
andset_auto_ack()
. Useavailable()
andread()
to fetch a received acknowledgement payload.
- enable_dynamic_ack()¶
Enable the radio’s Dynamic Ack feature.
By default the multicast parameter to
write()
is ineffective unless this function is called. This design decision was made for compatibility with the cheap chinese Si24R1 clones.
Radiation Options¶
-
set_pa_level(level: rf24_pa_dbm_e, lna_enable: bool =
True
)¶ Configure the radio’s Power Amplitude Level.
- Parameters:
- level : rf24_pa_dbm_e¶
The value used to configure Power Amplitude level. Accepted values are pre-defined in the
rf24_pa_dbm_e
enum struct.- lna_enable : bool¶
This parameter configures the LNA (Low Noise Amplifier) feature of the radio. This feature can only be configured on non-plus models of the nRF24L01 (or the Si24R1 clone).
- pa_level¶
This attribute represents the radio’s configured Power Amplitude level.
See Also
Accepted values are defined in the
rf24_pa_dbm_e
enum struct.
- data_rate¶
This attribute represents the radio’s OTA data rate.
Hint
The units “BPS” stand for “Bits Per Second” (not Bytes per second).
See Also
Accepted values are pre-defined in the
rf24_datarate_e
enum struct.
-
set_radiation(level: rf24_pa_dbm_e, speed: rf24_datarate_e, lna_enable: bool =
True
)¶ Configure the RF_SETUP register in 1 SPI transaction.
- Parameters:
- level : rf24_pa_dbm_e¶
The desired Power Amplitude level. Options are defined in the
rf24_pa_dbm_e
enum.- speed : rf24_datarate_e¶
The desired RF data rate. Options are defined in the
rf24_datarate_e
enum.- lna_enable : bool¶
A toggle for radio’s that support controlling the Low Noise Amplifier feature. This is always enabled by default and when not specified.
See Also
CRC Lengths¶
- crc_length¶
This attribute represents the radio’s CRC checksum length (in bits).
See Also
Accepted values are predefined in the
rf24_crclength_e
enum struct.Note
The radio automatically uses CRC checksums when the auto-ack feature is enabled. This attribute may not reflect this situation if CRC is disabled when auto-ack is enabled.
-
__init__(ce_pin: int, csn_pin: int, spi_speed: int =