Contiki-NG
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 /*
153  * Debug configuration, this is similar but not exactly like the Debugging
154  * System discussion at https://github.com/contiki-os/contiki/wiki.
155  */
156 #define DEBUG_MQTT 0
157 
158 #if DEBUG_MQTT == 1
159 #define DBG(...) printf(__VA_ARGS__)
160 #else
161 #define DBG(...)
162 #endif /* DEBUG */
163 /*---------------------------------------------------------------------------*/
164 extern process_event_t mqtt_update_event;
165 
166 /* Forward declaration */
167 struct mqtt_connection;
168 
169 typedef enum {
170  MQTT_RETAIN_OFF,
171  MQTT_RETAIN_ON,
172 } mqtt_retain_t;
173 
174 typedef enum {
175  MQTT_CLEAN_SESSION_OFF,
176  MQTT_CLEAN_SESSION_ON,
177 } mqtt_clean_session_t;
178 
179 /**
180  * \brief MQTT engine events
181  */
182 typedef enum {
183  MQTT_EVENT_CONNECTED,
184  MQTT_EVENT_DISCONNECTED,
185 
186  MQTT_EVENT_SUBACK,
187  MQTT_EVENT_UNSUBACK,
188  MQTT_EVENT_PUBLISH,
189  MQTT_EVENT_PUBACK,
190 
191  /* Errors */
192  MQTT_EVENT_ERROR = 0x80,
193  MQTT_EVENT_PROTOCOL_ERROR,
194  MQTT_EVENT_CONNECTION_REFUSED_ERROR,
195  MQTT_EVENT_DNS_ERROR,
196  MQTT_EVENT_NOT_IMPLEMENTED_ERROR,
197  /* Add more */
198 } mqtt_event_t;
199 
200 typedef enum {
201  MQTT_STATUS_OK,
202 
203  MQTT_STATUS_OUT_QUEUE_FULL,
204 
205  /* Errors */
206  MQTT_STATUS_ERROR = 0x80,
207  MQTT_STATUS_NOT_CONNECTED_ERROR,
208  MQTT_STATUS_INVALID_ARGS_ERROR,
209  MQTT_STATUS_DNS_ERROR,
210 } mqtt_status_t;
211 
212 typedef enum {
213  MQTT_QOS_LEVEL_0,
214  MQTT_QOS_LEVEL_1,
215  MQTT_QOS_LEVEL_2,
216 } mqtt_qos_level_t;
217 
218 typedef enum {
219  MQTT_QOS_STATE_NO_ACK,
220  MQTT_QOS_STATE_GOT_ACK,
221 
222  /* Expand for QoS 2 */
223 } mqtt_qos_state_t;
224 
225 typedef enum {
226  MQTT_PUBLISH_OK,
227  MQTT_PUBLISH_ERR,
228 } mqtt_pub_status_t;
229 /*---------------------------------------------------------------------------*/
230 /*
231  * This is the state of the connection itself.
232  *
233  * N.B. The order is important because of runtime checks on how far the
234  * connection has proceeded.
235  */
236 typedef enum {
237  MQTT_CONN_STATE_ERROR,
238  MQTT_CONN_STATE_DNS_ERROR,
239  MQTT_CONN_STATE_DISCONNECTING,
240  MQTT_CONN_STATE_ABORT_IMMEDIATE,
241  MQTT_CONN_STATE_NOT_CONNECTED,
242  MQTT_CONN_STATE_DNS_LOOKUP,
243  MQTT_CONN_STATE_TCP_CONNECTING,
244  MQTT_CONN_STATE_TCP_CONNECTED,
245  MQTT_CONN_STATE_CONNECTING_TO_BROKER,
246  MQTT_CONN_STATE_CONNECTED_TO_BROKER,
247  MQTT_CONN_STATE_SENDING_MQTT_DISCONNECT,
248 } mqtt_conn_state_t;
249 /*---------------------------------------------------------------------------*/
250 struct mqtt_string {
251  char *string;
252  uint16_t length;
253 };
254 
255 /*
256  * Note that the pairing mid <-> QoS level only applies one-to-one if we only
257  * allow the subscription of one topic at a time. Otherwise we will have an
258  * ordered list of QoS levels corresponding to the order of topics.
259  *
260  * This could be part of a union of event data structures.
261  */
262 typedef struct {
263  uint16_t mid;
264  mqtt_qos_level_t qos_level;
265 #if MQTT_311
266  uint8_t return_code;
267  uint8_t success;
268 #endif
269 } mqtt_suback_event_t;
270 
271 typedef struct {
272  uint8_t session_present;
273 } mqtt_connack_event_t;
274 
275 /* This is the MQTT message that is exposed to the end user. */
276 struct mqtt_message {
277  uint32_t mid;
278  char topic[MQTT_MAX_TOPIC_LENGTH + 1]; /* +1 for string termination */
279 
280  uint8_t *payload_chunk;
281  uint16_t payload_chunk_length;
282 
283  uint8_t first_chunk;
284  uint16_t payload_length;
285  uint16_t payload_left;
286 };
287 
288 /* This struct represents a packet received from the MQTT server. */
289 struct mqtt_in_packet {
290  /* Used by the list interface, must be first in the struct. */
291  struct mqtt_connection *next;
292 
293  /* Total bytes read so far. Compared to the remaining length to to decide when
294  * we've read the payload. */
295  uint32_t byte_counter;
296  uint8_t packet_received;
297 
298  uint8_t fhdr;
299  uint16_t remaining_length;
300  uint16_t mid;
301 
302  /* Helper variables needed to decode the remaining_length */
303  uint8_t remaining_multiplier;
304  uint8_t has_remaining_length;
305  uint8_t remaining_length_bytes;
306 
307  /* Not the same as payload in the MQTT sense, it also contains the variable
308  * header.
309  */
310  uint8_t payload_pos;
311  uint8_t payload[MQTT_INPUT_BUFF_SIZE];
312 
313  /* Message specific data */
314  uint16_t topic_len;
315  uint16_t topic_pos;
316  uint8_t topic_len_received;
317  uint8_t topic_received;
318 };
319 
320 /* This struct represents a packet sent to the MQTT server. */
321 struct mqtt_out_packet {
322  uint8_t fhdr;
323  uint32_t remaining_length;
324  uint8_t remaining_length_enc[MQTT_MAX_REMAINING_LENGTH_BYTES];
325  uint8_t remaining_length_enc_bytes;
326  uint16_t mid;
327  char *topic;
328  uint16_t topic_length;
329  uint8_t *payload;
330  uint32_t payload_size;
331  mqtt_qos_level_t qos;
332  mqtt_qos_state_t qos_state;
333  mqtt_retain_t retain;
334 };
335 /*---------------------------------------------------------------------------*/
336 /**
337  * \brief MQTT event callback function
338  * \param m A pointer to a MQTT connection
339  * \param event The event number
340  * \param data A user-defined pointer
341  *
342  * The MQTT socket event callback function gets called whenever there is an
343  * event on a MQTT connection, such as the connection getting connected
344  * or closed.
345  */
346 typedef void (*mqtt_event_callback_t)(struct mqtt_connection *m,
347  mqtt_event_t event,
348  void *data);
349 
350 typedef void (*mqtt_topic_callback_t)(struct mqtt_connection *m,
351  struct mqtt_message *msg);
352 /*---------------------------------------------------------------------------*/
353 struct mqtt_will {
354  struct mqtt_string topic;
355  struct mqtt_string message;
356  mqtt_qos_level_t qos;
357 };
358 
359 struct mqtt_credentials {
360  struct mqtt_string username;
361  struct mqtt_string password;
362 };
363 
364 struct mqtt_connection {
365  /* Used by the list interface, must be first in the struct */
366  struct mqtt_connection *next;
367  struct timer t;
368 
369  struct mqtt_string client_id;
370 
371  uint8_t connect_vhdr_flags;
372  uint8_t auto_reconnect;
373 
374  uint16_t keep_alive;
375  struct ctimer keep_alive_timer;
376  uint8_t waiting_for_pingresp;
377 
378  struct mqtt_will will;
379  struct mqtt_credentials credentials;
380 
381  mqtt_conn_state_t state;
382  mqtt_event_callback_t event_callback;
383 
384  /* Internal data */
385  uint16_t mid_counter;
386 
387  /* Used for communication between MQTT API and APP */
388  uint8_t out_queue_full;
389  struct process *app_process;
390 
391  /* Outgoing data related */
392  uint8_t *out_buffer_ptr;
393  uint8_t out_buffer[MQTT_TCP_OUTPUT_BUFF_SIZE];
394  uint8_t out_buffer_sent;
395  struct mqtt_out_packet out_packet;
396  struct pt out_proto_thread;
397  uint32_t out_write_pos;
398  uint16_t max_segment_size;
399 
400  /* Incoming data related */
401  uint8_t in_buffer[MQTT_TCP_INPUT_BUFF_SIZE];
402  struct mqtt_in_packet in_packet;
403  struct mqtt_message in_publish_msg;
404 
405  /* TCP related information */
406  char *server_host;
407  uip_ipaddr_t server_ip;
408  uint16_t server_port;
409  struct tcp_socket socket;
410 };
411 /* This is the API exposed to the user. */
412 /*---------------------------------------------------------------------------*/
413 /**
414  * \brief Initializes the MQTT engine.
415  * \param conn A pointer to the MQTT connection.
416  * \param app_process A pointer to the application process handling the MQTT
417  * connection.
418  * \param client_id A pointer to the MQTT client ID.
419  * \param event_callback Callback function responsible for handling the
420  * callback from MQTT engine.
421  * \param max_segment_size The TCP segment size to use for this MQTT/TCP
422  * connection.
423  * \return MQTT_STATUS_OK or MQTT_STATUS_INVALID_ARGS_ERROR
424  *
425  * This function initializes the MQTT engine and shall be called before any
426  * other MQTT function.
427  */
428 mqtt_status_t mqtt_register(struct mqtt_connection *conn,
429  struct process *app_process,
430  char *client_id,
431  mqtt_event_callback_t event_callback,
432  uint16_t max_segment_size);
433 /*---------------------------------------------------------------------------*/
434 /**
435  * \brief Connects to a MQTT broker.
436  * \param conn A pointer to the MQTT connection.
437  * \param host IP address of the broker to connect to.
438  * \param port Port of the broker to connect to, default is MQTT port is 1883.
439  * \param keep_alive Keep alive timer in seconds. Used by broker to handle
440  * client disc. Defines the maximum time interval between two messages
441  * from the client. Shall be min 1.5 x report interval.
442  * \param clean_session Request a new session and discard pending messages with
443  * QoS > 0, as well as client subscriptions
444  * \return MQTT_STATUS_OK or an error status
445  *
446  * This function connects to a MQTT broker.
447  */
448 mqtt_status_t mqtt_connect(struct mqtt_connection *conn,
449  char *host,
450  uint16_t port,
451  uint16_t keep_alive,
452  uint8_t clean_session);
453 /*---------------------------------------------------------------------------*/
454 /**
455  * \brief Disconnects from a MQTT broker.
456  * \param conn A pointer to the MQTT connection.
457  *
458  * This function disconnects from a MQTT broker.
459  */
460 void mqtt_disconnect(struct mqtt_connection *conn);
461 /*---------------------------------------------------------------------------*/
462 /**
463  * \brief Subscribes to a MQTT topic.
464  * \param conn A pointer to the MQTT connection.
465  * \param mid A pointer to message ID.
466  * \param topic A pointer to the topic to subscribe to.
467  * \param qos_level Quality Of Service level to use. Currently supports 0, 1.
468  * \return MQTT_STATUS_OK or some error status
469  *
470  * This function subscribes to a topic on a MQTT broker.
471  */
472 mqtt_status_t mqtt_subscribe(struct mqtt_connection *conn,
473  uint16_t *mid,
474  char *topic,
475  mqtt_qos_level_t qos_level);
476 /*---------------------------------------------------------------------------*/
477 /**
478  * \brief Unsubscribes from a MQTT topic.
479  * \param conn A pointer to the MQTT connection.
480  * \param mid A pointer to message ID.
481  * \param topic A pointer to the topic to unsubscribe from.
482  * \return MQTT_STATUS_OK or some error status
483  *
484  * This function unsubscribes from a topic on a MQTT broker.
485  */
486 mqtt_status_t mqtt_unsubscribe(struct mqtt_connection *conn,
487  uint16_t *mid,
488  char *topic);
489 /*---------------------------------------------------------------------------*/
490 /**
491  * \brief Publish to a MQTT topic.
492  * \param conn A pointer to the MQTT connection.
493  * \param mid A pointer to message ID.
494  * \param topic A pointer to the topic to subscribe to.
495  * \param payload A pointer to the topic payload.
496  * \param payload_size Payload size.
497  * \param qos_level Quality Of Service level to use. Currently supports 0, 1.
498  * \param retain If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a
499  * Client to a Server, the Server MUST store the Application Message
500  * and its QoS, so that it can be delivered to future subscribers whose
501  * subscriptions match its topic name
502  * \return MQTT_STATUS_OK or some error status
503  *
504  * This function publishes to a topic on a MQTT broker.
505  */
506 mqtt_status_t mqtt_publish(struct mqtt_connection *conn,
507  uint16_t *mid,
508  char *topic,
509  uint8_t *payload,
510  uint32_t payload_size,
511  mqtt_qos_level_t qos_level,
512  mqtt_retain_t retain);
513 /*---------------------------------------------------------------------------*/
514 /**
515  * \brief Set the user name and password for a MQTT client.
516  * \param conn A pointer to the MQTT connection.
517  * \param username A pointer to the user name.
518  * \param password A pointer to the password.
519  *
520  * This function sets clients user name and password to use when connecting to
521  * a MQTT broker.
522  */
523 void mqtt_set_username_password(struct mqtt_connection *conn,
524  char *username,
525  char *password);
526 /*---------------------------------------------------------------------------*/
527 /**
528  * \brief Set the last will topic and message for a MQTT client.
529  * \param conn A pointer to the MQTT connection.
530  * \param topic A pointer to the Last Will topic.
531  * \param message A pointer to the Last Will message (payload).
532  * \param qos The desired QoS level.
533  *
534  * This function sets clients Last Will topic and message (payload).
535  * If the Will Flag is set to 1 (using the function) this indicates that,
536  * if the Connect request is accepted, a Will Message MUST be stored on the
537  * Server and associated with the Network Connection. The Will Message MUST
538  * be published when the Network Connection is subsequently closed.
539  *
540  * This functionality can be used to get notified that a device has
541  * disconnected from the broker.
542  *
543  */
544 void mqtt_set_last_will(struct mqtt_connection *conn,
545  char *topic,
546  char *message,
547  mqtt_qos_level_t qos);
548 
549 #define mqtt_connected(conn) \
550  ((conn)->state == MQTT_CONN_STATE_CONNECTED_TO_BROKER ? 1 : 0)
551 
552 #define mqtt_ready(conn) \
553  (!(conn)->out_queue_full && mqtt_connected((conn)))
554 /*---------------------------------------------------------------------------*/
555 #endif /* MQTT_H_ */
556 /*---------------------------------------------------------------------------*/
557 /**
558  * @}
559  * @}
560  */
mqtt_status_t mqtt_subscribe(struct mqtt_connection *conn, uint16_t *mid, char *topic, mqtt_qos_level_t qos_level)
Subscribes to a MQTT topic.
Definition: mqtt.c:1473
mqtt_event_t
MQTT engine events.
Definition: mqtt.h:182
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)
Publish to a MQTT topic.
Definition: mqtt.c:1526
A timer.
Definition: timer.h:82
void(* mqtt_event_callback_t)(struct mqtt_connection *m, mqtt_event_t event, void *data)
MQTT event callback function.
Definition: mqtt.h:346
Header file for IPv6-related data structures.
Header file for the callback timer
Event timer header file.
mqtt_status_t mqtt_unsubscribe(struct mqtt_connection *conn, uint16_t *mid, char *topic)
Unsubscribes from a MQTT topic.
Definition: mqtt.c:1501
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:1558
Header file for the uIP TCP/IP stack.
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:1387
void mqtt_disconnect(struct mqtt_connection *conn)
Disconnects from a MQTT broker.
Definition: mqtt.c:1461
void mqtt_set_last_will(struct mqtt_connection *conn, char *topic, char *message, mqtt_qos_level_t qos)
Set the last will topic and message for a MQTT client.
Definition: mqtt.c:1579
Header file for the LED HAL.
mqtt_status_t mqtt_connect(struct mqtt_connection *conn, char *host, uint16_t port, uint16_t keep_alive, uint8_t clean_session)
Connects to a MQTT broker.
Definition: mqtt.c:1420