README.rst
1.. _mqtt-azure-sample:
2
3MQTT Azure Sample
4#################
5
6Overview
7********
8
9This sample application demonstrates how an MQTT client
10can publish messages to an Azure Cloud IoT hub based on MQTT protocol.
11
12- Acquire a DHCPv4 lease
13- Establish a TLS connection with Azure Cloud IoT hub
14- Publish data to the Azure cloud
15- SOCKS5 supported
16- DNS supported
17
18The source code of this sample application can be found at:
19:zephyr_file:`samples/net/cloud/mqtt_azure`.
20
21Requirements
22************
23
24- Azure Cloud account
25- Azure IOT Cloud credentials and required information
26- Freedom Board (FRDM-K64F)
27- Network connectivity
28
29Building and Running
30********************
31
32This application has been built and tested on the NXP FRDMK64F.
33Certs are required to authenticate to the Azure Cloud IoT hub.
34Current certs in :zephyr_file:`samples/net/cloud/mqtt_azure/src/digicert.cer` are
35copied from `<https://github.com/Azure/azure-iot-sdk-c/blob/master/certs/certs.c>`_
36
37Configure the following Kconfig options based on your Azure Cloud IoT Hub
38in your own overlay config file:
39
40- SAMPLE_CLOUD_AZURE_USERNAME - Username field use::
41
42 {iothubhostname}/{device_id}/?api-version=2018-06-30,
43
44 where ``{iothubhostname}`` is the full CName of the IoT hub.
45
46- SAMPLE_CLOUD_AZURE_PASSWORD - Password field, use an SAS token.
47- SAMPLE_CLOUD_AZURE_CLIENT_ID - ClientId field, use the deviceId.
48- SAMPLE_CLOUD_AZURE_HOSTNAME - IoT hub hostname
49- SAMPLE_CLOUD_AZURE_SERVER_ADDR - IP address of the Azure MQTT broker
50- SAMPLE_CLOUD_AZURE_SERVER_PORT - Port number of the Azure MQTT broker
51
52You'll also need to set these Kconfig options if you're running
53the sample behind a proxy:
54
55- SAMPLE_SOCKS_ADDR - IP address of SOCKS5 Proxy server
56- SAMPLE_SOCKS_PORT - Port number of SOCKS5 Proxy server
57
58On your Linux host computer, open a terminal window, locate the source code
59of this sample application (i.e., :zephyr_file:`samples/net/cloud/mqtt_azure`) and type:
60
61.. zephyr-app-commands::
62 :zephyr-app: samples/net/cloud/mqtt_azure
63 :board: frdm_k64f
64 :conf: "prj.conf <overlay.conf>"
65 :goals: build flash
66 :compact:
67
68Also this application can be tested with QEMU. This is described in
69:ref:`networking_with_qemu`. Set up Zephyr and NAT/masquerading on host
70to access Internet and use :file:`overlay-qemu_x86.conf`.
71DHCP support is not enabled with QEMU. It uses static IP addresses.
72
73Sample overlay file
74===================
75
76This is the overlay template for Azure IoT hub and other details:
77
78.. code-block:: console
79
80 CONFIG_SAMPLE_CLOUD_AZURE_USERNAME="<username>"
81 CONFIG_SAMPLE_CLOUD_AZURE_PASSWORD="<SAS token>"
82 CONFIG_SAMPLE_CLOUD_AZURE_CLIENT_ID="<device id>"
83 CONFIG_SAMPLE_CLOUD_AZURE_HOSTNAME="<IoT hub hostname>"
84 CONFIG_SAMPLE_SOCKS_ADDR="<proxy addr>"
85 CONFIG_SAMPLE_SOCKS_PORT=<proxy port>
86 CONFIG_SAMPLE_CLOUD_AZURE_SERVER_ADDR="<server ip addr, if DNS disabled set this>"
87 CONFIG_SAMPLE_CLOUD_AZURE_SERVER_PORT=<server port, if DNS disabled set this>
88
89Sample output
90=============
91
92This is the output from the FRDM UART console, with:
93
94.. code-block:: console
95
96 [00:00:03.001,000] <inf> eth_mcux: Enabled 100M full-duplex mode.
97 [00:00:03.010,000] <dbg> mqtt_azure.main: Waiting for network to setup...
98 [00:00:03.115,000] <inf> net_dhcpv4: Received: 10.0.0.2
99 [00:00:03.124,000] <inf> net_config: IPv4 address: 10.0.0.2
100 [00:00:03.132,000] <inf> net_config: Lease time: 43200 seconds
101 [00:00:03.140,000] <inf> net_config: Subnet: 255.255.255.0
102 [00:00:03.149,000] <inf> net_config: Router: 10.0.0.10
103 [00:00:06.157,000] <dbg> mqtt_azure.try_to_connect: attempting to connect...
104 [00:00:06.167,000] <dbg> net_sock_tls.tls_alloc: (0x200024f8): Allocated TLS context, 0x20001110
105 [00:00:19.412,000] <dbg> mqtt_azure.mqtt_event_handler: MQTT client connected!
106 [00:00:19.424,000] <dbg> mqtt_azure.publish_message: mqtt_publish OK
107 [00:00:19.830,000] <dbg> mqtt_azure.mqtt_event_handler: PUBACK packet id: 63387
108 [00:00:31.842,000] <dbg> mqtt_azure.publish_message: mqtt_publish OK
109 [00:00:51.852,000] <dbg> mqtt_azure.publish_message: mqtt_publish OK
110 [00:00:51.861,000] <dbg> mqtt_azure.mqtt_event_handler: PUBACK packet id: 38106
111
112You can also check events or messages information on Azure Portal.
113
114Cloud to device communication
115=============================
116
117Goto IoT devices section in Azure Portal. Click on the device from
118IoT devices. If you have configured multiple devices, select correct device.
119Goto Message to Device section. Enter text in Message Body section.
120Click on Send Message.
121
122See `Azure Cloud MQTT Documentation
123<https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support>`_.
124
