emCute, the MQTT-SN implementation for RIOT More...
emCute, the MQTT-SN implementation for RIOT
emCute is the implementation of the OASIS MQTT-SN protocol for RIOT. It is designed with a focus on small memory footprint and usability.
The implementation is based on a 2-thread model: emCute needs one thread of its own, in which receiving of packets and sending of ping messages are handled. All 'user space functions' have to run from (a) different (i.e. user) thread(s). emCute uses thread flags to synchronize between threads.
Further know restrictions are:
This implementation tries minimize parameter checks to a minimum, checking as many parameters as feasible using assertions. For the sake of run-time stability and usability, typical overflow checks are always done during run- time and explicit error values returned in case of errors.
In the current state, emCute supports:
The following features are however still missing (but planned):
Gateway discovery (so far there is no support for handling ADVERTISE, GWINFO, and SEARCHGW). Open question to answer here: how to put / how to encode the IPv(4/6) address AND the port of a gateway in the GwAdd field of the GWINFO message
QOS level 2
put the node to sleep (send DISCONNECT with duration field set)
handle DISCONNECT messages initiated by the broker/gateway
support for pre-defined and short topic IDs
handle (previously) active subscriptions on reconnect/disconnect
handle re-connect/disconnect from unresponsive gateway (in case a number of ping requests are unanswered)
react only to incoming ping requests that are actually send by the gateway we are connected to
|emCute MQTT-SN interface definition |
|emCute internals |
|MQTT-SN topic. More...|
|Data-structure for keeping track of topics we register to. More...|
|Default UDP port to listen on (also used as SRC port) |
|Buffer size used for emCute's transmit and receive buffers. More...|
|Maximum client ID length. More...|
|Maximum topic length. More...|
|#define||EMCUTE_KEEPALIVE (360) /* -> 6 min*/|
|Keep-alive interval [in s]. More...|
|#define||EMCUTE_T_RETRY (15U) /* -> 15 sec */|
|Re-send interval [in seconds]. More...|
|Number of retries when sending packets. More...|
|typedef void(*||emcute_cb_t) (const emcute_topic_t *topic, void *data, size_t len)|
|Signature for callbacks fired when publish messages are received. More...|
|typedef struct emcute_sub||emcute_sub_t|
|Data-structure for keeping track of topics we register to. |
EMCUTE_DUP = 0x80, EMCUTE_QOS_MASK = 0x60, EMCUTE_QOS_2 = 0x40, EMCUTE_QOS_1 = 0x20,
EMCUTE_QOS_0 = 0x00, EMCUTE_RETAIN = 0x10, EMCUTE_WILL = 0x08, EMCUTE_CS = 0x04,
EMCUTE_TIT_MASK = 0x03, EMCUTE_TIT_SHORT = 0x02, EMCUTE_TIT_PREDEF = 0x01, EMCUTE_TIT_NORMAL = 0x00
|MQTT-SN flags. More...|
EMCUTE_OK = 0, EMCUTE_NOGW = -1, EMCUTE_REJECT = -2, EMCUTE_OVERFLOW = -3,
EMCUTE_TIMEOUT = -4, EMCUTE_NOTSUP = -5
|Possible emCute return values. More...|
|int||emcute_con (sock_udp_ep_t *remote, bool clean, const char *will_topic, const void *will_msg, size_t will_msg_len, unsigned flags)|
|Connect to a given MQTT-SN gateway (CONNECT) More...|
|Disconnect from the gateway we are currently connected to. More...|
|int||emcute_reg (emcute_topic_t *topic)|
|Get a topic ID for the given topic name from the gateway. More...|
|int||emcute_pub (emcute_topic_t *topic, const void *buf, size_t len, unsigned flags)|
|Publish data on the given topic. More...|
|int||emcute_sub (emcute_sub_t *sub, unsigned flags)|
|Subscribe to the given topic. More...|
|int||emcute_unsub (emcute_sub_t *sub)|
|Unsubscripbe the given topic. More...|
|int||emcute_willupd_topic (const char *topic, unsigned flags)|
|Update the last will topic. More...|
|int||emcute_willupd_msg (const void *data, size_t len)|
|Update the last will message. More...|
|void||emcute_run (uint16_t port, const char *id)|
|Run emCute, will 'occupy' the calling thread. More...|
|const char *||emcute_type_str (uint8_t type)|
|Return the string representation of the given type value. More...|
|#define EMCUTE_BUFSIZE (512U)|
|#define EMCUTE_ID_MAXLEN (196U)|
|#define EMCUTE_KEEPALIVE (360) /* -> 6 min*/|
|#define EMCUTE_N_RETRY (3U)|
|#define EMCUTE_T_RETRY (15U) /* -> 15 sec */|
|#define EMCUTE_TOPIC_MAXLEN (196U)|
All MQTT-SN functions only support a sub-set of the available flags. It is up to the user to only supply valid/supported flags to a function. emCute will trigger assertion fails on the use of unsupported flags (if compiled with DEVELHELP).
Refer to the MQTT-SN spec section 5.3.4 for further information.
QoS level mask.
QoS level 2.
QoS level 1.
QoS level 0.
will flag, used during CONNECT
clean session flag
topic ID type mask
topic ID: short
topic ID: pre-defined
topic ID: normal
Possible emCute return values.
everything went as expect
error: not connected to a gateway
error: operation was rejected by broker
error: ran out of buffer space
error: feature not supported
|int emcute_con||(||sock_udp_ep_t *||remote,|
|const char *||will_topic,|
|const void *||will_msg,|
Connect to a given MQTT-SN gateway (CONNECT)
When called while already connected to a gateway, call emcute_discon() first to disconnect from the current gateway.
|[in]||remote||address and port of the target MQTT-SN gateway|
|[in]||clean||set to true to start a clean session|
|[in]||will_topic||last will topic name, no last will will be configured if set to NULL|
|[in]||will_msg||last will message content, will be ignored if |
|[in]||will_msg_len||length of |
|[in]||flags||flags used for the last will, allowed are retain and QoS|
Disconnect from the gateway we are currently connected to.
Publish data on the given topic.
|[in]||topic||topic to send data to, topic must be registered (topic.id must populated).|
|[in]||buf||data to publish|
|[in]||len||length of |
|[in]||flags||flags used for publication, allowed are QoS and retain|
|int emcute_reg||(||emcute_topic_t *||topic||)|
Get a topic ID for the given topic name from the gateway.
|[in,out]||topic||topic to register, topic.name must not be NULL|
|const char *||id|
Run emCute, will 'occupy' the calling thread.
This function will run the emCute message receiver. It will block the thread it is running in.
|[in]||port||UDP port used for listening (default: 1883)|
|[in]||id||client ID (should be unique)|
Subscribe to the given topic.
When calling this function,
sub->cb must be set.
|[in,out]||sub||subscription context, |
|[in]||flags||flags used when subscribing, allowed are QoS, DUP, and topic ID type|
|const char* emcute_type_str||(||uint8_t||type||)|
Return the string representation of the given type value.
This function is for debugging purposes.
|[in]||type||MQTT-SN message type|
|int emcute_unsub||(||emcute_sub_t *||sub||)|
Unsubscripbe the given topic.
|int emcute_willupd_msg||(||const void *||data,|
Update the last will message.
|[in]||data||new message to send on last will|
|[in]||len||length of |
|int emcute_willupd_topic||(||const char *||topic,|
Update the last will topic.
|[in]||topic||new last will topic|
|[in]||flags||flags used for the topic, allowed are QoS and retain|