enocean.h File Reference

EnOcean ESP3 serial codec (PROTOCORE_ENABLE_ENOCEAN) - energy-harvesting 868 MHz. More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	protocore_esp3_packet
	A parsed ESP3 telegram (pointers alias the caller's buffer). More...
struct	protocore_erp1
	A decoded ERP1 radio telegram (the payload aliases the caller's buffer). More...
struct	EnoceanNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	ESP3_SYNC   0x55
	ESP3 sync byte that starts every telegram.
#define	PROTOCORE_ERP_RORG_RPS   0xF6
	Repeated Switch communication (rocker switches): 1 payload octet.
#define	PROTOCORE_ERP_RORG_1BS   0xD5
	1-byte communication (contacts): 1 payload octet
#define	PROTOCORE_ERP_RORG_4BS   0xA5
	4-byte communication (sensors): 4 payload octets
#define	PROTOCORE_ERP_RORG_VLD   0xD2
	Variable-Length Data.
#define	PROTOCORE_ERP_RORG_MSC   0xD1
	Manufacturer-Specific Communication.
#define	PROTOCORE_ERP_RORG_ADT   0xA6
	Addressing Destination Telegram.
#define	PROTOCORE_ERP_RORG_UTE   0xD4
	Universal Teach-in.

Typedefs
typedef enum PROTO_ENUM_PACKED	protocore_esp3_type
	ESP3 packet types (the common ones).

Enumerations
enum	PROTO_ENUM_PACKED {   ESP3_RADIO_ERP1 = 0x01 , ESP3_RESPONSE = 0x02 , ESP3_RADIO_SUB_TEL = 0x03 , ESP3_EVENT = 0x04 ,   ESP3_COMMON_COMMAND = 0x05 , ESP3_SMART_ACK = 0x06 , ESP3_REMOTE_MAN = 0x07 , ESP3_RADIO_ERP2 = 0x0A }
	ESP3 packet types (the common ones). More...

Functions
	PROTOCORE_NS_LAYOUT (EnoceanNs, esp3_crc8, esp3_parse, esp3_build, erp1_parse, erp1_build)
uint8_t	protocore_enocean_esp3_crc8 (uint8_t *work, const uint8_t *buf, uint16_t len)
	CRC-8 used by ESP3 (polynomial 0x07, MSB-first, init 0x00).
int	protocore_enocean_esp3_parse (uint8_t *work, const uint8_t *raw, uint16_t len, protocore_esp3_packet *out)
	Frame one ESP3 telegram from the front of raw.
uint16_t	protocore_enocean_esp3_build (uint8_t *work, protocore_esp3_type type, const uint8_t *data, uint16_t data_len, const uint8_t *opt, uint8_t opt_len, uint8_t *out, uint16_t cap)
	Assemble an ESP3 telegram into out.
proto_bool	protocore_enocean_erp1_parse (uint8_t *work, const uint8_t *data, uint16_t len, protocore_erp1 *out)
	Decode an ERP1 radio telegram: RORG + payload + 4-octet sender id + .
uint16_t	protocore_enocean_erp1_build (uint8_t *work, uint8_t *out, uint16_t cap, uint8_t rorg, const uint8_t *payload, uint8_t payload_len, uint32_t sender_id, uint8_t status)
	Assemble an ERP1 radio telegram (the inverse of .

Variables
PROTOCORE_NS EnoceanNs Enocean	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

EnOcean ESP3 serial codec (PROTOCORE_ENABLE_ENOCEAN) - energy-harvesting 868 MHz.

A UART telegram codec for EnOcean Serial Protocol 3 (ESP3), the framing every USB / serial EnOcean gateway (TCM 310 / USB 300) speaks. A telegram is:

0x55 | data-len (2, big-endian) | opt-len (1) | packet-type (1) | CRC8H | data[data-len] | opt[opt-len] | CRC8D

where CRC8H protects the 4 header bytes and CRC8D protects the data + optional data (both CRC-8, polynomial 0x07, init 0). protocore_esp3_parse() frames one telegram out of a byte stream, resynchronizing on a bad sync / CRC, and protocore_esp3_build() assembles one. This is the radio- plugin codec for the gateway: an inbound RADIO_ERP1 telegram carries a sender id (its source address) and payload; bridge it northbound with protocore_gateway_uplink(). Pure - you feed it the UART bytes - so it is fully host-testable. See example EnOceanGateway.

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 enocean.h.

Macro Definition Documentation

ESP3_SYNC

#define ESP3_SYNC   0x55

ESP3 sync byte that starts every telegram.

Definition at line 41 of file enocean.h.

PROTOCORE_ERP_RORG_RPS

#define PROTOCORE_ERP_RORG_RPS   0xF6

Repeated Switch communication (rocker switches): 1 payload octet.

Definition at line 44 of file enocean.h.

PROTOCORE_ERP_RORG_1BS

#define PROTOCORE_ERP_RORG_1BS   0xD5

1-byte communication (contacts): 1 payload octet

Definition at line 45 of file enocean.h.

PROTOCORE_ERP_RORG_4BS

#define PROTOCORE_ERP_RORG_4BS   0xA5

4-byte communication (sensors): 4 payload octets

Definition at line 46 of file enocean.h.

PROTOCORE_ERP_RORG_VLD

#define PROTOCORE_ERP_RORG_VLD   0xD2

Variable-Length Data.

Definition at line 47 of file enocean.h.

PROTOCORE_ERP_RORG_MSC

#define PROTOCORE_ERP_RORG_MSC   0xD1

Manufacturer-Specific Communication.

Definition at line 48 of file enocean.h.

PROTOCORE_ERP_RORG_ADT

#define PROTOCORE_ERP_RORG_ADT   0xA6

Addressing Destination Telegram.

Definition at line 49 of file enocean.h.

PROTOCORE_ERP_RORG_UTE

#define PROTOCORE_ERP_RORG_UTE   0xD4

Universal Teach-in.

Definition at line 50 of file enocean.h.

Typedef Documentation

protocore_esp3_type

typedef enum PROTO_ENUM_PACKED protocore_esp3_type

ESP3 packet types (the common ones).

Enumeration Type Documentation

PROTO_ENUM_PACKED

enum PROTO_ENUM_PACKED

ESP3 packet types (the common ones).

Enumerator
ESP3_RADIO_ERP1
ESP3_RESPONSE
ESP3_RADIO_SUB_TEL
ESP3_EVENT
ESP3_COMMON_COMMAND
ESP3_SMART_ACK
ESP3_REMOTE_MAN
ESP3_RADIO_ERP2

Definition at line 53 of file enocean.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	EnoceanNs	,
		esp3_crc8	,
		esp3_parse	,
		esp3_build	,
		erp1_parse	,
		erp1_build
	)

protocore_enocean_esp3_crc8()

uint8_t protocore_enocean_esp3_crc8	(	uint8_t *	work,
		const uint8_t *	buf,
		uint16_t	len
	)

CRC-8 used by ESP3 (polynomial 0x07, MSB-first, init 0x00).

Parameters

work	PROTOCORE_ENOCEAN_BORROW bytes the caller took. Not held past the call.
buf	Buf
len	Len

Returns

The uint8_t.

protocore_enocean_esp3_parse()

int protocore_enocean_esp3_parse	(	uint8_t *	work,
		const uint8_t *	raw,
		uint16_t	len,
		protocore_esp3_packet *	out
	)

Frame one ESP3 telegram from the front of raw.

Parameters

work	PROTOCORE_ENOCEAN_BORROW bytes the caller took. Not held past the call.
raw	Raw
len	Len
out	Out

Returns

The int.

protocore_enocean_esp3_build()

uint16_t protocore_enocean_esp3_build	(	uint8_t *	work,
		protocore_esp3_type	type,
		const uint8_t *	data,
		uint16_t	data_len,
		const uint8_t *	opt,
		uint8_t	opt_len,
		uint8_t *	out,
		uint16_t	cap
	)

Assemble an ESP3 telegram into out.

Parameters

work	PROTOCORE_ENOCEAN_BORROW bytes the caller took. Not held past the call.
type	Type
data	Data
data_len	Data len
opt	Opt
opt_len	Opt len
out	Out
cap	Cap

Returns

The uint16_t.

protocore_enocean_erp1_parse()

proto_bool protocore_enocean_erp1_parse	(	uint8_t *	work,
		const uint8_t *	data,
		uint16_t	len,
		protocore_erp1 *	out
	)

Decode an ERP1 radio telegram: RORG + payload + 4-octet sender id + .

Parameters

work	PROTOCORE_ENOCEAN_BORROW bytes the caller took. Not held past the call.
data	Data
len	Len
out	Out

Returns

PROTO_TRUE on success.

protocore_enocean_erp1_build()

uint16_t protocore_enocean_erp1_build	(	uint8_t *	work,
		uint8_t *	out,
		uint16_t	cap,
		uint8_t	rorg,
		const uint8_t *	payload,
		uint8_t	payload_len,
		uint32_t	sender_id,
		uint8_t	status
	)

Assemble an ERP1 radio telegram (the inverse of .

Parameters

work	PROTOCORE_ENOCEAN_BORROW bytes the caller took. Not held past the call.
out	Out
cap	Cap
rorg	Rorg
payload	Payload
payload_len	Payload len
sender_id	Sender id
status	Status

Returns

The uint16_t.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS EnoceanNs Enocean PROTOCORE_UNUSED

Initial value:

= {.esp3_crc8 = protocore_enocean_esp3_crc8,
                                                   .esp3_parse = protocore_enocean_esp3_parse,
                                                   .esp3_build = protocore_enocean_esp3_build,
                                                   .erp1_parse = protocore_enocean_erp1_parse,
                                                   .erp1_build = protocore_enocean_erp1_build}

Module namespace.

Definition at line 153 of file enocean.h.