Contiki-NG
Loading...
Searching...
No Matches
mqtt.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2015, Texas Instruments Incorporated - http://www.ti.com/
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 * 3. Neither the name of the copyright holder nor the names of its
14 * contributors may be used to endorse or promote products derived
15 * from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 * OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30/*---------------------------------------------------------------------------*/
31/**
32 * \addtogroup apps
33 * @{
34 *
35 * \defgroup mqtt-engine An implementation of MQTT v3.1
36 * @{
37 *
38 * This application is an engine for MQTT v3.1. It supports QoS Levels 0 and 1.
39 *
40 * MQTT is a Client Server publish/subscribe messaging transport protocol.
41 * It is light weight, open, simple, and designed so as to be easy to implement.
42 * These characteristics make it ideal for use in many situations, including
43 * constrained environments such as for communication in Machine to Machine
44 * (M2M) and Internet of Things (IoT) contexts where a small code footprint is
45 * required and/or network bandwidth is at a premium.
46 *
47 * The protocol runs over TCP/IP, more specifically tcp_socket.
48 * Its features include:
49 *
50 * - Use of the publish/subscribe message pattern which provides
51 * one-to-many message distribution and decoupling of applications.
52 * - A messaging transport that is agnostic to the content of the payload.
53 * Three qualities of service for message delivery:
54 * -- "At most once" (0), where messages are delivered according to the best
55 * efforts of the operating environment. Message loss can occur.
56 * This level could be used, for example, with ambient sensor data where it
57 * does not matter if an individual reading is lost as the next one will be
58 * published soon after.
59 * --"At least once" (1), where messages are assured to arrive but duplicates
60 * can occur.
61 * -- "Exactly once" (2), where message are assured to arrive exactly once.
62 * This level could be used, for example, with billing systems where duplicate
63 * or lost messages could lead to incorrect charges being applied. This QoS
64 * level is currently not supported in this implementation.
65 *
66 * - A small transport overhead and protocol exchanges minimized to reduce
67 * network traffic.
68 * - A mechanism, Last Will, to notify interested parties when an abnormal
69 * disconnection occurs.
70 *
71 * The protocol specification and other useful information can be found
72 * here: http://mqtt.org
73 *
74 */
75/**
76 * \file
77 * Header file for the Contiki MQTT engine
78 *
79 * \author
80 * Texas Instruments
81 */
82/*---------------------------------------------------------------------------*/
83#ifndef MQTT_H_
84#define MQTT_H_
85/*---------------------------------------------------------------------------*/
86#include "contiki.h"
87#include "contiki-net.h"
88#include "contiki-lib.h"
89#include "lib/random.h"
90#include "sys/ctimer.h"
91#include "sys/etimer.h"
92#include "net/ipv6/uip.h"
93#include "net/ipv6/uip-ds6.h"
94#include "dev/leds.h"
95
96#include "tcp-socket.h"
97#include "udp-socket.h"
98
99#include <stdlib.h>
100#include <stdio.h>
101#include <string.h>
102/*---------------------------------------------------------------------------*/
103/* Protocol constants */
104#define MQTT_PROTOCOL_VERSION_3_1 3
105#define MQTT_PROTOCOL_VERSION_3_1_1 4
106#define MQTT_PROTOCOL_VERSION_5 5
107
108#ifdef MQTT_CONF_VERSION
109#define MQTT_PROTOCOL_VERSION MQTT_CONF_VERSION
110#else
111#define MQTT_PROTOCOL_VERSION MQTT_PROTOCOL_VERSION_3_1
112#endif
113
114#if MQTT_PROTOCOL_VERSION == MQTT_PROTOCOL_VERSION_5
115#define MQTT_5 1
116#elif MQTT_PROTOCOL_VERSION == MQTT_PROTOCOL_VERSION_3_1_1
117#define MQTT_311 1
118#elif MQTT_PROTOCOL_VERSION == MQTT_PROTOCOL_VERSION_3_1
119#define MQTT_31 1
120#endif
121
122#define MQTT_CLIENT_ID_MAX_LEN 23
123
124/* Size of the underlying TCP buffers */
125#define MQTT_TCP_INPUT_BUFF_SIZE 512
126#define MQTT_TCP_OUTPUT_BUFF_SIZE 512
127
128#define MQTT_INPUT_BUFF_SIZE 512
129#define MQTT_MAX_TOPIC_LENGTH 64
130#define MQTT_MAX_TOPICS_PER_SUBSCRIBE 1
131
132#define MQTT_FHDR_SIZE 1
133#define MQTT_MAX_REMAINING_LENGTH_BYTES 4
134#if MQTT_31
135#define MQTT_PROTOCOL_NAME "MQIsdp"
136#else
137#define MQTT_PROTOCOL_NAME "MQTT"
138#endif
139
140#define MQTT_TOPIC_MAX_LENGTH 128
141
142#if MQTT_PROTOCOL_VERSION >= MQTT_PROTOCOL_VERSION_3_1_1
143#ifdef MQTT_CONF_SUPPORTS_EMPTY_CLIENT_ID
144#define MQTT_SRV_SUPPORTS_EMPTY_CLIENT_ID MQTT_CONF_SUPPORTS_EMPTY_CLIENT_ID
145#else
146#define MQTT_SRV_SUPPORTS_EMPTY_CLIENT_ID 0
147#endif /* MQTT_CONF_SUPPORTS_EMPTY_CLIENT_ID */
148#else
149#define MQTT_SRV_SUPPORTS_EMPTY_CLIENT_ID 0
150#endif
151
152#if MQTT_31
153/* Len MSB(0)
154 * Len LSB(6)
155 * 'M'
156 * 'Q'
157 * 'I'
158 * 's'
159 * 'd'
160 * 'p'
161 * Protocol Level (3)
162 * Connect Flags
163 * Keep Alive MSB
164 * Keep Alive LSB
165 */
166#define MQTT_CONNECT_VHDR_SIZE 12
167#else
168/* Len MSB(0)
169 * Len LSB(4)
170 * 'M'
171 * 'Q'
172 * 'T'
173 * 'T'
174 * Protocol Level (4)
175 * Connect Flags
176 * Keep Alive MSB
177 * Keep Alive LSB
178 */
179#define MQTT_CONNECT_VHDR_SIZE 10
180#endif
181
182#define MQTT_STRING_LEN_SIZE 2
183#define MQTT_MID_SIZE 2
184#define MQTT_QOS_SIZE 1
185/*---------------------------------------------------------------------------*/
186/*
187 * Debug configuration, this is similar but not exactly like the Debugging
188 * System discussion at https://github.com/contiki-os/contiki/wiki.
189 */
190#define DEBUG_MQTT 0
191
192#if DEBUG_MQTT == 1
193#define DBG(...) printf(__VA_ARGS__)
194#else
195#define DBG(...)
196#endif /* DEBUG */
197/*---------------------------------------------------------------------------*/
198extern process_event_t mqtt_update_event;
199
200/* Forward declaration */
201struct mqtt_connection;
202/* Only defined in MQTTv5 */
203struct mqtt_prop_list;
204
205typedef enum {
206 MQTT_RETAIN_OFF,
207 MQTT_RETAIN_ON,
208} mqtt_retain_t;
209
210typedef enum {
211 MQTT_CLEAN_SESSION_OFF,
212 MQTT_CLEAN_SESSION_ON,
213} mqtt_clean_session_t;
214
215/**
216 * \brief MQTT engine events
217 */
218typedef enum {
219 MQTT_EVENT_CONNECTED,
220 MQTT_EVENT_DISCONNECTED,
221
222 MQTT_EVENT_SUBACK,
223 MQTT_EVENT_UNSUBACK,
224 MQTT_EVENT_PUBLISH,
225 MQTT_EVENT_PUBACK,
226
227 /* Errors */
228 MQTT_EVENT_ERROR = 0x80,
229 MQTT_EVENT_PROTOCOL_ERROR,
230 MQTT_EVENT_CONNECTION_REFUSED_ERROR,
231 MQTT_EVENT_DNS_ERROR,
232 MQTT_EVENT_NOT_IMPLEMENTED_ERROR,
233
234 MQTT_EVENT_AUTH,
235 /* Add more */
237
238typedef enum {
239 MQTT_STATUS_OK,
240
241 MQTT_STATUS_OUT_QUEUE_FULL,
242
243 /* Errors */
244 MQTT_STATUS_ERROR = 0x80,
245 MQTT_STATUS_NOT_CONNECTED_ERROR,
246 MQTT_STATUS_INVALID_ARGS_ERROR,
247 MQTT_STATUS_DNS_ERROR,
248} mqtt_status_t;
249
250typedef enum {
251 MQTT_QOS_LEVEL_0,
252 MQTT_QOS_LEVEL_1,
253 MQTT_QOS_LEVEL_2,
254} mqtt_qos_level_t;
255
256typedef enum {
257 MQTT_QOS_STATE_NO_ACK,
258 MQTT_QOS_STATE_GOT_ACK,
259
260 /* Expand for QoS 2 */
261} mqtt_qos_state_t;
262
263typedef enum {
264 MQTT_PUBLISH_OK,
265 MQTT_PUBLISH_ERR,
266} mqtt_pub_status_t;
267/*---------------------------------------------------------------------------*/
268/*
269 * This is the state of the connection itself.
270 *
271 * N.B. The order is important because of runtime checks on how far the
272 * connection has proceeded.
273 */
274typedef enum {
275 MQTT_CONN_STATE_ERROR,
276 MQTT_CONN_STATE_DNS_ERROR,
277 MQTT_CONN_STATE_DISCONNECTING,
278 MQTT_CONN_STATE_ABORT_IMMEDIATE,
279 MQTT_CONN_STATE_NOT_CONNECTED,
280 MQTT_CONN_STATE_DNS_LOOKUP,
281 MQTT_CONN_STATE_TCP_CONNECTING,
282 MQTT_CONN_STATE_TCP_CONNECTED,
283 MQTT_CONN_STATE_CONNECTING_TO_BROKER,
284 MQTT_CONN_STATE_CONNECTED_TO_BROKER,
285 MQTT_CONN_STATE_SENDING_MQTT_DISCONNECT,
286} mqtt_conn_state_t;
287/*---------------------------------------------------------------------------*/
288typedef enum {
289 MQTT_FHDR_MSG_TYPE_CONNECT = 0x10,
290 MQTT_FHDR_MSG_TYPE_CONNACK = 0x20,
291 MQTT_FHDR_MSG_TYPE_PUBLISH = 0x30,
292 MQTT_FHDR_MSG_TYPE_PUBACK = 0x40,
293 MQTT_FHDR_MSG_TYPE_PUBREC = 0x50,
294 MQTT_FHDR_MSG_TYPE_PUBREL = 0x60,
295 MQTT_FHDR_MSG_TYPE_PUBCOMP = 0x70,
296 MQTT_FHDR_MSG_TYPE_SUBSCRIBE = 0x80,
297 MQTT_FHDR_MSG_TYPE_SUBACK = 0x90,
298 MQTT_FHDR_MSG_TYPE_UNSUBSCRIBE = 0xA0,
299 MQTT_FHDR_MSG_TYPE_UNSUBACK = 0xB0,
300 MQTT_FHDR_MSG_TYPE_PINGREQ = 0xC0,
301 MQTT_FHDR_MSG_TYPE_PINGRESP = 0xD0,
302 MQTT_FHDR_MSG_TYPE_DISCONNECT = 0xE0,
303 MQTT_FHDR_MSG_TYPE_AUTH = 0xF0,
304} mqtt_msg_type_t;
305/*---------------------------------------------------------------------------*/
306/* MQTTv5.0 VHDR Properties */
307typedef enum {
308 MQTT_VHDR_PROP_ANY = 0x00, /* not in standard; for library use */
309 MQTT_VHDR_PROP_PAYLOAD_FMT_IND = 0x01,
310 MQTT_VHDR_PROP_MSG_EXP_INT = 0x02,
311 MQTT_VHDR_PROP_CONTENT_TYPE = 0x03,
312 MQTT_VHDR_PROP_RESP_TOPIC = 0x08,
313 MQTT_VHDR_PROP_CORRELATION_DATA = 0x09,
314 MQTT_VHDR_PROP_SUB_ID = 0x0B,
315 MQTT_VHDR_PROP_SESS_EXP_INT = 0x11,
316 MQTT_VHDR_PROP_ASSIGNED_CLIENT_ID = 0x12,
317 MQTT_VHDR_PROP_SERVER_KEEP_ALIVE = 0x13,
318 MQTT_VHDR_PROP_AUTH_METHOD = 0x15,
319 MQTT_VHDR_PROP_AUTH_DATA = 0x16,
320 MQTT_VHDR_PROP_REQ_PROBLEM_INFO = 0x17,
321 MQTT_VHDR_PROP_WILL_DELAY_INT = 0x18,
322 MQTT_VHDR_PROP_REQ_RESP_INFO = 0x19,
323 MQTT_VHDR_PROP_RESP_INFO = 0x1A,
324 MQTT_VHDR_PROP_SERVER_REFERENCE = 0x1C,
325 MQTT_VHDR_PROP_REASON_STRING = 0x1F,
326 MQTT_VHDR_PROP_RECEIVE_MAX = 0x21,
327 MQTT_VHDR_PROP_TOPIC_ALIAS_MAX = 0x22,
328 MQTT_VHDR_PROP_TOPIC_ALIAS = 0x23,
329 MQTT_VHDR_PROP_MAX_QOS = 0x24,
330 MQTT_VHDR_PROP_RETAIN_AVAIL = 0x25,
331 MQTT_VHDR_PROP_USER_PROP = 0x26,
332 MQTT_VHDR_PROP_MAX_PKT_SZ = 0x27,
333 MQTT_VHDR_PROP_WILD_SUB_AVAIL = 0x28,
334 MQTT_VHDR_PROP_SUB_ID_AVAIL = 0x29,
335 MQTT_VHDR_PROP_SHARED_SUB_AVAIL = 0x2A,
336} mqtt_vhdr_prop_t;
337/*---------------------------------------------------------------------------*/
338/* MQTTv5.0 Binary Capabilities */
339typedef enum {
340 MQTT_CAP_RETAIN_AVAIL = 0x00,
341 MQTT_CAP_WILD_SUB_AVAIL = 0x01,
342 MQTT_CAP_SUB_ID_AVAIL = 0x02,
343 MQTT_CAP_SHARED_SUB_AVAIL = 0x04,
344} mqtt_srv_capability_t;
345
346typedef enum {
347 MQTT_CAP_OFF,
348 MQTT_CAP_ON,
349} mqtt_capability_t;
350
351typedef enum {
352 MQTT_TOPIC_ALIAS_OFF,
353 MQTT_TOPIC_ALIAS_ON,
354} mqtt_topic_alias_en_t;
355
356typedef enum {
357 MQTT_SUB_OPTION_QOS = 0x03,
358 MQTT_SUB_OPTION_NL = 0x04,
359 MQTT_SUB_OPTION_RAP = 0x08,
360 MQTT_SUB_OPTION_RETAIN_HANDLING = 0x30,
361} mqtt_sub_option_t;
362
363typedef enum {
364 MQTT_NL_OFF,
365 MQTT_NL_ON,
366} mqtt_nl_en_t;
367
368typedef enum {
369 MQTT_RAP_OFF,
370 MQTT_RAP_ON,
371} mqtt_rap_en_t;
372
373typedef enum {
374 MQTT_RET_H_SEND_ALL = 0x00,
375 MQTT_RET_H_SEND_NEW = 0x01,
376 MQTT_RET_H_SEND_NONE = 0x02,
377} mqtt_retain_handling_t;
378/*---------------------------------------------------------------------------*/
379struct mqtt_string {
380 char *string;
381 uint16_t length;
382};
383
384/*
385 * Note that the pairing mid <-> QoS level only applies one-to-one if we only
386 * allow the subscription of one topic at a time. Otherwise we will have an
387 * ordered list of QoS levels corresponding to the order of topics.
388 *
389 * This could be part of a union of event data structures.
390 */
391struct mqtt_suback_event {
392 uint16_t mid;
393 mqtt_qos_level_t qos_level;
394#if !MQTT_31
395 uint8_t return_code;
396 uint8_t success;
397#endif
398};
399
400struct mqtt_connack_event {
401 uint8_t session_present;
402};
403
404typedef enum {
405 MQTT_AUTH_NORMAL,
406 MQTT_AUTH_RE_AUTH,
407} mqtt_auth_type_t;
408
409/* This is the MQTT message that is exposed to the end user. */
410struct mqtt_message {
411 uint32_t mid;
412 char topic[MQTT_MAX_TOPIC_LENGTH + 1]; /* +1 for string termination */
413
414 uint8_t *payload_chunk;
415 uint16_t payload_chunk_length;
416
417 uint8_t first_chunk;
418 uint16_t payload_length;
419 uint16_t payload_left;
420};
421
422/* This struct represents a packet received from the MQTT server. */
423struct mqtt_in_packet {
424 /* Used by the list interface, must be first in the struct. */
425 struct mqtt_connection *next;
426
427 /* Total bytes read so far. Compared to the remaining length to to decide when
428 * we've read the payload. */
429 uint32_t byte_counter;
430 uint8_t packet_received;
431
432 uint8_t fhdr;
433 uint16_t remaining_length;
434 uint16_t mid;
435
436 /* Helper variables needed to decode the remaining_length */
437 uint8_t has_remaining_length;
438
439 /* Not the same as payload in the MQTT sense, it also contains the variable
440 * header.
441 */
442 uint16_t payload_pos;
443 uint8_t payload[MQTT_INPUT_BUFF_SIZE];
444
445 /* Start of MQTT payload (after VHDR) */
446 uint8_t *payload_start;
447
448 /* Message specific data */
449 uint16_t topic_len;
450 uint16_t topic_pos;
451 uint8_t topic_len_received;
452 uint8_t topic_received;
453
454 /* Properties */
455#if MQTT_5
456 uint8_t has_reason_code;
457 uint8_t reason_code;
458
459 uint8_t has_props; /* the properties have been decoded */
460 uint8_t properties_enc_len; /* number of bytes used to encode property length */
461 uint16_t properties_len; /* length of properties excluding encoded length */
462 uint8_t *props_start; /* pointer to first byte in first property */
463 uint8_t *curr_props_pos; /* pointer to property to parse next */
464#endif
465};
466
467/* This struct represents a packet sent to the MQTT server. */
468struct mqtt_out_packet {
469 uint8_t fhdr;
470 uint32_t remaining_length;
471 uint8_t remaining_length_enc[MQTT_MAX_REMAINING_LENGTH_BYTES];
472 uint8_t remaining_length_enc_bytes;
473 uint16_t mid;
474 char *topic;
475 uint16_t topic_length;
476 uint8_t *payload;
477 uint32_t payload_size;
478 mqtt_qos_level_t qos;
479 mqtt_qos_state_t qos_state;
480 mqtt_retain_t retain;
481#if MQTT_5
482 uint8_t topic_alias;
483 uint8_t sub_options;
484 /* Continue Auth or Re-auth */
485 uint8_t auth_reason_code;
486#endif
487};
488/*---------------------------------------------------------------------------*/
489/**
490 * \brief MQTT event callback function
491 * \param m A pointer to a MQTT connection
492 * \param event The event number
493 * \param data A user-defined pointer
494 *
495 * The MQTT socket event callback function gets called whenever there is an
496 * event on a MQTT connection, such as the connection getting connected
497 * or closed.
498 */
499typedef void (*mqtt_event_callback_t)(struct mqtt_connection *m,
500 mqtt_event_t event,
501 void *data);
502
503typedef void (*mqtt_topic_callback_t)(struct mqtt_connection *m,
504 struct mqtt_message *msg);
505/*---------------------------------------------------------------------------*/
506struct mqtt_will {
507 struct mqtt_string topic;
508 struct mqtt_string message;
509 mqtt_qos_level_t qos;
510#if MQTT_5
511 LIST_STRUCT(properties);
512#endif
513};
514
515struct mqtt_credentials {
516 struct mqtt_string username;
517 struct mqtt_string password;
518};
519
520struct mqtt_connection {
521 /* Used by the list interface, must be first in the struct */
522 struct mqtt_connection *next;
523 struct timer t;
524
525 struct mqtt_string client_id;
526
527 uint8_t connect_vhdr_flags;
528 uint8_t auto_reconnect;
529
530 uint16_t keep_alive;
531 struct ctimer keep_alive_timer;
532 uint8_t waiting_for_pingresp;
533
534 struct mqtt_will will;
535 struct mqtt_credentials credentials;
536
537 mqtt_conn_state_t state;
538 mqtt_event_callback_t event_callback;
539
540 /* Internal data */
541 uint16_t mid_counter;
542
543 /* Used for communication between MQTT API and APP */
544 uint8_t out_queue_full;
545 struct process *app_process;
546
547 /* Outgoing data related */
548 uint8_t *out_buffer_ptr;
549 uint8_t out_buffer[MQTT_TCP_OUTPUT_BUFF_SIZE];
550 uint8_t out_buffer_sent;
551 struct mqtt_out_packet out_packet;
552 struct pt out_proto_thread;
553 uint32_t out_write_pos;
554 uint16_t max_segment_size;
555
556 /* Incoming data related */
557 uint8_t in_buffer[MQTT_TCP_INPUT_BUFF_SIZE];
558 struct mqtt_in_packet in_packet;
559 struct mqtt_message in_publish_msg;
560
561 /* TCP related information */
562 char *server_host;
563 uip_ipaddr_t server_ip;
564 uint16_t server_port;
565 struct tcp_socket socket;
566
567#if MQTT_5
568 /* Server Capabilities */
569 /* Binary capabilities (default: enabled) */
570 uint8_t srv_feature_en;
571 struct mqtt_prop_list *out_props;
572#endif
573};
574/* This is the API exposed to the user. */
575/*---------------------------------------------------------------------------*/
576/**
577 * \brief Initializes the MQTT engine.
578 * \param conn A pointer to the MQTT connection.
579 * \param app_process A pointer to the application process handling the MQTT
580 * connection.
581 * \param client_id A pointer to the MQTT client ID.
582 * \param event_callback Callback function responsible for handling the
583 * callback from MQTT engine.
584 * \param max_segment_size The TCP segment size to use for this MQTT/TCP
585 * connection.
586 * \return MQTT_STATUS_OK or MQTT_STATUS_INVALID_ARGS_ERROR
587 *
588 * This function initializes the MQTT engine and shall be called before any
589 * other MQTT function.
590 */
591mqtt_status_t mqtt_register(struct mqtt_connection *conn,
592 struct process *app_process,
593 char *client_id,
594 mqtt_event_callback_t event_callback,
595 uint16_t max_segment_size);
596/*---------------------------------------------------------------------------*/
597/**
598 * \brief Connects to a MQTT broker.
599 * \param conn A pointer to the MQTT connection.
600 * \param host IP address of the broker to connect to.
601 * \param port Port of the broker to connect to, default is MQTT port is 1883.
602 * \param keep_alive Keep alive timer in seconds. Used by broker to handle
603 * client disc. Defines the maximum time interval between two messages
604 * from the client. Shall be min 1.5 x report interval.
605 * \param clean_session Request a new session and discard pending messages with
606 * QoS > 0, as well as client subscriptions
607 * \param prop_list Output properties (MQTTv5-only).
608 * \return MQTT_STATUS_OK or an error status
609 *
610 * This function connects to a MQTT broker.
611 */
612mqtt_status_t mqtt_connect(struct mqtt_connection *conn,
613 char *host,
614 uint16_t port,
615 uint16_t keep_alive,
616#if MQTT_5
617 uint8_t clean_session,
618 struct mqtt_prop_list *prop_list);
619#else
620 uint8_t clean_session);
621#endif
622/*---------------------------------------------------------------------------*/
623/**
624 * \brief Disconnects from a MQTT broker.
625 * \param conn A pointer to the MQTT connection.
626 * \param prop_list Output properties (MQTTv5-only).
627 *
628 * This function disconnects from a MQTT broker.
629 */
630#if MQTT_5
631void mqtt_disconnect(struct mqtt_connection *conn,
632 struct mqtt_prop_list *prop_list);
633#else
634void mqtt_disconnect(struct mqtt_connection *conn);
635#endif
636/*---------------------------------------------------------------------------*/
637/**
638 * \brief Subscribes to a MQTT topic.
639 * \param conn A pointer to the MQTT connection.
640 * \param mid A pointer to message ID.
641 * \param topic A pointer to the topic to subscribe to.
642 * \param qos_level Quality Of Service level to use. Currently supports 0, 1.
643 * \param nl No Local (MQTTv5-only).
644 * \param rap Retain As Published (MQTTv5-only).
645 * \param ret_handling Retain handling options (MQTTv5-only).
646 * \param prop_list Output properties (MQTTv5-only).
647 * \return MQTT_STATUS_OK or some error status
648 *
649 * This function subscribes to a topic on a MQTT broker.
650 */
651mqtt_status_t mqtt_subscribe(struct mqtt_connection *conn,
652 uint16_t *mid,
653 char *topic,
654#if MQTT_5
655 mqtt_qos_level_t qos_level,
656 mqtt_nl_en_t nl, mqtt_rap_en_t rap,
657 mqtt_retain_handling_t ret_handling,
658 struct mqtt_prop_list *prop_list);
659#else
660 mqtt_qos_level_t qos_level);
661#endif
662/*---------------------------------------------------------------------------*/
663/**
664 * \brief Unsubscribes from a MQTT topic.
665 * \param conn A pointer to the MQTT connection.
666 * \param mid A pointer to message ID.
667 * \param topic A pointer to the topic to unsubscribe from.
668 * \param prop_list Output properties (MQTTv5-only).
669 * \return MQTT_STATUS_OK or some error status
670 *
671 * This function unsubscribes from a topic on a MQTT broker.
672 */
673mqtt_status_t mqtt_unsubscribe(struct mqtt_connection *conn,
674 uint16_t *mid,
675#if MQTT_5
676 char *topic,
677 struct mqtt_prop_list *prop_list);
678#else
679 char *topic);
680#endif
681/*---------------------------------------------------------------------------*/
682/**
683 * \brief Publish to a MQTT topic.
684 * \param conn A pointer to the MQTT connection.
685 * \param mid A pointer to message ID.
686 * \param topic A pointer to the topic to subscribe to.
687 * \param payload A pointer to the topic payload.
688 * \param payload_size Payload size.
689 * \param qos_level Quality Of Service level to use. Currently supports 0, 1.
690 * \param retain If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a
691 * Client to a Server, the Server MUST store the Application Message
692 * and its QoS, so that it can be delivered to future subscribers whose
693 * subscriptions match its topic name
694 * \param topic_alias Topic alias to send (MQTTv5-only).
695 * \param topic_alias_en Control whether or not to discard topic and only send
696 * topic alias s(MQTTv5-only).
697 * \param prop_list Output properties (MQTTv5-only).
698 * \return MQTT_STATUS_OK or some error status
699 *
700 * This function publishes to a topic on a MQTT broker.
701 */
702mqtt_status_t mqtt_publish(struct mqtt_connection *conn,
703 uint16_t *mid,
704 char *topic,
705 uint8_t *payload,
706 uint32_t payload_size,
707 mqtt_qos_level_t qos_level,
708#if MQTT_5
709 mqtt_retain_t retain,
710 uint8_t topic_alias,
711 mqtt_topic_alias_en_t topic_alias_en,
712 struct mqtt_prop_list *prop_list);
713#else
714 mqtt_retain_t retain);
715#endif
716/*---------------------------------------------------------------------------*/
717/**
718 * \brief Set the user name and password for a MQTT client.
719 * \param conn A pointer to the MQTT connection.
720 * \param username A pointer to the user name.
721 * \param password A pointer to the password.
722 *
723 * This function sets clients user name and password to use when connecting to
724 * a MQTT broker.
725 */
726void mqtt_set_username_password(struct mqtt_connection *conn,
727 char *username,
728 char *password);
729/*---------------------------------------------------------------------------*/
730/**
731 * \brief Set the last will topic and message for a MQTT client.
732 * \param conn A pointer to the MQTT connection.
733 * \param topic A pointer to the Last Will topic.
734 * \param message A pointer to the Last Will message (payload).
735 * \param qos The desired QoS level.
736 * \param will_props Will message properties (MQTTv5-only).
737 *
738 * This function sets clients Last Will topic and message (payload).
739 * If the Will Flag is set to 1 (using the function) this indicates that,
740 * if the Connect request is accepted, a Will Message MUST be stored on the
741 * Server and associated with the Network Connection. The Will Message MUST
742 * be published when the Network Connection is subsequently closed.
743 *
744 * This functionality can be used to get notified that a device has
745 * disconnected from the broker.
746 *
747 */
748void mqtt_set_last_will(struct mqtt_connection *conn,
749 char *topic,
750 char *message,
751#if MQTT_5
752 mqtt_qos_level_t qos,
753 struct mqtt_prop_list *will_props);
754#else
755 mqtt_qos_level_t qos);
756#endif
757
758#define mqtt_connected(conn) \
759 ((conn)->state == MQTT_CONN_STATE_CONNECTED_TO_BROKER ? 1 : 0)
760
761#define mqtt_ready(conn) \
762 (!(conn)->out_queue_full && mqtt_connected((conn)))
763/*---------------------------------------------------------------------------*/
764void mqtt_encode_var_byte_int(uint8_t *vbi_out,
765 uint8_t *vbi_bytes,
766 uint32_t val);
767/*---------------------------------------------------------------------------*/
768uint8_t mqtt_decode_var_byte_int(const uint8_t *input_data_ptr,
769 int input_data_len,
770 uint32_t *input_pos,
771 uint32_t *pkt_byte_count,
772 uint16_t *dest);
773/*---------------------------------------------------------------------------*/
774/**
775 * \brief Send authentication message (MQTTv5-only).
776 * \param conn A pointer to the MQTT connection.
777 * \param auth_type The type of auth to send (continue authentication or
778 * re-authentication).
779 * \param prop_list Output properties.
780 * \return MQTT_STATUS_OK or some error status
781 *
782 * This function send an MQTT authentication message.
783 */
784mqtt_status_t mqtt_auth(struct mqtt_connection *conn,
785 mqtt_auth_type_t auth_type,
786 struct mqtt_prop_list *prop_list);
787/*---------------------------------------------------------------------------*/
788#endif /* MQTT_H_ */
789/*---------------------------------------------------------------------------*/
790/**
791 * @}
792 * @}
793 */
Header file for the callback timer.
Event timer header file.
#define LIST_STRUCT(name)
Declare a linked list inside a structure declaraction.
Definition list.h:112
mqtt_status_t mqtt_auth(struct mqtt_connection *conn, mqtt_auth_type_t auth_type, struct mqtt_prop_list *prop_list)
Send authentication message (MQTTv5-only).
Definition mqtt.c:2095
mqtt_status_t mqtt_connect(struct mqtt_connection *conn, char *host, uint16_t port, uint16_t keep_alive, uint8_t clean_session, struct mqtt_prop_list *prop_list)
Connects to a MQTT broker.
Definition mqtt.c:1816
mqtt_status_t mqtt_register(struct mqtt_connection *conn, struct process *app_process, char *client_id, mqtt_event_callback_t event_callback, uint16_t max_segment_size)
Initializes the MQTT engine.
Definition mqtt.c:1777
mqtt_status_t mqtt_unsubscribe(struct mqtt_connection *conn, uint16_t *mid, char *topic, struct mqtt_prop_list *prop_list)
Unsubscribes from a MQTT topic.
Definition mqtt.c:1940
void(* mqtt_event_callback_t)(struct mqtt_connection *m, mqtt_event_t event, void *data)
MQTT event callback function.
Definition mqtt.h:499
mqtt_status_t mqtt_subscribe(struct mqtt_connection *conn, uint16_t *mid, char *topic, mqtt_qos_level_t qos_level, mqtt_nl_en_t nl, mqtt_rap_en_t rap, mqtt_retain_handling_t ret_handling, struct mqtt_prop_list *prop_list)
Subscribes to a MQTT topic.
Definition mqtt.c:1888
void mqtt_disconnect(struct mqtt_connection *conn, struct mqtt_prop_list *prop_list)
Disconnects from a MQTT broker.
Definition mqtt.c:1868
mqtt_status_t mqtt_publish(struct mqtt_connection *conn, uint16_t *mid, char *topic, uint8_t *payload, uint32_t payload_size, mqtt_qos_level_t qos_level, mqtt_retain_t retain, uint8_t topic_alias, mqtt_topic_alias_en_t topic_alias_en, struct mqtt_prop_list *prop_list)
Publish to a MQTT topic.
Definition mqtt.c:1979
mqtt_event_t
MQTT engine events.
Definition mqtt.h:218
void mqtt_set_username_password(struct mqtt_connection *conn, char *username, char *password)
Set the user name and password for a MQTT client.
Definition mqtt.c:2041
void mqtt_set_last_will(struct mqtt_connection *conn, char *topic, char *message, mqtt_qos_level_t qos, struct mqtt_prop_list *will_props)
Set the last will topic and message for a MQTT client.
Definition mqtt.c:2062
Header file for the LED HAL.
A timer.
Definition timer.h:84
Header file for IPv6-related data structures.
Header file for the uIP TCP/IP stack.