1.. zephyr:code-sample:: mqtt-publisher
2 :name: MQTT publisher
3 :relevant-api: mqtt_socket
4
5 Send MQTT PUBLISH messages to an MQTT server.
6
7Overview
8********
9
10`MQTT <http://mqtt.org/>`_ (MQ Telemetry Transport) is a lightweight
11publish/subscribe messaging protocol optimized for small sensors and
12mobile devices.
13
14The Zephyr MQTT Publisher sample application is a MQTT v3.1.1
15client that sends MQTT PUBLISH messages to a MQTT broker.
16See the `MQTT V3.1.1 spec`_ for more information.
17
18.. _MQTT V3.1.1 spec: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
19
20The source code of this sample application can be found at:
21:zephyr_file:`samples/net/mqtt_publisher`.
22
23Requirements
24************
25
26- Linux machine
27- Freedom Board (FRDM-K64F)
28- Mosquitto server: any version that supports MQTT v3.1.1. This sample
29 was tested with mosquitto 1.3.4.
30- Mosquitto subscriber
31- LAN for testing purposes (Ethernet)
32
33Build and Running
34*****************
35
36Currently, this sample application only supports static IP addresses.
37Open the :file:`src/config.h` file and set the IP addresses according
38to the LAN environment.
39Alternatively, set the IP addresses in the :file:`prj.conf` file.
40
41The file :file:`src/config.h` also contains some variables that may be changed:
42
43MQTT broker TCP port:
44
45.. code-block:: c
46
47 #define SERVER_PORT 1883
48
49Application sleep time:
50
51.. code-block:: c
52
53 #define APP_SLEEP_MSECS 500
54
55Max number of connection tries:
56
57.. code-block:: c
58
59 #define APP_CONNECT_TRIES 10
60
61MQTT Client Identifier:
62
63.. code-block:: c
64
65 #define MQTT_CLIENTID "zephyr_publisher"
66
67This sample application supports the IBM Bluemix Watson topic format that can
68be enabled by changing the default value of APP_BLUEMIX_TOPIC from 0 to 1:
69
70.. code-block:: c
71
72 #define APP_BLUEMIX_TOPIC 1
73
74The Bluemix topic may include some parameters like device type, device
75identifier, event type and message format. This application uses the
76following macros to specify those values:
77
78.. code-block:: c
79
80 #define BLUEMIX_DEVTYPE "sensor"
81 #define BLUEMIX_DEVID "carbon"
82 #define BLUEMIX_EVENT "status"
83 #define BLUEMIX_FORMAT "json"
84
85Max number of MQTT PUBLISH iterations is defined in Kconfig:
86
87.. code-block:: cfg
88
89 CONFIG_NET_SAMPLE_APP_MAX_ITERATIONS=5
90
91On your Linux host computer, open a terminal window, locate the source code
92of this sample application (i.e., :zephyr_file:`samples/net/mqtt_publisher`) and type:
93
94.. zephyr-app-commands::
95 :zephyr-app: samples/net/mqtt_publisher
96 :board: frdm_k64f
97 :goals: build flash
98 :compact:
99
100If the board is connected directly to the Linux host computer through LAN,
101configure the network interface:
102
103.. code-block:: console
104
105 $ IFACE=eth0 # Change this to the interface to which the LAN cable is connected
106
107 $ IPV4_ADDR_1="192.0.2.2/24"
108 $ IPV4_ROUTE_1="192.0.2.0/24"
109
110 $ sudo ip address add $IPV4_ADDR_1 dev $IFACE
111 $ sudo ip route add $IPV4_ROUTE_1 dev $IFACE
112 $ sudo ip link set dev $IFACE up
113
114You can run ``sudo ip addr flush dev $IFACE`` to undo the steps above.
115
116.. note::
117 For mosquitto 2.0 and up, ensure you set unauthenticated access by
118 adding the following to the mosquitto configuration file ``mosquitto.conf``:
119
120 .. code-block:: none
121
122 listener 1883
123 allow_anonymous true
124 bind_interface eth0
125
126Open another terminal window and type:
127
128.. code-block:: console
129
130 $ sudo mosquitto -v -p 1883 # For mosquitto < 2.0
131 $ sudo mosquitto -v -c mosquitto.conf # For mosquitto >= 2.0
132
133Open another terminal window and type:
134
135.. code-block:: console
136
137 $ mosquitto_sub -t sensors
138
139Connecting securely using TLS
140=============================
141
142While it is possible to set up a local secure MQTT server and update the
143sample to connect to it, it does require some work on the user's part to
144create the certificates and to set them up with the server.
145
146Alternatively, a `publicly available Mosquitto MQTT server/broker
147<https://test.mosquitto.org/>`_ is available to quickly and easily
148try this sample with TLS enabled, by following these steps:
149
150- Download the server's CA certificate file in DER format from
151 https://test.mosquitto.org
152- In :file:`src/test_certs.h`, set ``ca_certificate[]`` using the certificate
153 contents (or set it to its filename if the socket offloading feature is
154 enabled on your platform and :kconfig:option:`CONFIG_TLS_CREDENTIAL_FILENAMES` is
155 set to ``y``).
156- In :file:`src/config.h`, set SERVER_ADDR to the IP address to connect to,
157 i.e., the IP address of test.mosquitto.org ``"37.187.106.16"``
158- In :file:`src/main.c`, set TLS_SNI_HOSTNAME to ``"test.mosquitto.org"``
159 to match the Common Name (CN) in the downloaded certificate.
160- Build the sample by specifying ``-DEXTRA_CONF_FILE=overlay-tls.conf``
161 when running ``west build`` or ``cmake`` (or refer to the TLS offloading
162 section below if your platform uses the offloading feature).
163- Flash the binary onto the device to run the sample:
164
165.. code-block:: console
166
167 $ ninja flash
168
169TLS offloading
170==============
171
172For boards that support this feature, TLS offloading is used by
173specifying ``-DEXTRA_CONF_FILE=overlay-tls-offload.conf`` when running ``west
174build`` or ``cmake``.
175
176Using this overlay enables TLS without bringing in mbedtls.
177
178SOCKS5 proxy support
179====================
180
181It is also possible to connect to the MQTT broker through a SOCKS5 proxy.
182To enable it, use ``-DEXTRA_CONF_FILE=overlay-socks5.conf`` when running ``west
183build`` or ``cmake``.
184
185By default, to make the testing easier, the proxy is expected to run on the
186same host as the MQTT broker.
187
188To start a proxy server, ``ssh`` can be used.
189Use the following command to run it on your host with the default port:
190
191.. code-block:: console
192
193 $ ssh -N -D 0.0.0.0:1080 localhost
194
195To connect to a proxy server that is not running under the same IP as the MQTT
196broker or uses a different port number, modify the following values:
197
198.. code-block:: c
199
200 #define SOCKS5_PROXY_ADDR SERVER_ADDR
201 #define SOCKS5_PROXY_PORT 1080
202
203
204Running on cc3220sf_launchxl
205============================
206
207Offloading on cc3220sf_launchxl also provides DHCP services, so the sample
208uses dynamic IP addresses on this board.
209
210By default, the sample is set up to connect to the broker at the address
211specified by SERVER_ADDR in config.h. If the broker is secured using TLS, users
212should enable TLS offloading, upload the server's certificate
213authority file in DER format to the device filesystem using TI Uniflash,
214and name it "ca_cert.der".
215
216In addition, TLS_SNI_HOSTNAME in main.c should be defined to match the
217Common Name (CN) in the certificate file in order for the TLS domain
218name verification to succeed.
219
220See the note on Provisioning and Fast Connect in :zephyr:board:`cc3220sf_launchxl`.
221
222The Secure Socket Offload section has information on programming the
223certificate to flash.
224
225Proceed to test as above.
226
227Sample output
228=============
229
230This is the output from the FRDM UART console, with:
231
232.. code-block:: cfg
233
234 CONFIG_NET_SAMPLE_APP_MAX_ITERATIONS=5
235
236.. code-block:: console
237
238 [dev/eth_mcux] [INF] eth_0_init: Enabled 100M full-duplex mode.
239 [dev/eth_mcux] [DBG] eth_0_init: MAC 00:04:9f:3e:1a:0a
240 [publisher:233] network_setup: 0 <OK>
241 [publisher:258] mqtt_init: 0 <OK>
242 [connect_cb:81] user_data: CONNECTED
243 [try_to_connect:212] mqtt_tx_connect: 0 <OK>
244 [publisher:276] try_to_connect: 0 <OK>
245 [publisher:285] mqtt_tx_pingreq: 0 <OK>
246 [publisher:290] mqtt_tx_publish: 0 <OK>
247 [publish_cb:149] <MQTT_PUBACK> packet id: 1888, user_data: PUBLISH
248 [publisher:295] mqtt_tx_publish: 0 <OK>
249 [publish_cb:149] <MQTT_PUBREC> packet id: 16356, user_data: PUBLISH
250 [publish_cb:149] <MQTT_PUBCOMP> packet id: 16356, user_data: PUBLISH
251 [publisher:300] mqtt_tx_publish: 0 <OK>
252 [publisher:285] mqtt_tx_pingreq: 0 <OK>
253 [publisher:290] mqtt_tx_publish: 0 <OK>
254 [publish_cb:149] <MQTT_PUBACK> packet id: 45861, user_data: PUBLISH
255 [publisher:295] mqtt_tx_publish: 0 <OK>
256 [publish_cb:149] <MQTT_PUBREC> packet id: 53870, user_data: PUBLISH
257 [publish_cb:149] <MQTT_PUBCOMP> packet id: 53870, user_data: PUBLISH
258 [publisher:300] mqtt_tx_publish: 0 <OK>
259 [publisher:285] mqtt_tx_pingreq: 0 <OK>
260 [publisher:290] mqtt_tx_publish: 0 <OK>
261 [publish_cb:149] <MQTT_PUBACK> packet id: 60144, user_data: PUBLISH
262 [publisher:295] mqtt_tx_publish: 0 <OK>
263 [publish_cb:149] <MQTT_PUBREC> packet id: 6561, user_data: PUBLISH
264 [publish_cb:149] <MQTT_PUBCOMP> packet id: 6561, user_data: PUBLISH
265 [publisher:300] mqtt_tx_publish: 0 <OK>
266 [publisher:285] mqtt_tx_pingreq: 0 <OK>
267 [publisher:290] mqtt_tx_publish: 0 <OK>
268 [publish_cb:149] <MQTT_PUBACK> packet id: 38355, user_data: PUBLISH
269 [publisher:295] mqtt_tx_publish: 0 <OK>
270 [publish_cb:149] <MQTT_PUBREC> packet id: 60656, user_data: PUBLISH
271 [publish_cb:149] <MQTT_PUBCOMP> packet id: 60656, user_data: PUBLISH
272 [publisher:300] mqtt_tx_publish: 0 <OK>
273 [publisher:285] mqtt_tx_pingreq: 0 <OK>
274 [publisher:290] mqtt_tx_publish: 0 <OK>
275 [publish_cb:149] <MQTT_PUBACK> packet id: 28420, user_data: PUBLISH
276 [publisher:295] mqtt_tx_publish: 0 <OK>
277 [publish_cb:149] <MQTT_PUBREC> packet id: 49829, user_data: PUBLISH
278 [publish_cb:149] <MQTT_PUBCOMP> packet id: 49829, user_data: PUBLISH
279 [publisher:300] mqtt_tx_publish: 0 <OK>
280 [disconnect_cb:101] user_data: DISCONNECTED
281 [publisher:304] mqtt_tx_disconnect: 0 <OK>
282
283 Bye!
284
285The line:
286
287.. code-block:: console
288
289 [try_to_connect:220] mqtt_connect: -5 <ERROR>
290
291means that an error was detected and a new connect message will be sent.
292
293The MQTT API is asynchronous, so messages are displayed as the callbacks are
294executed.
295
296This is the information that the subscriber will receive:
297
298.. code-block:: console
299
300 $ mosquitto_sub -t sensors
301 DOORS:OPEN_QoS0
302 DOORS:OPEN_QoS1
303 DOORS:OPEN_QoS2
304 DOORS:OPEN_QoS0
305 DOORS:OPEN_QoS1
306 DOORS:OPEN_QoS2
307 DOORS:OPEN_QoS0
308 DOORS:OPEN_QoS1
309 DOORS:OPEN_QoS2
310 DOORS:OPEN_QoS0
311 DOORS:OPEN_QoS1
312 DOORS:OPEN_QoS2
313 DOORS:OPEN_QoS0
314 DOORS:OPEN_QoS1
315 DOORS:OPEN_QoS2
316
317This is the output from the MQTT broker:
318
319.. code-block:: console
320
321 $ sudo mosquitto -v
322 1485663791: mosquitto version 1.3.4 (build date 2014-08-17 00:14:52-0300) starting
323 1485663791: Using default config.
324 1485663791: Opening ipv4 listen socket on port 1883.
325 1485663791: Opening ipv6 listen socket on port 1883.
326 1485663797: New connection from 192.168.1.101 on port 1883.
327 1485663797: New client connected from 192.168.1.101 as zephyr_publisher (c1, k0).
328 1485663797: Sending CONNACK to zephyr_publisher (0)
329 1485663798: Received PINGREQ from zephyr_publisher
330 1485663798: Sending PINGRESP to zephyr_publisher
331 1485663798: Received PUBLISH from zephyr_publisher (d0, q0, r0, m0, 'sensors', ... (15 bytes))
332 1485663799: Received PUBLISH from zephyr_publisher (d0, q1, r0, m1888, 'sensors', ... (15 bytes))
333 1485663799: Sending PUBACK to zephyr_publisher (Mid: 1888)
334 1485663799: Received PUBLISH from zephyr_publisher (d0, q2, r0, m16356, 'sensors', ... (15 bytes))
335 1485663799: Sending PUBREC to zephyr_publisher (Mid: 16356)
336 1485663799: Received PUBREL from zephyr_publisher (Mid: 16356)
337 1485663799: Sending PUBCOMP to zephyr_publisher (Mid: 16356)
338 1485663800: Received PINGREQ from zephyr_publisher
339 1485663800: Sending PINGRESP to zephyr_publisher
340 1485663800: Received PUBLISH from zephyr_publisher (d0, q0, r0, m0, 'sensors', ... (15 bytes))
341 1485663801: Received PUBLISH from zephyr_publisher (d0, q1, r0, m45861, 'sensors', ... (15 bytes))
342 1485663801: Sending PUBACK to zephyr_publisher (Mid: 45861)
343 1485663801: Received PUBLISH from zephyr_publisher (d0, q2, r0, m53870, 'sensors', ... (15 bytes))
344 1485663801: Sending PUBREC to zephyr_publisher (Mid: 53870)
345 1485663801: Received PUBREL from zephyr_publisher (Mid: 53870)
346 1485663801: Sending PUBCOMP to zephyr_publisher (Mid: 53870)
347 1485663802: Received PINGREQ from zephyr_publisher
348 1485663802: Sending PINGRESP to zephyr_publisher
349 1485663802: Received PUBLISH from zephyr_publisher (d0, q0, r0, m0, 'sensors', ... (15 bytes))
350 1485663803: Received PUBLISH from zephyr_publisher (d0, q1, r0, m60144, 'sensors', ... (15 bytes))
351 1485663803: Sending PUBACK to zephyr_publisher (Mid: 60144)
352 1485663803: Received PUBLISH from zephyr_publisher (d0, q2, r0, m6561, 'sensors', ... (15 bytes))
353 1485663803: Sending PUBREC to zephyr_publisher (Mid: 6561)
354 1485663803: Received PUBREL from zephyr_publisher (Mid: 6561)
355 1485663803: Sending PUBCOMP to zephyr_publisher (Mid: 6561)
356 1485663804: Received PINGREQ from zephyr_publisher
357 1485663804: Sending PINGRESP to zephyr_publisher
358 1485663804: Received PUBLISH from zephyr_publisher (d0, q0, r0, m0, 'sensors', ... (15 bytes))
359 1485663805: Received PUBLISH from zephyr_publisher (d0, q1, r0, m38355, 'sensors', ... (15 bytes))
360 1485663805: Sending PUBACK to zephyr_publisher (Mid: 38355)
361 1485663805: Received PUBLISH from zephyr_publisher (d0, q2, r0, m60656, 'sensors', ... (15 bytes))
362 1485663805: Sending PUBREC to zephyr_publisher (Mid: 60656)
363 1485663805: Received PUBREL from zephyr_publisher (Mid: 60656)
364 1485663805: Sending PUBCOMP to zephyr_publisher (Mid: 60656)
365 1485663806: Received PINGREQ from zephyr_publisher
366 1485663806: Sending PINGRESP to zephyr_publisher
367 1485663806: Received PUBLISH from zephyr_publisher (d0, q0, r0, m0, 'sensors', ... (15 bytes))
368 1485663807: Received PUBLISH from zephyr_publisher (d0, q1, r0, m28420, 'sensors', ... (15 bytes))
369 1485663807: Sending PUBACK to zephyr_publisher (Mid: 28420)
370 1485663807: Received PUBLISH from zephyr_publisher (d0, q2, r0, m49829, 'sensors', ... (15 bytes))
371 1485663807: Sending PUBREC to zephyr_publisher (Mid: 49829)
372 1485663807: Received PUBREL from zephyr_publisher (Mid: 49829)
373 1485663807: Sending PUBCOMP to zephyr_publisher (Mid: 49829)
374 1485663808: Received DISCONNECT from zephyr_publisher
375
376Wi-Fi
377=====
378
379The IPv4 Wi-Fi support can be enabled in the sample with
380:ref:`Wi-Fi snippet <snippet-wifi-ipv4>`.
381
