gateway.h File Reference

Radio / wireless gateway bridge (PROTOCORE_ENABLE_GATEWAY) - the v5 southbound-to- northbound bridge. More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	protocore_gateway_msg
	A northbound message: a southbound frame enveloped with its routing metadata. payload points at the caller's bytes and is valid only for the duration of the uplink callback - copy what you publish asynchronously. More...
struct	protocore_gateway_port_config
	Southbound port (radio / bus) configuration passed to protocore_gateway_add_port(). More...
struct	protocore_gateway_stats
	Gateway counters (monotonic since the last protocore_gateway_reset()). More...
struct	GatewayNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Typedefs
typedef enum PROTO_ENUM_PACKED	protocore_gateway_kind
	Southbound radio / bus kind a port bridges (informational + topic hint).
typedef proto_bool(*	protocore_gateway_uplink_fn) (const protocore_gateway_msg *msg, void *ctx)
	Northbound publish: emit msg to MQTT / HTTP / WebSocket / UDP.
typedef proto_bool(*	protocore_gateway_tx_fn) (uint8_t port_id, uint16_t dst_addr, const uint8_t *payload, uint16_t len, void *ctx)
	Southbound transmit (downlink): send payload to dst_addr on port_id.

Enumerations
enum	PROTO_ENUM_PACKED {   PROTOCORE_GW_OTHER = 0 , PROTOCORE_GW_LORA , PROTOCORE_GW_NRF24 , PROTOCORE_GW_CC1101 ,   PROTOCORE_GW_THREAD , PROTOCORE_GW_ZIGBEE , PROTOCORE_GW_ZWAVE , PROTOCORE_GW_ENOCEAN ,   PROTOCORE_GW_SIGFOX , PROTOCORE_GW_WISUN , PROTOCORE_GW_NFC , PROTOCORE_GW_BLE }
	Southbound radio / bus kind a port bridges (informational + topic hint). More...

Functions
	PROTOCORE_NS_LAYOUT (GatewayNs, reset, add_port, set_uplink_cb, set_topic_prefix, uplink, downlink, topic, get_stats)
void	protocore_gateway_reset (uint8_t *work)
	Clear all ports, the uplink sink, the topic prefix, and stats.
proto_bool	protocore_gateway_add_port (uint8_t *work, const protocore_gateway_port_config *cfg)
	Register a southbound port.
void	protocore_gateway_set_uplink_cb (uint8_t *work, protocore_gateway_uplink_fn fn, void *ctx)
	Install the northbound publish callback (required to publish .
void	protocore_gateway_set_topic_prefix (uint8_t *work, const char *prefix)
	Set the topic prefix used by protocore_gateway_topic() .
proto_bool	protocore_gateway_uplink (uint8_t *work, uint8_t port_id, uint16_t src_addr, const uint8_t *payload, uint16_t len, int16_t rssi)
	Bridge a received southbound frame northbound: envelope it and .
proto_bool	protocore_gateway_downlink (uint8_t *work, uint8_t port_id, uint16_t dst_addr, const uint8_t *payload, uint16_t len)
	Bridge a northbound command southbound: transmit it on port_id's .
uint16_t	protocore_gateway_topic (uint8_t *work, const protocore_gateway_msg *msg, char *buf, uint16_t buflen)
	Format a northbound routing key <prefix>/<port>/<addr> for msg .
void	protocore_gateway_get_stats (uint8_t *work, protocore_gateway_stats *out)
	Copy the current gateway counters into out. The uplink rate window .
uint8_t *	protocore_gateway_span (void)
	The PROTOCORE_GATEWAY_BORROW bytes this module's state lives in.

Variables
PROTOCORE_NS GatewayNs Gateway	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

Radio / wireless gateway bridge (PROTOCORE_ENABLE_GATEWAY) - the v5 southbound-to- northbound bridge.

The generic gateway pattern that ties the hardware-ingest pipeline to the web stack. A southbound radio (LoRa / nRF24 / CC1101 / Zigbee / Z-Wave / ... reached over SPI / I2C / UART) is a port. When it receives a frame - the data-ready ISR reads it over DMA (mmgr/dma), posts it onto the FORWARD lane (services/system/preempt_queue), and a per-radio codec extracts the source node address and payload - you call protocore_gateway_uplink(). The gateway envelopes the frame (source address, port, RSSI, a sequence number) and publishes it northbound through the uplink callback, which you wire to MQTT / HTTP / WebSocket / UDP. A northbound command runs the other way through protocore_gateway_downlink() to the port's transmit callback (the radio's SPI / UART write).

The radio transmit and the northbound publish are callbacks - the seam a real radio driver and a real protocol binding plug into - so the bridge is fully host- and device-testable with no radio hardware (the tests / example supply capturing callbacks and feed simulated frames). This is the northbound half; the DMA + FORWARD lane carry the bytes, and each radio's frame format is its own codec.

Per-port uplink rate cap (fail-closed), a routing-key helper (protocore_gateway_topic() formats <prefix>/<port>/<addr>), and static tables (zero heap): PROTOCORE_GW_MAX_PORTS ports.

work is PROTOCORE_GATEWAY_BORROW bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. How those bytes are carved is this module's and is never named here.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file gateway.h.

Typedef Documentation

protocore_gateway_kind

typedef enum PROTO_ENUM_PACKED protocore_gateway_kind

Southbound radio / bus kind a port bridges (informational + topic hint).

protocore_gateway_uplink_fn

typedef proto_bool(* protocore_gateway_uplink_fn)(const protocore_gateway_msg *msg, void *ctx)

Northbound publish: emit msg to MQTT / HTTP / WebSocket / UDP.

Returns

true if the northbound stack accepted it; false drops (counted).

Definition at line 80 of file gateway.h.

protocore_gateway_tx_fn

typedef proto_bool(* protocore_gateway_tx_fn) (uint8_t port_id, uint16_t dst_addr, const uint8_t *payload, uint16_t len, void *ctx)

Southbound transmit (downlink): send payload to dst_addr on port_id.

Returns

true if the radio accepted the frame; false drops (counted).

Definition at line 86 of file gateway.h.

Enumeration Type Documentation

PROTO_ENUM_PACKED

enum PROTO_ENUM_PACKED

Southbound radio / bus kind a port bridges (informational + topic hint).

Enumerator
PROTOCORE_GW_OTHER
PROTOCORE_GW_LORA
PROTOCORE_GW_NRF24
PROTOCORE_GW_CC1101
PROTOCORE_GW_THREAD
PROTOCORE_GW_ZIGBEE
PROTOCORE_GW_ZWAVE
PROTOCORE_GW_ENOCEAN
PROTOCORE_GW_SIGFOX
PROTOCORE_GW_WISUN
PROTOCORE_GW_NFC
PROTOCORE_GW_BLE

Definition at line 44 of file gateway.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	GatewayNs	,
		reset	,
		add_port	,
		set_uplink_cb	,
		set_topic_prefix	,
		uplink	,
		downlink	,
		topic	,
		get_stats
	)

protocore_gateway_reset()

void protocore_gateway_reset

(

uint8_t *

work

)

Clear all ports, the uplink sink, the topic prefix, and stats.

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.

protocore_gateway_add_port()

proto_bool protocore_gateway_add_port	(	uint8_t *	work,
		const protocore_gateway_port_config *	cfg
	)

Register a southbound port.

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
cfg	Cfg

Returns

PROTO_TRUE on success.

protocore_gateway_set_uplink_cb()

void protocore_gateway_set_uplink_cb	(	uint8_t *	work,
		protocore_gateway_uplink_fn	fn,
		void *	ctx
	)

Install the northbound publish callback (required to publish .

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
fn	Fn
ctx	Ctx

protocore_gateway_set_topic_prefix()

void protocore_gateway_set_topic_prefix	(	uint8_t *	work,
		const char *	prefix
	)

Set the topic prefix used by protocore_gateway_topic() .

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
prefix	Prefix

protocore_gateway_uplink()

proto_bool protocore_gateway_uplink	(	uint8_t *	work,
		uint8_t	port_id,
		uint16_t	src_addr,
		const uint8_t *	payload,
		uint16_t	len,
		int16_t	rssi
	)

Bridge a received southbound frame northbound: envelope it and .

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
port_id	Port id
src_addr	Src addr
payload	Payload
len	Len
rssi	Rssi

Returns

PROTO_TRUE on success.

protocore_gateway_downlink()

proto_bool protocore_gateway_downlink	(	uint8_t *	work,
		uint8_t	port_id,
		uint16_t	dst_addr,
		const uint8_t *	payload,
		uint16_t	len
	)

Bridge a northbound command southbound: transmit it on port_id's .

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
port_id	Port id
dst_addr	Dst addr
payload	Payload
len	Len

Returns

PROTO_TRUE on success.

protocore_gateway_topic()

uint16_t protocore_gateway_topic	(	uint8_t *	work,
		const protocore_gateway_msg *	msg,
		char *	buf,
		uint16_t	buflen
	)

Format a northbound routing key <prefix>/<port>/<addr> for msg .

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
msg	Msg
buf	Buf
buflen	Buflen

Returns

The uint16_t.

protocore_gateway_get_stats()

void protocore_gateway_get_stats	(	uint8_t *	work,
		protocore_gateway_stats *	out
	)

Copy the current gateway counters into out. The uplink rate window .

Parameters

work	PROTOCORE_GATEWAY_BORROW bytes the caller took. Not held past the call.
out	Out

protocore_gateway_span()

uint8_t * protocore_gateway_span

(

void

)

The PROTOCORE_GATEWAY_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns

the span.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS GatewayNs Gateway PROTOCORE_UNUSED

Initial value:

= {.reset = protocore_gateway_reset,
                                                   .add_port = protocore_gateway_add_port,
                                                   .set_uplink_cb = protocore_gateway_set_uplink_cb,
                                                   .set_topic_prefix = protocore_gateway_set_topic_prefix,
                                                   .uplink = protocore_gateway_uplink,
                                                   .downlink = protocore_gateway_downlink,
                                                   .topic = protocore_gateway_topic,
                                                   .get_stats = protocore_gateway_get_stats}

Module namespace.

Definition at line 205 of file gateway.h.