Detailed Description

This module implements the MQTT-SN client according to the MQTT-SN specification version 1.2. MQTT-SN, or Message Queuing Telemetry Transport for Sensor Networks, is a lightweight and efficient messaging protocol designed for constrained environments, particularly suited for low-power, low-bandwidth, and high-latency networks. It is an extension of the widely adopted MQTT protocol, optimized to meet the specific requirements of sensor networks and other resource-constrained devices.

One of the most important technical aspects of MQTT-SN is that it uses the UDP transport protocol instead of TCP used in MQTT. It also uses topic IDs instead of topic strings allowing for shorter UDP datagrams, at the expense of necessity to first register the topic in the gateway prior any usage.

This MQTT-SN Client service is a UDP based service running over the embeNET wireless communication protocol. The MQTT-SN protocol is a version of the popular Message Queuing Telemetry Transport (MQTT) protocol but made suitable for Sensor Networks that utilize UDP transport protocol instead of TCP.

This client supports the following functions:

connecting and disconnecting to the gateway
registering topics
subscribing to topics and receiving messages on that topic
publishing messages on topics

Data Structures
struct	MQTTSNClientEventHandlers
	Structure grouping event callbacks for MQTT-SN client. More...

struct	MQTTSNTopicDescriptor
	Structure describing a single MQTT-SN topic. More...

struct	MQTTSNSessionFlags
	MQTT-SN session flags. More...

struct	MQTTSNClient
	Structure describing the MQTT-SN Client. More...

Macro Definition Documentation

◆ MQTTSN_MAX_TOPIC_NAME_LENGTH

#define MQTTSN_MAX_TOPIC_NAME_LENGTH 38

Maximum length of the MQTT-SN topic name.

◆ MQTTSN_MAX_MESSAGE_DATA

#define MQTTSN_MAX_MESSAGE_DATA 32

Maximum length of the MQTT-SN message data.

◆ MQTTSN_MAX_CLIENT_ID_LENGTH

#define MQTTSN_MAX_CLIENT_ID_LENGTH 23

Maximum length of the MQTT-SN client id.

◆ MQTTSN_CLIENT_GATEWAY_RESPONSE_TIMEOUT_MS

#define MQTTSN_CLIENT_GATEWAY_RESPONSE_TIMEOUT_MS 5000

Gateway response timeout in milliseconds, after which the client assumes the gateway is not responding.

◆ MQTTSN_CLIENT_MAX_TOPICS_TO_SUBSCRIBE

#define MQTTSN_CLIENT_MAX_TOPICS_TO_SUBSCRIBE 10

Maximum number of topics that the client can subscribe to.

◆ MQTTSN_CLIENT_MAX_TOPICS_TO_PUBLISH

#define MQTTSN_CLIENT_MAX_TOPICS_TO_PUBLISH 10

Maximum number of topics that the client can publish to.

Typedef Documentation

◆ MQTTSNTopicId

typedef uint16_t MQTTSNTopicId

Type describing topic id.

◆ MQTTSNOnClientConnected

typedef void(* MQTTSNOnClientConnected) (struct MQTTSNClient *client)

Callback function type describing a function that is called when the MQTT-SN client connects to the gateway.

This callback is called to signal the event that the client successfully connected to the gateway. Once the client is connected, it is ready to publish and receive messages.

Parameters

[in] client pointer to the MQTT-SN client description structure

◆ MQTTSNOnClientDisconnected

typedef void(* MQTTSNOnClientDisconnected) (struct MQTTSNClient *client)

Callback function type describing a function that is called when the MQTT-SN client gets disconnected from the gateway.

This callback is called when the client detects that there is no response from the gateway it was connected to.

Parameters

[in] client pointer to the MQTT-SN client description structure

◆ MQTTSNOnTopicRegisteredByClient

typedef void(* MQTTSNOnTopicRegisteredByClient) (const struct MQTTSNClient *client, MQTTSNTopicId topicId, const char *topicName)

Callback function type describing a function that is called when a topic is successfully registered by the client in the gateway.

This callback is called as a result of client trying to register a topic. It is called when the gateway acknowledges the topic registration assigning a topic id to the topic name.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topicId	topic id assigned by the gateway to the topic name
[in]	topicName	topic name that was registered

◆ MQTTSNOnTopicRegisteredByGateway

typedef void(* MQTTSNOnTopicRegisteredByGateway) (struct MQTTSNClient *client, MQTTSNTopicId topicId, const char *topicName)

Callback function type describing a function that is called when a topic is successfully registered by the gateway.

This callback is called as a result of gateway informing the client about a topic. It is called when the gateway acknowledges the topic registration assigning a topic id to the topic name.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topicId	topic id assigned by the gateway to the topic name
[in]	topicName	topic name that was registered

◆ MQTTSNOnPublishReceived

typedef void(* MQTTSNOnPublishReceived) (struct MQTTSNClient *client, MQTTSNTopicId topicId, const void *data, size_t dataSize)

Callback function type describing a function that is called when a message is received on a topic.

This callback is called when a message is received on a topic that the client subscribed to.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topicId	topic id assigned by the gateway to the topic name
[in]	data	pointer to the message data
[in]	dataSize	length of the message data

◆ MQTTSNTopicDescriptor

typedef struct MQTTSNTopicDescriptor MQTTSNTopicDescriptor

Structure describing a single MQTT-SN topic.

◆ MQTTSNClient

typedef struct MQTTSNClient MQTTSNClient

Structure describing the MQTT-SN Client.

Enumeration Type Documentation

◆ MQTTSNClientState

enum MQTTSNClientState

Possible states of the MQTT-SN client.

Enumerator
MQTTSN_CLIENT_STATE_DISCONNECTED	Client is disconnected from the gateway.
MQTTSN_CLIENT_STATE_CONNECTING	Client is awaiting CONNACK from the gateway.
MQTTSN_CLIENT_STATE_AWAITING_WILL_TOPIC_REQ	Client is awaiting WILL TOPIC REQUEST from the gateway.
MQTTSN_CLIENT_STATE_AWAITING_WILL_MSG_REQ	Client is awaiting WILL MESSAGE REQUEST from the gateway.
MQTTSN_CLIENT_STATE_CONNECTED	Client is connected to the gateway.
MQTTSN_CLIENT_STATE_DISCONNECTING	Client is disconnecting from the gateway.

◆ MQTTSNClientResult

enum MQTTSNClientResult

Possible results of the MQTT-SN client API calls.

Enumerator
MQTTSN_CLIENT_RESULT_OK
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT
MQTTSN_CLIENT_RESULT_FAILED_TO_REGISTER_UDP_SOCKET
MQTTSN_CLIENT_RESULT_FAILED_TO_CREATE_TASK
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET
MQTTSN_CLIENT_RESULT_CONNECT_SERIALIZATION_ERR
MQTTSN_CLIENT_RESULT_BUFFER_OR_CLIENT_IS_NULL
MQTTSN_CLIENT_CLIENTID_FORBIDDEN_LENGTH
MQTTSN_CLIENT_UNEXPECTED_ACK_RECEIVED
MQTTSN_CLIENT_TOPIC_NOT_IN_REGISTRATION
MQTTSN_CLIENT_REGACK_DESERIALIZATION_FAILED
MQTTSN_CLIENT_PUBLISH_DESERIALIZATION_FAILED
MQTTSN_CLIENT_SUBACK_DESERIALIZATION_FAILED
MQTTSN_CLIENT_GW_ERR_CONGESTION
MQTTSN_CLIENT_GW_INVALID_TOPIC_ID
MQTTSN_CLIENT_GW_ERR_NOT_SUPPORTED
MQTTSN_CLIENT_UNKNOWN_ERROR
MQTTSN_CLIENT_WILL_TOPIC_SERIALIZATION_ERROR
MQTTSN_CLIENT_UNEXPECTED_WILL_TOPIC_REQ_RECEIVED
MQTTSN_CLIENT_UNEXPECTED_WILL_MSG_REQ_RECEIVED
MQTTSN_CLIENT_WILL_MSG_SERIALIZATION_ERROR
MQTTSN_CLIENT_PING_SERIALIZATION_ERROR
MQTTSN_CLIENT_TXTOPICS_BUFFER_FULL
MQTTSN_CLIENT_REGISTER_SERIALIZATION_ERROR
MQTTSN_CLIENT_PUBLISH_SERIALIZATION_ERROR
MQTTSN_CLIENT_TOPIC_NOT_REGISTERED
MQTTSN_CLIENT_SUBSCRIBE_SERIALIZATION_ERROR
MQTTSN_CLIENT_RECEIVED_BROKEN_PACKET
MQTTSN_CLIENT_CLIENT_NOT_CONNECTED
MQTTSN_CLIENT_CLIENT_NOT_DISCONNECTED
MQTTSN_CLIENT_DISCONNECT_SERIALIZATION_ERROR
MQTTSN_CLIENT_RESULT_TOPIC_NOT_FOUND
MQTTSN_CLIENT_RESULT_TOPIC_NOT_PENDING_REGISTRATION
MQTTSN_CLIENT_RESULT_DISCONNECT_SERIALIZATION_ERROR
MQTTSN_CLIENT_SUBSCRIBE_BUFFER_FULL
MQTTSN_CLIENT_TOPIC_EXCEEDS_SET_MAX_LEN

Function Documentation

◆ MQTTSN_CLIENT_Init()

MQTTSNClientResult MQTTSN_CLIENT_Init	(	MQTTSNClient *	client,
		uint16_t	port,
		const char *	clientId,
		const MQTTSNClientEventHandlers *	eventHandlers
	)

Initializes the MQTT-SN client.

This function initializes the MQTT-SN client descriptor structure to a sane state using the provided setting. It also registers embeNET tasks required for maintenance. Once the client is initialized, it is ready to establish connection with the gateway.

Note: This function must be called before any other function of the MQTT-SN client API.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	port	UDP port number to use on the client side
[in]	clientId	a 1 to 23 character long unique string that identifies the MQTT-SN client
[in]	eventHandlers	structure gathering user defined callbacks for handling client specific events

Return values

MQTTSN_CLIENT_RESULT_OK	if the client was initialized successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_RESULT_FAILED_TO_CREATE_TASK	if one or more tasks failed to be created

◆ MQTTSN_CLIENT_Deinit()

void MQTTSN_CLIENT_Deinit ( MQTTSNClient * client )

Deinitializes the MQTT-SN client.

This function deinitializes the MQTTSNClient, closing the UDP socket (if open) and destroying all internal tasks.

Parameters

[in] client pointer to the MQTT-SN client description structure

◆ MQTTSN_CLIENT_Connect()

MQTTSNClientResult MQTTSN_CLIENT_Connect	(	MQTTSNClient *	client,
		EMBENET_IPV6 const *	gatewayAddress,
		uint16_t	gatewayPort,
		uint16_t	keepAliveTime,
		uint16_t	pingPeriod,
		const char *	willTopic,
		const uint8_t *	willMsg
	)

Makes the client try to connect to a gateway.

This function opens the UDP socket that will be used for communication with the gateway and makes the client start the connection procedure against a given gateway using the provided settings. Once the connection is established, the MQTTSNClientEventHandlers.onConnected callback is called (as provided in MQTTSN_CLIENT_Init). If the connection procedure fails, the MQTTSNClientEventHandlers.onDisconnected callback is called (as provided in MQTTSN_CLIENT_Init).

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	gatewayAddress	IPv6 address of the MQTT Gateway
[in]	gatewayPort	UDP port number of the MQTT Gateway
[in]	keepAliveTime	time (in seconds) after which the gateway assumes the client is disconnected, if no message from client in that time is received
[in]	pingPeriod	minimum time between messages sent from the client. When no user messages are sent, PING should be sent instead. This value should be less than keepAliveTime
[in]	willTopic	topic to which will shall be published if gateway deems the client lost. Nullable if will is not used.
[in]	willMsg	message that shall be published if gateway deems the client lost. Nullable if will is not used.

Return values

MQTTSN_CLIENT_RESULT_OK	if the connection procedure started successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_CLIENT_NOT_DISCONNECTED	if the client is already connected or in the process of connecting or disconnecting
MQTTSN_CLIENT_RESULT_FAILED_TO_REGISTER_UDP_SOCKET	if the UDP socket could not be opened
MQTTSN_CLIENT_RESULT_CONNECT_SERIALIZATION_ERR	if the connection request could not be serialized
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET	if the connection request could not be sent via UDP socket

◆ MQTTSN_CLIENT_CleanConnect()

MQTTSNClientResult MQTTSN_CLIENT_CleanConnect	(	MQTTSNClient *	client,
		EMBENET_IPV6 const *	gatewayAddress,
		uint16_t	gatewayPort,
		uint16_t	keepAliveTime,
		uint16_t	pingPeriod,
		const char *	willTopic,
		const uint8_t *	willMsg
	)

Makes the client try to connect to a gateway using clean connection.

This function opens the UDP socket that will be used for communication with the gateway and makes the client start the connection procedure against a given gateway using the provided settings. Once the connection is established, the MQTTSNClientEventHandlers.onConnected callback is called (as provided in MQTTSN_CLIENT_Init). If the connection procedure fails, the MQTTSNClientEventHandlers.onDisconnected callback is called (as provided in MQTTSN_CLIENT_Init).

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	gatewayAddress	IPv6 address of the MQTT Gateway
[in]	gatewayPort	UDP port number of the MQTT Gateway
[in]	keepAliveTime	time (in seconds) after which the gateway assumes the client is disconnected, if no message from client in that time is received
[in]	pingPeriod	minimum time between messages sent from the client. When no user messages are sent, PING should be sent instead. This value should be less than keepAliveTime
[in]	willTopic	topic to which will shall be published if gateway deems the client lost. Nullable if will is not used.
[in]	willMsg	message that shall be published if gateway deems the client lost. Nullable if will is not used.

Return values

MQTTSN_CLIENT_RESULT_OK	if the connection procedure started successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_CLIENT_NOT_DISCONNECTED	if the client is already connected or in the process of connecting or disconnecting
MQTTSN_CLIENT_RESULT_FAILED_TO_REGISTER_UDP_SOCKET	if the UDP socket could not be opened
MQTTSN_CLIENT_RESULT_CONNECT_SERIALIZATION_ERR	if the connection request could not be serialized
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET	if the connection request could not be sent via UDP socket

◆ MQTTSN_CLIENT_Disconnect()

MQTTSNClientResult MQTTSN_CLIENT_Disconnect ( MQTTSNClient * client )

Disconnects the client from the gateway.

This function starts the disconnection procedure. Once completed, the MQTTSNClientEventHandlers.onDisconnected callback is called (as provided in MQTTSN_CLIENT_Init).

Return values

MQTTSN_CLIENT_RESULT_OK	if the connection procedure started successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_CLIENT_NOT_CONNECTED	if the client is not connected to the gateway
MQTTSN_CLIENT_RESULT_DISCONNECT_SERIALIZATION_ERROR	if the disconnection request could not be serialized
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET	if the disconnection request could not be sent via UDP socket

◆ MQTTSN_CLIENT_RegisterTopic()

MQTTSNClientResult MQTTSN_CLIENT_RegisterTopic	(	MQTTSNClient *	client,
		const char *	topic,
		MQTTSNOnTopicRegisteredByClient	onTopicRegisteredCallback
	)

Registers a topic in the gateway.

Sends REGISTER packet to the gateway with provided topic string starting registration procedure. Once completed the provided onTopicRegisteredCallback is called.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topic	topic string to register
[in]	onTopicRegisteredCallback	callback that will be called when the topic is registered

Return values

MQTTSN_CLIENT_RESULT_OK	if the topic registration procedure started successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_CLIENT_NOT_CONNECTED	if the client is not connected to the gateway
MQTTSN_CLIENT_TXTOPICS_BUFFER_FULL	if the client has no more space to register new topics
MQTTSN_CLIENT_REGISTER_SERIALIZATION_ERROR	if the registration request could not be serialized
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET	if the registration request could not be sent via UDP socket

◆ MQTTSN_CLIENT_GetTopicId()

MQTTSNTopicId MQTTSN_CLIENT_GetTopicId	(	MQTTSNClient *	client,
		const char *	topic
	)

Gets the id of the registered topic.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topic	topic string to search for

Returns: topic id or 0 if the provided topic could not be found

◆ MQTTSN_CLIENT_PublishMessage()

MQTTSNClientResult MQTTSN_CLIENT_PublishMessage	(	MQTTSNClient *	client,
		const char *	topic,
		const char *	message,
		size_t	messageLen
	)

Publishes a message on a topic given the topic string.

Publishes a message using PUBLISH packet to a provided topic. Currently only supports QoS0

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topic	string containing regular topic name
[in]	message	string of characters to be used as a payload
[in]	messageLen	length of message

Return values

MQTTSN_CLIENT_RESULT_OK	if the message was published successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_CLIENT_NOT_CONNECTED	if the client is not connected to the gateway

◆ MQTTSN_CLIENT_PublishMessageById()

MQTTSNClientResult MQTTSN_CLIENT_PublishMessageById	(	MQTTSNClient *	client,
		MQTTSNTopicId	topicId,
		const char *	message,
		size_t	messageLen
	)

Publishes a message on a topic given the topic id.

Publishes a message using PUBLISH packet to a provided topic. Currently only supports QoS0

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topicId	id of a target topic
[in]	message	string of characters to be used as a payload
[in]	messageLen	length of message

Return values

MQTTSN_CLIENT_RESULT_OK	if the message was published successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_PUBLISH_SERIALIZATION_ERROR	if the publish request could not be serialized
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET	if the publish request could not be sent via UDP socket

◆ MQTTSN_CLIENT_Subscribe()

MQTTSNClientResult MQTTSN_CLIENT_Subscribe	(	MQTTSNClient *	client,
		const char *	topic,
		MQTTSNOnPublishReceived	onPublishReceivedCallback
	)

Subscribes to the topic.

Subscribes to the topic by a regular topic name via SUBSCRIBE packet. Once subscribed, the client will receive messages published on the topic through the provided callback.

Parameters

[in]	client	pointer to the MQTT-SN client description structure
[in]	topic	string containing regular topic name
[in]	onPublishReceivedCallback	callback that will be called when a message is received on the topic

Return values

MQTTSN_CLIENT_RESULT_OK	if the client subscribed successfully
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT	if one or more arguments are invalid
MQTTSN_CLIENT_CLIENT_NOT_CONNECTED	if the client is not connected to the gateway
MQTTSN_CLIENT_SUBSCRIBE_BUFFER_FULL	if the client has no more space to subscribe to new topics
MQTTSN_CLIENT_SUBSCRIBE_SERIALIZATION_ERROR	if the subscribe request could not be serialized
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET	if the subscribe request could not be sent via UDP socket

MQTT-SN Client

Detailed Description

Data Structures

Macro Definition Documentation

◆ MQTTSN_MAX_TOPIC_NAME_LENGTH

◆ MQTTSN_MAX_MESSAGE_DATA

◆ MQTTSN_MAX_CLIENT_ID_LENGTH

◆ MQTTSN_CLIENT_GATEWAY_RESPONSE_TIMEOUT_MS

◆ MQTTSN_CLIENT_MAX_TOPICS_TO_SUBSCRIBE

◆ MQTTSN_CLIENT_MAX_TOPICS_TO_PUBLISH

Typedef Documentation

◆ MQTTSNTopicId

◆ MQTTSNOnClientConnected

◆ MQTTSNOnClientDisconnected

◆ MQTTSNOnTopicRegisteredByClient

◆ MQTTSNOnTopicRegisteredByGateway

◆ MQTTSNOnPublishReceived

◆ MQTTSNTopicDescriptor

◆ MQTTSNClient

Enumeration Type Documentation

◆ MQTTSNClientState

◆ MQTTSNClientResult

Function Documentation

◆ MQTTSN_CLIENT_Init()

◆ MQTTSN_CLIENT_Deinit()

◆ MQTTSN_CLIENT_Connect()

◆ MQTTSN_CLIENT_CleanConnect()

◆ MQTTSN_CLIENT_Disconnect()

◆ MQTTSN_CLIENT_RegisterTopic()

◆ MQTTSN_CLIENT_GetTopicId()

◆ MQTTSN_CLIENT_PublishMessage()

◆ MQTTSN_CLIENT_PublishMessageById()

◆ MQTTSN_CLIENT_Subscribe()