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.
1.1. Enable the MQTT helper library and disable persistent sessions by enabling the following Kconfig symbols in the prj.conf file.
Copy
CONFIG_MQTT_HELPER=yCONFIG_MQTT_CLEAN_SESSION=y
Kconfig
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.
We recommend selecting your own topic names as other users of this course are likely to use the same topic and be publishing and subscribing to it simultaneously.
1.3 Include the header file for the MQTT helper library in main.c.
Copy
#include<net/mqtt_helper.h>
C
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.
3. Define the message ID used when subscribing to topics.
This will be used to verify that a subscription succeeded.
Copy
#define SUBSCRIBE_TOPIC_ID 1234
C
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.
Copy
(void)mqtt_helper_disconnect();
C
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.
struct mqtt_topic signature
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.
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.
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.
Copy
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; }
C
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.
struct mqtt_publish_param
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.
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
enum mqtt_conn_return_code
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.
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.
Copy
staticvoidon_mqtt_suback(uint16_tmessage_id, intresult){ 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);}
C
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.
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.
Copy
int err = publish(BUTTON1_MSG, sizeof(BUTTON1_MSG) - 1);if (err) {LOG_ERR("Failed to send message, %d", err);return; }
C
8.2 Publish BUTTON2_MSG if button 2 is pressed.
Copy
int err = publish(BUTTON2_MSG, sizeof(BUTTON2_MSG) - 1);
C
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
Data fields for struct mqtt_helper_cfg
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.
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().
Copy
uint32_t id = sys_rand32_get();snprintf(client_id, sizeof(client_id), "%s-%010u", CONFIG_BOARD, id);
C
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
Data fields for 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.
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.
v2.9.0 – v2.8.0
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.
1.1. Enable the MQTT helper library and disable persistent sessions by enabling the following Kconfig symbols in the prj.conf file.
Copy
CONFIG_MQTT_HELPER=yCONFIG_MQTT_CLEAN_SESSION=y
Kconfig
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.
We recommend selecting your own topic names as other users of this course are likely to use the same topic and be publishing and subscribing to it simultaneously.
1.3 Include the header file for the MQTT helper library in main.c.
Copy
#include<net/mqtt_helper.h>
C
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.
3. Define the message ID used when subscribing to topics.
This will be used to verify that a subscription succeeded.
Copy
#define SUBSCRIBE_TOPIC_ID 1234
C
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.
Copy
(void)mqtt_helper_disconnect();
C
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.
struct mqtt_topic signature
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.
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.
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.
Copy
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; }
C
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.
struct mqtt_publish_param
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.
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
enum mqtt_conn_return_code
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.
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.
Copy
staticvoidon_mqtt_suback(uint16_tmessage_id, intresult){ 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);}
C
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.
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.
Copy
int err = publish(BUTTON1_MSG, sizeof(BUTTON1_MSG) - 1);if (err) {LOG_ERR("Failed to send message, %d", err);return; }
C
8.2 Publish BUTTON2_MSG if button 2 is pressed.
Copy
int err = publish(BUTTON2_MSG, sizeof(BUTTON2_MSG) - 1);
C
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
Data fields for struct mqtt_helper_cfg
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.
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().
Copy
uint32_t id = sys_rand32_get();snprintf(client_id, sizeof(client_id), "%s-%010u", CONFIG_BOARD, id);
C
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
Data fields for 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.
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.
v2.7.0 – v2.6.1
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 a PC, tablet, or a smartphone. 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 (for example, your mobile app) 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 library in nRF Connect SDK to:
Configure the board as an MQTT client
Connect to a public MQTT broker (broker.hivemq.com)
Publish and subscribe to MQTT topics, set by the Kconfig symbols: CONFIG_MQTT_PUB_TOPIC and CONFIG_MQTT_SUB_TOPIC
Control LEDs on the board via the remote MQTT client running on a smartphone
Read the status of buttons 1 and 2 on the board via the remote MQTT client running on a smartphone
We are configuring a connection to a public MQTT broker (broker.hivemq.com) over TCP port 1883, but you can choose any other preferred MQTT broker. For the CONFIG_MQTT_PUB_TOPIC and CONFIG_MQTT_SUB_TOPIC, we highly recommend selecting your own topic names as other users of this course are likely to use the same topic and be publishing and subscribing to it simultaneously.
1.3 Include the header file for the MQTT library in main.c.
Copy
#include<zephyr/net/mqtt.h>
C
2. Define the function client_init() to initialize the MQTT client instance.
2.1 Initialize the client instance with mqtt_client_init().
Copy
mqtt_client_init(client);
C
2.2 Call the function server_resolve() to resolve the hostname and get the IP address, which we will use to populate the MQTT broker structure.
Copy
err = server_resolve();if (err) {LOG_ERR("Failed to initialize broker connection");return err;}
C
2.3 Populate the mqtt_client struct, which includes:
Passing the pointer to the broker structure client->broker = &server.
Registering the MQTT event handler client->evt_cb = mqtt_evt_handler.
Assigning an MQTT client ID for the board. client->client_id.utf8 = client_id_get();
The broker does not require a password or a user name, therefore we set these two to NULL in client->password = NULL; and client->user_name = NULL;
2.5 Set the transport type of the MQTT client to non-secure.
Since we are using non-secure TCP transport for the MQTT connection in this exercise, we set the transport type to non-secure (MQTT_TRANSPORT_NON_SECURE).
3. Define the function subscribe() to subscribe to a specific topic.
We can subscribe to as many MQTT topics as we want.
3.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.
struct mqtt_topic signature
This is done in the code below where we have created one variable subscribe_topic of type mqtt_topic, to subscribe to CONFIG_MQTT_SUB_TOPIC with QoS1.
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.
Once we have the list variable initialized, we can call the MQTT library function mqtt_subscribe(), which takes two parameters, the mqtt_client and the mqtt_subscription_list.
mqtt_subscribe() signature
Copy
LOG_INF("Subscribing to %s", CONFIG_MQTT_SUB_TOPIC);returnmqtt_subscribe(c, &subscription_list);
C
Note
To keep it simple, messages with QoS 2 are not supported by this application.
4. Upon a successful connection, subscribe to topics.
Upon a successful connection to a broker, MQTT_EVT_CONNACK, call subscribe() to subscribe to topics. First, investigate evt->result for a successful connection or not, then call subscribe() to subscribe to the topic CONFIG_MQTT_SUB_TOPIC.
Add the following lines under the MQTT_EVT_CONNACK case.
5. In event MQTT_EVT_PUBLISH, listen to published messages received from the broker and extract the message.
5.1 Extract the payload using get_received_payload(), and (if relevant) send an acknowledgment.
First, we extract the payload using get_received_payload(). Then we examine the QoS of the received message, and if it is 1 (at least once), we send an acknowledgment with mqtt_publish_qos1_ack().
5.2 On successful extraction of data, examine the command and toggle LED accordingly.
If the extraction of the received message was successful, examine the message and use strncmp() to compare it to the LED ON and LED OFF commands and turn the LED on or off accordingly.
5.3 On failed extraction of data, examine error code from get_received_payload().
If the error is the payload buffer being too small, print an error message. If the extraction failed for any other reason, disconnect from the MQTT broker.
Copy
elseif (err == -EMSGSIZE) {LOG_ERR("Received payload (%d bytes) is larger than the payload buffer size (%d bytes).", p->message.payload.len, sizeof(payload_buf));} else {LOG_ERR("get_received_payload failed: %d", err);LOG_INF("Disconnecting MQTT client..."); err = mqtt_disconnect(c);if (err) {LOG_ERR("Could not disconnect: %d", err); }}
C
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 library function mqtt_publish(), which takes two parameters: a pointer to the client instance (mqtt_client) and a pointer to a variable of type mqtt_publish_param which encapsulates the message to be sent.
struct mqtt_publish_param signature
The function should take as input the client instance pointer, the quality of service requested, the data to be sent, and the length of the data. The function needs to populate the members of the mqtt_publish_param struct and call mqtt_publish() to publish the message to the broker.
We are setting the topic the device will publish to in the line param.message.topic.topic.utf8 = CONFIG_MQTT_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 to be a random number by calling the function sys_rand32_get().
Since we are not using duplication or a persistent MQTT session, the flags dup_flag and retain_flag are set to 0
7. 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 four parameters:
Client instance pointer &client which is defined at the top of main.c and initialized through the function client_init().
The quality of service requested (MQTT_QOS_0_AT_MOST_ONCE, MQTT_QOS_1_AT_LEAST_ONCE, or MQTT_QOS_2_EXACTLY_ONCE). In this exercise, we are using MQTT_QOS_1_AT_LEAST_ONCE both for subscription and publishing.
Pointer to the message to be sent CONFIG_BUTTON_MSG defined in Kconfig.
The size of the message to be sent. Note that we are not sending the null terminator of the string here and hence the -1 at the end.
In main(), after establishing a Wi-FI connection and initializing the client, call mqtt_connect() with a pointer to the client instance &client to establish a connection to the MQTT broker.
Copy
err = mqtt_connect(&client);if (err) {LOG_ERR("Error in mqtt_connect: %d", err);goto do_connect;}
C
9. Listen for incoming messages on the socket.
9.1 Configure fds to monitor the socket.
Set the fd field to the socket created by the MQTT library, found in the mqtt_client structure, and set the events we want to monitor to POLLIN, meaning there is data to be read from the socket.
9.2 Continuously poll the socket for incoming data.
Use poll() to poll the socket for incoming events. To ensure the connection stays alive, use the helper function mqtt_keepalive_time_left() to set the timeout of the poll function to the time that is left until the next keep alive message must be sent to the MQTT broker.
When poll() returns, either due to an event on the socket or because the timeout ran out, call mqtt_live(), which has the following signature
This ensures the connection to the MQTT broker is kept alive.
10. 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.
Board
Build with TF-M
Extra CMake arguments
nRF7002 DK
nrf7002dk_nrf5340_cpuapp_ns
N/A
nRF5340 DK + nRF7002 EK
nrf5340dk_nrf5340_cpuapp_ns
-DSHIELD=nrf7002ek
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 ***[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:07.886,535] <inf> Lesson4_Exercise1: Connecting to MQTT broker[00:00:07.914,733] <inf> Lesson4_Exercise1: IPv4 address of MQTT broker found 52.28.62.138[00:00:08.021,911] <inf> Lesson4_Exercise1: MQTT client connected[00:00:08.021,911] <inf> Lesson4_Exercise1: Subscribing to wifi/fund/board/subscribe/led/topic99[00:00:08.070,770] <inf> Lesson4_Exercise1: SUBACK packet id: 1234
Terminal
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 using a PC.
11. Set up an MQTT client on your computer.
11.1 Install MQTT Explorer and launch it on your computer.
11.2 Connect to the MQTT broker.
We want to connect to the same MQTT broker that the board has connected to, in this case, broker.hivemq.com.
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.
12. 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.
13. 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.
v2.6.0 – v2.5.0
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 a PC, tablet, or a smartphone. 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 (for example, your mobile app) 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 library in nRF Connect SDK to:
Configure the board as an MQTT client
Connect to a public MQTT broker (broker.hivemq.com)
Publish and subscribe to MQTT topics, set by the Kconfig symbols: CONFIG_MQTT_PUB_TOPIC and CONFIG_MQTT_SUB_TOPIC
Control LEDs on the board via the remote MQTT client running on a smartphone
Read the status of buttons 1 and 2 on the board via the remote MQTT client running on a smartphone
We are configuring a connection to a public MQTT broker (broker.hivemq.com) over TCP port 1883, but you can choose any other preferred MQTT broker. For the CONFIG_MQTT_PUB_TOPIC and CONFIG_MQTT_SUB_TOPIC, we highly recommend selecting your own topic names as other users of this course are likely to use the same topic and be publishing and subscribing to it simultaneously.
1.3 Include the header file for the MQTT library in main.c.
Copy
#include<zephyr/net/mqtt.h>
C
2. Define the function client_init() to initialize the MQTT client instance.
2.1 Initialize the client instance with mqtt_client_init().
Copy
mqtt_client_init(client);
C
2.2 Call the function server_resolve() to resolve the hostname and get the IP address, which we will use to populate the MQTT broker structure.
Copy
err = server_resolve();if (err) {LOG_ERR("Failed to initialize broker connection");return err;}
C
2.3 Populate the mqtt_client struct, which includes:
Passing the pointer to the broker structure client->broker = &server.
Registering the MQTT event handler client->evt_cb = mqtt_evt_handler.
Assigning an MQTT client ID for the board. client->client_id.utf8 = client_id_get();
The broker does not require a password or a user name, therefore we set these two to NULL in client->password = NULL; and client->user_name = NULL;
2.5 Set the transport type of the MQTT client to non-secure.
Since we are using non-secure TCP transport for the MQTT connection in this exercise, we set the transport type to non-secure (MQTT_TRANSPORT_NON_SECURE).
3. Define the function subscribe() to subscribe to a specific topic.
We can subscribe to as many MQTT topics as we want.
3.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.
struct mqtt_topic signature
This is done in the code below where we have created one variable subscribe_topic of type mqtt_topic, to subscribe to CONFIG_MQTT_SUB_TOPIC with QoS1.
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.
Once we have the list variable initialized, we can call the MQTT library function mqtt_subscribe(), which takes two parameters, the mqtt_client and the mqtt_subscription_list.
mqtt_subscribe() signature
Copy
LOG_INF("Subscribing to %s", CONFIG_MQTT_SUB_TOPIC);returnmqtt_subscribe(c, &subscription_list);
C
Note
To keep it simple, messages with QoS 2 are not supported by this application.
4. Upon a successful connection, subscribe to topics.
Upon a successful connection to a broker, MQTT_EVT_CONNACK, call subscribe() to subscribe to topics. First, investigate evt->result for a successful connection or not, then call subscribe() to subscribe to the topic CONFIG_MQTT_SUB_TOPIC.
Add the following lines under the MQTT_EVT_CONNACK case.
5. In event MQTT_EVT_PUBLISH, listen to published messages received from the broker and extract the message.
5.1 Extract the payload using get_received_payload(), and (if relevant) send an acknowledgment.
First, we extract the payload using get_received_payload(). Then we examine the QoS of the received message, and if it is 1 (at least once), we send an acknowledgment with mqtt_publish_qos1_ack().
5.2 On successful extraction of data, examine the command and toggle LED accordingly.
If the extraction of the received message was successful, examine the message and use strncmp() to compare it to the LED ON and LED OFF commands and turn the LED on or off accordingly.
5.3 On failed extraction of data, examine error code from get_received_payload().
If the error is the payload buffer being too small, print an error message. If the extraction failed for any other reason, disconnect from the MQTT broker.
Copy
elseif (err == -EMSGSIZE) {LOG_ERR("Received payload (%d bytes) is larger than the payload buffer size (%d bytes).", p->message.payload.len, sizeof(payload_buf));} else {LOG_ERR("get_received_payload failed: %d", err);LOG_INF("Disconnecting MQTT client..."); err = mqtt_disconnect(c);if (err) {LOG_ERR("Could not disconnect: %d", err); }}
C
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 library function mqtt_publish(), which takes two parameters: a pointer to the client instance (mqtt_client) and a pointer to a variable of type mqtt_publish_param which encapsulates the message to be sent.
struct mqtt_publish_param signature
The function should take as input the client instance pointer, the quality of service requested, the data to be sent, and the length of the data. The function needs to populate the members of the mqtt_publish_param struct and call mqtt_publish() to publish the message to the broker.
We are setting the topic the device will publish to in the line param.message.topic.topic.utf8 = CONFIG_MQTT_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 to be a random number by calling the function sys_rand32_get().
Since we are not using duplication or a persistent MQTT session, the flags dup_flag and retain_flag are set to 0
7. 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 four parameters:
Client instance pointer &client which is defined at the top of main.c and initialized through the function client_init().
The quality of service requested (MQTT_QOS_0_AT_MOST_ONCE, MQTT_QOS_1_AT_LEAST_ONCE, or MQTT_QOS_2_EXACTLY_ONCE). In this exercise, we are using MQTT_QOS_1_AT_LEAST_ONCE both for subscription and publishing.
Pointer to the message to be sent CONFIG_BUTTON_MSG defined in Kconfig.
The size of the message to be sent. Note that we are not sending the null terminator of the string here and hence the -1 at the end.
In main(), after establishing a Wi-FI connection and initializing the client, call mqtt_connect() with a pointer to the client instance &client to establish a connection to the MQTT broker.
Copy
err = mqtt_connect(&client);if (err) {LOG_ERR("Error in mqtt_connect: %d", err);goto do_connect;}
C
9. Listen for incoming messages on the socket.
9.1 Configure fds to monitor the socket.
Set the fd field to the socket created by the MQTT library, found in the mqtt_client structure, and set the events we want to monitor to POLLIN, meaning there is data to be read from the socket.
9.2 Continuously poll the socket for incoming data.
Use poll() to poll the socket for incoming events. To ensure the connection stays alive, use the helper function mqtt_keepalive_time_left() to set the timeout of the poll function to the time that is left until the next keep alive message must be sent to the MQTT broker.
When poll() returns, either due to an event on the socket or because the timeout ran out, call mqtt_live(), which has the following signature
This ensures the connection to the MQTT broker is kept alive.
10. 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.
Board
Build with TF-M
Extra CMake arguments
nRF7002 DK
nrf7002dk_nrf5340_cpuapp_ns
N/A
nRF5340 DK + nRF7002 EK
nrf5340dk_nrf5340_cpuapp_ns
-DSHIELD=nrf7002ek
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 ***[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:07.886,535] <inf> Lesson4_Exercise1: Connecting to MQTT broker[00:00:07.914,733] <inf> Lesson4_Exercise1: IPv4 address of MQTT broker found 52.28.62.138[00:00:08.021,911] <inf> Lesson4_Exercise1: MQTT client connected[00:00:08.021,911] <inf> Lesson4_Exercise1: Subscribing to wifi/fund/board/subscribe/led/topic99[00:00:08.070,770] <inf> Lesson4_Exercise1: SUBACK packet id: 1234
Terminal
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 using a PC.
11. Set up an MQTT client on your computer.
11.1 Install MQTT Explorer and launch it on your computer.
11.2 Connect to the MQTT broker.
We want to connect to the same MQTT broker that the board has connected to, in this case, broker.hivemq.com.
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.
12. 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.
13. 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.
Nordic Developer Academy Privacy Policy
1. Introduction
In this Privacy Policy you will find information on Nordic Semiconductor ASA (“Nordic Semiconductor”) processes your personal data when you use the Nordic Developer Academy.
References to “we” and “us” in this document refers to Nordic Semiconductor.
2. Our processing of personal data when you use the Nordic Developer Academy
2.1 Nordic Developer Academy
Nordic Semiconductor processes personal data in order to provide you with the features and functionality of the Nordic Developer Academy. Creating a user account is optional, but required if you want to track you progress and view your completed courses and obtained certificates. If you choose to create a user account, we will process the following categories of personal data:
Email
Name
Password (encrypted)
Course progression (e.g. which course you have completely or partly completed)
Certificate information, which consists of name of completed course and the validity of the certificate
Course results
During your use of the Nordic Developer Academy, you may also be asked if you want to provide feedback. If you choose to respond to any such surveys, we will also process the personal data in your responses in that survey.
The legal basis for this processing is GDPR article 6 (1) b. The processing is necessary for Nordic Semiconductor to provide the Nordic Developer Academy under the Terms of Service.
2.2 Analytics
If you consent to analytics, Nordic Semiconductor will use Google Analytics to obtain statistics about how the Nordic Developer Academy is used. This includes collecting information on for example what pages are viewed, the duration of the visit, the way in which the pages are maneuvered, what links are clicked, technical information about your equipment. The information is used to learn how Nordic Developer Academy is used and how the user experience can be further developed.
2.2 Newsletter
You can consent to receive newsletters from Nordic from within the Nordic Developer Academy. How your personal data is processed when you sign up for our newsletters is described in the Nordic Semiconductor Privacy Policy.
3. Retention period
We will store your personal data for as long you use the Nordic Developer Academy. If our systems register that you have not used your account for 36 months, your account will be deleted.
4. Additional information
Additional information on how we process personal data can be found in the Nordic Semiconductor Privacy Policy and Cookie Policy.
Nordic Developer Academy Terms of Service
1. Introduction
These terms and conditions (“Terms of Use”) apply to the use of the Nordic Developer Academy, provided by Nordic Semiconductor ASA, org. nr. 966 011 726, a public limited liability company registered in Norway (“Nordic Semiconductor”).
Nordic Developer Academy allows the user to take technical courses related to Nordic Semiconductor products, software and services, and obtain a certificate certifying completion of these courses. By completing the registration process for the Nordic Developer Academy, you are agreeing to be bound by these Terms of Use.
These Terms of Use are applicable as long as you have a user account giving you access to Nordic Developer Academy.
2. Access to and use of Nordic Developer Academy
Upon acceptance of these Terms of Use you are granted a non-exclusive right of access to, and use of Nordic Developer Academy, as it is provided to you at any time. Nordic Semiconductor provides Nordic Developer Academy to you free of charge, subject to the provisions of these Terms of Use and the Nordic Developer Academy Privacy Policy.
To access select features of Nordic Developer Academy, you need to create a user account. You are solely responsible for the security associated with your user account, including always keeping your login details safe.
You will able to receive an electronic certificate from Nordic Developer Academy upon completion of courses. By issuing you such a certificate, Nordic Semiconductor certifies that you have completed the applicable course, but does not provide any further warrants or endorsements for any particular skills or professional qualifications.
Nordic Semiconductor will continuously develop Nordic Developer Academy with new features and functionality, but reserves the right to remove or alter any existing functions without notice.
3. Acceptable use
You undertake that you will use Nordic Developer Academy in accordance with applicable law and regulations, and in accordance with these Terms of Use. You must not modify, adapt, or hack Nordic Developer Academy or modify another website so as to falsely imply that it is associated with Nordic Developer Academy, Nordic Semiconductor, or any other Nordic Semiconductor product, software or service.
You agree not to reproduce, duplicate, copy, sell, resell or in any other way exploit any portion of Nordic Developer Academy, use of Nordic Developer Academy, or access to Nordic Developer Academy without the express written permission by Nordic Semiconductor. You must not upload, post, host, or transmit unsolicited email, SMS, or \”spam\” messages.
You are responsible for ensuring that the information you post and the content you share does not;
contain false, misleading or otherwise erroneous information
infringe someone else’s copyrights or other intellectual property rights
contain sensitive personal data or
contain information that might be received as offensive or insulting.
Such information may be removed without prior notice.
Nordic Semiconductor reserves the right to at any time determine whether a use of Nordic Developer Academy is in violation of its requirements for acceptable use.
Violation of the at any time applicable requirements for acceptable use may result in termination of your account. We will take reasonable steps to notify you and state the reason for termination in such cases.
4. Routines for planned maintenance
Certain types of maintenance may imply a stop or reduction in availability of Nordic Developer Academy. Nordic Semiconductor does not warrant any level of service availability but will provide its best effort to limit the impact of any planned maintenance on the availability of Nordic Developer Academy.
5. Intellectual property rights
Nordic Semiconductor retains all rights to all elements of Nordic Developer Academy. This includes, but is not limited to, the concept, design, trademarks, know-how, trade secrets, copyrights and all other intellectual property rights.
Nordic Semiconductor receives all rights to all content uploaded or created in Nordic Developer Academy. You do not receive any license or usage rights to Nordic Developer Academy beyond what is explicitly stated in this Agreement.
6. Liability and damages
Nothing within these Terms of Use is intended to limit your statutory data privacy rights as a data subject, as described in the Nordic Developer Academy Privacy Policy. You acknowledge that errors might occur from time to time and waive any right to claim for compensation as a result of errors in Nordic Developer Academy. When an error occurs, you shall notify Nordic Semiconductor of the error and provide a description of the error situation.
You agree to indemnify Nordic Semiconductor for any loss, including indirect loss, arising out of or in connection with your use of Nordic Developer Academy or violations of these Terms of Use. Nordic Semiconductor shall not be held liable for, and does not warrant that (i) Nordic Developer Academy will meet your specific requirements, (ii) Nordic Developer Academy will be uninterrupted, timely, secure, or error-free, (iii) the results that may be obtained from the use of Nordic Developer Academy will be accurate or reliable, (iv) the quality of any products, services, information, or other material purchased or obtained by you through Nordic Developer Academy will meet your expectations, or that (v) any errors in Nordic Developer Academy will be corrected.
You accept that this is a service provided to you without any payment and hence you accept that Nordic Semiconductor will not be held responsible, or liable, for any breaches of these Terms of Use or any loss connected to your use of Nordic Developer Academy. Unless otherwise follows from mandatory law, Nordic Semiconductor will not accept any such responsibility or liability.
7. Change of terms
Nordic Semiconductor may update and change the Terms of Use from time to time. Nordic Semiconductor will seek to notify you about significant changes before such changes come into force and give you a possibility to evaluate the effects of proposed changes. Continued use of Nordic Developer Academy after any such changes shall constitute your acceptance of such changes. You can review the current version of the Terms of Use at any time at https://academy.nordicsemi.com/terms-of-service/
8. Transfer of rights
Nordic Semiconductor is entitled to transfer its rights and obligation pursuant to these Terms of Use to a third party as part of a merger or acquisition process, or as a result of other organizational changes.
9. Third Party Services
To the extent Nordic Developer Academy facilitates access to services provided by a third party, you agree to comply with the terms governing such third party services. Nordic Semiconductor shall not be held liable for any errors, omissions, inaccuracies, etc. related to such third party services.
10. Dispute resolution
The Terms of Use and any other legally binding agreement between yourself and Nordic Semiconductor shall be subject to Norwegian law and Norwegian courts’ exclusive jurisdiction.
