Overview

These example applications demonstrate how lwIP stack on nRF51 and the MQTT protocol can be used to talk to a Xively cloud service.

The example consists of two MQTT clients that realize the publish-subscribe pattern:

MQTT Publisher
MQTT Subscriber

The MQTT Publisher application can periodically update the state of a data channel (Thermometer), while the MQTT Subscriber can receive notifications about these updates.

To properly identify IoT devices, Xively uses Feed ID and API Key parameters. A Feed is the collection of channels (datastreams) defined for a device with additional metadata, such as location, whether the device is physical/virtual, fixed/mobile, indoor/outdoor, etc. An API Key determines the levels of permissions for access to Xively resources. Feed Id and API Key are generated automatically. However, you can change the API Key on the device's webpage.

These parameters and the channel name are hardcoded in the header section of main.c file of both applications. Parameters of your device can simply be put into quotation marks (without brackets).

#define APP_MQTT_XIVELY_CHANNEL  "Thermometer"         /**< Device's Channel name. */
#define APP_MQTT_XIVELY_FEED_ID  "{PUT FEED ID HERE}"  /**< Device's Feed ID. E.g. "1234567890" */
#define APP_MQTT_XIVELY_API_KEY  "{PUT API KEY HERE}"  /**< API key used for authentication. E.g. "abcdef123456" */

Note: To communicate with the cloud service, IPv6 global connectivity is required for the applications.

The hostname of the Xively MQTT Broker is hardcoded in main.c.

For more information about the data format, protocols and API of Xively cloud, please refer to Xively REST API

The setup of the example applications is presented in Figure 1.

Figure 1: Setup of the cloud example applications for Xively.

Any recent data that has been published on MQTT publisher and has been received on MQTT subscriber is also transmitted through the serial device and terminal program (such as PUTTY) so that it can be used to monitor the COM port of each development kit through a terminal session.

The sequence of MQTT messages exchanged between the example applications and the MQTT broker is shown in Figure 2.

Figure 2: Message sequence chart.

Xively MQTT Publisher

This application serves as a data source, sending periodic updates (at the interval of 10 seconds) with simulated temperature within the range 17.00 - 24.00 °C.

The Xively cloud accepts JSON data representation. For more information, see /v2/feeds/FEED_ID.json. The simulated temperature is sent using the following format:

{                                                
   "datastreams":
   [
       {
           "id": "Thermometer",
           "current_value" : "XX.00"
       }
   ]
}

Pressing Button 1 triggers the MQTT connection establishment process and after its successful completion nRF51 kit starts publishing the timer. It is also possible to close the connection by pressing Button 2.

MQTT Xively publisher indicates the remainder of the temperature value with division by 4 on LED 3 and LED 4. So, for example, if the current value is 17, then LED3 is OFF and LED4 is ON indicating that the remainder is 1.

If the MQTT Publish Request is sent successfully, a new datapoint is registered on the MQTT cloud and it appears in the graph on the web interface (Figure 3).

Figure 3: Presenting data in value/time format.

Common module dependency and usage

This section summarizes the usage of nRF51 resources and common modules in the examples apart from the IoT 6lowpan and IPv6 stack library.

Module	Inclusion/Usage	Description
Timer	3	Three timers are used for IoT timer, buttons and for application purpose
Buttons	2	Buttons are used for initiating MQTT requests. See Button assignments section for details.
LEDs	4	LEDs are used to indicate the application states. See LED assignments section for details.
Adv Data Encoder	Yes	The device name used is 'MQTTXivelyPublisher', IPSP Service UUID is included in the UUID list.
Scheduler	Yes	Scheduler is used for processing stack events.
UART Trace	Included not enabled	Tracing is included but not enabled by default.

Setup

The name of this example is iot_lwip_mqtt_xively_publisher. The source code and project files of the example can be found in the following folder:
<InstallFolder>/Nordic/nrf51/examples/iot/cloud/mqtt/publisher

LED assignments

LED 1	LED 2	LED 3	LED 4
Blinking	Off	Off	Off	Device advertising as BLE peripheral.
On	Blinking	Off	Off	BLE link established, IPv6 interface down.
On	Off	Off	Off	IPv6 interface up.
Off	On	Off	Off	MQTT connection established.
Off	On	On/Off	On/Off	Recently sent temperature value (LED 3 LED 4 = temperature modulo 4). For example, value of 17 = LED 3 OFF, LED 4 ON. Value of 19 = LED 3 ON, LED 4 ON
On	On	On	On	Assertion failure in the application.

Button assignments

Button 1	Button 2
MQTT Xively Connection request. Start periodic data updates.	MQTT Xively Disconnection request. Stop periodic data updates.

Testing

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

Compile and program the application. Observe that the device is advertising.
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 using the Bluetooth 6LoWPAN connect command.
Check if the connected state is reflected by the LEDs (LED 2 is ON).
Ensure that the kit has an IPv6 Internet connection.
Push Button 1 on the kit and keep an eye on your terminal window and LEDs. In addition, Wireshark with MQTT dissector can be used to track data exchange.
Observe that LED 2 is ON, which means that the connection is established.
Observe that LED 3 and LED 4 change their state every 10 seconds.
Check the Graph on the Xively web interface to see the new datapoints plotted.
Push Button 2 on the kit again.
Observe that LED 2 is OFF, which means that the connection is closed.
Disconnect from the device by using the Bluetooth 6LoWPAN disconnect command.
Observe that LED 1 is blinking and that the device is advertising.

It is also possible to test Xively MQTT publisher without using another nRF51 kit with Xively MQTT Subscriber code. This part can be simulated with the following program.

Note: Remember to set a proper Feed Id and API Key.

# Installation of mosquitto clients, if needed.
sudo apt-get install mosquitto-clients
# Run MQTT subscriber
mosquitto_sub -h api.xively.com -t /v2/feeds/{FEED_ID}.json -u {API_KEY}

Xively MQTT Subscriber

This application acts as a MQTT subscriber that subscribes to the following topic: /v2/feeds/FEED_ID.json.

Pressing Button 1 triggers the MQTT connection establishment process and after its successful completion the nRF51 kit will send a subscribe message to the MQTT broker. Immediately after that the MQTT broker will send a MQTT Publish message with the actual value of the Thermometer channel. It is also possible to close the connection by pressing Button 2.

Xively MQTT Subscriber receives data from Xively MQTT Broker in JSON format. The application looks for the "current_value" string and converts the string temperature value to a decimal one. Finally, the remainder of the temperature value with division by 4 is presented on LED 3 and LED 4.

With a proper setup, Xively MQTT Subscriber should indicate the same status of LED 3 and LED 4 as Xively MQTT Publisher with a small delay.

Common module dependency and usage

This section summarizes the usage of nRF51 resources and common modules in the examples apart from the IoT 6lowpan and IPv6 stack library.

Module	Inclusion/Usage	Description
Timer	3	Three timers are used for IoT timer, buttons and for application purpose
Buttons	2	Buttons are used for initiating MQTT requests. See Button assignments section for details.
LEDs	4	LEDs are used to indicate the application states. See LED assignments section for details.
Adv Data Encoder	Yes	The device name used is 'MQTTXivelySubscriber', IPSP Service UUID is included in the UUID list.
Scheduler	Yes	Scheduler is used for processing stack events.
UART Trace	Included not enabled	Tracing is included but not enabled by default.

Setup

The name of this example is iot_lwip_mqtt_xively_subscriber. The source code and project files of the example can be found in the following folder:
<InstallFolder>/Nordic/nrf51/examples/iot/cloud/mqtt/subscriber

LED assignments

LED 1	LED 2	LED 3	LED 4
Blinking	Off	Off	Off	Device advertising as BLE peripheral.
On	Blinking	Off	Off	BLE link established, IPv6 interface down.
On	Off	Off	Off	IPv6 interface up.
Off	On	Off	Off	MQTT connection established.
Off	On	On/Off	On/Off	Actual received temperature value (LED 3 LED 4 = temperature modulo 4). For example, value of 17 = LED 3 OFF, LED 4 ON. Value of 19 = LED 3 ON, LED 4 ON
On	On	On	On	Assertion failure in the application.

Button assignments

Button 1	Button 2
MQTT Xively Connection request. Start periodic data updates.	MQTT Xively Disconnection request. Stop periodic data updates.

Testing

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

Test steps:

Compile and program the application. Observe that the device is advertising.
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 using the Bluetooth 6LoWPAN connect command.
Check if the connected state is reflected by the LEDs (LED 2 is ON).
Ensure that the kit has an IPv6 Internet connection.
Push Button 1 on the kit and keep an eye on your terminal window and LEDs. In addition, Wireshark with MQTT dissector can be used to track data exchange.
Observe that LED 2 is ON, which means that the connection is established.
Observe that LED 3 and LED4 change their state on the current temperature update. This update can be triggered by Xively MQTT Publisher, python code, or directly on the Xively webpage.
Push Button 2 again on the kit.
Observe that LED2 is OFF, which means that the connection is closed.
Disconnect from the device by using the Bluetooth 6LoWPAN disconnect command.
Observe that LED 1 is blinking and that the device is advertising.

It is also possible to test Xively MQTT Subscriber without using another nRF51 kit with Xively MQTT Publisher code. This part can be simulated with the following Python program.

Note: Remember to set a proper Feed Id and API Key.; Remember to change the current_value (from 17.00 to 24.00) to receive a new notification.

# Installation of mosquitto clients, if needed.
sudo apt-get install mosquitto-clients
# Run MQTT Publisher
mosquitto_pub -h api.xively.com -t /v2/feeds/{FEED_ID}.json -u {API_KEY} -m '{"datastreams":[{"id":"Thermometer","current_value":"17.00"}]}'

Restrictions

In the demonstration version of Xively cloud, some restrictions have been identified:

After hundreds of seconds the MQTT connection in TCP level is dropped. Thus, an auto reconnection was implemented in the Xively example.
Xively has usage limits that may cause a problem with connection or publishing/notification procedure, and so publishing interval of 10 seconds was chosen. For more information, see Usage limits
By subscribing to the actual datastream (Thermometer, for example) instead of the whole feed (as it is on example), a subscriber may not receive the latest data in a notification.