Author(s): Jerry Needell
- class adafruit_rfm.rfm_common.RFMSPI(spi: SPI, cs_pin: DigitalInOut, baudrate: int = 5000000, polarity: int = 0, phase: int = 0)
Base class for SPI type devices
- ack_delay: float
The delay time before attemting to send an ACK. If ACKs are being missed try setting this to .1 or .2.
- ack_retries
The number of ACK retries before reporting a failure.
- ack_wait
The delay time before attempting a retry after not receiving an ACK
- async asyncio_receive(*, keep_listening: bool = True, with_header: bool = False, timeout: float | None = None) bytearray | None
Wait to receive a packet from the receiver. If a packet is found the payload bytes are returned, otherwise None is returned (which indicates the timeout elapsed with no reception). If keep_listening is True (the default) the chip will immediately enter listening mode after reception of a packet, otherwise it will fall back to idle mode and ignore any future reception. Packets may have a 4-byte header for compatibility with the RadioHead library. The header consists of 4 bytes (To,From,ID,Flags). The default setting will strip the header before returning the packet to the caller. If with_header is True then the 4 byte header will be returned with the packet. The payload then begins at packet[4].
- async asyncio_receive_with_ack(*, keep_listening: bool = True, with_header: bool = False, timeout: float | None = None) bytearray | None
Wait to receive a RadioHead packet from the receiver then send an ACK packet in response. AKA Reliable Datagram mode. If a packet is found the payload bytes are returned, otherwise None is returned (which indicates the timeout elapsed with no reception). If keep_listening is True (the default) the chip will immediately enter listening mode after receipt of a packet, otherwise it will fall back to idle mode and ignore any incomming packets until it is called again. All packets must have a 4-byte header for compatibility with the RadioHead library. The header consists of 4 bytes (To,From,ID,Flags). The default setting will strip the header before returning the packet to the caller. If with_header is True then the 4 byte header will be returned with the packet. The payload then begins at packet[4].
- async asyncio_send(data: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray, *, keep_listening: bool = False, destination: int | None = None, node: int | None = None, identifier: int | None = None, flags: int | None = None) bool
Send a string of data using the transmitter. You can only send 252 bytes at a time (limited by chip’s FIFO size and appended headers). if the propert radiohead is True then this appends a 4 byte header to be compatible with the RadioHead library. The header defaults to using the initialized attributes: (destination,node,identifier,flags) It may be temporarily overidden via the kwargs - destination,node,identifier,flags. Values passed via kwargs do not alter the attribute settings. The keep_listening argument should be set to True if you want to start listening automatically after the packet is sent. The default setting is False.
Returns: True if success or False if the send timed out.
- async asyncio_send_with_ack(data: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray) bool
Reliable Datagram mode: Send a packet with data and wait for an ACK response. The packet header is automatically generated. If enabled, the packet transmission will be retried on failure
- destination
The default destination address for packet transmissions. (0-255). If 255 (0xff) then any receiving node should accept the packet. Second byte of the RadioHead header.
- flags
Upper 4 bits reserved for use by Reliable Datagram Mode. Lower 4 bits may be used to pass information. Fourth byte of the RadioHead header.
- identifier
Automatically set to the sequence number when send_with_ack() used. Third byte of the RadioHead header.
- last_rssi
The RSSI of the last received packet. Stored when the packet was received. The instantaneous RSSI value may not be accurate once the operating mode has been changed.
- last_snr
The SNR of the last received packet. Stored when the packet was received. The instantaneous SNR value may not be accurate once the operating mode has been changed.
- node
The default address of this Node. (0-255). If not 255 (0xff) then only packets address to this node will be accepted. First byte of the RadioHead header.
- radiohead
Enable RadioHead compatibility
- read_into(address: int, buf: array | bytearray | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray, length: int | None = None) None
Read a number of bytes from the specified address into the provided buffer. If length is not specified (the default) the entire buffer will be filled.
- receive(*args, **kwargs)
Non-asyncio wrapper to Receive a packet using the same arguments and keywords as asyncio_receive()
- receive_timeout
The amount of time to poll for a received packet. If no packet is received, the returned packet will be None
- receive_with_ack(*args, **kwargs)
Non-asyncio wrapper to Receive a packet using the same arguments and keywords as asyncio_receive_with_ack()
- send(*args, **kwargs)
Non-asyncio wrapper to Send a string of data using the transmitter using the same arguments and keywords as asyncio_send()
- send_with_ack(*args, **kwargs)
Non-asyncio wrapper to Send a string of data using the transmitter using the same arguments and keywords as asyncio_send_with_ack()
- write_from(address: int, buf: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray, length: int | None = None) None
Write a number of bytes to the provided address and taken from the provided buffer. If no length is specified (the default) the entire buffer is written.
- write_u8(address: int, val: int) None
Write a byte register to the chip. Specify the 7-bit address and the 8-bit value to write to that address.
- xmit_timeout
The amount of time to wait for the HW to transmit the packet. This is mainly used to prevent a hang due to a HW issue
- async adafruit_rfm.rfm_common.asyncio_check_timeout(flag: Callable, limit: float, timeout_poll: float) bool
test for timeout waiting for specified flag
- adafruit_rfm.rfm_common.asyncio_to_blocking(function)
run async function as normal blocking function
- adafruit_rfm.rfm_common.ticks_diff(ticks1: int, ticks2: int) int
Compute the signed difference between two ticks values assuming that they are within 2**28 ticks
adafruit_rfm.rfm69
CircuitPython RFM69 packet radio module. This supports sending and receiving of packets with RFM69 series radios (433/915Mhz).
Warning
This is NOT for LoRa radios!
Note
This is a ‘best effort’ at receiving data using pure Python code. You might lose packets if they’re sent too quickly for the board to process them.
Author(s): Jerry Needell
- class adafruit_rfm.rfm69.RFM69(spi: SPI, cs: DigitalInOut, rst: DigitalInOut, frequency: int, *, sync_word: bytes = b'-\xd4', preamble_length: int = 4, encryption_key: bytes | None = None, high_power: bool = True, baudrate: int = 2000000, crc: bool = True)
Interface to a RFM69 series packet radio. Allows simple sending and receiving of wireless data at supported frequencies of the radio (433/915mhz).
- Parameters:
spi (busio.SPI) – The SPI bus connected to the chip. Ensure SCK, MOSI, and MISO are connected.
cs (DigitalInOut) – A DigitalInOut object connected to the chip’s CS/chip select line.
reset (DigitalInOut) – A DigitalInOut object connected to the chip’s RST/reset line.
frequency (int) – The center frequency to configure for radio transmission and reception. Must be a frequency supported by your hardware (i.e. either 433 or 915mhz).
sync_word (bytes) – A byte string up to 8 bytes long which represents the syncronization word used by received and transmitted packets. Read the datasheet for a full understanding of this value! However by default the library will set a value that matches the RadioHead Arduino library.
preamble_length (int) – The number of bytes to pre-pend to a data packet as a preamble. This is by default 4 to match the RadioHead library.
encryption_key (bytes) – A 16 byte long string that represents the AES encryption key to use when encrypting and decrypting packets. Both the transmitter and receiver MUST have the same key value! By default no encryption key is set or used.
high_power (bool) – Indicate if the chip is a high power variant that supports boosted transmission power. The default is True as it supports the common RFM69HCW modules sold by Adafruit.
Remember this library makes a best effort at receiving packets with pure Python code. Trying to receive packets too quickly will result in lost data so limit yourself to simple scenarios of sending and receiving single packets at a time.
Also note this library defaults to be compatible with RadioHead Arduino library communication. This means the library sets up the radio modulation to match RadioHead’s default of GFSK encoding, 250kbit/s bitrate, and 250khz frequency deviation. To change this requires explicitly setting the radio’s bitrate and encoding register bits. Read the datasheet and study the init function to see an example of this–advanced users only! Advanced RadioHead features like address/node specific packets or “reliable datagram” delivery are supported however due to the limitations noted, “reliable datagram” is still subject to missed packets.
- property bitrate: float
The modulation bitrate in bits/second (or chip rate if Manchester encoding is enabled). Can be a value from ~489 to 32mbit/s, but see the datasheet for the exact supported values.
- property enable_address_filter: bool
Set to True to enable address filtering. Incoming packets that do no match the node address or broadcast address will be ignored.
- property enable_crc: bool
Set to True to enable hardware CRC checking of incoming packets. Incoming packets that fail the CRC check are not processed. Set to False to disable CRC checking and process all incoming packets.
- property encryption_key: bytearray
The AES encryption key used to encrypt and decrypt packets by the chip. This can be set to None to disable encryption (the default), otherwise it must be a 16 byte long byte string which defines the key (both the transmitter and receiver must use the same key value).
- fill_fifo(payload: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray) None
Write the payload to the FIFO.
- property frequency_mhz: float
The frequency of the radio in Megahertz. Only the allowed values for your radio must be specified (i.e. 433 vs. 915 mhz)!
- listen() None
Listen for packets to be received by the chip. Use
receive()to listen, wait and retrieve packets as they’re available.
- property operation_mode: int
The operation mode value. Unless you’re manually controlling the chip you shouldn’t change the operation_mode with this property as other side-effects are required for changing logical modes–use
idle(),sleep(),transmit(),listen()instead to signal intent for explicit logical modes.
- property preamble_length: int
The length of the preamble for sent and received packets, an unsigned 16-bit value. Received packets must match this length or they are ignored! Set to 4 to match the RadioHead RFM69 library.
- property rssi: float
The received strength indicator (in dBm). May be inaccuate if not read immediatey. last_rssi contains the value read immediately receipt of the last packet.
- property sync_word: bytearray
The synchronization word value. This is a byte string up to 8 bytes long (64 bits) which indicates the synchronization word for transmitted and received packets. Any received packet which does not include this sync word will be ignored. The default value is 0x2D, 0xD4 which matches the RadioHead RFM69 library. Setting a value of None will disable synchronization word matching entirely.
- property temperature: float
The internal temperature of the chip in degrees Celsius. Be warned this is not calibrated or very accurate.
Warning
Reading this will STOP any receiving/sending that might be happening!
adafruit_rfm.rfm9x
CircuitPython module for the RFM95/6/7/8 LoRa 433/915mhz radio modules.
Author(s): Jerry Needell
- class adafruit_rfm.rfm9x.RFM9x(spi: SPI, cs: DigitalInOut, rst: DigitalInOut, frequency: int, *, preamble_length: int = 8, high_power: bool = True, baudrate: int = 5000000, agc: bool = False, crc: bool = True)
Interface to a RFM95/6/7/8 LoRa radio module. Allows sending and receiving bytes of data in long range LoRa mode at a support board frequency (433/915mhz).
You must specify the following parameters: - spi: The SPI bus connected to the radio. - cs: The CS pin DigitalInOut connected to the radio. - reset: The reset/RST pin DigialInOut connected to the radio. - frequency: The frequency (in mhz) of the radio module (433/915mhz typically).
You can optionally specify: - preamble_length: The length in bytes of the packet preamble (default 8). - high_power: Boolean to indicate a high power board (RFM95, etc.). Default is True for high power. - baudrate: Baud rate of the SPI connection, default is 5mhz but you might choose to lower to 1mhz if using long wires or a breadboard. - agc: Boolean to Enable/Disable Automatic Gain Control - Default=False (AGC off) - crc: Boolean to Enable/Disable Cyclic Redundancy Check - Default=True (CRC Enabled) Remember this library makes a best effort at receiving packets with pure Python code. Trying to receive packets too quickly will result in lost data so limit yourself to simple scenarios of sending and receiving single packets at a time.
Also note this library tries to be compatible with raw RadioHead Arduino library communication. This means the library sets up the radio modulation to match RadioHead’s defaults. Advanced RadioHead features like address/node specific packets or “reliable datagram” delivery are supported however due to the limitations noted, “reliable datagram” is still subject to missed packets.
- auto_agc
Automatic Gain Control state
- property coding_rate: Literal[5, 6, 7, 8]
The coding rate used by the radio to control forward error correction (try setting to a higher value to increase tolerance of short bursts of interference or to a lower value to increase bit rate). Valid values are limited to 5, 6, 7, or 8.
- fill_fifo(payload: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray) None
len_data is not used but is here for compatibility with rfm69 Fill the FIFO with a packet to send
- property frequency_mhz: Literal[433.0, 915.0]
The frequency of the radio in Megahertz. Only the allowed values for your radio must be specified (i.e. 433 vs. 915 mhz)!
- listen() None
Listen for packets to be received by the chip. Use
receive()to listen, wait and retrieve packets as they’re available.
- property preamble_length: int
The length of the preamble for sent and received packets, an unsigned 16-bit value. Received packets must match this length or they are ignored! Set to 8 to match the RadioHead RFM95 library.
- property signal_bandwidth: int
The signal bandwidth used by the radio (try setting to a higher value to increase throughput or to a lower value to increase the likelihood of successfully received payloads). Valid values are listed in RFM9x.bw_bins.
- property spreading_factor: Literal[6, 7, 8, 9, 10, 11, 12]
The spreading factor used by the radio (try setting to a higher value to increase the receiver’s ability to distinguish signal from noise or to a lower value to increase the data transmission rate). Valid values are limited to 6, 7, 8, 9, 10, 11, or 12.
- transmit() None
Transmit a packet which is queued in the FIFO. This is a low level function for entering transmit mode and more. For generating and transmitting a packet of data use
send()instead.
- property tx_power: int
The transmit power in dBm. Can be set to a value from 5 to 23 for high power devices (RFM95/96/97/98, high_power=True) or -1 to 14 for low power devices. Only integer power levels are actually set (i.e. 12.5 will result in a value of 12 dBm). The actual maximum setting for high_power=True is 20dBm but for values > 20 the PA_BOOST will be enabled resulting in an additional gain of 3dBm. The actual setting is reduced by 3dBm. The reported value will reflect the reduced setting.
adafruit_rfm.rfm9xfsk
CircuitPython module for the RFM95/6/7/8 FSK 433/915mhz radio modules.
Author(s): Jerry Needell
- class adafruit_rfm.rfm9xfsk.RFM9xFSK(spi: SPI, cs: DigitalInOut, rst: DigitalInOut, frequency: int, *, sync_word: bytes = b'-\xd4', preamble_length: int = 4, high_power: bool = True, baudrate: int = 5000000, crc: bool = True)
Interface to a RFM95/6/7/8 FSK radio module. Allows sending and receiving bytes of data in FSK mode at a support board frequency (433/915mhz).
- Parameters:
spi (busio.SPI) – The SPI bus connected to the chip. Ensure SCK, MOSI, and MISO are connected.
cs (DigitalInOut) – A DigitalInOut object connected to the chip’s CS/chip select line.
reset (DigitalInOut) – A DigitalInOut object connected to the chip’s RST/reset line.
frequency (int) – The center frequency to configure for radio transmission and reception. Must be a frequency supported by your hardware (i.e. either 433 or 915mhz).
sync_word (bytes) – A byte string up to 8 bytes long which represents the syncronization word used by received and transmitted packets. Read the datasheet for a full understanding of this value! However by default the library will set a value that matches the RadioHead Arduino library.
preamble_length (int) – The number of bytes to pre-pend to a data packet as a preamble. This is by default 4 to match the RadioHead library.
high_power (bool) – Indicate if the chip is a high power variant that supports boosted transmission power. The default is True as it supports the common RFM69HCW modules sold by Adafruit.
Also note this library tries to be compatible with raw RadioHead Arduino library communication. This means the library sets up the radio modulation to match RadioHead’s defaults. Advanced RadioHead features like address/node specific packets or “reliable datagram” delivery are supported however due to the limitations noted, “reliable datagram” is still subject to missed packets.
- property bitrate: float
The modulation bitrate in bits/second (or chip rate if Manchester encoding is enabled). Can be a value from ~489 to 32mbit/s, but see the datasheet for the exact supported values.
- property enable_address_filter: bool
Set to True to enable address filtering. Incoming packets that do no match the node address or broadcast address will be ignored.
- fill_fifo(payload: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray) None
Write the payload to the FIFO.
- property frequency_mhz: Literal[433.0, 915.0]
The frequency of the radio in Megahertz. Only the allowed values for your radio must be specified (i.e. 433 vs. 915 mhz)!
- listen() None
Listen for packets to be received by the chip. Use
receive()to listen, wait and retrieve packets as they’re available.
- property preamble_length: int
The length of the preamble for sent and received packets, an unsigned 16-bit value. Received packets must match this length or they are ignored! Set to 4 to match the RF69.
- property sync_word: bytearray
The synchronization word value. This is a byte string up to 8 bytes long (64 bits) which indicates the synchronization word for transmitted and received packets. Any received packet which does not include this sync word will be ignored. The default value is 0x2D, 0xD4 which matches the RadioHead RFM69 library. Setting a value of None will disable synchronization word matching entirely.
- property temperature: float
The internal temperature of the chip.. See Sec 5.5.7 of the DataSheet calibrated or very accurate.
- transmit() None
Transmit a packet which is queued in the FIFO. This is a low level function for entering transmit mode and more. For generating and transmitting a packet of data use
send()instead.
- property tx_power: int
The transmit power in dBm. Can be set to a value from 5 to 23 for high power devices (RFM95/96/97/98, high_power=True) or -1 to 14 for low power devices. Only integer power levels are actually set (i.e. 12.5 will result in a value of 12 dBm). The actual maximum setting for high_power=True is 20dBm but for values > 20 the PA_BOOST will be enabled resulting in an additional gain of 3dBm. The actual setting is reduced by 3dBm. The reported value will reflect the reduced setting.