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
◆ MQTTSN_MAX_TOPIC_NAME_LENGTH
#define MQTTSN_MAX_TOPIC_NAME_LENGTH 38 |
Maximum length of the MQTT-SN topic name.
◆ MQTTSN_MAX_MESSAGE_LENGTH
#define MQTTSN_MAX_MESSAGE_LENGTH 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_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.
◆ MQTTSN_CLIENT_MAX_PINGRESP_LOST
#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.
◆ 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
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 |
[in] | disconnectionReason | reason why the client got disconnected (see MQTTSNClientDisconnectionReason) |
◆ MQTTSNOnTopicRegisteredByClient
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.
- 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
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 |
◆ MQTTSNOnTopicSubscribedByClient
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.
- Parameters
-
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topicId | topic id |
[in] | topicName | topic name |
◆ MQTTSNOnTopicUnsubscribedByClient
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.
- Parameters
-
[in] | client | pointer to the MQTT-SN client description structure |
[in] | topicId | topic id |
[in] | topicName | topic name |
◆ MQTTSNOnPublishReceived
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.
- 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 |
◆ MQTTSNOnPublishSent
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.
- 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 |
◆ 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
Possible results of the MQTT-SN client API calls.
Enumerator |
---|
MQTTSN_CLIENT_RESULT_OK | Indicates that the operation was successful. |
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT | Indicates that one or more arguments are invalid. |
MQTTSN_CLIENT_RESULT_FAILED_TO_REGISTER_UDP_SOCKET | Indicates that the operation failed because the client failed to register the UDP socket in the embeNET stack. |
MQTTSN_CLIENT_RESULT_FAILED_TO_CREATE_TASK | Indicates that the operation failed because because the client failed to create an embeNET task. |
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET | Indicates that the operation failed because the client failed to send out packet (network error) |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | Indicates that the operation failed because the client failed to serialize a packet (internal error) |
MQTTSN_CLIENT_RESULT_CLIENT_NOT_CONNECTED | Indicates that the operation failed because the client is not connected. |
MQTTSN_CLIENT_RESULT_CLIENT_ALREADY_CONNECTED | Indicates that the operation failed because the client is already connected. |
MQTTSN_CLIENT_RESULT_TOPIC_NOT_FOUND | Indicates that the operation failed because the requested topic was not found. |
MQTTSN_CLIENT_RESULT_PUBLISH_BUFFER_FULL | Indicates that the operation failed because the topic buffer is full. |
MQTTSN_CLIENT_RESULT_SUBSCRIBE_BUFFER_FULL | Indicates that the operation failed because the subscribe buffer is full. |
MQTTSN_CLIENT_RESULT_TOPIC_TOO_LONG | Indicates that the operation failed because the requested topic name is too long. |
MQTTSN_CLIENT_RESULT_MESSAGE_TOO_LONG | Indicates that the operation failed because the requested message is too long. |
◆ MQTTSNPacketQoS
Possible levels of QoS.
Enumerator |
---|
MQTTSN_QOS0 | QoS0: At most once delivery. |
MQTTSN_QOS1 | QoS1: At least once delivery. |
MQTTSN_QOS2 | QoS2: Exactly once delivery. |
◆ MQTTSNClientDisconnectionReason
Possible disconnection reasons.
Enumerator |
---|
MQTTSN_CLIENT_DISCONNECTED_DUE_TO_OWN_REQUEST | Indicates that the client got disconnected due to own request - MQTTSN_CLIENT_Disconnect was called. |
MQTTSN_CLIENT_DISCONNECTED_BY_GATEWAY | Indicates that the client got disconnected due to message from gateway. |
MQTTSN_CLIENT_DISCONNECTED_DUE_TO_TIMEOUT | Indicates that the client got disconnected due to gateway communication timeout. |
◆ MQTTSN_CLIENT_Init()
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()
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, |
| | uint32_t | keepAliveTimeMs, |
| | uint32_t | gatewayTimeoutMs, |
| | 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).
- 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] | keepAliveTimeMs | time (in milliseconds) after which the gateway assumes the client is disconnected, if no message from client in that time is received. In case there are no user generated messages produced, the client will send PING message automatically. |
[in] | gatewayTimeoutMs | gateway response timeout (in milliseconds), after which the client assumes the gateway is not responding |
[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 |
- 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_RESULT_CLIENT_ALREADY_CONNECTED | 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_FAILED_TO_SERIALIZE_PACKET | 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()
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_RESULT_CLIENT_NOT_CONNECTED | if the client is not connected to the gateway |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | 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()
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_RESULT_CLIENT_NOT_CONNECTED | if the client is not connected to the gateway |
MQTTSN_CLIENT_RESULT_PUBLISH_BUFFER_FULL | if the client has no more space to register new topics |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | 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()
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()
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] | qos | QoS level of message. |
[in] | message | message data to be published |
[in] | messageLen | length of message, must not be larger than MQTTSN_MAX_MESSAGE_LENGTH |
[in] | onPublishSentCallback | callback that will be called when the message is sent to the topic |
- 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_RESULT_CLIENT_NOT_CONNECTED | if the client is not connected to the gateway |
MQTTSN_CLIENT_TOPIC_NOT_REGISTERED | if the topic was not previously registered |
MQTTSN_CLIENT_RESULT_MESSAGE_TOO_LONG | if the message is too long |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | if the publish message could not be serialized |
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET | if the publish message could not be sent via UDP socket |
◆ MQTTSN_CLIENT_PublishMessageById()
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] | qos | QoS level when publishing the message |
[in] | message | message data to be published |
[in] | messageLen | length of message, must not be larger than MQTTSN_MAX_MESSAGE_LENGTH |
[in] | onPublishSentCallback | callback that will be called when the message is sent to the topic |
- 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_RESULT_CLIENT_NOT_CONNECTED | if the client is not connected to the gateway |
MQTTSN_CLIENT_TOPIC_NOT_REGISTERED | if the topic was not previously registered |
MQTTSN_CLIENT_RESULT_MESSAGE_TOO_LONG | if the message is too long |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | if the publish message could not be serialized |
MQTTSN_CLIENT_RESULT_FAILED_TO_SEND_PACKET | if the publish message could not be sent via UDP socket |
◆ MQTTSN_CLIENT_Subscribe()
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] | 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 |
- 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_RESULT_CLIENT_NOT_CONNECTED | if the client is not connected to the gateway |
MQTTSN_CLIENT_RESULT_SUBSCRIBE_BUFFER_FULL | if the client has no more space to subscribe to new topics |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | 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 |
◆ MQTTSN_CLIENT_Unsubscribe()
Unsubscribes from the topic.
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.
- Parameters
-
[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 |
- Return values
-
MQTTSN_CLIENT_RESULT_OK | if the client unsubscribed successfully |
MQTTSN_CLIENT_RESULT_INVALID_INPUT_ARGUMENT | if one or more arguments are invalid |
MQTTSN_CLIENT_RESULT_CLIENT_NOT_CONNECTED | if the client is not connected to the gateway |
MQTTSN_CLIENT_RESULT_TOPIC_NOT_FOUND | if the topic was not found in the list of subscribed topics |
MQTTSN_CLIENT_RESULT_FAILED_TO_SERIALIZE_PACKET | 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 |