File syn_mqttsn.h

FileList > proto > syn_mqttsn.h

Go to the source code of this file

MQTT for Sensor Networks (MQTT-SN v1.2) Protocol Client Engine. More...

• #include "../common/syn_defs.h"
• #include "../net/syn_transport.h"
• #include "../pt/syn_pt.h"
• #include "../sched/syn_sched.h"
• #include <stdbool.h>
• #include <stddef.h>
• #include <stdint.h>

Classes

Type	Name
struct	SYN_MQTTSN_Client MQTT-SN Client instance structure.
struct	SYN_MQTTSN_Config MQTT-SN client configuration descriptor.
struct	SYN_MQTTSN_TopicEntry Registered topic entry mapping string name to 16-bit Topic ID.

Public Types

Type	Name
typedef void(*	SYN_MQTTSN_MessageCb Incoming publish message handler callback.
enum	SYN_MQTTSN_State MQTT-SN client connection state.

Public Functions

Type	Name
SYN_Status	syn_mqttsn_client_connect (SYN_MQTTSN_Client * client) Send CONNECT packet to MQTT-SN gateway.
SYN_Status	syn_mqttsn_client_disconnect (SYN_MQTTSN_Client * client) Disconnect client from gateway.
SYN_Status	syn_mqttsn_client_init (SYN_MQTTSN_Client * client, const SYN_MQTTSN_Config * cfg) Initialize MQTT-SN client.
SYN_PT_Status	syn_mqttsn_client_pt (SYN_PT * pt, SYN_Task * task) Protothread continuation function for syn_sched .
SYN_Status	syn_mqttsn_client_publish (SYN_MQTTSN_Client * client, uint16_t topic_id, int8_t qos, bool retain, const uint8_t * payload, size_t len) Publish data payload using a registered 16-bit Topic ID.
SYN_Status	syn_mqttsn_client_publish_predefined (SYN_MQTTSN_Client * client, uint16_t predef_id, int8_t qos, bool retain, const uint8_t * payload, size_t len) Publish data payload using a predefined 16-bit Topic ID.
SYN_Status	syn_mqttsn_client_publish_short (SYN_MQTTSN_Client * client, const char short_topic, int8_t qos, bool retain, const uint8_t * payload, size_t len) Publish data payload using a short 2-character topic name.
SYN_Status	syn_mqttsn_client_register_topic (SYN_MQTTSN_Client * client, const char * topic_name, uint16_t * out_msg_id) Register a topic name with gateway to obtain a 16-bit Topic ID.
SYN_Status	syn_mqttsn_client_searchgw (SYN_MQTTSN_Client * client, uint8_t radius) Broadcast SEARCHGW to discover active MQTT-SN gateways.
SYN_Status	syn_mqttsn_client_sleep (SYN_MQTTSN_Client * client, uint16_t sleep_duration_s) Put client into low-power SLEEP state with specified sleep duration.
SYN_Status	syn_mqttsn_client_step (SYN_MQTTSN_Client * client, uint32_t now_ms) Non-blocking poll step processing received frames and keep-alive ping timers.
SYN_Status	syn_mqttsn_client_subscribe (SYN_MQTTSN_Client * client, const char * topic_name, uint16_t predef_id, int8_t qos) Subscribe to a topic name or predefined ID.
SYN_Status	syn_mqttsn_client_unsubscribe (SYN_MQTTSN_Client * client, const char * topic_name, uint16_t predef_id) Unsubscribe from a topic.
SYN_Status	syn_mqttsn_client_wake (SYN_MQTTSN_Client * client) Wake up from sleep to flush messages or return to connected state.

Macros

Type	Name
define	SYN_MQTTSN_DEFAULT_DURATION_S 60U
define	SYN_MQTTSN_FLAG_CLEAN_SESSION 0x04U
define	SYN_MQTTSN_FLAG_DUP 0x80U
define	SYN_MQTTSN_FLAG_QOS_0 0x00U
define	SYN_MQTTSN_FLAG_QOS_1 0x20U
define	SYN_MQTTSN_FLAG_QOS_2 0x40U
define	SYN_MQTTSN_FLAG_QOS_MASK 0x60U
define	SYN_MQTTSN_FLAG_QOS_NEG1 0x60U
define	SYN_MQTTSN_FLAG_RETAIN 0x10U
define	SYN_MQTTSN_FLAG_TOPIC_MASK 0x03U
define	SYN_MQTTSN_FLAG_TOPIC_NORMAL 0x00U
define	SYN_MQTTSN_FLAG_TOPIC_PREDEF 0x01U
define	SYN_MQTTSN_FLAG_TOPIC_SHORT 0x02U
define	SYN_MQTTSN_FLAG_WILL 0x08U
define	SYN_MQTTSN_MAX_CLIENT_ID 24U
define	SYN_MQTTSN_MAX_REGISTRATIONS 16U
define	SYN_MQTTSN_MAX_TOPIC_NAME 64U
define	SYN_MQTTSN_MSG_ADVERTISE 0x00U
define	SYN_MQTTSN_MSG_CONNACK 0x05U
define	SYN_MQTTSN_MSG_CONNECT 0x04U
define	SYN_MQTTSN_MSG_DISCONNECT 0x18U
define	SYN_MQTTSN_MSG_GWINFO 0x02U
define	SYN_MQTTSN_MSG_PINGREQ 0x16U
define	SYN_MQTTSN_MSG_PINGRESP 0x17U
define	SYN_MQTTSN_MSG_PUBACK 0x0DU
define	SYN_MQTTSN_MSG_PUBCOMP 0x0EU
define	SYN_MQTTSN_MSG_PUBLISH 0x0CU
define	SYN_MQTTSN_MSG_PUBREC 0x0FU
define	SYN_MQTTSN_MSG_PUBREL 0x10U
define	SYN_MQTTSN_MSG_REGACK 0x0BU
define	SYN_MQTTSN_MSG_REGISTER 0x0AU
define	SYN_MQTTSN_MSG_SEARCHGW 0x01U
define	SYN_MQTTSN_MSG_SUBACK 0x13U
define	SYN_MQTTSN_MSG_SUBSCRIBE 0x12U
define	SYN_MQTTSN_MSG_UNSUBACK 0x15U
define	SYN_MQTTSN_MSG_UNSUBSCRIBE 0x14U
define	SYN_MQTTSN_MSG_WILLMSG 0x09U
define	SYN_MQTTSN_MSG_WILLMSGREQ 0x08U
define	SYN_MQTTSN_MSG_WILLMSGRESP 0x1DU
define	SYN_MQTTSN_MSG_WILLMSGUPD 0x1CU
define	SYN_MQTTSN_MSG_WILLTOPIC 0x07U
define	SYN_MQTTSN_MSG_WILLTOPICREQ 0x06U
define	SYN_MQTTSN_MSG_WILLTOPICRESP 0x1BU
define	SYN_MQTTSN_MSG_WILLTOPICUPD 0x1AU
define	SYN_MQTTSN_PROTOCOL_ID 0x01U
define	SYN_MQTTSN_RC_ACCEPTED 0x00U
define	SYN_MQTTSN_RC_REJ_CONGESTION 0x01U
define	SYN_MQTTSN_RC_REJ_INVALID_TOPIC_ID 0x02U
define	SYN_MQTTSN_RC_REJ_NOT_SUPPORTED 0x03U

Detailed Description

Implements a zero-heap, deterministic MQTT-SN v1.2 client for low-power wireless networks: * Operates over datagram transports (UDP, Zigbee, 802.15.4, Sub-GHz, BLE, RS485). * Gateway Discovery (SEARCHGW, GWINFO, ADVERTISE). * Short (2-char), Predefined, and Dynamically Registered Topic IDs (REGISTER, REGACK). * Publish and Subscribe (QoS 0, QoS 1, QoS -1) with payload framing. * Low-power Sleep/Awake mode transitions (SLEEP, AWAKE queue flush). * Non-blocking poll step and cooperative protothread continuation for syn_sched.

Public Types Documentation

typedef SYN_MQTTSN_MessageCb

Incoming publish message handler callback.

typedef void(* SYN_MQTTSN_MessageCb) (struct SYN_MQTTSN_Client *client, uint16_t topic_id, uint8_t topic_type, const uint8_t *payload, size_t len, void *user_data);

Parameters:

• client Client instance.
• topic_id 16-bit Topic ID or 2-char short topic.
• topic_type Type of topic (normal, predef, short).
• payload Payload data pointer.
• len Payload length in bytes.
• user_data User context pointer.

---

enum SYN_MQTTSN_State

MQTT-SN client connection state.

enum SYN_MQTTSN_State {
    SYN_MQTTSN_STATE_DISCONNECTED = 0,
    SYN_MQTTSN_STATE_SEARCHING_GW,
    SYN_MQTTSN_STATE_CONNECTING,
    SYN_MQTTSN_STATE_CONNECTED,
    SYN_MQTTSN_STATE_ASLEEP,
    SYN_MQTTSN_STATE_AWAKE
};

---

Public Functions Documentation

function syn_mqttsn_client_connect

Send CONNECT packet to MQTT-SN gateway.

SYN_Status syn_mqttsn_client_connect (
    SYN_MQTTSN_Client * client
) 

Parameters:

• client Client instance.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_disconnect

Disconnect client from gateway.

SYN_Status syn_mqttsn_client_disconnect (
    SYN_MQTTSN_Client * client
) 

Parameters:

• client Client instance.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_init

Initialize MQTT-SN client.

SYN_Status syn_mqttsn_client_init (
    SYN_MQTTSN_Client * client,
    const SYN_MQTTSN_Config * cfg
) 

Parameters:

• client Client instance pointer.
• cfg Configuration descriptor.

Returns:

SYN_OK on success, SYN_INVALID_PARAM on invalid argument.

---

function syn_mqttsn_client_pt

Protothread continuation function for syn_sched .

SYN_PT_Status syn_mqttsn_client_pt (
    SYN_PT * pt,
    SYN_Task * task
) 

Parameters:

• pt Protothread continuation structure.
• task Task handle containing SYN_MQTTSN_Client in user_data.

Returns:

SYN_PT_Status continuation status.

---

function syn_mqttsn_client_publish

Publish data payload using a registered 16-bit Topic ID.

SYN_Status syn_mqttsn_client_publish (
    SYN_MQTTSN_Client * client,
    uint16_t topic_id,
    int8_t qos,
    bool retain,
    const uint8_t * payload,
    size_t len
) 

Parameters:

• client Client instance.
• topic_id 16-bit Topic ID.
• qos Quality of Service (0, 1, or -1).
• retain Retain flag.
• payload Payload buffer.
• len Payload length.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_publish_predefined

Publish data payload using a predefined 16-bit Topic ID.

SYN_Status syn_mqttsn_client_publish_predefined (
    SYN_MQTTSN_Client * client,
    uint16_t predef_id,
    int8_t qos,
    bool retain,
    const uint8_t * payload,
    size_t len
) 

Parameters:

• client Client instance.
• predef_id Predefined 16-bit Topic ID.
• qos Quality of Service (0, 1, or -1).
• retain Retain flag.
• payload Payload buffer.
• len Payload length.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_publish_short

Publish data payload using a short 2-character topic name.

SYN_Status syn_mqttsn_client_publish_short (
    SYN_MQTTSN_Client * client,
    const char short_topic,
    int8_t qos,
    bool retain,
    const uint8_t * payload,
    size_t len
) 

Parameters:

• client Client instance.
• short_topic 2-character topic string.
• qos Quality of Service (0, 1, or -1).
• retain Retain flag.
• payload Payload buffer.
• len Payload length.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_register_topic

Register a topic name with gateway to obtain a 16-bit Topic ID.

SYN_Status syn_mqttsn_client_register_topic (
    SYN_MQTTSN_Client * client,
    const char * topic_name,
    uint16_t * out_msg_id
) 

Parameters:

• client Client instance.
• topic_name String topic name.
• out_msg_id Optional pointer to receive allocated MsgId.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_searchgw

Broadcast SEARCHGW to discover active MQTT-SN gateways.

SYN_Status syn_mqttsn_client_searchgw (
    SYN_MQTTSN_Client * client,
    uint8_t radius
) 

Parameters:

• client Client instance.
• radius Search radius hop count.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_sleep

Put client into low-power SLEEP state with specified sleep duration.

SYN_Status syn_mqttsn_client_sleep (
    SYN_MQTTSN_Client * client,
    uint16_t sleep_duration_s
) 

Parameters:

• client Client instance.
• sleep_duration_s Sleep duration in seconds.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_step

Non-blocking poll step processing received frames and keep-alive ping timers.

SYN_Status syn_mqttsn_client_step (
    SYN_MQTTSN_Client * client,
    uint32_t now_ms
) 

Parameters:

• client Client instance.
• now_ms Current timestamp in milliseconds.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_subscribe

Subscribe to a topic name or predefined ID.

SYN_Status syn_mqttsn_client_subscribe (
    SYN_MQTTSN_Client * client,
    const char * topic_name,
    uint16_t predef_id,
    int8_t qos
) 

Parameters:

• client Client instance.
• topic_name Topic name string (or NULL if subscribing by predef_id).
• predef_id Predefined Topic ID (if topic_name is NULL).
• qos Requested QoS level.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_unsubscribe

Unsubscribe from a topic.

SYN_Status syn_mqttsn_client_unsubscribe (
    SYN_MQTTSN_Client * client,
    const char * topic_name,
    uint16_t predef_id
) 

Parameters:

• client Client instance.
• topic_name Topic name string.
• predef_id Predefined Topic ID.

Returns:

SYN_OK on success.

---

function syn_mqttsn_client_wake

Wake up from sleep to flush messages or return to connected state.

SYN_Status syn_mqttsn_client_wake (
    SYN_MQTTSN_Client * client
) 

Parameters:

• client Client instance.

Returns:

SYN_OK on success.

---

Macro Definition Documentation

define SYN_MQTTSN_DEFAULT_DURATION_S

#define SYN_MQTTSN_DEFAULT_DURATION_S `60U`

Default Keep-Alive duration in seconds

---

define SYN_MQTTSN_FLAG_CLEAN_SESSION

#define SYN_MQTTSN_FLAG_CLEAN_SESSION `0x04U`

Clean session flag

---

define SYN_MQTTSN_FLAG_DUP

#define SYN_MQTTSN_FLAG_DUP `0x80U`

Duplicate delivery flag

---

define SYN_MQTTSN_FLAG_QOS_0

#define SYN_MQTTSN_FLAG_QOS_0 `0x00U`

QoS level 0

---

define SYN_MQTTSN_FLAG_QOS_1

#define SYN_MQTTSN_FLAG_QOS_1 `0x20U`

QoS level 1

---

define SYN_MQTTSN_FLAG_QOS_2

#define SYN_MQTTSN_FLAG_QOS_2 `0x40U`

QoS level 2

---

define SYN_MQTTSN_FLAG_QOS_MASK

#define SYN_MQTTSN_FLAG_QOS_MASK `0x60U`

QoS mask

---

define SYN_MQTTSN_FLAG_QOS_NEG1

#define SYN_MQTTSN_FLAG_QOS_NEG1 `0x60U`

QoS level -1 (transparent)

---

define SYN_MQTTSN_FLAG_RETAIN

#define SYN_MQTTSN_FLAG_RETAIN `0x10U`

Retain flag

---

define SYN_MQTTSN_FLAG_TOPIC_MASK

#define SYN_MQTTSN_FLAG_TOPIC_MASK `0x03U`

Topic ID type mask

---

define SYN_MQTTSN_FLAG_TOPIC_NORMAL

#define SYN_MQTTSN_FLAG_TOPIC_NORMAL `0x00U`

Topic ID type: Normal registered ID

---

define SYN_MQTTSN_FLAG_TOPIC_PREDEF

#define SYN_MQTTSN_FLAG_TOPIC_PREDEF `0x01U`

Topic ID type: Predefined 16-bit ID

---

define SYN_MQTTSN_FLAG_TOPIC_SHORT

#define SYN_MQTTSN_FLAG_TOPIC_SHORT `0x02U`

Topic ID type: Short 2-char string

---

define SYN_MQTTSN_FLAG_WILL

#define SYN_MQTTSN_FLAG_WILL `0x08U`

Will flag

---

define SYN_MQTTSN_MAX_CLIENT_ID

#define SYN_MQTTSN_MAX_CLIENT_ID `24U`

Max Client Identifier string length

---

define SYN_MQTTSN_MAX_REGISTRATIONS

#define SYN_MQTTSN_MAX_REGISTRATIONS `16U`

Max tracked registered topics

---

define SYN_MQTTSN_MAX_TOPIC_NAME

#define SYN_MQTTSN_MAX_TOPIC_NAME `64U`

Max Topic name string length

---

define SYN_MQTTSN_MSG_ADVERTISE

#define SYN_MQTTSN_MSG_ADVERTISE `0x00U`

Gateway advertise broadcast

---

define SYN_MQTTSN_MSG_CONNACK

#define SYN_MQTTSN_MSG_CONNACK `0x05U`

Connect acknowledgment

---

define SYN_MQTTSN_MSG_CONNECT

#define SYN_MQTTSN_MSG_CONNECT `0x04U`

Connect request

---

define SYN_MQTTSN_MSG_DISCONNECT

#define SYN_MQTTSN_MSG_DISCONNECT `0x18U`

Disconnect / sleep command

---

define SYN_MQTTSN_MSG_GWINFO

#define SYN_MQTTSN_MSG_GWINFO `0x02U`

Gateway information response

---

define SYN_MQTTSN_MSG_PINGREQ

#define SYN_MQTTSN_MSG_PINGREQ `0x16U`

Ping request / wake ping

---

define SYN_MQTTSN_MSG_PINGRESP

#define SYN_MQTTSN_MSG_PINGRESP `0x17U`

Ping response

---

define SYN_MQTTSN_MSG_PUBACK

#define SYN_MQTTSN_MSG_PUBACK `0x0DU`

Publish acknowledgment

---

define SYN_MQTTSN_MSG_PUBCOMP

#define SYN_MQTTSN_MSG_PUBCOMP `0x0EU`

Publish complete (QoS 2)

---

define SYN_MQTTSN_MSG_PUBLISH

#define SYN_MQTTSN_MSG_PUBLISH `0x0CU`

Publish message

---

define SYN_MQTTSN_MSG_PUBREC

#define SYN_MQTTSN_MSG_PUBREC `0x0FU`

Publish received (QoS 2)

---

define SYN_MQTTSN_MSG_PUBREL

#define SYN_MQTTSN_MSG_PUBREL `0x10U`

Publish release (QoS 2)

---

define SYN_MQTTSN_MSG_REGACK

#define SYN_MQTTSN_MSG_REGACK `0x0BU`

Topic registration acknowledgment

---

define SYN_MQTTSN_MSG_REGISTER

#define SYN_MQTTSN_MSG_REGISTER `0x0AU`

Topic registration request

---

define SYN_MQTTSN_MSG_SEARCHGW

#define SYN_MQTTSN_MSG_SEARCHGW `0x01U`

Client search gateway broadcast

---

define SYN_MQTTSN_MSG_SUBACK

#define SYN_MQTTSN_MSG_SUBACK `0x13U`

Subscribe acknowledgment

---

define SYN_MQTTSN_MSG_SUBSCRIBE

#define SYN_MQTTSN_MSG_SUBSCRIBE `0x12U`

Subscribe request

---

define SYN_MQTTSN_MSG_UNSUBACK

#define SYN_MQTTSN_MSG_UNSUBACK `0x15U`

Unsubscribe acknowledgment

---

define SYN_MQTTSN_MSG_UNSUBSCRIBE

#define SYN_MQTTSN_MSG_UNSUBSCRIBE `0x14U`

Unsubscribe request

---

define SYN_MQTTSN_MSG_WILLMSG

#define SYN_MQTTSN_MSG_WILLMSG `0x09U`

Will message payload

---

define SYN_MQTTSN_MSG_WILLMSGREQ

#define SYN_MQTTSN_MSG_WILLMSGREQ `0x08U`

Will message request

---

define SYN_MQTTSN_MSG_WILLMSGRESP

#define SYN_MQTTSN_MSG_WILLMSGRESP `0x1DU`

Will message update response

---

define SYN_MQTTSN_MSG_WILLMSGUPD

#define SYN_MQTTSN_MSG_WILLMSGUPD `0x1CU`

Will message update

---

define SYN_MQTTSN_MSG_WILLTOPIC

#define SYN_MQTTSN_MSG_WILLTOPIC `0x07U`

Will topic specification

---

define SYN_MQTTSN_MSG_WILLTOPICREQ

#define SYN_MQTTSN_MSG_WILLTOPICREQ `0x06U`

Will topic request

---

define SYN_MQTTSN_MSG_WILLTOPICRESP

#define SYN_MQTTSN_MSG_WILLTOPICRESP `0x1BU`

Will topic update response

---

define SYN_MQTTSN_MSG_WILLTOPICUPD

#define SYN_MQTTSN_MSG_WILLTOPICUPD `0x1AU`

Will topic update

---

define SYN_MQTTSN_PROTOCOL_ID

#define SYN_MQTTSN_PROTOCOL_ID `0x01U`

MQTT-SN Protocol ID v1.2

---

define SYN_MQTTSN_RC_ACCEPTED

#define SYN_MQTTSN_RC_ACCEPTED `0x00U`

Request accepted

---

define SYN_MQTTSN_RC_REJ_CONGESTION

#define SYN_MQTTSN_RC_REJ_CONGESTION `0x01U`

Rejected: Congestion

---

define SYN_MQTTSN_RC_REJ_INVALID_TOPIC_ID

#define SYN_MQTTSN_RC_REJ_INVALID_TOPIC_ID `0x02U`

Rejected: Invalid Topic ID

---

define SYN_MQTTSN_RC_REJ_NOT_SUPPORTED

#define SYN_MQTTSN_RC_REJ_NOT_SUPPORTED `0x03U`

Rejected: Not supported

---

---

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