LoRa Driver API

Header: main/lora_rylr.h

Drives RYLR-series LoRa modules over UART using AT commands. Handles command/response flow and async +RCV receive notifications.

In QEMU mode (CONFIG_QEMU_TEST_MODE), all UART operations are replaced with FreeRTOS queue loopback.

Data types

`lora_rx_packet_t`

Received packet data.

Field	Type	Description
`address`	`uint16_t`	Sender LoRa address
`data_len`	`uint16_t`	Payload length
`data`	`char[241]`	Null-terminated ASCII payload
`rssi`	`int16_t`	Signal strength in dBm
`snr`	`int8_t`	Signal-to-noise ratio in dB

`lora_config_t`

Module configuration.

Field	Type	Default	Description
`address`	`uint16_t`	1	Our LoRa address (0–65535)
`dest_address`	`uint16_t`	0	Default send destination
`network_id`	`uint8_t`	0	Network ID (0–16)
`band`	`uint32_t`	915000000	Frequency in Hz
`sf`	`uint8_t`	9	Spreading factor (7–12)
`bw`	`uint8_t`	7	Bandwidth: 7=125kHz, 8=250kHz, 9=500kHz
`cr`	`uint8_t`	1	Coding rate (1–4 → 4/5 to 4/8)
`preamble`	`uint8_t`	7	Preamble length (4–25)

`lora_stats_t`

Runtime statistics.

Field	Type	Description
`last_rssi`	`int16_t`	RSSI of last received packet
`last_snr`	`int8_t`	SNR of last received packet
`tx_count`	`uint32_t`	Total packets sent
`rx_count`	`uint32_t`	Total packets received
`tx_errors`	`uint32_t`	Send failures
`rx_errors`	`uint32_t`	Parse/queue failures

Functions

`lora_init`

esp_err_t lora_init(const lora_config_t *config);

Initialize the LoRa module. In QEMU mode, creates a loopback queue. On hardware, sends AT commands to configure the RYLR module: address, network ID, frequency band, and RF parameters.

Returns: ESP_OK on success, ESP_FAIL if the module doesn’t respond.

`lora_send`

esp_err_t lora_send(uint16_t dest_addr, const char *data, size_t len);

Send ASCII data to a specific address. Data must be printable ASCII, max 240 characters. In QEMU mode, writes to the loopback queue.

`lora_send_default`

esp_err_t lora_send_default(const char *data, size_t len);

Send to the configured default destination address.

`lora_send_binary`

esp_err_t lora_send_binary(uint16_t dest_addr, const uint8_t *data, size_t len);

Send raw binary data. Writes the AT prefix, binary payload, and terminator as three separate UART operations. The RYLR998 reads exactly len bytes — null bytes and non-printable data are safe. In QEMU mode, copies the binary payload directly into the loopback queue (binary-safe).

`lora_receive`

esp_err_t lora_receive(lora_rx_packet_t *pkt, uint32_t timeout_ms);

Receive a packet. Checks the stashed queue first (packets received during AT responses), then polls UART for +RCV messages. Uses line-based parsing — safe for ASCII payloads but not for binary data containing 0x0A (newline) or 0x2C (comma).

Returns: ESP_OK if a packet was received, ESP_ERR_TIMEOUT otherwise.

`lora_receive_binary`

esp_err_t lora_receive_binary(lora_rx_packet_t *pkt, uint32_t timeout_ms);

Receive a binary-safe packet. In QEMU mode, reads from the loopback queue (identical to lora_receive). On hardware, uses length-delimited parsing: reads the +RCV=addr,len, ASCII prefix, then reads exactly len raw bytes (safe for 0x0A, 0x2C, and null bytes), then parses the ASCII ,rssi,snr suffix.

Needed by the ACK layer (pjpeg_lora_ack) to receive 4-byte ACK/NACK packets whose binary payloads break the line-based lora_receive() path.

Returns: ESP_OK if a packet was received, ESP_ERR_TIMEOUT otherwise.

Runtime configuration

esp_err_t lora_set_address(uint16_t addr);
esp_err_t lora_set_network(uint8_t id);
esp_err_t lora_set_band(uint32_t freq);
esp_err_t lora_set_rf_params(uint8_t sf, uint8_t bw, uint8_t cr, uint8_t preamble);
esp_err_t lora_sleep(void);   // AT+MODE=1
esp_err_t lora_wake(void);    // AT (any command wakes module)

Accessors

const lora_stats_t  *lora_get_stats(void);
const lora_config_t *lora_get_config(void);
bool                 lora_is_initialized(void);

AT command reference

These are the RYLR AT commands used by the driver:

Command	Response	Description
`AT`	`+OK`	Ping / wake
`AT+ADDRESS=N`	`+OK`	Set address (0–65535)
`AT+NETWORKID=N`	`+OK`	Set network ID (0–16)
`AT+BAND=N`	`+OK`	Set frequency (Hz)
`AT+PARAMETER=SF,BW,CR,PP`	`+OK`	Set RF parameters
`AT+SEND=addr,len,data`	`+OK`	Send data (max 240 chars)
`AT+MODE=1`	`+OK`	Enter sleep mode
(async) `+RCV=addr,len,data,rssi,snr`	—	Received data notification