nRF9160: Simple MQTT

The Simple MQTT sample demonstrates how to easily connect an nRF9160 SiP to an MQTT broker and send and receive data.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

Additionally, the sample supports X86 Emulation (QEMU).

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Overview

The sample connects to an MQTT broker and publishes the data it receives on the configured subscribe topic to the configured publish topic. On a button press event or typing mqtt publish in the terminal emulator, the sample publishes the configured message to the configured publish topic. By default, the sample can establish a secure (TLS) connection or a non-secure connection to the configured MQTT broker. The sample disables power saving modes (PSM and eDRX) so that network events are processed as soon as possible.

Configuration

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

Configuration options

Check and configure the following configuration options for the sample:

CONFIG_MQTT_BROKER_HOSTNAME - MQTT Broker host name

This configuration option defines the MQTT Broker host name.

CONFIG_MQTT_CLIENT_ID - MQTT Client ID

This configuration option specifies the MQTT Client ID.

CONFIG_MQTT_SUB_TOPIC - MQTT Subscribe topic

This configuration option sets the MQTT Subscribe topic.

CONFIG_MQTT_PUB_TOPIC - MQTT Publish topic

This configuration option sets the MQTT Publish topic.

CONFIG_MQTT_BROKER_PORT - MQTT Broker Port

This configuration option specifies the port number associated with the MQTT broker.

CONFIG_BUTTON_EVENT_PUBLISH_MSG - Button event publish message

This configuration option specifies the message text which is published on a button press.

CONFIG_BUTTON_EVENT_BTN_NUM - Button number for publish

This configuration option specifies the button number which, when pressed, will publish an MQTT message.

CONFIG_MQTT_RECONNECT_DELAY_S - MQTT broker reconnect delay

This configuration option specifies the delay (in seconds) before attempting to reconnect to the broker.

CONFIG_LTE_CONNECT_RETRY_DELAY_S - LTE connection retry delay

This configuration option specifies delay (in seconds) before attempting to retry LTE connection.

Configuration files

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

  • prj.conf - For nRF9160 DK

  • prj_qemu_x86.conf - For x86 Emulation (QEMU)

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

  • overlay-tls.conf - TLS overlay configuration file for nRF9160 DK

  • overlay-qemu-x86-tls.conf - TLS overlay configuration file for x86 Emulation (QEMU)

They are located in samples/nrf9160/mqtt_simple 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 on the command line, you can build the sample with the TLS configuration for nRF9160 DK as follows:

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

Note

The CA certificate for the default MQTT broker is included in the project and automatically provisioned after boot if the sample is built with the TLS configuration.

Building and running

This sample can be found under samples/nrf9160/mqtt_simple 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 nRF9160 DK.

  4. Observe that the sample displays the following information in the terminal:

    The MQTT simple sample started

  5. Observe that the development kit connects to the configured MQTT broker (CONFIG_MQTT_BROKER_HOSTNAME) after it gets the LTE connection. At this stage, the development kit is ready to echo the data sent to it on the configured subscribe topic (CONFIG_MQTT_SUB_TOPIC).

  6. Use an MQTT client like Mosquitto to subscribe to and publish data to the broker. Observe that the development kit publishes all the data that you publish to CONFIG_MQTT_SUB_TOPIC on CONFIG_MQTT_PUB_TOPIC.

Sample output

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

*** Booting Zephyr OS build v2.4.0-ncs1-rc1-6-g45f2d5cf8ea4  ***
<inf> mqtt_simple: The MQTT simple sample started
<inf> mqtt_simple: LTE Link Connecting...
<inf> mqtt_simple: LTE Link Connected!
<inf> mqtt_simple: Disabling PSM and eDRX
<inf> mqtt_simple: IPv4 Address found 137.135.83.217
<inf> mqtt_simple: MQTT client connected
<inf> mqtt_simple: Subscribing to: my/subscribe/topic len 18
<inf> mqtt_simple: SUBACK packet id: 1234
<inf> mqtt_simple: Publishing: Hello from nRF91 MQTT Simple Sample
<inf> mqtt_simple: to topic: my/publish/topic len: 16
<inf> mqtt_simple: PUBACK packet id: 51700

Troubleshooting

Public MQTT brokers might be unstable. If you experience problems connecting to the MQTT broker, try switching to another MQTT broker by changing the value of the CONFIG_MQTT_BROKER_HOSTNAME configuration option.

Note

If the CONFIG_MQTT_BROKER_HOSTNAME configuration option is changed and the overlay TLS configuration is used, the included CA certificate must be updated with the CA certificate for the newly configurated MQTT broker.

Dependencies

This sample uses the following nRF Connect SDK library:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr library:

In addition, it uses the following secure firmware component: