samples/net/cloud/mqtt_azure/README.rst

.. _mqtt-azure-sample:

MQTT Azure Sample
#################

Overview
********

This sample application demonstrates how an MQTT client
can publish messages to an Azure Cloud IoT hub based on MQTT protocol.

- Acquire a DHCPv4 lease
- Establish a TLS connection with Azure Cloud IoT hub
- Publish data to the Azure cloud
- SOCKS5 supported
- DNS supported

The source code of this sample application can be found at:
:zephyr_file:`samples/net/mqtt_azure`.

Requirements
************

- Azure Cloud account
- Azure IOT Cloud credentials and required information
- Freedom Board (FRDM-K64F)
- Network connectivity

Building and Running
********************

This application has been built and tested on the NXP FRDMK64F.
Certs are required to authenticate to the Azure Cloud IoT hub.
Current certs in :zephyr_file:`samples/net/cloud/mqtt_azure/src/digicert.cer` are
copied from `<https://github.com/Azure/azure-iot-sdk-c/blob/master/certs/certs.c>`_

Configure the following Kconfig options based on your Azure Cloud IoT Hub
in your own overlay config file:

- SAMPLE_CLOUD_AZURE_USERNAME - Username field use::

    {iothubhostname}/{device_id}/?api-version=2018-06-30,

  where ``{iothubhostname}`` is the full CName of the IoT hub.

- SAMPLE_CLOUD_AZURE_PASSWORD    - Password field, use an SAS token.
- SAMPLE_CLOUD_AZURE_CLIENT_ID   - ClientId field, use the deviceId.
- SAMPLE_CLOUD_AZURE_HOSTNAME    - IoT hub hostname
- SAMPLE_CLOUD_AZURE_SERVER_ADDR - IP address of the Azure MQTT broker
- SAMPLE_CLOUD_AZURE_SERVER_PORT - Port number of the Azure MQTT broker

You'll also need to set these Kconfig options if you're running
the sample behind a proxy:

- SAMPLE_SOCKS_ADDR - IP address of SOCKS5 Proxy server
- SAMPLE_SOCKS_PORT - Port number of SOCKS5 Proxy server

On your Linux host computer, open a terminal window, locate the source code
of this sample application (i.e., :zephyr_file:`samples/net/cloud/mqtt_azure`) and type:

.. zephyr-app-commands::
   :zephyr-app: samples/net/cloud/mqtt_azure
   :board: frdm_k64f
   :conf: "prj.conf <overlay.conf>"
   :goals: build flash
   :compact:

Also this application can be tested with QEMU. This is described in
:ref:`networking_with_qemu`. Set up Zephyr and NAT/masquerading on host
to access Internet and use :file:`overlay-qemu_x86.conf`.
DHCP support is not enabled with QEMU. It uses static IP addresses.

Sample overlay file
===================

This is the overlay template for Azure IoT hub and other details:

.. code-block:: console

	CONFIG_SAMPLE_CLOUD_AZURE_USERNAME="<username>"
	CONFIG_SAMPLE_CLOUD_AZURE_PASSWORD="<SAS token>"
	CONFIG_SAMPLE_CLOUD_AZURE_CLIENT_ID="<device id>"
	CONFIG_SAMPLE_CLOUD_AZURE_HOSTNAME="<IoT hub hostname>"
	CONFIG_SAMPLE_SOCKS_ADDR="<proxy addr>"
	CONFIG_SAMPLE_SOCKS_PORT=<proxy port>
	CONFIG_SAMPLE_CLOUD_AZURE_SERVER_ADDR="<server ip addr, if DNS disabled set this>"
	CONFIG_SAMPLE_CLOUD_AZURE_SERVER_PORT=<server port, if DNS disabled set this>

Sample output
=============

This is the output from the FRDM UART console, with:

.. code-block:: console

	[00:00:03.001,000] <inf> eth_mcux: Enabled 100M full-duplex mode.
	[00:00:03.010,000] <dbg> mqtt_azure.main: Waiting for network to setup...
	[00:00:03.115,000] <inf> net_dhcpv4: Received: 10.0.0.2
	[00:00:03.124,000] <inf> net_config: IPv4 address: 10.0.0.2
	[00:00:03.132,000] <inf> net_config: Lease time: 43200 seconds
	[00:00:03.140,000] <inf> net_config: Subnet: 255.255.255.0
	[00:00:03.149,000] <inf> net_config: Router: 10.0.0.10
	[00:00:06.157,000] <dbg> mqtt_azure.try_to_connect: attempting to connect...
	[00:00:06.167,000] <dbg> net_sock_tls.tls_alloc: (0x200024f8): Allocated TLS context, 0x20001110
	[00:00:19.412,000] <dbg> mqtt_azure.mqtt_event_handler: MQTT client connected!
	[00:00:19.424,000] <dbg> mqtt_azure.publish_message: mqtt_publish OK
	[00:00:19.830,000] <dbg> mqtt_azure.mqtt_event_handler: PUBACK packet id: 63387
	[00:00:31.842,000] <dbg> mqtt_azure.publish_message: mqtt_publish OK
	[00:00:51.852,000] <dbg> mqtt_azure.publish_message: mqtt_publish OK
	[00:00:51.861,000] <dbg> mqtt_azure.mqtt_event_handler: PUBACK packet id: 38106

You can also check events or messages information on Azure Portal.

See `Azure Cloud MQTT Documentation
<https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support>`_.