nRF51 IoT SDK
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
MQTT Client - Subscriber

The MQTT publisher 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.


MQTT_Overall.svg
Scenario 1: Setup of the lwIP based MQTT application on the nRF51 SoC


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


MQTT_Server.svg
Scenario 2: Setup of the lwIP based MQTT client publisher application on the nRF51 SoC


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


MQTT_Client_Server.svg
Scenario 3: Setup of the lwIP based MQTT client Subscriber and Publisher on the nRF51 SoC


Common Modules Dependency and Usage

This section summarizes the usage of the nRF51 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 Included not enabledTracing is included but not enabled by default.
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>/Nordic/nrf51/external/lwip/license.txt

Setup

The name of this example is iot_lwip_mqtt_subscriber. You can find the source code and project file of the example in the following folder: <InstallFolder>/Nordic/nrf51/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

MQTT Broker Setup

To check the client functionality, the MQTT Broker must be set up.

Note
The example assumes that the broker has the IPv6 address 2004::1. Change this appropriately to get the example to function as expected.

This section describes setting up the mosquitto MQTT broker on a Linux system. mosquitto is an open source implementation of the MQTT broker under BSD license. Visit http://mosquitto.org/ for more details.

For the quick setup, proceed as follows:

# Installation of mosquitto.
sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt-get update
sudo apt-get install mosquitto
# Running it in verbosity mode in default port 1883.
sudo service mosquitto stop
sudo mosquitto -p 1883 -v
Note
To install mosquitto on other operating systems, visit the web page: http://mosquitto.org/download/

Testing

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

  1. Ensure that the MQTT broker address is set correct in the application.
  2. Compile and program the application. Observe that the device is advertising.
  3. Prepare the Linux router device by initializing the 6LoWPAN module.
  4. Discover the advertising device by using the hcitool lescan command.
  5. Connect to the discovered device from the Linux console by using the Bluetooth 6LoWPAN connect command.
  6. Check if the connected state is reflected by the LEDs.
  7. Prepare the IPv6 global prefix for the btX interface.
  8. Push Button 1. Observe that the mosquitto broker reports a new connection from the client "nrfSubscriber-51".
  9. Observe that LED 2 turns on once when the MQTT connection is established.
  10. Push Button 2.
  11. Observe that the MQTT subscribe message from the client is reported by the broker; an acknowledgement is sent back by the broker.
  12. Observe that LED 3 turns on once when the subscription acknowledgement is received.
  13. Not much happens after this stage, unless the publisher publishes on the topic "led/state".
  14. 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 nRF51 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.
  15. Disconnect the MQTT connection with the broker by pressing Button 3. LED 3 is turned off on disconnection.
  16. Disconnect from the device by using the Bluetooth 6LoWPAN disconnect command.
  17. Observe that only the advertising LED is lit.

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