1.. _mqtt_socket_interface:
2
3MQTT
4####
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13MQTT (Message Queuing Telemetry Transport) is an application layer protocol
14which works on top of the TCP/IP stack. It is a lightweight
15publish/subscribe messaging transport for machine-to-machine communication.
16For more information about the protocol itself, see http://mqtt.org/.
17
18Zephyr provides an MQTT client library built on top of BSD sockets API. The
19library can be enabled with :kconfig:option:`CONFIG_MQTT_LIB` Kconfig option and
20is configurable at a per-client basis, with support for MQTT versions
213.1.0 and 3.1.1. The Zephyr MQTT implementation can be used with either plain
22sockets communicating over TCP, or with secure sockets communicating over
23TLS. See :ref:`bsd_sockets_interface` for more information about Zephyr sockets.
24
25MQTT clients require an MQTT server to connect to. Such a server, called an MQTT Broker,
26is responsible for managing client subscriptions and distributing messages
27published by clients. There are many implementations of MQTT brokers, one of them
28being Eclipse Mosquitto. See https://mosquitto.org/ for more information about
29the Eclipse Mosquitto project.
30
31Sample usage
32************
33
34To create an MQTT client, a client context structure and buffers need to be
35defined:
36
37.. code-block:: c
38
39   /* Buffers for MQTT client. */
40   static uint8_t rx_buffer[256];
41   static uint8_t tx_buffer[256];
42
43   /* MQTT client context */
44   static struct mqtt_client client_ctx;
45
46Multiple MQTT client instances can be created in the application and managed
47independently. Additionally, a structure for MQTT Broker address information
48is needed. This structure must be accessible throughout the lifespan
49of the MQTT client and can be shared among MQTT clients:
50
51.. code-block:: c
52
53   /* MQTT Broker address information. */
54   static struct sockaddr_storage broker;
55
56An MQTT client library will notify MQTT events to the application through a
57callback function created to handle respective events:
58
59.. code-block:: c
60
61   void mqtt_evt_handler(struct mqtt_client *client,
62                         const struct mqtt_evt *evt)
63   {
64      switch (evt->type) {
65         /* Handle events here. */
66      }
67   }
68
69For a list of possible events, see :ref:`mqtt_api_reference`.
70
71The client context structure needs to be initialized and set up before it can be
72used. An example configuration for TCP transport is shown below:
73
74.. code-block:: c
75
76   mqtt_client_init(&client_ctx);
77
78   /* MQTT client configuration */
79   client_ctx.broker = &broker;
80   client_ctx.evt_cb = mqtt_evt_handler;
81   client_ctx.client_id.utf8 = (uint8_t *)"zephyr_mqtt_client";
82   client_ctx.client_id.size = sizeof("zephyr_mqtt_client") - 1;
83   client_ctx.password = NULL;
84   client_ctx.user_name = NULL;
85   client_ctx.protocol_version = MQTT_VERSION_3_1_1;
86   client_ctx.transport.type = MQTT_TRANSPORT_NON_SECURE;
87
88   /* MQTT buffers configuration */
89   client_ctx.rx_buf = rx_buffer;
90   client_ctx.rx_buf_size = sizeof(rx_buffer);
91   client_ctx.tx_buf = tx_buffer;
92   client_ctx.tx_buf_size = sizeof(tx_buffer);
93
94After the configuration is set up, the MQTT client can connect to the MQTT broker.
95Call the ``mqtt_connect`` function, which will create the appropriate socket,
96establish a TCP/TLS connection, and send an ``MQTT CONNECT`` message.
97When notified, the application should call the ``mqtt_input`` function to process
98the response received. Note, that ``mqtt_input`` is a non-blocking function,
99therefore the application should use socket ``poll`` to wait for the response.
100If the connection was successful, ``MQTT_EVT_CONNACK`` will be notified to the
101application through the callback function.
102
103.. code-block:: c
104
105   rc = mqtt_connect(&client_ctx);
106   if (rc != 0) {
107      return rc;
108   }
109
110   fds[0].fd = client_ctx.transport.tcp.sock;
111   fds[0].events = ZSOCK_POLLIN;
112   poll(fds, 1, 5000);
113
114   mqtt_input(&client_ctx);
115
116   if (!connected) {
117      mqtt_abort(&client_ctx);
118   }
119
120In the above code snippet, the MQTT callback function should set the ``connected``
121flag upon a successful connection. If the connection fails at the MQTT level
122or a timeout occurs, the connection will be aborted, and the underlying socket
123closed.
124
125After the connection is established, an application needs to call ``mqtt_input``
126and ``mqtt_live`` functions periodically to process incoming data and upkeep
127the connection. If an MQTT message is received, an MQTT callback function will
128be called and an appropriate event notified.
129
130The connection can be closed by calling the ``mqtt_disconnect`` function.
131
132Zephyr provides sample code utilizing the MQTT client API. See
133:zephyr:code-sample:`mqtt-publisher` for more information.
134
135Using MQTT with TLS
136*******************
137
138The Zephyr MQTT library can be used with TLS transport for secure communication
139by selecting a secure transport type (``MQTT_TRANSPORT_SECURE``) and some
140additional configuration information:
141
142.. code-block:: c
143
144   client_ctx.transport.type = MQTT_TRANSPORT_SECURE;
145
146   struct mqtt_sec_config *tls_config = &client_ctx.transport.tls.config;
147
148   tls_config->peer_verify = TLS_PEER_VERIFY_REQUIRED;
149   tls_config->cipher_list = NULL;
150   tls_config->sec_tag_list = m_sec_tags;
151   tls_config->sec_tag_count = ARRAY_SIZE(m_sec_tags);
152   tls_config->hostname = MQTT_BROKER_HOSTNAME;
153
154In this sample code, the ``m_sec_tags`` array holds a list of tags, referencing TLS
155credentials that the MQTT library should use for authentication. We do not specify
156``cipher_list``, to allow the use of all cipher suites available in the system.
157We set ``hostname`` field to broker hostname, which is required for server
158authentication. Finally, we enforce peer certificate verification by setting
159the ``peer_verify`` field.
160
161Note, that TLS credentials referenced by the ``m_sec_tags`` array must be
162registered in the system first. For more information on how to do that, refer
163to :ref:`secure sockets documentation <secure_sockets_interface>`.
164
165An example of how to use TLS with MQTT is also present in
166:zephyr:code-sample:`mqtt-publisher` sample application.
167
168.. _mqtt_api_reference:
169
170API Reference
171*************
172
173.. doxygengroup:: mqtt_socket
174