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:
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 | MQTTSNQosMsg |
Structure describing the MQTTSN QOS(1-2) message. More... | |
struct | MQTTSNClient |
Structure describing the MQTT-SN Client. More... | |
#define MQTTSN_MAX_TOPIC_NAME_LENGTH 38 |
Maximum length of the MQTT-SN topic name.
#define MQTTSN_MAX_MESSAGE_DATA 32 |
Maximum length of the MQTT-SN message data.
#define MQTTSN_MAX_CLIENT_ID_LENGTH 23 |
Maximum length of the MQTT-SN client id.
#define MQTTSN_CLIENT_GATEWAY_RESPONSE_TIMEOUT_MS 10000 |
Gateway response timeout in milliseconds, after which the client assumes the gateway is not responding.
#define MQTTSN_CLIENT_MAX_TOPICS_TO_SUBSCRIBE 10 |
Maximum number of topics that the client can subscribe to.
#define MQTTSN_CLIENT_MAX_TOPICS_TO_PUBLISH 10 |
Maximum number of topics that the client can publish to.
#define MQTTSN_CLIENT_MAX_PINGRESP_LOST 3 |
Maximum number of consecutive PINGRESP messages that can be lost before the client assumes the gateway is not responding.
typedef uint16_t MQTTSNTopicId |
Type describing topic id.
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.
[in] | client | pointer to the MQTT-SN client description structure |
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.
[in] | client | pointer to the MQTT-SN client description structure |
typedef void(* MQTTSNOnTopicRegisteredByClient) (const struct MQTTSNClient *client, MQTTSNTopicId topicId, char const *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.
[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 |
typedef void(* MQTTSNOnTopicRegisteredByGateway) (struct MQTTSNClient *client, MQTTSNTopicId topicId, char const *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.
[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 |
typedef void(* MQTTSNOnTopicSubscribedByClient) (const struct MQTTSNClient *client, MQTTSNTopicId topicId, char const *topicName) |
Callback function type describing a function that is called when the client successfully subscribes to a topic.
This callback is called as a result of client trying to subscribe to a topic. It is called when the gateway acknowledges the topic subscription.
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topicId | topic id |
[in] | topicName | topic name |
typedef void(* MQTTSNOnTopicUnsubscribedByClient) (const struct MQTTSNClient *client, MQTTSNTopicId topicId, char const *topicName) |
Callback function type describing a function that is called when the client successfully unsubscribes from a topic.
This callback is called as a result of client trying to unsubscribe from a topic. It is called when the gateway acknowledges the topic unsubscription.
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topicId | topic id |
[in] | topicName | topic name |
typedef void(* MQTTSNOnPublishReceived) (struct MQTTSNClient *client, MQTTSNTopicId topicId, void const *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.
[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 |
typedef void(* MQTTSNOnPublishSent) (struct MQTTSNClient *client, MQTTSNTopicId topicId, void const *data, size_t dataSize) |
Callback function type describing a function that is called when a message is sent to a topic.
This callback is called when a message is sent to a topic that the client published to.
[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 |
typedef struct MQTTSNTopicDescriptor MQTTSNTopicDescriptor |
Structure describing a single MQTT-SN topic.
typedef struct MQTTSNQosMsg MQTTSNQosMsg |
Structure describing the MQTTSN QOS(1-2) message.
typedef struct MQTTSNClient MQTTSNClient |
Structure describing the MQTT-SN Client.
enum MQTTSNClientState |
Possible states of the MQTT-SN client.
enum MQTTSNClientResult |
Possible results of the MQTT-SN client API calls.
enum MQTTSNPacketQoS |
MQTTSNClientResult MQTTSN_CLIENT_Init | ( | MQTTSNClient * | client, |
uint16_t | port, | ||
char const * | clientId, | ||
MQTTSNClientEventHandlers const * | 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.
[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 |
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 |
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.
[in] | client | pointer to the MQTT-SN client description structure |
MQTTSNClientResult MQTTSN_CLIENT_Connect | ( | MQTTSNClient * | client, |
EMBENET_IPV6 const * | gatewayAddress, | ||
uint16_t | gatewayPort, | ||
uint16_t | keepAliveTime, | ||
uint16_t | pingPeriod, | ||
char const * | willTopic, | ||
uint8_t const * | willMsg, | ||
uint8_t const | qosRetransmissions ) |
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).
[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 PING messages sent from the client to test the connection. This value should be less than keepAliveTime |
[in] | willTopic | topic to which the will message shall be published if gateway deems the client lost. Nullable if will is not used. |
[in] | willMsg | message that shall be published as the last will if gateway deems the client lost. Nullable if will is not used. |
[in] | qosRetransmissions | maximum number of retransmissions for QoS messages |
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 |
MQTTSNClientResult MQTTSN_CLIENT_CleanConnect | ( | MQTTSNClient * | client, |
EMBENET_IPV6 const * | gatewayAddress, | ||
uint16_t | gatewayPort, | ||
uint16_t | keepAliveTime, | ||
uint16_t | pingPeriod, | ||
char const * | willTopic, | ||
uint8_t const * | willMsg, | ||
uint8_t const | qosRetransmissions ) |
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).
[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 PING messages sent from the client to test the connection. This value should be less than keepAliveTime |
[in] | willTopic | topic to which the will message shall be published if gateway deems the client lost. Nullable if will is not used. |
[in] | willMsg | message that shall be published as the last will if gateway deems the client lost. Nullable if will is not used. |
[in] | qosRetransmissions | maximum number of retransmissions for QoS messages |
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 |
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).
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 |
MQTTSNClientResult MQTTSN_CLIENT_RegisterTopic | ( | MQTTSNClient * | client, |
char const * | 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.
[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 |
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 |
MQTTSNTopicId MQTTSN_CLIENT_GetTopicId | ( | MQTTSNClient * | client, |
char const * | topic ) |
Gets the id of the registered topic.
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topic | topic string to search for |
MQTTSNClientResult MQTTSN_CLIENT_PublishMessage | ( | MQTTSNClient * | client, |
char const * | topic, | ||
MQTTSNPacketQoS | qos, | ||
char const * | message, | ||
size_t | messageLen, | ||
MQTTSNOnPublishSent | onPublishSentCallback ) |
Publishes a message on a topic given the topic string.
Publishes a message using PUBLISH packet to a provided topic. Currently only supports QoS0
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topic | string containing regular topic name |
[in] | qos | QoS level of message. |
[in] | message | string of characters to be used as a payload |
[in] | messageLen | length of message |
[in] | onPublishSentCallback | callback that will be called when the message is sent to the topic |
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 |
MQTTSNClientResult MQTTSN_CLIENT_PublishMessageById | ( | MQTTSNClient * | client, |
MQTTSNTopicId | topicId, | ||
MQTTSNPacketQoS | qos, | ||
char const * | message, | ||
size_t | messageLen, | ||
MQTTSNOnPublishSent | onPublishSentCallback ) |
Publishes a message on a topic given the topic id.
Publishes a message using PUBLISH packet to a provided topic. Currently only supports QoS0
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topicId | id of a target topic |
[in] | qos | QoS level when publishing the message |
[in] | message | string of characters to be used as a payload |
[in] | messageLen | length of message |
[in] | onPublishSentCallback | callback that will be called when the message is sent to the topic |
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 |
MQTTSNClientResult MQTTSN_CLIENT_Subscribe | ( | MQTTSNClient * | client, |
char const * | topic, | ||
MQTTSNPacketQoS | qos, | ||
MQTTSNOnTopicSubscribedByClient | onTopicSubscribedByClient, | ||
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.
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topic | string containing regular topic name |
[in] | qos | requested QoS level of the subscription |
[in] | onTopicSubscribedByClient | callback that will be called when the client subscribes to the topic |
[in] | onPublishReceivedCallback | callback that will be called when a message is received on the topic |
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 |
MQTTSNClientResult MQTTSN_CLIENT_Unsubscribe | ( | MQTTSNClient * | client, |
char const * | topic, | ||
MQTTSNOnTopicUnsubscribedByClient | onTopicUnsubscribedByClient ) |
Unsubscribes from the topic by a regular topic name via UNSUBSCRIBE packet. Once unsubscribed, the client will no longer receive messages published on the topic.
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topic | string containing regular topic name |
[in] | onTopicUnsubscribedByClient | callback that will be called when the client unsubscribes from the topic |
MQTTSN_CLIENT_RESULT_OK | if the client unsubscribed 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_UNSUBSCRIBE_SERIALIZATION_ERROR | if the unsubscribe request could not be serialized |
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET | if the unsubscribe request could not be sent via UDP socket |
Any question or remarks? Just write us a message!
Feel free to get in touch