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:

Modules

 Asymcute (MQTT-SN Client) compile configurations
 

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   (1 << CONFIG_ASYMCUTE_BUFSIZE_EXP)
 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.
 

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_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 163 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 234 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 245 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 176 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 189 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 334 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 348 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 405 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 390 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 376 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 362 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