File syn_mbus.h¶

FileList > proto > syn_mbus.h

M-Bus (Meter-Bus, EN 13757-2 / EN 13757-3) Protocol Engine. More...

#include "../common/syn_defs.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_MBUS_Decoder M-Bus streaming state machine decoder.
struct	SYN_MBUS_Frame

Public Types¶

Type	Name
typedef void(*	SYN_MBUS_FrameCallback Callback invoked when a complete, valid M-Bus frame is received.
enum	SYN_MBUS_FrameType

Public Functions¶

Type	Name
uint8_t	syn_mbus_calc_checksum (const uint8_t * data, size_t len) Calculate M-Bus 8-bit checksum (modulo-256 sum over specified buffer).
SYN_Status	syn_mbus_decode_frame (const uint8_t * buf, size_t len, SYN_MBUS_Frame * frame) Decode a raw M-Bus byte buffer into a frame structure.
void	syn_mbus_decoder_feed (SYN_MBUS_Decoder * dec, uint8_t byte) Feed a single byte to the streaming M-Bus decoder.
void	syn_mbus_decoder_init (SYN_MBUS_Decoder * dec, SYN_MBUS_FrameCallback callback, void * ctx) Initialize an M-Bus streaming state machine decoder.
void	syn_mbus_decoder_reset (SYN_MBUS_Decoder * dec) Reset the streaming decoder state.
SYN_Status	syn_mbus_encode_ack (uint8_t * buf, size_t cap, size_t * out_len) Encode a Single Character ACK frame (0xE5).
SYN_Status	syn_mbus_encode_control (uint8_t c_field, uint8_t a_field, uint8_t ci_field, uint8_t * buf, size_t cap, size_t * out_len) Encode a Control Frame (9 bytes: 0x68 \| 0x03 \| 0x03 \| 0x68 \| C \| A \| CI \| Checksum \| 0x16).
SYN_Status	syn_mbus_encode_long (uint8_t c_field, uint8_t a_field, uint8_t ci_field, const uint8_t * payload, uint8_t payload_len, uint8_t * buf, size_t cap, size_t * out_len) Encode a Long Frame (0x68 \| L \| L \| 0x68 \| C \| A \| CI \| Payload... \| Checksum \| 0x16).
SYN_Status	syn_mbus_encode_short (uint8_t c_field, uint8_t a_field, uint8_t * buf, size_t cap, size_t * out_len) Encode a Short Frame (5 bytes: 0x10 \| C \| A \| Checksum \| 0x16).

Macros¶

Type	Name
define	SYN_MBUS_ACK_BYTE `0xE5u`
define	SYN_MBUS_ADDR_BROADCAST_NONE `0xFFu`
define	SYN_MBUS_ADDR_BROADCAST_REPLY `0xFEu`
define	SYN_MBUS_CI_RSP_DATA_LSB `0x72u`
define	SYN_MBUS_CI_RSP_DATA_MSB `0x73u`
define	SYN_MBUS_CI_SELECT_SLAVE `0x52u`
define	SYN_MBUS_CI_SND_UD_LSB `0x51u`
define	SYN_MBUS_C_REQ_UD1 `0x5Au`
define	SYN_MBUS_C_REQ_UD2 `0x5Bu`
define	SYN_MBUS_C_REQ_UD2_FCB `0x7Bu`
define	SYN_MBUS_C_RSP_UD `0x08u`
define	SYN_MBUS_C_SND_NKE `0x40u`
define	SYN_MBUS_C_SND_UD `0x53u`
define	SYN_MBUS_C_SND_UD_FCB `0x73u`
define	SYN_MBUS_MAX_FRAME_LEN `261u`
define	SYN_MBUS_MAX_PAYLOAD `252u`
define	SYN_MBUS_START_CONTROL `0x68u`
define	SYN_MBUS_START_LONG `0x68u`
define	SYN_MBUS_START_SHORT `0x10u`
define	SYN_MBUS_STOP `0x16u`

Detailed Description¶

Implements M-Bus master and slave frame formatting, checksum validation, one-shot encoding/decoding, and streaming byte-by-byte frame reception. Supports all 4 M-Bus EN 13757-2 frame types: * Single Character ACK (0xE5) * Short Frame (0x10) * Control Frame (0x68) * Long Frame (0x68)

Public Types Documentation¶

typedef SYN_MBUS_FrameCallback¶

Callback invoked when a complete, valid M-Bus frame is received.

typedef void(* SYN_MBUS_FrameCallback) (const SYN_MBUS_Frame *frame, void *ctx);

Parameters:

frame Pointer to decoded frame structure.
ctx User context.

enum SYN_MBUS_FrameType¶

enum SYN_MBUS_FrameType {
    SYN_MBUS_FRAME_TYPE_UNKNOWN = 0,
    SYN_MBUS_FRAME_TYPE_SINGLE_ACK,
    SYN_MBUS_FRAME_TYPE_SHORT,
    SYN_MBUS_FRAME_TYPE_CONTROL,
    SYN_MBUS_FRAME_TYPE_LONG
};

Public Functions Documentation¶

function syn_mbus_calc_checksum¶

Calculate M-Bus 8-bit checksum (modulo-256 sum over specified buffer).

uint8_t syn_mbus_calc_checksum (
    const uint8_t * data,
    size_t len
)

Parameters:

data Pointer to buffer.
len Length of data in bytes.

Returns:

Calculated checksum byte.

function syn_mbus_decode_frame¶

Decode a raw M-Bus byte buffer into a frame structure.

SYN_Status syn_mbus_decode_frame (
    const uint8_t * buf,
    size_t len,
    SYN_MBUS_Frame * frame
)

Parameters:

buf Input byte buffer containing a complete M-Bus frame.
len Buffer length in bytes.
frame Destination frame structure.

Returns:

SYN_OK on success, SYN_ERR_INVALID_CHECKSUM on checksum failure, or error status.

function syn_mbus_decoder_feed¶

Feed a single byte to the streaming M-Bus decoder.

void syn_mbus_decoder_feed (
    SYN_MBUS_Decoder * dec,
    uint8_t byte
)

Parameters:

dec Decoder instance.
byte Byte received from UART/RS232/transceiver.

function syn_mbus_decoder_init¶

Initialize an M-Bus streaming state machine decoder.

void syn_mbus_decoder_init (
    SYN_MBUS_Decoder * dec,
    SYN_MBUS_FrameCallback callback,
    void * ctx
)

Parameters:

dec Decoder instance.
callback Callback called upon successful frame completion.
ctx User context passed to callback.

function syn_mbus_decoder_reset¶

Reset the streaming decoder state.

void syn_mbus_decoder_reset (
    SYN_MBUS_Decoder * dec
)

Parameters:

dec Decoder instance.

function syn_mbus_encode_ack¶

Encode a Single Character ACK frame (0xE5).

SYN_Status syn_mbus_encode_ack (
    uint8_t * buf,
    size_t cap,
    size_t * out_len
)

Parameters:

buf Output buffer.
cap Buffer capacity (must be >= 1).
out_len Receives total bytes written (1).

Returns:

SYN_OK on success, or error status.

function syn_mbus_encode_control¶

Encode a Control Frame (9 bytes: 0x68 | 0x03 | 0x03 | 0x68 | C | A | CI | Checksum | 0x16).

SYN_Status syn_mbus_encode_control (
    uint8_t c_field,
    uint8_t a_field,
    uint8_t ci_field,
    uint8_t * buf,
    size_t cap,
    size_t * out_len
)

Parameters:

c_field Control field byte.
a_field Address field byte.
ci_field Control Information field byte.
buf Output buffer.
cap Buffer capacity (must be >= 9).
out_len Receives total bytes written (9).

Returns:

SYN_OK on success, or error status.

function syn_mbus_encode_long¶

Encode a Long Frame (0x68 | L | L | 0x68 | C | A | CI | Payload... | Checksum | 0x16).

SYN_Status syn_mbus_encode_long (
    uint8_t c_field,
    uint8_t a_field,
    uint8_t ci_field,
    const uint8_t * payload,
    uint8_t payload_len,
    uint8_t * buf,
    size_t cap,
    size_t * out_len
)

Parameters:

c_field Control field byte.
a_field Address field byte.
ci_field Control Information field byte.
payload Pointer to payload data buffer.
payload_len Payload length (max 252 bytes).
buf Output buffer.
cap Buffer capacity (must be >= payload_len + 9).
out_len Receives total bytes written.

Returns:

SYN_OK on success, or error status.

function syn_mbus_encode_short¶

Encode a Short Frame (5 bytes: 0x10 | C | A | Checksum | 0x16).

SYN_Status syn_mbus_encode_short (
    uint8_t c_field,
    uint8_t a_field,
    uint8_t * buf,
    size_t cap,
    size_t * out_len
)

Parameters:

c_field Control field byte.
a_field Address field byte.
buf Output buffer.
cap Buffer capacity (must be >= 5).
out_len Receives total bytes written (5).

Returns:

SYN_OK on success, or error status.

Macro Definition Documentation¶

define SYN_MBUS_ACK_BYTE¶

#define SYN_MBUS_ACK_BYTE `0xE5u`

Single character ACK byte

define SYN_MBUS_ADDR_BROADCAST_NONE¶

#define SYN_MBUS_ADDR_BROADCAST_NONE `0xFFu`

Broadcast without reply

define SYN_MBUS_ADDR_BROADCAST_REPLY¶

#define SYN_MBUS_ADDR_BROADCAST_REPLY `0xFEu`

Broadcast with reply

define SYN_MBUS_CI_RSP_DATA_LSB¶

#define SYN_MBUS_CI_RSP_DATA_LSB `0x72u`

Response data, 12-byte header (LSB first)

define SYN_MBUS_CI_RSP_DATA_MSB¶

#define SYN_MBUS_CI_RSP_DATA_MSB `0x73u`

Response data, 12-byte header (MSB first)

define SYN_MBUS_CI_SELECT_SLAVE¶

#define SYN_MBUS_CI_SELECT_SLAVE `0x52u`

Select slave (secondary address)

define SYN_MBUS_CI_SND_UD_LSB¶

#define SYN_MBUS_CI_SND_UD_LSB `0x51u`

Send data, 12-byte header

define SYN_MBUS_C_REQ_UD1¶

#define SYN_MBUS_C_REQ_UD1 `0x5Au`

Master -> Slave: Request data class 1 (FCB=0)

define SYN_MBUS_C_REQ_UD2¶

#define SYN_MBUS_C_REQ_UD2 `0x5Bu`

Master -> Slave: Request data class 2 (FCB=0)

define SYN_MBUS_C_REQ_UD2_FCB¶

#define SYN_MBUS_C_REQ_UD2_FCB `0x7Bu`

Master -> Slave: Request data class 2 (FCB=1)

define SYN_MBUS_C_RSP_UD¶

#define SYN_MBUS_C_RSP_UD `0x08u`

Slave -> Master: Response user data

define SYN_MBUS_C_SND_NKE¶

#define SYN_MBUS_C_SND_NKE `0x40u`

Master -> Slave: Link reset (SND_NKE)

define SYN_MBUS_C_SND_UD¶

#define SYN_MBUS_C_SND_UD `0x53u`

Master -> Slave: Send user data (FCB=0)

define SYN_MBUS_C_SND_UD_FCB¶

#define SYN_MBUS_C_SND_UD_FCB `0x73u`

Master -> Slave: Send user data (FCB=1)

define SYN_MBUS_MAX_FRAME_LEN¶

#define SYN_MBUS_MAX_FRAME_LEN `261u`

Max total raw frame size (SOF+L+L+SOF+C+A+CI+Data+CHK+EOF)

define SYN_MBUS_MAX_PAYLOAD¶

#define SYN_MBUS_MAX_PAYLOAD `252u`

Max user payload size in bytes

define SYN_MBUS_START_CONTROL¶

#define SYN_MBUS_START_CONTROL `0x68u`

Start delimiter for Control frame

define SYN_MBUS_START_LONG¶

#define SYN_MBUS_START_LONG `0x68u`

Start delimiter for Long frame

define SYN_MBUS_START_SHORT¶

#define SYN_MBUS_START_SHORT `0x10u`

Start delimiter for Short frame

define SYN_MBUS_STOP¶

#define SYN_MBUS_STOP `0x16u`

Stop delimiter for frames

The documentation for this class was generated from the following file src/syntropic/proto/syn_mbus.h