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:

Connecting to multiple gateways simultaneously
Registration of topic names
Publishing of data (QoS 0 and QoS 1)
Subscription to topics
Pre-defined topic IDs as well as short and normal topic names

Missing features:

Gateway discovery process not implemented
Last will feature not implemented
No support for QoS level 2
No support for QoS level -1
No support for wildcard characters in topic names when subscribing
Actual granted QoS level on subscription is ignored

Modules
	Asymcute (MQTT-SN Client) compile configurations
	Compile-time configuration options for Asymcute, an asynchronous MQTT-SN implementation based on the OASIS MQTT-SN protocol.

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

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.

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.

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 , ASYMCUTE_SENDERR = -7 }
	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.

static bool	asymcute_sub_active (const asymcute_sub_t *sub)
	Check if a given subscription is currently active.

static void	asymcute_topic_reset (asymcute_topic_t *topic)
	Reset the given topic.

static bool	asymcute_topic_is_reg (const asymcute_topic_t *topic)
	Check if a given topic is currently registered with a gateway.

static bool	asymcute_topic_is_short (const asymcute_topic_t *topic)
	Check if a given topic is a short topic.

static bool	asymcute_topic_is_predef (const asymcute_topic_t *topic)
	Check if a given topic is a pre-defined topic.

static bool	asymcute_topic_is_init (const asymcute_topic_t *topic)
	Check if a given topic is initialized.

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.

int	asymcute_topic_init (asymcute_topic_t topic, const char topic_name, uint16_t topic_id)
	Initialize the given topic.

void	asymcute_handler_run (void)
	Start the global Asymcute handler thread for processing timeouts and keep alive events.

bool	asymcute_is_connected (const asymcute_con_t *con)
	Check if the given connection context is connected to a gateway.

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, asymcute_evt_cb_t callback)
	Connect to the given MQTT-SN gateway.

int	asymcute_disconnect (asymcute_con_t con, asymcute_req_t req)
	Close the given connection.

int	asymcute_register (asymcute_con_t con, asymcute_req_t req, asymcute_topic_t *topic)
	Register a given topic with the connected gateway.

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.

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.

int	asymcute_unsubscribe (asymcute_con_t con, asymcute_req_t req, asymcute_sub_t *sub)
	Cancel an active subscription.

Macro Definition Documentation

◆ ASYMCUTE_HANDLER_PRIO

#define ASYMCUTE_HANDLER_PRIO (THREAD_PRIORITY_MAIN - 2)

Default priority for Asymcute's handler thread.

Definition at line 152 of file asymcute.h.

◆ ASYMCUTE_HANDLER_STACKSIZE

#define ASYMCUTE_HANDLER_STACKSIZE (THREAD_STACKSIZE_DEFAULT)

Default stack size for Asymcute's handler thread.

Definition at line 159 of file asymcute.h.

Typedef Documentation

◆ asymcute_con_t

typedef struct asymcute_con asymcute_con_t

Forward type declaration for connections contexts.

Definition at line 194 of file asymcute.h.

◆ 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]	req	pointer to the request context that triggered the event, may be NULL of unsolicited events
[in]	evt_type	type of the event

Definition at line 224 of file asymcute.h.

◆ asymcute_req_t

typedef struct asymcute_req asymcute_req_t

Forward type declaration for request contexts.

Definition at line 199 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]	sub	pointer to subscription context triggering this event
[in]	evt_type	type of the event
[in]	data	incoming data for PUBLISHED events, may be NULL
[in]	len	length of `data` in bytes
[in]	arg	user supplied argument

Definition at line 235 of file asymcute.h.

◆ asymcute_sub_t

typedef struct asymcute_sub asymcute_sub_t

Forward type declaration for subscription contexts.

Definition at line 204 of file asymcute.h.

◆ asymcute_to_cb_t

typedef unsigned(* asymcute_to_cb_t) (asymcute_con_t *con, asymcute_req_t *req)

Context specific timeout callback, only used internally.

Definition at line 248 of file asymcute.h.

◆ asymcute_topic_t

typedef struct asymcute_topic asymcute_topic_t

Forward type declaration for topic definitions.

Definition at line 209 of file asymcute.h.

◆ asymcute_will_t

typedef struct asymcute_will asymcute_will_t

Forward type declaration for last will definitions.

Definition at line 214 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
ASYMCUTE_SENDERR	error: unable to sent packet

Definition at line 165 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 179 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,
		asymcute_evt_cb_t	callback
	)

Connect to the given MQTT-SN gateway.

Parameters

[in,out]	con	connection to use
[in,out]	req	request context to use for CONNECT procedure
[in]	server	UDP endpoint of the target gateway
[in]	cli_id	client ID to register with the gateway
[in]	clean	set `true` to start a clean session
[in]	will	last will (currently not implemented)
[in]	callback	user callback triggered on defined events

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 initializing the socket for the connection failed; ASYMCUTE_BUSY if the connection or the request context are in use

◆ asymcute_disconnect()

int asymcute_disconnect	(	asymcute_con_t *	con,
		asymcute_req_t *	req
	)

Close the given connection.

Parameters

[in,out]	con	connection to close
[in,out]	req	request 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] con connection to check

Returns: true if context is connected; false if not connected

◆ 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]	con	connection to use
[in,out]	req	request context used for PUBLISH procedure
[in]	topic	publish data to this topic
[in]	data	actual payload to send
[in]	data_len	size of `data` in bytes
[in]	flags	additional 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]	con	connection to use
[in,out]	req	request context to use for REGISTER procedure
[in,out]	topic	topic 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] req request context to check

Returns: true if context is currently used; false if context is not used

Definition at line 323 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] sub subscription context to check

Returns: true if subscription is active; false if subscription is not active

Definition at line 337 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]	con	connection to use
[in,out]	req	request context used for SUBSCRIBE procedure
[out]	sub	subscription context to store subscription state
[in,out]	topic	topic to subscribe to, must be initialized (see asymcute_topic_init())
[in]	callback	user callback triggered on events for this subscription
[in]	arg	user supplied argument passed to the event callback
[in]	flags	additional 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]	a	topic A
[in]	b	topic B

Returns: true if both topics are equal; false if topics differ

Definition at line 422 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]	topic	topic to initialize
[in]	topic_name	topic name (ASCII), may be NULL if topic should use a pre-defined topic ID
[in]	topic_id	pre-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] topic topic to check

Returns: true if topic is initialized; false if topic is not initialized

Definition at line 407 of file asymcute.h.

◆ asymcute_topic_is_predef()

static bool asymcute_topic_is_predef ( const asymcute_topic_t * topic )

inlinestatic

Check if a given topic is a pre-defined topic.

Parameters

[in] topic topic to check

Returns: true if topic is pre-defined; false if topic is not pre-defined

Definition at line 393 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] topic topic to check

Returns: true if topic is registered; false if topic is not registered

Definition at line 365 of file asymcute.h.

◆ asymcute_topic_is_short()

static bool asymcute_topic_is_short ( const asymcute_topic_t * topic )

inlinestatic

Check if a given topic is a short topic.

Parameters

[in] topic topic to check

Returns: true if topic is a short topic; false if topic is not short topic

Definition at line 379 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] topic topic to reset

Definition at line 351 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]	con	connection to use
[in,out]	req	request context used for UNSUBSCRIBE procedure
[in,out]	sub	subscription 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

Detailed Description

About

Implementation state

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ ASYMCUTE_HANDLER_PRIO

◆ ASYMCUTE_HANDLER_STACKSIZE

Typedef Documentation

◆ asymcute_con_t

◆ asymcute_evt_cb_t

◆ asymcute_req_t

◆ asymcute_sub_cb_t

◆ asymcute_sub_t

◆ asymcute_to_cb_t

◆ asymcute_topic_t

◆ asymcute_will_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ asymcute_connect()

◆ asymcute_disconnect()

◆ asymcute_handler_run()

◆ asymcute_is_connected()

◆ asymcute_publish()

◆ asymcute_register()

◆ asymcute_req_in_use()

◆ asymcute_sub_active()

◆ asymcute_subscribe()

◆ asymcute_topic_equal()

◆ asymcute_topic_init()

◆ asymcute_topic_is_init()

◆ asymcute_topic_is_predef()

◆ asymcute_topic_is_reg()

◆ asymcute_topic_is_short()

◆ asymcute_topic_reset()

◆ asymcute_unsubscribe()