Sample description

The MQTT sample communicates with an MQTT broker either over LTE using the nRF9160 DK or Thingy:91, or over Wi-Fi using the nRF7002 DK.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

Thingy:91

PCA20035

thingy91_nrf9160

thingy91_nrf9160_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

nRF7002 DK

PCA10143

nrf7002dk_nrf5340

nrf7002dk_nrf5340_cpuapp

Additionally, the sample supports emulation using Native Posix.

Overview

The sample connects to either LTE or Wi-Fi, depending on the board for which the sample is compiled. Subsequently, the sample connects to a configured MQTT server (default is test.mosquitto.org), where it publishes messages to the topic my/publish/topic. You can also trigger message publication by pressing any of the buttons on the board.

The sample also subscribes to the topic my/subscribe/topic, and receives any message published to that topic. The sample supports Transport Layer Security (TLS) and it can be enabled through overlay configuration files included in the sample.

Note

When enabling TLS and building for nRF9160 based boards, the size of the incoming message cannot exceed 2 kB. This is due to a limitation in the modem’s internal TLS buffers.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Configuration options

Check and configure the following Kconfig options:

General options

CONFIG_MQTT_SAMPLE_TRIGGER_TIMEOUT_SECONDS - Trigger timeout

This configuration option sets the interval at which the sample publishes a message to the MQTT broker.

CONFIG_MQTT_SAMPLE_TRANSPORT_RECONNECTION_TIMEOUT_SECONDS - Transport reconnection timeout

This configuration option sets the interval at which the sample tries to reconnect to the MQTT broker upon a lost connection.

CONFIG_MQTT_SAMPLE_TRANSPORT_BROKER_HOSTNAME - MQTT broker hostname

This configuration sets the MQTT broker hostname. Default is test.mosquitto.org.

CONFIG_MQTT_SAMPLE_TRANSPORT_CLIENT_ID - MQTT client ID

This configuration sets the MQTT client ID name. If not set, the client ID will default to the modem’s IMEI number for nRF9160 boards, MAC address for the nRF7002 DK, or a random number for Native Posix.

CONFIG_MQTT_SAMPLE_TRANSPORT_PUBLISH_TOPIC - MQTT publish topic

This configuration option sets the topic to which the sample publishes messages. Default is my/publish/topic.

CONFIG_MQTT_SAMPLE_TRANSPORT_SUBSCRIBE_TOPIC - MQTT subscribe topic

This configuration option sets the topic to which the sample subscribes. Default is my/subscribe/topic.

Wi-Fi options

Additional configuration

Check and configure the following library Kconfig options specific to the MQTT helper library:

Configuration files

The sample provides predefined configuration files for the following development kits:

  • prj.conf - General project configuration file.

  • boards/nrf9160dk_nrf9160_ns.conf - Configuration file for the nRF9160 DK.

  • boards/thingy91_nrf9160_ns.conf - Configuration file for the Thingy:91.

  • boards/nrf7002dk_nrf5340_cpuapp.conf - Configuration file for the nRF7002 DK.

  • boards/native_posix.conf - Configuration file for native posix.

Files that are located under the /boards folder is automatically merged with the prj.conf file when you build for corresponding target.

In addition, the sample provides the following overlay configuration files, which are used to enable additional features in the sample:

  • overlay-tls-nrf9160.conf - TLS overlay configuration file for nRF9160 DK and Thingy:91.

  • overlay-tls-nrf7002.conf - TLS overlay configuration file for nRF7002 DK.

  • overlay-tls-native_posix.conf - TLS overlay configuration file for native posix.

They are located in samples/net/mqtt folder.

To add a specific overlay configuration file to the build, add the -- -DOVERLAY_CONFIG=<overlay_config_file> flag to your build.

See Providing CMake options for instructions on how to add this option to your build. For example, when building with the command line, the following commands can be used for the nRF9160 DK:

west build -b nrf9160dk_nrf9160_ns -- -DOVERLAY_CONFIG=overlay-tls-nrf9160.conf

Building and running

This sample can be found under samples/net/mqtt in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, complete the following steps to test it:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  3. Reset your board.

  4. Observe that the board connects to the network and the configured MQTT broker (CONFIG_MQTT_SAMPLE_TRANSPORT_BROKER_HOSTNAME). When a network connection has been established, LED 1 (green) on the board lights up. After the connection has been established the board starts to publish messages to the topic set by CONFIG_MQTT_SAMPLE_TRANSPORT_PUBLISH_TOPIC. The frequency of the messages that are published to the broker can be set by CONFIG_MQTT_SAMPLE_TRIGGER_TIMEOUT_SECONDS or triggered asynchronously by pressing any of the buttons on the board. At any time, the sample can receive messages published to the subscribe topic set by CONFIG_MQTT_SAMPLE_TRANSPORT_SUBSCRIBE_TOPIC.

  5. Use an MQTT client like Mosquitto or VSMQTT to subscribe to, and publish data to the broker.

Sample output

The following serial UART output is displayed in the terminal emulator:

*** Booting Zephyr OS build v2.4.0-ncs1-rc1-6-g45f2d5cf8ea4  ***
[00:00:05.996,520] <inf> network: Connecting to SSID: NORDIC-TEST
[00:00:12.477,783] <inf> network: Wi-Fi Connected
[00:00:17.997,253] <inf> transport: Connected to MQTT broker
[00:00:18.007,049] <inf> transport: Hostname: test.mosquitto.org
[00:00:18.009,981] <inf> transport: Client ID: F4CE37111350
[00:00:18.013,519] <inf> transport: Port: 8883
[00:00:18.018,341] <inf> transport: TLS: Yes
[00:00:18.078,521] <inf> transport: Subscribed to topic my/subscribe/topic
[00:01:01.475,982] <inf> transport: Publishing message: "Hello MQTT! Current uptime is: 61458" on topic: "my/publish/topic"
[00:02:01.475,982] <inf> transport: Publishing message: "Hello MQTT! Current uptime is: 121458" on topic: "my/publish/topic"
[00:03:01.475,982] <inf> transport: Publishing message: "Hello MQTT! Current uptime is: 181458" on topic: "my/publish/topic"
[00:04:01.475,982] <inf> transport: Publishing message: "Hello MQTT! Current uptime is: 241458" on topic: "my/publish/topic"
[00:05:01.475,982] <inf> transport: Publishing message: "Hello MQTT! Current uptime is: 301459" on topic: "my/publish/topic"

Reconnection logic

If the network connection is lost, the following log output is displayed:

<inf> network: Disconnected

If this occurs, the network stack automatically reconnects to the network using its built-in backoff functionality.

If the TCP/IP (MQTT) connection is lost, the following log output is displayed:

<inf> transport: Disconnected from MQTT broker

If this occurs, the sample’s transport module has built-in reconnection logic that will try to reconnect at the frequency set by CONFIG_MQTT_SAMPLE_TRANSPORT_RECONNECTION_TIMEOUT_SECONDS.

Emulation

The sample can be run in Native Posix that simplifies development and testing and removes the need for hardware. Before you can build and run native posix, you need to perform the steps included in this link: Networking with native_posix board.

When the aforementioned steps are completed, you can build and run the sample by using the following commands:

west build -b native_posix samples/net/mqtt
west build -t run

Troubleshooting

  • If you are having issues with connectivity on nRF9160 based boards, see the Trace Collector documentation to learn how to capture modem traces in order to debug network traffic in Wireshark.

  • Public MQTT brokers might be unstable. If you have trouble connecting to the MQTT broker, try switching to another broker by changing the value of the CONFIG_MQTT_SAMPLE_TRANSPORT_BROKER_HOSTNAME configuration option. If you are switching to another broker, remember to update the CA certificate. To know more on certificates and provisioning, see Provisioning.

Dependencies

This sample uses the following Zephyr libraries:

It uses the following libraries and secure firmware component for nRF9160 DK and Thingy:91 builds:

It uses the following libraries for nRF7002 DK builds: