The MQTT subscriber example is an MQTT client that connects to the broker identified by the broker address configured in the example at compile time. If the connection succeeds, it is ready to subscribe to the LED state information under the topic "led/state".

The example allows the user to unsubscribe from the topic, disconnect the MQTT client from the broker and then reconnect.

An overview of how the examples could be used are shown in the scenarios below. Scenario 1 is a complex, but possibly a real-time scenario where there are one or more publishers and subscribers. In this scenario not all MQTT clients (publishers/subscribers) have to be BLE enabled IPv6 devices; they could be computer applications and/or embedded devices, wired or wireless, that use MQTT as application protocol over the IP stack. This scenario is seen as a super-set of possible scenarios.

Scenario 1: Setup of the lwIP based MQTT application on the nRF5x SoC

Scenario 2 shows a possible use case where the nRF5x SoC MQTT subscriber is used to receive messages that come from not BLE MQTT clients, such as computer applications. This scenario is realized when the mosquitto publisher application is used to test the subscriber application on the nRF5x SoC.

Scenario 2: Setup of the lwIP based MQTT client publisher application on the nRF5x SoC

Scenario 3 shows a possible use case where all the MQTT clients are nRF5x devices running MQTT clients, either publisher or subscriber. This scenario is realized when the subscriber and publisher applications included in the IoT SDK are used to connect to the MQTT broker.

Scenario 3: Setup of the lwIP based MQTT client Subscriber and Publisher on the nRF5x SoC

Common Modules Dependency and Usage

This section summarizes the usage of the nRF5x SoC resources and common modules in the examples apart from the IoT 6LoWPAN and lwIP stack library.

Module	Inclusion/Usage	Description
Timer	3	Timer for lwIP, leds and the button module.
Button	3	Buttons are used to control the application. See the Overview section.
LEDs	4	LEDs are used to indicate the application states. See LED assignments.
Adv Data Encoder	Yes	The device name used is 'MQTTPublisher', IPSP Service UUID is included in the UUID list.
Scheduler	No	Scheduler is used for processing stack events.
UART Trace	Yes	Tracing used to help mointor state of application.

Note: The lwIP library used for this example is under BSD-style license; this is different from the Nordic SDK license. The license text can be found at <InstallFolder>external/lwip/license.txt

Setup

You can find the source code and project file of the example in the following folder: <InstallFolder>/examples/iot/mqtt/subscriber

LED assignments

Connection state:

LED 1	LED 2	Description
Blinking	Off	Device advertising as BLE peripheral.
Off	Blinking	BLE link established, IPv6 interface down.
On	Off	BLE link established, IPv6 interface up.
Off	On	MQTT connection is established.
On	On	Assertion failure in the application.

MQTT message subscription:

LED 3 LED 4

On, if successfully subscribed to the LED state messages. Toggles based on the LED state messages from the broker.

Both LED 3 and LED 4 are turned on in case of an assertion failure in the application.

Button assignments

Button	Mapped Action
1	MQTT Connection Request
2	Subscribe/Unsubscribe from a Topic
3	MQTT Disconnection

Note: If commissioning is enabled, additional LED and Button assignments are made.

The example by default requests a secure connection on MQTT Secure port 8883. In order to disable security for MQTT clients, please follow the following setps.

Change the MQTT broker port from 8883 to 1883 (or the non secure port that MQTT broker is configured to listen on).
Edit the connection parameters for the mqtt_connect request as below. Change from:
m_app_mqtt_id.transport_type = MQTT_TRANSPORT_SECURE;

m_app_mqtt_id.p_security_settings = &m_tls_keys;

uint32_t err_code = mqtt_connect(&m_app_mqtt_id);

APP_ERROR_CHECK(err_code);

To:
m_app_mqtt_id.transport_type = MQTT_TRANSPORT_NON_SECURE;

m_app_mqtt_id.p_security_settings = NULL;

uint32_t err_code = mqtt_connect(&m_app_mqtt_id);

APP_ERROR_CHECK(err_code);

MQTT Broker Setup

Please refer to Setting up the Mosquitto MQTT broker for detailed description of setting up mostquitto in various configurations.

Since the example uses security by default, the broker shall be setup to use TLS.

MQTT Publisher setup

This section describes how mosquitto can be used as a publisher application to test this example.

# Installation of mosquitto.
sudo apt-get install mosquitto-clients
# Publish 1 in verbosity mode on default port 1883.
mosquitto_pub -t "led/state" -m 1
# Publish 0 in verbosity mode on default port 1883.
mosquitto_pub -t "led/state" -m 0

Testing

See Connecting devices to the router for a list of relevant Linux commands.

Ensure that the MQTT broker address is set correct in the application.
Compile and program the application. Observe that the device is advertising.
Open a terminal program (for example PUTTY) to monitor the messages from the kit on the COM port.
Prepare the Linux router device by initializing the 6LoWPAN module.
Discover the advertising device by using the hcitool lescan command.
Connect to the discovered device from the Linux console by using the Bluetooth 6LoWPAN connect command.
Check if the connected state is reflected by the LEDs.
Prepare the IPv6 global prefix for the btX interface.
Push Button 1. Observe that the mosquitto broker reports a new connection from the client "nrfSubscriber".
Observe that LED 2 is ON, which means that the connection is established. In case the LED 2 is not turned on within 30 seconds, the procedure might have failed. This can be verified by observing a notification of MQTT_EVT_CONNECT with a failure (non-zero result code). Retry MQTT connection by pushing Button 1. Pushing the button before the procedure is complete, either with success or failure, will result in application assertion.
Push Button 2.
Observe that the MQTT subscribe message from the client is reported by the broker; an acknowledgement is sent back by the broker.
Observe that LED 3 turns on once when the subscription acknowledgement is received.
Not much happens after this stage, unless the publisher publishes on the topic "led/state".
Observe when a publisher publishes "led/state", LED 4 changes its state to ON or OFF based on the message published for the topic being 1 or 0.
Note
If the nRF5x SoC kit running the MQTT publisher is also connected to the broker, observe that LED 4 of the subscriber is synchronising with the LED 4 of the publisher each time the topic is published.
Disconnect the MQTT connection with the broker by pressing Button 3. LED 3 is turned off on disconnection.
Disconnect from the device by using the Bluetooth 6LoWPAN disconnect command.
Observe that only the advertising LED is lit.