MQTT-SN Client (Asymcute)

Asymcute is an asynchronous MQTT-SN implementation. More...

Detailed Description

Asymcute is an asynchronous MQTT-SN implementation.

About

Asymcute is a asynchronous MQTT-SN client implementation, aiming at providing the user a high degree of flexibility. It provides a flexible interface that allows users to issue any number of concurrent requests to one or more different gateways simultaneously.

Implementation state

Implemented features:

Missing features:

Files

file  asymcute.h
 Asymcute MQTT-SN interface definition.
 

Data Structures

struct  asymcute_req
 Asymcute request context. More...
 
struct  asymcute_con
 Asymcute connection context. More...
 
struct  asymcute_topic
 Data-structure for holding topics and their registration status. More...
 
struct  asymcute_sub
 Data-structure holding the state of subscriptions. More...
 
struct  asymcute_will
 Data structure for defining a last will. More...
 

Macros

#define ASYMCUTE_BUFSIZE   (128U)
 Default buffer size used for receive and request buffers.
 
#define ASYMCUTE_HANDLER_PRIO   (THREAD_PRIORITY_MAIN - 2)
 Default priority for Asymcute's handler thread.
 
#define ASYMCUTE_HANDLER_STACKSIZE   (THREAD_STACKSIZE_DEFAULT)
 Default stack size for Asymcute's handler thread.
 
#define ASYMCUTE_LISTENER_PRIO   (THREAD_PRIORITY_MAIN - 3)
 Default priority for an Asymcute listener thread. More...
 
#define ASYMCUTE_LISTENER_STACKSIZE   (THREAD_STACKSIZE_DEFAULT)
 Default stack size for an Asymcute listener thread.
 
#define ASYMCUTE_ID_MAXLEN   (32U)
 Maximum client ID length. More...
 
#define ASYMCUTE_TOPIC_MAXLEN   (32U)
 Maximum topic length. More...
 
#define ASYMCUTE_KEEPALIVE   (360) /* -> 6 min*/
 Keep alive interval [in s] communicated to the gateway. More...
 
#define ASYMCUTE_KEEPALIVE_PING   ((ASYMCUTE_KEEPALIVE / 4) * 3)
 Interval to use for sending periodic ping messages. More...
 
#define ASYMCUTE_T_RETRY   (10U) /* -> 10 sec */
 Resend interval [in seconds]. More...
 
#define ASYMCUTE_N_RETRY   (3U)
 Number of retransmissions until requests time out. More...
 

Typedefs

typedef struct asymcute_con asymcute_con_t
 Forward type declaration for connections contexts.
 
typedef struct asymcute_req asymcute_req_t
 Forward type declaration for request contexts.
 
typedef struct asymcute_sub asymcute_sub_t
 Forward type declaration for subscription contexts.
 
typedef struct asymcute_topic asymcute_topic_t
 Forward type declaration for topic definitions.
 
typedef struct asymcute_will asymcute_will_t
 Forward type declaration for last will definitions.
 
typedef void(* asymcute_evt_cb_t) (asymcute_req_t *req, unsigned evt_type)
 Event callback used for communicating connection and request related events to the user. More...
 
typedef void(* asymcute_sub_cb_t) (const asymcute_sub_t *sub, unsigned evt_type, const void *data, size_t len, void *arg)
 Callback triggered on events for active subscriptions. More...
 
typedef unsigned(* asymcute_to_cb_t) (asymcute_con_t *con, asymcute_req_t *req)
 Context specific timeout callback, only used internally.
 

Enumerations

enum  {
  ASYMCUTE_OK = 0, ASYMCUTE_OVERFLOW = -1, ASYMCUTE_GWERR = -2, ASYMCUTE_NOTSUP = -3,
  ASYMCUTE_BUSY = -4, ASYMCUTE_REGERR = -5, ASYMCUTE_SUBERR = -6
}
 Return values used by public Asymcute functions. More...
 
enum  {
  ASYMCUTE_TIMEOUT, ASYMCUTE_CANCELED, ASYMCUTE_REJECTED, ASYMCUTE_CONNECTED,
  ASYMCUTE_DISCONNECTED, ASYMCUTE_REGISTERED, ASYMCUTE_PUBLISHED, ASYMCUTE_SUBSCRIBED,
  ASYMCUTE_UNSUBSCRIBED
}
 Possible event types passed to the event callback. More...
 

Functions

static bool asymcute_req_in_use (const asymcute_req_t *req)
 Check if a given request context is currently used. More...
 
static bool asymcute_sub_active (const asymcute_sub_t *sub)
 Check if a given subscription is currently active. More...
 
static void asymcute_topic_reset (asymcute_topic_t *topic)
 Reset the given topic. More...
 
static bool asymcute_topic_is_reg (const asymcute_topic_t *topic)
 Check if a given topic is currently registered with a gateway. More...
 
static bool asymcute_topic_is_init (const asymcute_topic_t *topic)
 Check if a given topic is initialized. More...
 
static bool asymcute_topic_equal (const asymcute_topic_t *a, const asymcute_topic_t *b)
 Compare two given topics and check if they are equal. More...
 
int asymcute_topic_init (asymcute_topic_t *topic, const char *topic_name, uint16_t topic_id)
 Initialize the given topic. More...
 
int asymcute_listener_run (asymcute_con_t *con, char *stack, size_t stacksize, char priority, asymcute_evt_cb_t callback)
 Start a listener thread. More...
 
void asymcute_handler_run (void)
 Start the global Asymcute handler thread for processing timeouts and keep alive events. More...
 
bool asymcute_is_connected (const asymcute_con_t *con)
 Check if the given connection context is connected to a gateway. More...
 
int asymcute_connect (asymcute_con_t *con, asymcute_req_t *req, sock_udp_ep_t *server, const char *cli_id, bool clean, asymcute_will_t *will)
 Connect to the given MQTT-SN gateway. More...
 
int asymcute_disconnect (asymcute_con_t *con, asymcute_req_t *req)
 Close the given connection. More...
 
int asymcute_register (asymcute_con_t *con, asymcute_req_t *req, asymcute_topic_t *topic)
 Register a given topic with the connected gateway. More...
 
int asymcute_publish (asymcute_con_t *con, asymcute_req_t *req, const asymcute_topic_t *topic, const void *data, size_t data_len, uint8_t flags)
 Publish the given data to the given topic. More...
 
int asymcute_subscribe (asymcute_con_t *con, asymcute_req_t *req, asymcute_sub_t *sub, asymcute_topic_t *topic, asymcute_sub_cb_t callback, void *arg, uint8_t flags)
 Subscribe to a given topic. More...
 
int asymcute_unsubscribe (asymcute_con_t *con, asymcute_req_t *req, asymcute_sub_t *sub)
 Cancel an active subscription. More...
 

Macro Definition Documentation

◆ ASYMCUTE_ID_MAXLEN

#define ASYMCUTE_ID_MAXLEN   (32U)

Maximum client ID length.

Note
Must be less than (256 - 8) and less than (ASYMCUTE_BUFSIZE - 8)

Definition at line 104 of file asymcute.h.

◆ ASYMCUTE_KEEPALIVE

#define ASYMCUTE_KEEPALIVE   (360) /* -> 6 min*/

Keep alive interval [in s] communicated to the gateway.

For the default value, see spec v1.2, section 7.2 -> T_WAIT: > 5 min

Definition at line 122 of file asymcute.h.

◆ ASYMCUTE_KEEPALIVE_PING

#define ASYMCUTE_KEEPALIVE_PING   ((ASYMCUTE_KEEPALIVE / 4) * 3)

Interval to use for sending periodic ping messages.

The default behavior of this implementation is to send ping messages as soon as three quarters of the keep alive interval have passed.

Note
Must be less than ASYMCUTE_KEEPALIVE

Definition at line 134 of file asymcute.h.

◆ ASYMCUTE_LISTENER_PRIO

#define ASYMCUTE_LISTENER_PRIO   (THREAD_PRIORITY_MAIN - 3)

Default priority for an Asymcute listener thread.

Note
Must be of higher priority than ASYMCUTE_HANDLER_PRIO

Definition at line 88 of file asymcute.h.

◆ ASYMCUTE_N_RETRY

#define ASYMCUTE_N_RETRY   (3U)

Number of retransmissions until requests time out.

For the default value, see spec v1.2, section 7.2 -> N_RETRY: 3-5

Definition at line 152 of file asymcute.h.

◆ ASYMCUTE_T_RETRY

#define ASYMCUTE_T_RETRY   (10U) /* -> 10 sec */

Resend interval [in seconds].

For the default value, see spec v1.2, section 7.2 -> T_RETRY: 10 to 15 sec

Definition at line 143 of file asymcute.h.

◆ ASYMCUTE_TOPIC_MAXLEN

#define ASYMCUTE_TOPIC_MAXLEN   (32U)

Maximum topic length.

Note
Must be less than (256 - 8) AND less than (ASYMCUTE_BUFSIZE - 8).

Definition at line 113 of file asymcute.h.

Typedef Documentation

◆ asymcute_evt_cb_t

typedef void(* asymcute_evt_cb_t) (asymcute_req_t *req, unsigned evt_type)

Event callback used for communicating connection and request related events to the user.

Parameters
[in]reqpointer to the request context that triggered the event, may be NULL of unsolicited events
[in]evt_typetype of the event

Definition at line 216 of file asymcute.h.

◆ asymcute_sub_cb_t

typedef void(* asymcute_sub_cb_t) (const asymcute_sub_t *sub, unsigned evt_type, const void *data, size_t len, void *arg)

Callback triggered on events for active subscriptions.

Parameters
[in]subpointer to subscription context triggering this event
[in]evt_typetype of the event
[in]dataincoming data for PUBLISHED events, may be NULL
[in]lenlength of data in bytes
[in]arguser supplied argument

Definition at line 227 of file asymcute.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return values used by public Asymcute functions.

Enumerator
ASYMCUTE_OK 

all is good

ASYMCUTE_OVERFLOW 

error: insufficient buffer space

ASYMCUTE_GWERR 

error: bad gateway connection state

ASYMCUTE_NOTSUP 

error: feature not supported

ASYMCUTE_BUSY 

error: context already in use

ASYMCUTE_REGERR 

error: registration invalid

ASYMCUTE_SUBERR 

error: subscription invalid

Definition at line 158 of file asymcute.h.

◆ anonymous enum

anonymous enum

Possible event types passed to the event callback.

Enumerator
ASYMCUTE_TIMEOUT 

request timed out

ASYMCUTE_CANCELED 

request was canceled

ASYMCUTE_REJECTED 

request was rejected

ASYMCUTE_CONNECTED 

connected to gateway

ASYMCUTE_DISCONNECTED 

connection got disconnected

ASYMCUTE_REGISTERED 

topic was registered

ASYMCUTE_PUBLISHED 

data was published

ASYMCUTE_SUBSCRIBED 

client was subscribed to topic

ASYMCUTE_UNSUBSCRIBED 

client was unsubscribed from topic

Definition at line 171 of file asymcute.h.

Function Documentation

◆ asymcute_connect()

int asymcute_connect ( asymcute_con_t con,
asymcute_req_t req,
sock_udp_ep_t server,
const char *  cli_id,
bool  clean,
asymcute_will_t will 
)

Connect to the given MQTT-SN gateway.

Parameters
[in,out]conconnection to use
[in,out]reqrequest context to use for CONNECT procedure
[in]serverUDP endpoint of the target gateway
[in]cli_idclient ID to register with the gateway
[in]cleanset true to start a clean session
[in]willlast will (currently not implemented)
Returns
ASYMCUTE_OK if CONNECT message has been sent
ASYMCUTE_NOTSUP if last will was given (temporary until implemented)
ASYMCUTE_OVERFLOW if cli_id is larger than ASYMCUTE_ID_MAXLEN
ASYMCUTE_GWERR if the connection is not in idle state
ASYMCUTE_BUSY if the given request context is already in use

◆ asymcute_disconnect()

int asymcute_disconnect ( asymcute_con_t con,
asymcute_req_t req 
)

Close the given connection.

Parameters
[in,out]conconnection to close
[in,out]reqrequest context to use for DISCONNECT procedure
Returns
ASYMCUTE_OK if DISCONNECT message has been sent
ASYMCUTE_GWERR if connection context is not connected
ASYMCUTE_BUSY if the given request context is already in use

◆ asymcute_handler_run()

void asymcute_handler_run ( void  )

Start the global Asymcute handler thread for processing timeouts and keep alive events.

This function is typically called during system initialization.

◆ asymcute_is_connected()

bool asymcute_is_connected ( const asymcute_con_t con)

Check if the given connection context is connected to a gateway.

Parameters
[in]conconnection to check
Returns
true if context is connected
false if not connected

◆ asymcute_listener_run()

int asymcute_listener_run ( asymcute_con_t con,
char *  stack,
size_t  stacksize,
char  priority,
asymcute_evt_cb_t  callback 
)

Start a listener thread.

Note
Must have higher priority then the handler thread (defined by ASYMCUTE_HANDLER_PRIO)
Parameters
[in]conconnection context to use for this connection
[in]stackstack used to run the listener thread
[in]stacksizesize of stack in bytes
[in]prioritypriority of the listener thread created by this function
[in]callbackuser callback for notification about connection related events
Returns
ASYMCUTE_OK on success
ASYMCUTE_BUSY if connection context is already in use

◆ asymcute_publish()

int asymcute_publish ( asymcute_con_t con,
asymcute_req_t req,
const asymcute_topic_t topic,
const void *  data,
size_t  data_len,
uint8_t  flags 
)

Publish the given data to the given topic.

Parameters
[in]conconnection to use
[in,out]reqrequest context used for PUBLISH procedure
[in]topicpublish data to this topic
[in]dataactual payload to send
[in]data_lensize of data in bytes
[in]flagsadditional flags (QoS level, DUP, and RETAIN)
Returns
ASYMCUTE_OK if PUBLISH message has been sent
ASYMCUTE_NOTSUP if unsupported flags have been set
ASYMCUTE_OVERFLOW if data does not fit into transmit buffer
ASYMCUTE_REGERR if given topic is not registered
ASYMCUTE_GWERR if not connected to a gateway
ASYMCUTE_BUSY if the given request context is already in use

◆ asymcute_register()

int asymcute_register ( asymcute_con_t con,
asymcute_req_t req,
asymcute_topic_t topic 
)

Register a given topic with the connected gateway.

Parameters
[in]conconnection to use
[in,out]reqrequest context to use for REGISTER procedure
[in,out]topictopic to register
Returns
ASYMCUTE_OK if REGISTER message has been sent
ASYMCUTE_REGERR if topic is already registered
ASYMCUTE_GWERR if not connected to a gateway
ASYMCUTE_BUSY if the given request context is already in use

◆ asymcute_req_in_use()

static bool asymcute_req_in_use ( const asymcute_req_t req)
inlinestatic

Check if a given request context is currently used.

Parameters
[in]reqrequest context to check
Returns
true if context is currently used
false if context is not used

Definition at line 316 of file asymcute.h.

◆ asymcute_sub_active()

static bool asymcute_sub_active ( const asymcute_sub_t sub)
inlinestatic

Check if a given subscription is currently active.

Parameters
[in]subsubscription context to check
Returns
true if subscription is active
false if subscription is not active

Definition at line 330 of file asymcute.h.

◆ asymcute_subscribe()

int asymcute_subscribe ( asymcute_con_t con,
asymcute_req_t req,
asymcute_sub_t sub,
asymcute_topic_t topic,
asymcute_sub_cb_t  callback,
void *  arg,
uint8_t  flags 
)

Subscribe to a given topic.

Parameters
[in]conconnection to use
[in,out]reqrequest context used for SUBSCRIBE procedure
[out]subsubscription context to store subscription state
[in,out]topictopic to subscribe to, must be initialized (see asymcute_topic_init())
[in]callbackuser callback triggered on events for this subscription
[in]arguser supplied argument passed to the event callback
[in]flagsadditional flags (QoS level and DUP)
Returns
ASYMCUTE_OK if SUBSCRIBE message has been sent
ASYMCUTE_NOTSUP if invalid or unsupported flags have been set
ASYMCUTE_REGERR if topic is not initialized
ASYMCUTE_GWERR if not connected to a gateway
ASYMCUTE_SUBERR if already subscribed to the given topic
ASYMCUTE_BUSY if the given request context is already in use

◆ asymcute_topic_equal()

static bool asymcute_topic_equal ( const asymcute_topic_t a,
const asymcute_topic_t b 
)
inlinestatic

Compare two given topics and check if they are equal.

Parameters
[in]atopic A
[in]btopic B
Returns
true if both topics are equal
false if topics differ

Definition at line 387 of file asymcute.h.

◆ asymcute_topic_init()

int asymcute_topic_init ( asymcute_topic_t topic,
const char *  topic_name,
uint16_t  topic_id 
)

Initialize the given topic.

Parameters
[out]topictopic to initialize
[in]topic_nametopic name (ASCII), may be NULL if topic should use a pre-defined topic ID
[in]topic_idpre-defined topic ID, or don't care if topic_name is given
Returns
ASYMCUTE_OK on success
ASYMCUTE_REGERR if topic is already registered
ASYMCUTE_OVERFLOW if topic name does not fit into buffer or if pre- defined topic ID is invalid

◆ asymcute_topic_is_init()

static bool asymcute_topic_is_init ( const asymcute_topic_t topic)
inlinestatic

Check if a given topic is initialized.

Parameters
[in]topictopic to check
Returns
true if topic is initialized
false if topic is not initialized

Definition at line 372 of file asymcute.h.

◆ asymcute_topic_is_reg()

static bool asymcute_topic_is_reg ( const asymcute_topic_t topic)
inlinestatic

Check if a given topic is currently registered with a gateway.

Parameters
[in]topictopic to check
Returns
true if topic is registered
false if topic is not registered

Definition at line 358 of file asymcute.h.

◆ asymcute_topic_reset()

static void asymcute_topic_reset ( asymcute_topic_t topic)
inlinestatic

Reset the given topic.

Warning
Make sure that the given topic is not used by any subscription or last will when calling this function
Parameters
[out]topictopic to reset

Definition at line 344 of file asymcute.h.

◆ asymcute_unsubscribe()

int asymcute_unsubscribe ( asymcute_con_t con,
asymcute_req_t req,
asymcute_sub_t sub 
)

Cancel an active subscription.

Parameters
[in]conconnection to use
[in,out]reqrequest context used for UNSUBSCRIBE procedure
[in,out]subsubscription to cancel
Returns
ASYMCUTE_OK if UNSUBSCRIBE message has been sent
ASYMCUTE_SUBERR if subscription is not currently active
ASYMCUTE_GWERR if not connected to a gateway
ASYMCUTE_BUSY if the given request context is already in use