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 wildcard characters in topic names when subscribing
Actual granted QoS level on subscription is ignored

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]	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 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]	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 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]	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)

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]	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_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]	con	connection context to use for this connection
[in]	stack	stack used to run the listener thread
[in]	stacksize	size of `stack` in bytes
[in]	priority	priority of the listener thread created by this function
[in]	callback	user 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]	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 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] sub subscription 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]	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 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]	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 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] topic topic 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] topic topic 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]	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_LISTENER_PRIO

Typedef Documentation

◆ asymcute_evt_cb_t

◆ asymcute_sub_cb_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ asymcute_connect()

◆ asymcute_disconnect()

◆ asymcute_handler_run()

◆ asymcute_is_connected()

◆ asymcute_listener_run()

◆ 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_reg()

◆ asymcute_topic_reset()

◆ asymcute_unsubscribe()