Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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_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__})})
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
Abstracts memory buffers.
Definition mqtt_sn.h:85

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]literalLiteral 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]clientIdentifies the client for which the event is notified.
[in]evtEvent description along with result and associated parameters (if any).

Enumeration Type Documentation

◆ 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

#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

#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

#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
clientThe MQTT-SN client to connect.
gw_idSingle byte Gateway Identifier
gw_addrAddress 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
clientThe 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
clientThe MQTT-SN client to initialize.
client_idThe ID to be used by the client.
transportThe transport to be used by the client.
evt_cbThe event callback function for the client.
txPointer to the transmit buffer.
txszSize of the transmit buffer.
rxPointer to the receive buffer.
rxszSize 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
clientThe MQTT-SN client to connect.
willFlag indicating if a Will message should be sent.
clean_sessionFlag 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
clientThe 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]clientThe MQTT-SN client that uses this topic.
[in]idTopic identifier.
[out]topic_nameWill 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
clientThe 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.

Has to be called after mqtt_sn_connect, if a clear session is started. Otherwise, the clearing will also remove all predefined topics. Additionally, 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]clientThe MQTT-SN client to define the topic on.
[in]topic_idTopic identifier.
[in]topic_nameThe 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
clientThe MQTT-SN client that should publish.
qosThe desired quality of service for the publish.
topic_nameThe name of the topic to publish to.
retainFlag indicating if the message should be retained by the broker.
dataThe 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
clientThe MQTT-SN client to connect.
radiusBroadcast 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
clientThe MQTT-SN client to be put to sleep.
durationSleep 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
clientThe MQTT-SN client that should subscribe.
qosThe desired quality of service for the subscription.
topic_nameThe 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
clientThe MQTT-SN client that should unsubscribe.
qosThe quality of service used when subscribing.
topic_nameThe 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]clientThe 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]clientThe MQTT-SN client to use for sending the update.
Returns
0 or a negative error code (errno.h) indicating reason of failure.