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_client
	Structure describing an MQTT-SN client. More...

Macros
#define	MQTT_SN_DATA_STRING_LITERAL(literal)   ((struct mqtt_sn_data){literal, sizeof(literal) - 1})
	Initialize memory buffer from C literal string.
#define	MQTT_SN_DATA_BYTES(...)    ((struct mqtt_sn_data) { (uint8_t[]){ __VA_ARGS__ }, sizeof((uint8_t[]){ __VA_ARGS__ })})
	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 }
	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_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.

Detailed Description

Macro Definition Documentation

MQTT_SN_DATA_BYTES

#define MQTT_SN_DATA_BYTES

(

...

)

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

#include <zephyr/net/mqtt_sn.h>

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

)

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

#include <zephyr/net/mqtt_sn.h>

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_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_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_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_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_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.