lora.h File Reference

LoRa radio codec + driver (PROTOCORE_ENABLE_LORA) - Semtech SX127x / RFM95-96. More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	protocore_lora_header
	RadioHead-compatible LoRa frame header (precedes the payload). More...
struct	protocore_lora_bus
	The register-access bus a driver call uses (your SPI + chip-select behind it). More...
struct	protocore_lora_config
	Radio configuration applied by protocore_lora_init(). More...
struct	LoraNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Typedefs
typedef uint8_t(*	protocore_lora_reg_read_fn) (uint8_t reg, void *ctx)
	Read one SX127x register (reg is the bare 7-bit address).
typedef void(*	protocore_lora_reg_write_fn) (uint8_t reg, uint8_t val, void *ctx)
	Write one SX127x register (reg is the bare 7-bit address).

Functions
	PROTOCORE_NS_LAYOUT (LoraNs, frame_parse, frame_build, init, send, tx_done, set_rx, recv)
proto_bool	protocore_lora_frame_parse (uint8_t *work, const uint8_t *raw, uint16_t len, protocore_lora_header *hdr, const uint8_t **payload, uint16_t *payload_len)
	Split a received frame into its header and payload.
uint16_t	protocore_lora_frame_build (uint8_t *work, const protocore_lora_header *hdr, const uint8_t *payload, uint16_t len, uint8_t *out, uint16_t cap)
	Build a frame (header + payload) into out.
proto_bool	protocore_lora_init (uint8_t *work, const protocore_lora_bus *bus, const protocore_lora_config *cfg)
	Initialize the SX127x: verify the chip, switch to LoRa mode, and .
proto_bool	protocore_lora_send (uint8_t *work, const protocore_lora_bus *bus, const uint8_t *frame, uint8_t len)
	Load frame into the FIFO and start a transmit (the radio returns to .
proto_bool	protocore_lora_tx_done (uint8_t *work, const protocore_lora_bus *bus)
	True once a transmit has finished (RegIrqFlags TxDone); clears the .
void	protocore_lora_set_rx (uint8_t *work, const protocore_lora_bus *bus)
	Put the radio in continuous-receive mode (call once, then poll .
int	protocore_lora_recv (uint8_t *work, const protocore_lora_bus *bus, uint8_t *buf, uint8_t cap, int16_t *rssi)
	If a frame has been received, copy it into buf and report its RSSI.

Variables
PROTOCORE_NS LoraNs Lora	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

LoRa radio codec + driver (PROTOCORE_ENABLE_LORA) - Semtech SX127x / RFM95-96.

A per-radio plugin for the gateway (PROTOCORE_ENABLE_GATEWAY): the southbound-radio half of a LoRa-to-web bridge. Two layers:

• Codec - the RadioHead-compatible 4-byte frame header (to / from / id / flags) that virtually every hobby / sensor LoRa deployment uses on top of the header-less LoRa PHY. protocore_lora_frame_parse() splits a received frame into that header and the payload; protocore_lora_frame_build() prepends it. Pure, no hardware.
• Driver - the SX127x register protocol (init / send / receive / enter-RX) over a caller-supplied register-access bus (protocore_lora_bus). The SPI transfer and the chip-select / reset GPIOs are the integration's - you implement two callbacks that read and write a chip register - so the register sequence is host-testable with a mock bus and portable across whatever SPI peripheral you wire the module to.

Wiring to the gateway (see example LoRaGateway): poll protocore_lora_recv(); on a frame, protocore_lora_frame_parse() then protocore_gateway_uplink(port, header.from, payload, len, rssi). A downlink builds a frame with protocore_lora_frame_build() and protocore_lora_send()s it. The codec + register protocol are verified on the host; the RF link itself needs the module.

work is bytes the CALLER holds. This module reads none of them: it carries nothing between calls, so there is no state to keep and nothing to wipe. The parameter is there so a caller drives every namespace the same way.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file lora.h.

Typedef Documentation

protocore_lora_reg_read_fn

typedef uint8_t(* protocore_lora_reg_read_fn)(uint8_t reg, void *ctx)

Read one SX127x register (reg is the bare 7-bit address).

Definition at line 55 of file lora.h.

protocore_lora_reg_write_fn

typedef void(* protocore_lora_reg_write_fn)(uint8_t reg, uint8_t val, void *ctx)

Write one SX127x register (reg is the bare 7-bit address).

Definition at line 58 of file lora.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	LoraNs	,
		frame_parse	,
		frame_build	,
		init	,
		send	,
		tx_done	,
		set_rx	,
		recv
	)

protocore_lora_frame_parse()

proto_bool protocore_lora_frame_parse	(	uint8_t *	work,
		const uint8_t *	raw,
		uint16_t	len,
		protocore_lora_header *	hdr,
		const uint8_t **	payload,
		uint16_t *	payload_len
	)

Split a received frame into its header and payload.

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
raw	Raw
len	Len
hdr	Hdr
payload	Payload
payload_len	Payload len

Returns

PROTO_TRUE on success.

protocore_lora_frame_build()

uint16_t protocore_lora_frame_build	(	uint8_t *	work,
		const protocore_lora_header *	hdr,
		const uint8_t *	payload,
		uint16_t	len,
		uint8_t *	out,
		uint16_t	cap
	)

Build a frame (header + payload) into out.

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
hdr	Hdr
payload	Payload
len	Len
out	Out
cap	Cap

Returns

The uint16_t.

protocore_lora_init()

proto_bool protocore_lora_init	(	uint8_t *	work,
		const protocore_lora_bus *	bus,
		const protocore_lora_config *	cfg
	)

Initialize the SX127x: verify the chip, switch to LoRa mode, and .

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
bus	Bus
cfg	Cfg

Returns

PROTO_TRUE on success.

protocore_lora_send()

proto_bool protocore_lora_send	(	uint8_t *	work,
		const protocore_lora_bus *	bus,
		const uint8_t *	frame,
		uint8_t	len
	)

Load frame into the FIFO and start a transmit (the radio returns to .

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
bus	Bus
frame	Frame
len	Len

Returns

PROTO_TRUE on success.

protocore_lora_tx_done()

proto_bool protocore_lora_tx_done	(	uint8_t *	work,
		const protocore_lora_bus *	bus
	)

True once a transmit has finished (RegIrqFlags TxDone); clears the .

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
bus	Bus

Returns

PROTO_TRUE on success.

protocore_lora_set_rx()

void protocore_lora_set_rx	(	uint8_t *	work,
		const protocore_lora_bus *	bus
	)

Put the radio in continuous-receive mode (call once, then poll .

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
bus	Bus

protocore_lora_recv()

int protocore_lora_recv	(	uint8_t *	work,
		const protocore_lora_bus *	bus,
		uint8_t *	buf,
		uint8_t	cap,
		int16_t *	rssi
	)

If a frame has been received, copy it into buf and report its RSSI.

Parameters

work	PROTOCORE_LORA_BORROW bytes the caller took. Not held past the call.
bus	Bus
buf	Buf
cap	Cap
rssi	Rssi

Returns

The int.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS LoraNs Lora PROTOCORE_UNUSED

Initial value:

= {.frame_parse = protocore_lora_frame_parse,
                                             .frame_build = protocore_lora_frame_build,
                                             .init = protocore_lora_init,
                                             .send = protocore_lora_send,
                                             .tx_done = protocore_lora_tx_done,
                                             .set_rx = protocore_lora_set_rx,
                                             .recv = protocore_lora_recv}

Module namespace.

Definition at line 164 of file lora.h.