`radio-nrf24l01`¶

glasgow run radio-nrf24l01¶

Transmit and receive packets using the nRF24L01/nRF24L01+ RF PHY.

This applet allows configuring all channel and packet parameters, and provides basic transmit and receive workflow, as well as monitor mode. It supports Enhanced ShockBurst (new packet framing with automatic transaction handling) with one pipe, as well as ShockBurst (old packet framing). It does not support multiple pipes or acknowledgement payloads.

Note that in the CLI, the addresses are most significant byte first (the same as on-air order, and reversed with regards to register access order.)

The monitor subcommand is functionally identical to the receive subcommand, except that it will never attempt to acknowledge packets; this way, it is possible to watch a transaction started by a node with a known address without disturbing either party. It is not natively supported by nRF24L01(+), and is emulated in an imperfect way.

The pinout of a common 8-pin nRF24L01+ module is as follows (live bug view):

 GND @ * VCC
  CE * * CS
 SCK * * COPI
CIPO * * IRQ

usage: glasgow run radio-nrf24l01 [-h] [-V SPEC] [--ce PIN] [--cs PIN]
                                  [--sck PIN] [--copi PIN] [--cipo PIN]
                                  [--irq PIN] [-f FREQ] -c RF-CHANNEL
                                  -b RF-BANDWIDTH [-p RF-POWER] -A WIDTH
                                  -C WIDTH [-L] [-d]
                                  OPERATION ...

-h, --help¶: show this help message and exit

-V <spec>, --voltage <spec>¶: configure I/O port voltage to SPEC (e.g.: ‘3.3’, ‘A=5.0,B=3.3’, ‘A=SA’)

--ce <pin>¶: bind the applet I/O line ‘ce’ to PIN (default: ‘A0’, required)

--cs <pin>¶: bind the applet I/O line ‘cs’ to PIN (default: ‘A1’, required)

--sck <pin>¶: bind the applet I/O line ‘sck’ to PIN (default: ‘A2’, required)

--copi <pin>¶: bind the applet I/O line ‘copi’ to PIN (default: ‘A3’, required)

--cipo <pin>¶: bind the applet I/O line ‘cipo’ to PIN (default: ‘A4’, required)

--irq <pin>¶: bind the applet I/O line ‘irq’ to PIN (default: ‘A5’, optional)

-f <freq>, --frequency <freq>¶: set SCK frequency to FREQ kHz (default: 8000)

-c <rf-channel>, --channel <rf-channel>¶: set channel number to RF-CHANNEL (range: 0..125, corresponds to 2400..2525 MHz)

-b {250,1000,2000}, --bandwidth {250,1000,2000}¶: set air data rate to RF-BANDWIDTH kbps (one of: 250 1000 2000)

-p {0,-6,-12,-18}, --power {0,-6,-12,-18}¶: set output power to RF-POWER dBm (one of: 0 -6 -12 -18, default: 0)

-A {2,3,4,5}, --address-width {2,3,4,5}¶: set address width to WIDTH bytes (one of: 2 3 4 5)

-C {0,1,2}, --crc-width {0,1,2}¶: set CRC width to WIDTH bytes (one of: 0 1 2)

-L, --compat-framing¶: disable automatic transaction handling, for pre-L01 compatibility

-d, --dynamic-length¶: enable dynamic payload length (L01+ only)

glasgow run radio-nrf24l01 monitor¶

usage: glasgow run radio-nrf24l01 monitor [-h] [-l LENGTH] [-R] ADDRESS

address¶: receive packet with hex address ADDRESS

-h, --help¶: show this help message and exit

-l <length>, --length <length>¶: receive packet with length LENGTH (mutually exclusive with –dynamic-length)

-R, --repeat¶: keep receiving packets until interrupted

glasgow run radio-nrf24l01 receive¶

usage: glasgow run radio-nrf24l01 receive [-h] [-l LENGTH] [-R] ADDRESS

address¶: receive packet with hex address ADDRESS

-h, --help¶: show this help message and exit

-l <length>, --length <length>¶: receive packet with length LENGTH (mutually exclusive with –dynamic-length)

-R, --repeat¶: keep receiving packets until interrupted

glasgow run radio-nrf24l01 transmit¶

usage: glasgow run radio-nrf24l01 transmit [-h] [--transmit-timeout DELAY]
                                           [--retransmit-count COUNT] [-N]
                                           ADDRESS DATA

address¶: transmit packet with hex address ADDRESS

data¶: transmit DATA as packet payload

-h, --help¶: show this help message and exit

--transmit-timeout {250,500,750,1000,1250,1500,1750,2000,2250,2500,2750,3000,3250,3500,3750,4000}¶: if not acknowledged within DELAY µs, consider packet lost (default: 1500 us)

--retransmit-count {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}¶: if unacknowledged, retransmit up to COUNT times (default: 3)

-N, --no-ack¶: do not request acknowledgement (L01+ only)

API reference¶

exception glasgow.applet.radio.nrf24l01.RadioNRF24L01Error¶

class glasgow.applet.radio.nrf24l01.RadioNRF24L01Interface(logger: Logger, assembly: AbstractAssembly, *, cs: GlasgowPin, sck: GlasgowPin, copi: GlasgowPin, cipo: GlasgowPin, ce: GlasgowPin)¶

property clock: ClockDivisor¶: SCK clock divisor.

async read_register(address: int) → int¶: Read a single register at address.

async write_register(address: int, value: int)¶: Write value to a single register at address.

async read_register_wide(address: int, length: int) → bytes¶: Read length consecutive registers starting at address.

async write_register_wide(address: int, value: bytes)¶: Write value to consecutive registers starting at address.

async enable()¶: Transition to TX mode, RX mode, or Standby-II state by asserting CE.

async disable()¶: Transition to Standby-I state by deasserting CE.

async poll_rx_status(delay=0.010) → REG_STATUS¶

Poll for, and clear, the RX_DR IRQ.

The delay parameter sets the busy loop delay, in seconds.

Returns the status register before any bits have been cleared.

async read_rx_payload_length() → int¶: Retrieve payload length of the first packet in the RX FIFO.

async read_rx_payload(length: int) → bytes¶

Remove packet from the RX FIFO and return its payload.

The length parameter sets the payload length, and must be retrieved using read_rx_payload_length(). If the packet length is greater than 32, it was corrupted and must be discarded using flush_rx() instead.

async flush_rx()¶: Remove packet from the RX FIFO.

async flush_rx_all()¶: Remove all packets from the RX FIFO.

async poll_tx_status(delay=0.010) → REG_STATUS¶

Poll for the TX_DS or MAX_RT IRQs, and clear the TX_DS IRQ.

The delay parameter sets the busy loop delay, in seconds.

Returns the status register before any bits have been cleared. To find out whether the last transmitted packet has been removed from the TX FIFO, check the MAX_RT field of the returned value. If MAX_RT is set, payload has not been removed.

async write_tx_payload(payload: bytes, *, ack=True)¶: Insert packet with given payload into the TX FIFO, and request acknowledgement if ack is true.

async reuse_tx_payload()¶

Reuse last transmitted payload.

Payload may be reused after a packet was transmitted and until a subsequent write_tx_payload() or flush_tx() call.

async flush_tx()¶

Remove packet from the TX FIFO.

Use this method to clear a packet that has exceeded the maximum retransmission count.

async flush_tx_all()¶: Remove all packets from the TX FIFO.