Connecting to an MQTT broker

In this exercise, we will establish bidirectional communication between your board (acting as an MQTT client) and another remote MQTT client, running on your PC. The remote client will control the LEDs and monitor the status of the buttons on the board via MQTT subscribe and publish commands.

To achieve this, we will program the board to publish the status of its buttons to a “buttons topic” upon a button push. Consequently, the remote client (running on your computer) can subscribe to this topic and receive messages whenever a button is pushed.

Following the same logic, the board will subscribe to a LEDs topic. The remote client can then publish to this topic with commands on whether the LED should be off or on. This will make the board receive commands about what the status of its LEDs should be.

We will practice using the MQTT helper library in nRF Connect SDK to:

• Configure the board as an MQTT client
• Connect to an MQTT broker (mqtt.nordicsemi.academy)
• Publish and subscribe to MQTT topics, set by the Kconfig symbols: CONFIG_MQTT_SAMPLE_PUB_TOPIC and CONFIG_MQTT_SAMPLE_SUB_TOPIC
• Control LEDs on the board via a remote MQTT client running on your PC
• Read the status of buttons 1 and 2 on the board via the remote MQTT client running on your PC

Exercise steps

In the GitHub repository for this course, go to the base code for this exercise, found in l4/l4_e1.

1. Enable and configure the MQTT helper library.

1.1. Enable the MQTT helper library and disable persistent sessions by enabling the following Kconfig symbols in the prj.conf file.

CONFIG_MQTT_HELPER=y
CONFIG_MQTT_CLEAN_SESSION=y

• CONFIG_MQTT_HELPER enables the MQTT helper which selects the necessary Kconfigs for MQTT.
• CONFIG_MQTT_CLEAN_SESSION is to disable persistent sessions. Setting this flag to y disables a persistent MQTT session.

1.2 Set the MQTT topics.

In the Kconfig file in the exercise folder, notice that there are many custom Kconfigs defined. Some of these have default values, like the broker hostname, and some we need to set in prj.conf before building the project.

We need to set the following Kconfigs in the prj.conf file.

• CONFIG_MQTT_SAMPLE_PUB_TOPIC: the topic name that the board will publish to.
• CONFIG_MQTT_SAMPLE_SUB_TOPIC: the topic name that the board will subscribe to.

Add the following lines to the prj.conf file

CONFIG_MQTT_SAMPLE_PUB_TOPIC="wifi/fund/board/publish/button/topic99"
CONFIG_MQTT_SAMPLE_SUB_TOPIC="wifi/fund/board/subscribe/led/topic99"

1.3  Include the header file for the MQTT helper library in main.c.

#include <net/mqtt_helper.h>

2. Define the commands to control and monitor LEDs and buttons.

Define the strings to send over MQTT that will tell the board to turn on or off either LED1 or LED2 and what message to send when pressing button 1 or 2.

#define LED1_ON_CMD       "LED1ON"
#define LED1_OFF_CMD      "LED1OFF"
#define LED2_ON_CMD       "LED2ON"
#define LED2_OFF_CMD      "LED2OFF"
#define BUTTON1_MSG       "Button 1 pressed"
#define BUTTON2_MSG       "Button 2 pressed"

3. Define the message ID used when subscribing to topics.

This will be used to verify that a subscription succeeded.

#define SUBSCRIBE_TOPIC_ID 1234

4. Disconnect from MQTT broker if disconnected from network.

In net_mgmt_event_handler(), in the event case NET_EVENT_L4_DISCONNECTED, add a call to mqtt_helper_disconnect() to make sure we explicitly disconnect when losing network connectivity.

This is to cleanup any internal library state.

(void)mqtt_helper_disconnect();

5. Define the function subscribe() to subscribe to a specific topic.

We can subscribe to as many MQTT topics as we want.

5.1 Declare a variable of type mqtt_topic.

For each topic of interest, declare a variable of type mqtt_topic. This variable needs to contain the topic name (in UTF-8 format), the length of the topic name, and the quality of service requested for the subscription.

This is done in the code below where we have created one variable subscribe_topic of type mqtt_topic, to subscribe to CONFIG_MQTT_SAMPLE_SUB_TOPIC with QoS1.

struct mqtt_topic subscribe_topic = {
	.topic = {
		.utf8 = CONFIG_MQTT_SAMPLE_SUB_TOPIC,
		.size = strlen(CONFIG_MQTT_SAMPLE_SUB_TOPIC)
	},
	.qos = MQTT_QOS_1_AT_LEAST_ONCE
};

5.2 Define a subscription list.

Once we have declared the topic(s) of interest, we need to create a subscription list variable of type mqtt_subscription_list. In the initialization of the list, we must provide a pointer to the topic or a pointer to the array of topics (if subscribed to more than one topic). In addition, we specify the number of topics and a message id, which can be a random number, and is used to identify the subscription request.

const struct mqtt_subscription_list subscription_list = {
	.list = &subscribe_topic,
	.list_count = 1,
	.message_id = SUBSCRIBE_TOPIC_ID};

5.3 Subscribe to topics using mqtt_helper_subscribe().

Once we have the list variable initialized, we can call the MQTT helper library function mqtt_subscribe(), which takes one parameter, a pointer to a variable of type mqtt_subscription_list.

	LOG_INF("Subscribing to %s", CONFIG_MQTT_SAMPLE_SUB_TOPIC);
	err = mqtt_helper_subscribe(&subscription_list);
	if (err) {
		LOG_ERR("Failed to subscribe to topics, error: %d", err);
		return;
	}

6. Define the function publish() to publish data to the broker.

In order to publish to a broker (send a message to a topic), we need to use the MQTT helper function mqtt_helper_publish(), which takes one parameter: a pointer to a variable of type mqtt_publish_param which encapsulates the message to be sent.

The function needs to populate the members of the mqtt_publish_param struct and call mqtt_helper_publish() to publish the message to the broker.

6.1 Declare and populate a variable of type mqtt_publish_param.

	struct mqtt_publish_param mqtt_param;

	mqtt_param.message.payload.data = data;
	mqtt_param.message.payload.len = len;
	mqtt_param.message.topic.qos = MQTT_QOS_1_AT_LEAST_ONCE;
	mqtt_param.message_id = mqtt_helper_msg_id_get(),
	mqtt_param.message.topic.topic.utf8 = CONFIG_MQTT_SAMPLE_PUB_TOPIC;
	mqtt_param.message.topic.topic.size = strlen(CONFIG_MQTT_SAMPLE_PUB_TOPIC);
	mqtt_param.dup_flag = 0;
	mqtt_param.retain_flag = 0;

A few things to note:

• We are setting the topic the device will publish to in the line param.message.topic.topic.utf8 = CONFIG_MQTT_SAMPLE_PUB_TOPIC.
• The data to be sent is passed to the function, uint8_t *data, and is set in the line param.message.payload.data = data.
• The message ID is set by using the MQTT helper function mqtt_helper_msg_id_get(), which increments values by one for each call.
• Since we are not using duplication or a persistent MQTT session, the flags dup_flag and retain_flag are set to 0

6.2 Publish to MQTT broker using mqtt_helper_publish().

	err = mqtt_helper_publish(&mqtt_param);
	if (err) {
		LOG_WRN("Failed to send payload, err: %d", err);
		return err;
	}

	LOG_INF("Published message: \"%.*s\" on topic: \"%.*s\"", mqtt_param.message.payload.len,
								  mqtt_param.message.payload.data,
								  mqtt_param.message.topic.topic.size,
								  mqtt_param.message.topic.topic.utf8);

7. Define the callback handlers from the MQTT helper library.

These functions will be called whenever specific MQTT packets are received from the broker, or some library state has changed.

7.1 Define callback handler for CONNACK event.

This function is called upon a CONNACK event, which is an acknowledgement from the broker of the connection result. The return_code variable will indicate whether the connection was succesful or not, see the list of return codes below

If the return code indicates the connection was accepted MQTT_CONNECTION_ACCEPTED, log that as well as some information about the connection.

Then call subscribe() to subscribe to topics from the broker.

static void on_mqtt_connack(enum mqtt_conn_return_code return_code, bool session_present)
{
	if (return_code == MQTT_CONNECTION_ACCEPTED) {
		LOG_INF("Connected to MQTT broker");
		LOG_INF("Hostname: %s", CONFIG_MQTT_SAMPLE_BROKER_HOSTNAME);
		LOG_INF("Client ID: %s", (char *)client_id);
		LOG_INF("Port: %d", CONFIG_MQTT_HELPER_PORT);
		LOG_INF("TLS: %s", IS_ENABLED(CONFIG_MQTT_LIB_TLS) ? "Yes" : "No");
		subscribe();
	} else {
		LOG_WRN("Connection to broker not established, return_code: %d", return_code);
	}
}

7.2 Define callback handler for SUBACK event.

This function is called upon a SUBACK event, which is an acknowledgment from the broker for the subscription request. The result variable will indicate whether the subscription was succesful or not, see the list of return codes below

If the subscription was succesfull, check if the message ID of the packet matches SUBSCRIBE_TOPIC_ID, to confirm it’s the subscription acknowledgement for the CONFIG_MQTT_SAMPLE_SUB_TOPIC topic. Then log the subscription status as well as the received QoS level.

static void on_mqtt_suback(uint16_t message_id, int result)
{	
	if (result != MQTT_SUBACK_FAILURE) {
		if (message_id == SUBSCRIBE_TOPIC_ID) {
			LOG_INF("Subscribed to %s with QoS %d", CONFIG_MQTT_SAMPLE_SUB_TOPIC, result);
			return;
		}
		LOG_WRN("Subscribed to unknown topic, id: %d with QoS %d", message_id, result);
		return;
	}
	LOG_ERR("Topic subscription failed, error: %d", result);
}

7.3 Define callback handler for PUBLISH event.

This callback handler is called whenever there is a message published to the topic we are subscribed to.

We want to examine the message using strncmp() to compare it to the LED commands and turn the LED on or off accordingly.

static void on_mqtt_publish(struct mqtt_helper_buf topic, struct mqtt_helper_buf payload)
{
	LOG_INF("Received payload: %.*s on topic: %.*s", payload.size,
							 payload.ptr,
							 topic.size,
							 topic.ptr);
	
	if (strncmp(payload.ptr, LED1_ON_CMD,
			    sizeof(LED1_ON_CMD) - 1) == 0) {
				dk_set_led_on(DK_LED1);
	} else if (strncmp(payload.ptr, LED1_OFF_CMD,
			   sizeof(LED1_OFF_CMD) - 1) == 0) {
				dk_set_led_off(DK_LED1);
	} else if (strncmp(payload.ptr, LED2_ON_CMD,
			   sizeof(LED2_ON_CMD) - 1) == 0) {
				dk_set_led_on(DK_LED2);
	} else if (strncmp(payload.ptr, LED2_OFF_CMD,
			   sizeof(LED2_OFF_CMD) - 1) == 0) {
				dk_set_led_off(DK_LED2);
	}
}

7.4 Define callback handler for DISCONNECT event.

This function is called upon a disconnect event from the broker. In this case, we log the event and the result.

static void on_mqtt_disconnect(int result)
{
	LOG_INF("MQTT client disconnected: %d", result);
}

8. Define the button handler to publish upon button triggers.

Upon pressing either button 1 or button 2, we want the button handler to publish the corresponding message to the MQTT broker.

In button_handler(), if a button is pressed, call publish() with the message to be published, either BUTTON1_MSG or BUTTON2_MSG, depending on which button was pressed.

8.1 Publish BUTTON1_MSG if button 1 is pressed.

int err = publish(BUTTON1_MSG, sizeof(BUTTON1_MSG) - 1);
if (err) {
	LOG_ERR("Failed to send message, %d", err);
	return;	
}

8.2 Publish BUTTON2_MSG if button 2 is pressed.

int err = publish(BUTTON2_MSG, sizeof(BUTTON2_MSG) - 1);

9. Initialize the MQTT helper library.

Before connecting to the MQTT broker, we need to initialize the MQTT helper library using the library function mqtt_helper_init(), which takes a single parameter: struct mqtt_helper_cfg, with the following members

Let’s assign the callback functions we created in a previous step to the relevant members and pass the struct to mqtt_helper_init() to initialize the library with the callbacks.

Add the following code snippet

	struct mqtt_helper_cfg config = {
		.cb = {
			.on_connack = on_mqtt_connack,
			.on_disconnect = on_mqtt_disconnect,
			.on_publish = on_mqtt_publish,
			.on_suback = on_mqtt_suback,
		},
	};

	err = mqtt_helper_init(&config);
	if (err) {
		LOG_ERR("Failed to initialize MQTT helper, error: %d", err);
		return 0;
	}

10. Generate the client ID.

Before we connect, we need a client ID to be used when connecting to the MQTT broker.

The client ID will consist of the board name and 11 random digits.

10.1 Declare a variable for the client ID.

static uint8_t client_id[sizeof(CONFIG_BOARD) + 11];

10.2 Generate the client ID.

Generate the client ID with 11 random digits, using sys_rand32_get(). Then combine the board name and digits in client_id.

Add the following code snippet to the beginning of main().

uint32_t id = sys_rand32_get();
snprintf(client_id, sizeof(client_id), "%s-%010u", CONFIG_BOARD, id);

11. Connect to the MQTT broker.

To connect to the MQTT broker, we will use the MQTT helper function mqtt_helper_connect(), which takes a single parameter: struct mqtt_helper_conn_params

Declare the structure and assign the Kconfig CONFIG_MQTT_SAMPLE_BROKER_HOSTNAME to hostname and the client ID (client_id) we generated in the previous step to device_id. Then call mqtt_helper_connect() with the struct to initiate the connection.

	struct mqtt_helper_conn_params conn_params = {
		.hostname.ptr = CONFIG_MQTT_SAMPLE_BROKER_HOSTNAME,
		.hostname.size = strlen(CONFIG_MQTT_SAMPLE_BROKER_HOSTNAME),
		.device_id.ptr = (char *)client_id,
		.device_id.size = strlen(client_id),
	};
	
	err = mqtt_helper_connect(&conn_params);
	if (err) {
		LOG_ERR("Failed to connect to MQTT, error code: %d", err);
		return 0;
	}

12. Build and flash the application to your board.

This exercise uses the PSA backend for storing the Wi-Fi credentials. Therefore, you must build with TF-M.

If necessary, input the commands to connect to Wi-Fi, as we have done in the previous exercises.

You should see the following log output

[00:00:00.456,512] <inf> wifi_nrf: Firmware (v1.2.8.1) booted successfully
*** Booting nRF Connect SDK 2.9.0-3758bcbfa5cd ***
[00:00:01.609,649] <inf> Lesson4_Exercise1: Waiting to connect to Wi-Fi
[00:00:07.349,853] <inf> Lesson4_Exercise1: Network connected
[00:00:23.657,257] <inf> Lesson4_Exercise1: Connected to MQTT broker
[00:00:23.657,379] <inf> Lesson4_Exercise1: Hostname: mqtt.nordicsemi.academy
[00:00:23.658,081] <inf> Lesson4_Exercise1: Client ID: nrf7002dk-4065437673
[00:00:23.658,111] <inf> Lesson4_Exercise1: Port: 1883
[00:00:23.658,111] <inf> Lesson4_Exercise1: TLS: No
[00:00:23.658,142] <inf> Lesson4_Exercise1: Subscribing to wifi/fund/board/subscribe/led/topic99
[00:00:23.704,772] <inf> Lesson4_Exercise1: Subscribed to topic wifi/fund/board/subscribe/led/topic99

Testing

To test the application, let’s set up an MQTT client to communicate with our device.

You will need an MQTT client running on your PC, smartphone, or tablet. In this exercise, we will show you how to communicate with the device through your PC using the MQTT client MQTT Explorer.

13. Set up an MQTT client on your computer.

13.1 Install MQTT Explorer and launch it on your computer.

13.2 Connect to the MQTT broker.

We want to connect to the same MQTT broker that the board has connected to, in this case, mqtt.nordicsemi.academy.

In MQTT Explorer, add a connection to the same broker the board is connected to by providing the broker name, hostname and its port as shown in the illustration below. Make sure to switch off TLS and certificates. Now click on Advanced.

In the new window, under Topic, input the topic that the device is publishing to, specified in the Kconfig CONFIG_MQTT_PUB_TOPIC. The default value is wifi/fund/board/publish/button/topic99.

Select Add, and then Back to go to the previous window where you can select Connect to connect to the broker.

14. Publish commands to the LED topic, to control the LEDs on the board.

When the connection to the broker has been established, we want to publish a command to the LED topic, to control the LED on the board.

In the panel to the right, scroll down to the bottom. Enter the topic name that the board is subscribed to (set by CONFIG_MQTT_SUB_TOPIC defined in prj.conf). The default value is wifi/fund/board/subscribe/led/topic99.

Select raw as the message type and input one of the predefined commands to control the LEDs.

LED 1: LED1ON / LED1OFF

LED 2: LED2ON / LED2OFF

Click Publish and observe that the LED on the device reflects the command you sent.

15. Monitor the buttons on the board.

We programmed the device to publish a message whenever a button was pressed and we have configured the MQTT broker connection to subscribe to the topic that the device is publishing to.

Try to press button 1 or 2 on your board and notice a message appearing on the left-side of the screen. If you expand all the sub-headings, you will find the message posted at the bottom stating which button was pressed on the device.