File syn_mqtt.h¶

Lightweight MQTT 3.1.1 client.

#include "../common/syn_defs.h"
#include "../port/syn_port_socket.h"
#include "../pt/syn_pt.h"
#include "../sched/syn_task.h"

Classes¶

Type	Name
struct	SYN_Mqtt5_UserProp MQTT v5.0 Key-Value User Property.
struct	SYN_MqttClient MQTT client context structure.

Public Types¶

Type	Name
enum	SYN_MqttRxPhase Non-blocking packet reception states.
enum	SYN_MqttState MQTT client connection states.
enum	SYN_MqttVersion MQTT Protocol Version.

Public Functions¶

Type	Name
size_t	syn_mqtt5_encode_user_prop (const char * key, const char * val, uint8_t * buf, size_t max_buf_len) Encode an MQTT 5.0 User Property (Key-Value string pair).
bool	syn_mqtt_decode_varint (const uint8_t * buf, size_t buf_len, uint32_t * val, size_t * bytes_read) Decode a Variable Byte Integer (MQTT 3.1.1 & MQTT 5.0).
void	syn_mqtt_disconnect (SYN_MqttClient * client) Disconnect the MQTT client and close underlying TCP socket.
size_t	syn_mqtt_encode_varint (uint32_t val, uint8_t buf) Encode a Variable Byte Integer (MQTT 3.1.1 & MQTT 5.0).
SYN_Status	syn_mqtt_init (SYN_MqttClient * client, const char * host, uint16_t port, const char * client_id, const char * username, const char * password, uint16_t keep_alive_s, uint8_t * rx_buf, size_t rx_buf_size, uint8_t * tx_buf, size_t tx_buf_size) Initialize the MQTT client.
SYN_Status	syn_mqtt_ping (SYN_MqttClient * client) Transmit an explicit MQTT PINGREQ packet.
SYN_Status	syn_mqtt_publish (SYN_MqttClient * client, const char * topic, const void * payload, size_t len, uint8_t qos, bool retain) Publish a message to a topic.
SYN_Status	syn_mqtt_subscribe (SYN_MqttClient * client, const char * topic, uint8_t qos) Subscribe to a topic.
SYN_PT_Status	syn_mqtt_task (SYN_PT * pt, SYN_Task * task) Cooperative task for driving the MQTT client.

Macros¶

Type	Name
define	SYN_MQTT5_PROP_ASSIGNED_CLIENT_ID `0x12U`
define	SYN_MQTT5_PROP_AUTH_DATA `0x16U`
define	SYN_MQTT5_PROP_AUTH_METHOD `0x15U`
define	SYN_MQTT5_PROP_CONTENT_TYPE `0x03U`
define	SYN_MQTT5_PROP_CORRELATION_DATA `0x09U`
define	SYN_MQTT5_PROP_MAXIMUM_QOS `0x24U`
define	SYN_MQTT5_PROP_MAX_PACKET_SIZE `0x27U`
define	SYN_MQTT5_PROP_MESSAGE_EXPIRY_INTERVAL `0x02U`
define	SYN_MQTT5_PROP_PAYLOAD_FORMAT_INDICATOR `0x01U`
define	SYN_MQTT5_PROP_REASON_STRING `0x1FU`
define	SYN_MQTT5_PROP_RECEIVE_MAXIMUM `0x21U`
define	SYN_MQTT5_PROP_REQ_PROBLEM_INFO `0x17U`
define	SYN_MQTT5_PROP_REQ_RESPONSE_INFO `0x19U`
define	SYN_MQTT5_PROP_RESPONSE_INFO `0x1AU`
define	SYN_MQTT5_PROP_RESPONSE_TOPIC `0x08U`
define	SYN_MQTT5_PROP_RETAIN_AVAILABLE `0x25U`
define	SYN_MQTT5_PROP_SERVER_KEEP_ALIVE `0x13U`
define	SYN_MQTT5_PROP_SERVER_REFERENCE `0x1CU`
define	SYN_MQTT5_PROP_SESSION_EXPIRY_INTERVAL `0x11U`
define	SYN_MQTT5_PROP_SHARED_SUB_AVAIL `0x2AU`
define	SYN_MQTT5_PROP_SUBSCRIPTION_IDENTIFIER `0x0BU`
define	SYN_MQTT5_PROP_SUB_ID_AVAIL `0x29U`
define	SYN_MQTT5_PROP_TOPIC_ALIAS `0x23U`
define	SYN_MQTT5_PROP_TOPIC_ALIAS_MAXIMUM `0x22U`
define	SYN_MQTT5_PROP_USER_PROPERTY `0x26U`
define	SYN_MQTT5_PROP_WILDCARD_SUB_AVAIL `0x28U`
define	SYN_MQTT5_PROP_WILL_DELAY_INTERVAL `0x18U`

Public Types Documentation¶

enum SYN_MqttRxPhase¶

Non-blocking packet reception states.

enum SYN_MqttRxPhase {
    SYN_MQTT_RX_IDLE,
    SYN_MQTT_RX_REMAINING_LEN,
    SYN_MQTT_RX_PAYLOAD,
    SYN_MQTT_RX_DISCARD
};

enum SYN_MqttState¶

MQTT client connection states.

enum SYN_MqttState {
    SYN_MQTT_DISCONNECTED,
    SYN_MQTT_CONNECTING,
    SYN_MQTT_CONNECTED
};

enum SYN_MqttVersion¶

MQTT Protocol Version.

enum SYN_MqttVersion {
    SYN_MQTT_VERSION_3_1_1 = 4,
    SYN_MQTT_VERSION_5_0 = 5
};

Public Functions Documentation¶

function syn_mqtt5_encode_user_prop¶

Encode an MQTT 5.0 User Property (Key-Value string pair).

size_t syn_mqtt5_encode_user_prop (
    const char * key,
    const char * val,
    uint8_t * buf,
    size_t max_buf_len
)

Parameters:

key Property key string.
val Property value string.
buf [out] Output buffer.
max_buf_len Capacity of output buffer.

Returns:

Number of bytes written, or 0 on error/overflow.

function syn_mqtt_decode_varint¶

Decode a Variable Byte Integer (MQTT 3.1.1 & MQTT 5.0).

bool syn_mqtt_decode_varint (
    const uint8_t * buf,
    size_t buf_len,
    uint32_t * val,
    size_t * bytes_read
)

Parameters:

buf Buffer containing varint bytes.
buf_len Available bytes in buffer.
val [out] Parsed integer value.
bytes_read [out] Number of bytes consumed (1..4).

Returns:

true on success, false if incomplete or malformed (> 4 bytes).

function syn_mqtt_disconnect¶

Disconnect the MQTT client and close underlying TCP socket.

void syn_mqtt_disconnect (
    SYN_MqttClient * client
)

Sends an MQTT DISCONNECT packet if currently connected, then closes the socket and transitions client state to DISCONNECTED.

Parameters:

client Pointer to client context.

function syn_mqtt_encode_varint¶

Encode a Variable Byte Integer (MQTT 3.1.1 & MQTT 5.0).

size_t syn_mqtt_encode_varint (
    uint32_t val,
    uint8_t buf
)

Parameters:

val Value to encode (0..268435455).
buf [out] Output buffer (must have at least 4 bytes capacity).

Returns:

Number of bytes written (1..4).

function syn_mqtt_init¶

Initialize the MQTT client.

SYN_Status syn_mqtt_init (
    SYN_MqttClient * client,
    const char * host,
    uint16_t port,
    const char * client_id,
    const char * username,
    const char * password,
    uint16_t keep_alive_s,
    uint8_t * rx_buf,
    size_t rx_buf_size,
    uint8_t * tx_buf,
    size_t tx_buf_size
)

Configures broker destination, client ID, authentication credentials, keep-alive timing parameters, and network packet buffers.

Parameters:

client Pointer to client context.
host Broker network address string.
port Broker port number.
client_id MQTT client identity string.
username Authentication username (or NULL).
password Authentication password (or NULL).
keep_alive_s Keep-alive timeout parameter in seconds.
rx_buf Receive buffer storage.
rx_buf_size Receive buffer capacity.
tx_buf Transmit buffer storage.
tx_buf_size Transmit buffer capacity.

Returns:

SYN_OK on successful configuration, or error parameter code.

function syn_mqtt_ping¶

Transmit an explicit MQTT PINGREQ packet.

SYN_Status syn_mqtt_ping (
    SYN_MqttClient * client
)

Note: PINGREQ packets are sent automatically by syn_mqtt_task based on the configured keep_alive_s interval. This function allows manual pinging on demand.

Parameters:

client Pointer to client context.

Returns:

SYN_OK on success, SYN_ERROR if not connected or transmit failed.

function syn_mqtt_publish¶

Publish a message to a topic.

SYN_Status syn_mqtt_publish (
    SYN_MqttClient * client,
    const char * topic,
    const void * payload,
    size_t len,
    uint8_t qos,
    bool retain
)

Non-blocking publish command. For QoS 0, queued directly. For QoS 1, tracks acknowledgement state.

Parameters:

client Pointer to client context.
topic Topic name to target.
payload Data payload to send.
len Payload size in bytes.
qos Quality of service level (0 or 1).
retain Retain flag on broker.

Returns:

SYN_OK on queued, or error status if payload bounds exceeded.

function syn_mqtt_subscribe¶

Subscribe to a topic.

SYN_Status syn_mqtt_subscribe (
    SYN_MqttClient * client,
    const char * topic,
    uint8_t qos
)

Formats and queues a subscription request for transmission.

Parameters:

client Pointer to client context.
topic Topic filter string.
qos Requested quality of service.

Returns:

SYN_OK on success.

function syn_mqtt_task¶

Cooperative task for driving the MQTT client.

SYN_PT_Status syn_mqtt_task (
    SYN_PT * pt,
    SYN_Task * task
)

Yields during connection, socket polling, keep-alive pinging, and packet parsing loops. Runs within the cooperative scheduler context.

Parameters:

pt Cooperative protothread handle.
task Corresponding task control block.

Returns:

PT_WAITING or PT_EXITED status.

Macro Definition Documentation¶

define SYN_MQTT5_PROP_ASSIGNED_CLIENT_ID¶

#define SYN_MQTT5_PROP_ASSIGNED_CLIENT_ID `0x12U`

Assigned Client Identifier

define SYN_MQTT5_PROP_AUTH_DATA¶

#define SYN_MQTT5_PROP_AUTH_DATA `0x16U`

Authentication Data

define SYN_MQTT5_PROP_AUTH_METHOD¶

#define SYN_MQTT5_PROP_AUTH_METHOD `0x15U`

Authentication Method

define SYN_MQTT5_PROP_CONTENT_TYPE¶

#define SYN_MQTT5_PROP_CONTENT_TYPE `0x03U`

Content Type

define SYN_MQTT5_PROP_CORRELATION_DATA¶

#define SYN_MQTT5_PROP_CORRELATION_DATA `0x09U`

Correlation Data

define SYN_MQTT5_PROP_MAXIMUM_QOS¶

#define SYN_MQTT5_PROP_MAXIMUM_QOS `0x24U`

Maximum QoS

define SYN_MQTT5_PROP_MAX_PACKET_SIZE¶

#define SYN_MQTT5_PROP_MAX_PACKET_SIZE `0x27U`

Maximum Packet Size

define SYN_MQTT5_PROP_MESSAGE_EXPIRY_INTERVAL¶

#define SYN_MQTT5_PROP_MESSAGE_EXPIRY_INTERVAL `0x02U`

Message Expiry Interval

define SYN_MQTT5_PROP_PAYLOAD_FORMAT_INDICATOR¶

#define SYN_MQTT5_PROP_PAYLOAD_FORMAT_INDICATOR `0x01U`

Payload Format Indicator

define SYN_MQTT5_PROP_REASON_STRING¶

#define SYN_MQTT5_PROP_REASON_STRING `0x1FU`

Reason String

define SYN_MQTT5_PROP_RECEIVE_MAXIMUM¶

#define SYN_MQTT5_PROP_RECEIVE_MAXIMUM `0x21U`

Receive Maximum

define SYN_MQTT5_PROP_REQ_PROBLEM_INFO¶

#define SYN_MQTT5_PROP_REQ_PROBLEM_INFO `0x17U`

Request Problem Information

define SYN_MQTT5_PROP_REQ_RESPONSE_INFO¶

#define SYN_MQTT5_PROP_REQ_RESPONSE_INFO `0x19U`

Request Response Information

define SYN_MQTT5_PROP_RESPONSE_INFO¶

#define SYN_MQTT5_PROP_RESPONSE_INFO `0x1AU`

Response Information

define SYN_MQTT5_PROP_RESPONSE_TOPIC¶

#define SYN_MQTT5_PROP_RESPONSE_TOPIC `0x08U`

Response Topic

define SYN_MQTT5_PROP_RETAIN_AVAILABLE¶

#define SYN_MQTT5_PROP_RETAIN_AVAILABLE `0x25U`

Retain Available

define SYN_MQTT5_PROP_SERVER_KEEP_ALIVE¶

#define SYN_MQTT5_PROP_SERVER_KEEP_ALIVE `0x13U`

Server Keep Alive

define SYN_MQTT5_PROP_SERVER_REFERENCE¶

#define SYN_MQTT5_PROP_SERVER_REFERENCE `0x1CU`

Server Reference

define SYN_MQTT5_PROP_SESSION_EXPIRY_INTERVAL¶

#define SYN_MQTT5_PROP_SESSION_EXPIRY_INTERVAL `0x11U`

Session Expiry Interval

define SYN_MQTT5_PROP_SHARED_SUB_AVAIL¶

#define SYN_MQTT5_PROP_SHARED_SUB_AVAIL `0x2AU`

Shared Subscription Available

define SYN_MQTT5_PROP_SUBSCRIPTION_IDENTIFIER¶

#define SYN_MQTT5_PROP_SUBSCRIPTION_IDENTIFIER `0x0BU`

Subscription Identifier

define SYN_MQTT5_PROP_SUB_ID_AVAIL¶

#define SYN_MQTT5_PROP_SUB_ID_AVAIL `0x29U`

Subscription Identifiers Available

define SYN_MQTT5_PROP_TOPIC_ALIAS¶

#define SYN_MQTT5_PROP_TOPIC_ALIAS `0x23U`

Topic Alias

define SYN_MQTT5_PROP_TOPIC_ALIAS_MAXIMUM¶

#define SYN_MQTT5_PROP_TOPIC_ALIAS_MAXIMUM `0x22U`

Topic Alias Maximum

define SYN_MQTT5_PROP_USER_PROPERTY¶

#define SYN_MQTT5_PROP_USER_PROPERTY `0x26U`

User Property

define SYN_MQTT5_PROP_WILDCARD_SUB_AVAIL¶

#define SYN_MQTT5_PROP_WILDCARD_SUB_AVAIL `0x28U`

Wildcard Subscription Available

define SYN_MQTT5_PROP_WILL_DELAY_INTERVAL¶

#define SYN_MQTT5_PROP_WILL_DELAY_INTERVAL `0x18U`

Will Delay Interval

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