MQTT-SN Client library

Data Structures
struct	mqtt_sn_data
	Abstracts memory buffers. More...
union	mqtt_sn_evt_param
	Event metadata. More...
struct	mqtt_sn_evt
	MQTT-SN event structure to be handled by the event callback. More...
struct	mqtt_sn_transport
	Structure to describe an MQTT-SN transport. More...
struct	mqtt_sn_will_update
	Structure for storing will update state. More...
struct	mqtt_sn_client
	Structure describing an MQTT-SN client. More...

Macros
#define	MQTT_SN_DATA_STRING_LITERAL(literal)
	Initialize memory buffer from C literal string.
#define	MQTT_SN_DATA_BYTES(...)
	Initialize memory buffer from single bytes.

Typedefs
typedef void(*	mqtt_sn_evt_cb_t) (struct mqtt_sn_client *client, const struct mqtt_sn_evt *evt)
	Asynchronous event notification callback registered by the application.

Enumerations
enum	mqtt_sn_qos { MQTT_SN_QOS_0 , MQTT_SN_QOS_1 , MQTT_SN_QOS_2 , MQTT_SN_QOS_M1 }
	Quality of Service. More...
enum	mqtt_sn_topic_type { MQTT_SN_TOPIC_TYPE_NORMAL , MQTT_SN_TOPIC_TYPE_PREDEF , MQTT_SN_TOPIC_TYPE_SHORT }
	MQTT-SN topic types. More...
enum	mqtt_sn_return_code { MQTT_SN_CODE_ACCEPTED = 0x00 , MQTT_SN_CODE_REJECTED_CONGESTION = 0x01 , MQTT_SN_CODE_REJECTED_TOPIC_ID = 0x02 , MQTT_SN_CODE_REJECTED_NOTSUP = 0x03 }
	MQTT-SN return codes. More...
enum	mqtt_sn_evt_type {   MQTT_SN_EVT_CONNECTED , MQTT_SN_EVT_DISCONNECTED , MQTT_SN_EVT_ASLEEP , MQTT_SN_EVT_AWAKE ,   MQTT_SN_EVT_PUBLISH , MQTT_SN_EVT_PINGRESP , MQTT_SN_EVT_ADVERTISE , MQTT_SN_EVT_GWINFO ,   MQTT_SN_EVT_SEARCHGW }
	Event types that can be emitted by the library. More...

Functions
int	mqtt_sn_client_init (struct mqtt_sn_client *client, const struct mqtt_sn_data *client_id, struct mqtt_sn_transport *transport, mqtt_sn_evt_cb_t evt_cb, void *tx, size_t txsz, void *rx, size_t rxsz)
	Initialize a client.
void	mqtt_sn_client_deinit (struct mqtt_sn_client *client)
	Deinitialize the client.
int	mqtt_sn_add_gw (struct mqtt_sn_client *client, uint8_t gw_id, struct mqtt_sn_data gw_addr)
	Manually add a Gateway, bypasing the normal search process.
int	mqtt_sn_search (struct mqtt_sn_client *client, uint8_t radius)
	Initiate the MQTT-SN GW Search process.
int	mqtt_sn_connect (struct mqtt_sn_client *client, bool will, bool clean_session)
	Connect the client.
int	mqtt_sn_disconnect (struct mqtt_sn_client *client)
	Disconnect the client.
int	mqtt_sn_sleep (struct mqtt_sn_client *client, uint16_t duration)
	Set the client into sleep state.
int	mqtt_sn_subscribe (struct mqtt_sn_client *client, enum mqtt_sn_qos qos, struct mqtt_sn_data *topic_name)
	Subscribe to a given topic.
int	mqtt_sn_unsubscribe (struct mqtt_sn_client *client, enum mqtt_sn_qos qos, struct mqtt_sn_data *topic_name)
	Unsubscribe from a topic.
int	mqtt_sn_publish (struct mqtt_sn_client *client, enum mqtt_sn_qos qos, struct mqtt_sn_data *topic_name, bool retain, struct mqtt_sn_data *data)
	Publish a value.
int	mqtt_sn_input (struct mqtt_sn_client *client)
	Check the transport for new incoming data.
int	mqtt_sn_get_topic_name (struct mqtt_sn_client *client, uint16_t id, struct mqtt_sn_data *topic_name)
	Get topic name by topic ID.
int	mqtt_sn_predefine_topic (struct mqtt_sn_client *client, uint16_t topic_id, struct mqtt_sn_data *topic_name)
	Predefine topic.
int	mqtt_sn_define_short_topic (struct mqtt_sn_client *client, struct mqtt_sn_data *topic_name)
	Define a short topic.
int	mqtt_sn_update_will_topic (struct mqtt_sn_client *client)
	Send a will topic update to the server.
int	mqtt_sn_update_will_message (struct mqtt_sn_client *client)
	Send a will message update to the server.

Detailed Description

Since

3.3

Version

0.1.0

Macro Definition Documentation

MQTT_SN_DATA_BYTES

#define MQTT_SN_DATA_BYTES

(

...

)

#include <zephyr/net/mqtt_sn.h>

Value:

        ((struct mqtt_sn_data){(uint8_t[]){__VA_ARGS__}, sizeof((uint8_t[]){__VA_ARGS__})})

Initialize memory buffer from single bytes.

Use it as follows:

struct mqtt_sn_data data = MQTT_SN_DATA_BYTES(0x13, 0x37);

MQTT_SN_DATA_STRING_LITERAL

#define MQTT_SN_DATA_STRING_LITERAL

(

literal

)

#include <zephyr/net/mqtt_sn.h>

Value:

((struct mqtt_sn_data){literal, sizeof(literal) - 1})

Initialize memory buffer from C literal string.

Use it as follows:

struct mqtt_sn_data topic = MQTT_SN_DATA_STRING_LITERAL("/zephyr");

Parameters

[in]

literal

Literal string from which to generate mqtt_sn_data object.

Typedef Documentation

mqtt_sn_evt_cb_t

typedef void(* mqtt_sn_evt_cb_t) (struct mqtt_sn_client *client, const struct mqtt_sn_evt *evt)

#include <zephyr/net/mqtt_sn.h>

Asynchronous event notification callback registered by the application.

Parameters

[in]	client	Identifies the client for which the event is notified.
[in]	evt	Event description along with result and associated parameters (if any).

Enumeration Type Documentation

mqtt_sn_evt_type

enum mqtt_sn_evt_type

#include <zephyr/net/mqtt_sn.h>

Event types that can be emitted by the library.

Enumerator
MQTT_SN_EVT_CONNECTED	Connected to a gateway.
MQTT_SN_EVT_DISCONNECTED	Disconnected.
MQTT_SN_EVT_ASLEEP	Entered ASLEEP state.
MQTT_SN_EVT_AWAKE	Entered AWAKE state.
MQTT_SN_EVT_PUBLISH	Received a PUBLISH message.
MQTT_SN_EVT_PINGRESP	Received a PINGRESP.
MQTT_SN_EVT_ADVERTISE	Received a ADVERTISE.
MQTT_SN_EVT_GWINFO	Received a GWINFO.
MQTT_SN_EVT_SEARCHGW	Received a SEARCHGW.

mqtt_sn_qos

enum mqtt_sn_qos

#include <zephyr/net/mqtt_sn.h>

Quality of Service.

QoS 0-2 work the same as basic MQTT, QoS -1 is an MQTT-SN addition. QOS -1 is not supported yet.

Enumerator
MQTT_SN_QOS_0	QOS 0.
MQTT_SN_QOS_1	QOS 1.
MQTT_SN_QOS_2	QOS 2.
MQTT_SN_QOS_M1	QOS -1.

mqtt_sn_return_code

enum mqtt_sn_return_code

#include <zephyr/net/mqtt_sn.h>

MQTT-SN return codes.

Enumerator
MQTT_SN_CODE_ACCEPTED	Accepted.
MQTT_SN_CODE_REJECTED_CONGESTION	Rejected: congestion.
MQTT_SN_CODE_REJECTED_TOPIC_ID	Rejected: Invalid Topic ID.
MQTT_SN_CODE_REJECTED_NOTSUP	Rejected: Not Supported.

mqtt_sn_topic_type

enum mqtt_sn_topic_type

#include <zephyr/net/mqtt_sn.h>

MQTT-SN topic types.

Enumerator
MQTT_SN_TOPIC_TYPE_NORMAL	Normal topic. It allows usage of any valid UTF-8 string as a topic name.
MQTT_SN_TOPIC_TYPE_PREDEF	Pre-defined topic. It allows usage of a two-byte identifier representing a topic name for which the corresponding topic name is known in advance by both the client and the gateway/server.
MQTT_SN_TOPIC_TYPE_SHORT	Short topic. It allows usage of a two-byte string as a topic name.

Function Documentation

mqtt_sn_add_gw()

int mqtt_sn_add_gw	(	struct mqtt_sn_client *	client,
		uint8_t	gw_id,
		struct mqtt_sn_data	gw_addr )

#include <zephyr/net/mqtt_sn.h>

Manually add a Gateway, bypasing the normal search process.

This function manually creates a gateway that is stored internal to the library.

Parameters

client	The MQTT-SN client to connect.
gw_id	Single byte Gateway Identifier
gw_addr	Address data structure to be used by the transport layer.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_client_deinit()

void mqtt_sn_client_deinit

(

struct mqtt_sn_client *

client

)

#include <zephyr/net/mqtt_sn.h>

Deinitialize the client.

This removes all topics and publishes, and also de-inits the transport.

Parameters

client

The MQTT-SN client to deinitialize.

mqtt_sn_client_init()

int mqtt_sn_client_init	(	struct mqtt_sn_client *	client,
		const struct mqtt_sn_data *	client_id,
		struct mqtt_sn_transport *	transport,
		mqtt_sn_evt_cb_t	evt_cb,
		void *	tx,
		size_t	txsz,
		void *	rx,
		size_t	rxsz )

#include <zephyr/net/mqtt_sn.h>

Initialize a client.

Parameters

client	The MQTT-SN client to initialize.
client_id	The ID to be used by the client.
transport	The transport to be used by the client.
evt_cb	The event callback function for the client.
tx	Pointer to the transmit buffer.
txsz	Size of the transmit buffer.
rx	Pointer to the receive buffer.
rxsz	Size of the receive buffer.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_connect()

int mqtt_sn_connect	(	struct mqtt_sn_client *	client,
		bool	will,
		bool	clean_session )

#include <zephyr/net/mqtt_sn.h>

Connect the client.

Parameters

client	The MQTT-SN client to connect.
will	Flag indicating if a Will message should be sent.
clean_session	Flag indicating if a clean session should be started.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_define_short_topic()

int mqtt_sn_define_short_topic	(	struct mqtt_sn_client *	client,
		struct mqtt_sn_data *	topic_name )

#include <zephyr/net/mqtt_sn.h>

Define a short topic.

Can be called before mqtt_sn_connect, because short topics are never cleared.

Parameters

[in]	client	The MQTT-SN client to define the topic on.
[in]	topic_name	The name of the topic. Must be exactly 2 bytes long.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_disconnect()

int mqtt_sn_disconnect

(

struct mqtt_sn_client *

client

)

#include <zephyr/net/mqtt_sn.h>

Disconnect the client.

Parameters

client

The MQTT-SN client to disconnect.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_get_topic_name()

int mqtt_sn_get_topic_name	(	struct mqtt_sn_client *	client,
		uint16_t	id,
		struct mqtt_sn_data *	topic_name )

#include <zephyr/net/mqtt_sn.h>

Get topic name by topic ID.

Parameters

[in]	client	The MQTT-SN client that uses this topic.
[in]	id	Topic identifier.
[out]	topic_name	Will be assigned to topic name.

Returns

0 on success, -ENOENT if topic ID doesn't exist, or -EINVAL on invalid arguments.

mqtt_sn_input()

int mqtt_sn_input

(

struct mqtt_sn_client *

client

)

#include <zephyr/net/mqtt_sn.h>

Check the transport for new incoming data.

Call this function periodically, or if you have good reason to believe there is any data. If the client's transport struct contains a poll-function, this function is non-blocking.

Parameters

client

The MQTT-SN client to check for incoming data.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_predefine_topic()

int mqtt_sn_predefine_topic	(	struct mqtt_sn_client *	client,
		uint16_t	topic_id,
		struct mqtt_sn_data *	topic_name )

#include <zephyr/net/mqtt_sn.h>

Predefine topic.

Can be called before mqtt_sn_connect, because predefined topics are never cleared. If you call it afterwards, it has to be called before calling mqtt_sn_input for the first time after the connect, to prevent race conditions where incoming publications use predefined topics which were not defined, yet.

Parameters

[in]	client	The MQTT-SN client to define the topic on.
[in]	topic_id	Topic identifier.
[in]	topic_name	The name of the topic.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_publish()

int mqtt_sn_publish	(	struct mqtt_sn_client *	client,
		enum mqtt_sn_qos	qos,
		struct mqtt_sn_data *	topic_name,
		bool	retain,
		struct mqtt_sn_data *	data )

#include <zephyr/net/mqtt_sn.h>

Publish a value.

If the topic is not yet registered with the gateway, the library takes care of it.

Parameters

client	The MQTT-SN client that should publish.
qos	The desired quality of service for the publish.
topic_name	The name of the topic to publish to.
retain	Flag indicating if the message should be retained by the broker.
data	The data to be published.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_search()

int mqtt_sn_search	(	struct mqtt_sn_client *	client,
		uint8_t	radius )

#include <zephyr/net/mqtt_sn.h>

Initiate the MQTT-SN GW Search process.

Parameters

client	The MQTT-SN client to connect.
radius	Broadcast radius for the search message.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_sleep()

int mqtt_sn_sleep	(	struct mqtt_sn_client *	client,
		uint16_t	duration )

#include <zephyr/net/mqtt_sn.h>

Set the client into sleep state.

Parameters

client	The MQTT-SN client to be put to sleep.
duration	Sleep duration (in seconds).

Returns

0 on success, negative errno code on failure.

mqtt_sn_subscribe()

int mqtt_sn_subscribe	(	struct mqtt_sn_client *	client,
		enum mqtt_sn_qos	qos,
		struct mqtt_sn_data *	topic_name )

#include <zephyr/net/mqtt_sn.h>

Subscribe to a given topic.

Parameters

client	The MQTT-SN client that should subscribe.
qos	The desired quality of service for the subscription.
topic_name	The name of the topic to subscribe to.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_unsubscribe()

int mqtt_sn_unsubscribe	(	struct mqtt_sn_client *	client,
		enum mqtt_sn_qos	qos,
		struct mqtt_sn_data *	topic_name )

#include <zephyr/net/mqtt_sn.h>

Unsubscribe from a topic.

Parameters

client	The MQTT-SN client that should unsubscribe.
qos	The quality of service used when subscribing.
topic_name	The name of the topic to unsubscribe from.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_update_will_message()

int mqtt_sn_update_will_message

(

struct mqtt_sn_client *

client

)

#include <zephyr/net/mqtt_sn.h>

Send a will message update to the server.

Call this to send the will message stored in client->will_msg to the server. Should be used if you changed the value after connecting.

Warning

Since there is no message ID in the will message update message, this can't be done without race conditions. Contribute to newer versions of the specification if you want this to be changed.

Parameters

[in]

client

The MQTT-SN client to use for sending the update.

Returns

0 or a negative error code (errno.h) indicating reason of failure.

mqtt_sn_update_will_topic()

int mqtt_sn_update_will_topic

(

struct mqtt_sn_client *

client

)

#include <zephyr/net/mqtt_sn.h>

Send a will topic update to the server.

Call this to send the will topic stored in client->will_topic to the server. Should be used if you changed the value after connecting. The variables client->will_retain and client->will_qos will also be sent as part of the update.

Warning

Since there is no message ID in the will topic update message, this can't be done without race conditions. Contribute to newer versions of the specification if you want this to be changed.

Parameters

[in]

client

The MQTT-SN client to use for sending the update.

Returns

0 or a negative error code (errno.h) indicating reason of failure.