June 3, 2016

Watson IoT MQTT APIs walkthrough

After several experiments with IBM Watson IoT Platform I have decided to take a step back and play MQTT manually to really understand how it works. In this post I will walk through my experiments with of the Watson IoT Platform MQTT messaging API for devices, applications and gateways.


First of all you need an account on IBM Watson IoT Platform on Bluemix. In all cases you need to create your own Internet of Things Platform service and create your own device type and device. I suggest you to follow the IoT Starter tutorial if you are on familiar with Watson IoT.

Another important preliminary step is to have an MQTT client to simulate MQTT calls. I have decided to use MQTT Spy tool. Download it from here and have it ready on your PC. There is a very good tutorial here if you want to learn more.
If you don't like it you can also try MQTT Lens.

Publish event from a device

This is the most simple example. A device sending MQTT messages to the cloud.
The device must be first registered on Watson IoT Platform. On you IBM Bluemix dashboard, click on the Internet of Things Platform service. Open the dashboard by clicking on the 'Launch Dashboard' button.
Open the Devices page and click on the Create Device button. First create a Device Type and then a new Device with the following details:
  • Type: TestDeviceType
  • Name: TestDev1
  • Security token: test1234
A summary page will be displayed with the device information needed for the connection.

Now we are ready to send our first message.
Devices use the following identification/authentication information (detailed documentation):
  • Client ID in formatted as d:[OrgId]:[DeviceType]:[DeviceId]
  • Username is use-token-auth
  • Password is the authentication token generated during device registration
  • Topic for publishing events is iot-2/evt/status/fmt/json

Create an new connection on MQTT Spy (replace [OrgId] with your Organization ID).
  • Protocol version: MQTT 3.1.1
  • Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
  • Client ID: d:[OrgId]:TestDeviceType:TestDev1
  • Username: use-token-auth
  • Password: test1234

Now you can publish the first MQTT message.
  • Topic: iot-2/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT"}}

Now open the Watson IoT device details and click on the Publish button on MQTT Spy. You should see the incoming message like this.

Publish event from an application on behalf of the device

The Watson Iot Platform allow to define external applications that can publish events on behalf of any device and subscribe to device events. In this tutorial we will publish a message for the Dev1 device and subscribe to its events.

We first need to define the application on Watson Iot Platform Dashboard. Open the Access and API Keys tab, then click on Generate API Keys button. Take note of the API Key and Authentication Token.

Applications use the following identification/authentication information (detailed documentation):
  • Client ID in formatted as d:[OrgId]:[AppId]
  • Username id the API Key generated during registration
  • Password is the Authentication Token generated during registration
An application can publish events as if they came from any registered device.
  • Topic for publishing events is iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json

Create an new connection with your MQTT client.
  • Protocol version: MQTT 3.1.1
  • Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
  • Client ID: a:[OrgId]:App1
  • Username: enter your API Key
  • Password: enter your Authentication Token

Now you can publish a message on behalf of device TestDev1 used before.
  • Topic: iot-2/type/TestDeviceType/id/TestDev1/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm App1"}}

Subscribe to device events from an application

An application can subscribe to events from one or more devices using topic iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json
The MQTT wildcard character '+' can be used to subscribe to more than one type of event.

On MQTT Spy subscribe to all events from the TestDev1 device using topic iot-2/type/TestDeviceType/id/TestDev1/evt/+/fmt/json

Play with MQTT Spy and see how App 1 is notified when publishing events from the device. Try changing the subscription topic as well.


Gateways can publish events from itself and on behalf of any device connected to it. In this tutorial we will publish a message for the Dev1 device and see how it is received from the subscribed app.

Open the Devices page on your Watson IoT dashboard and click on the Add Device button. First create a Gateway Type and then a new Gateway.
  • Type: TestGwType
  • Name: TestGw1
  • Security token: test1234

Gateways use the following identification/authentication information (detailed documentation):
  • Client ID in formatted as g:[OrgId]:[GwType]:[GwId]
  • Username is use-token-auth
  • Password is the authentication token generated during device registration
Note that these information are very similar to the device connection properties but the Client ID has now a 'g' prefix instead of 'd'.
A gateway can publish events on behalf of a device.
  • Topic for publishing events is iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json

Create an new connection with your MQTT client.
  • Protocol version: MQTT 3.1.1
  • Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
  • Client ID: g:[OrgId]:TestGwType:TestGw1
  • Username: use-token-auth
  • Password: test1234

Publish an event for the gateway:
  • Topic: iot-2/type/TestGwType/id/TestGw1/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm Gw1"}}
Publish an event for the device:
  • Topic: iot-2/type/TestDeviceType/id/TestDev1/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm Gw1"}}
Note haw the App1 subscription is receiving the events from the device. You can also try to subscribe to the gateway's events.


IBM Watson IoT Platform documentation
MQTT Spy tutorial

May 7, 2016

Install Kura on Raspberry PI

Eclipse Kura is an Open Source project that provides a platform for building IoT gateways. It is a smart application container that enables remote management of such gateways and provides a wide range of APIs for allowing you to write and deploy your own IoT application. Kura runs on top of the Java Virtual Machine (JVM) and leverages OSGi, a dynamic component system for Java, to simplify the process of writing reusable software building blocks. Kura APIs offer easy access to the underlying hardware including serial ports, GPS, watchdog, USB, GPIOs, I2C, etc. It also offer OSGI bundle to simplify the management of network configurations, the communication with IoT servers, and the remote management of the gateway.

In this post I will describe my own quick way of installing and configuring Kura on a Raspberry PI board. Please refer to the official Kura installation guide for more information.


  • Raspberry PI 2 or 3 with a recent version of Raspbian OS and connected to the internet. See my quick start.

Download Kura package

First of all you need to download Kura on your PI from this page.
Identify the package to be downloaded from the list. I typically use the Extended, No Net, with Web UI version - Kura 1.4.0 Extended Download: Raspbian (Model 2, No Net, with Web UI).
Versions with network are a little bit more challenging to install.

Download the selected package using the web browser or you can use this command:
cd /tmp
wget https://s3.amazonaws.com/kura_downloads/raspbian/release/1.4.0/kura_1.4.0_raspberry-pi-2-nn_installer.deb

Install Kura

First update your system's package list by entering the following command:
sudo apt-get update

Install the Kura package:
sudo dpkg -i kura_1.4.0_raspberry-pi-2-nn_installer.deb

Ignore the dependency problems warnings and fix the installation by running the following command:
sudo apt-get install -f

You can now delete the Kura package:
rm kura_1.4.0_raspberry-pi-2-nn_installer.deb

Reboot the Raspberry Pi
sudo reboot

Kura server will be restarted automatically so you should be able to access the Kura administrative UI - http://[HOST]/kura
Default login is admin/admin

To view Kura logs type the following command
tail -f /var/log/kura.log

It is strongly suggested to change admin password. This can be done by selecting the WebConsole service from the UI.

Disable CloudService (optional)

In my examples I will connect Kura to IBM Watson IoT Platform. The CloudService is a proprietary service and not appropriate for connecting to Watson IoT so we can disable it permanently.

Edit the Kura /opt/eclipse/kura/kura/config.ini file and modify the osgi.bundles parameter by changing the action for the https://developer.ibm.com/recipes/kura/plugins/org.eclipse.kura.core.cloud_*.jar from "start" to "stop".

May 6, 2016

Raspberry PI installation and first setup

In this post I will describe how to install the Raspbian operating system on a Raspberry PI 2 or 3 and some basic configuration settings to start your IoT projects.
The described procedure will not require a display and keyyboard and can be performed just connecting the PI to your router using a LAN cable.

Raspbian OS installation

First of all you need to download the latest Raspbian OS image from here. Choose the full version not the lite one.
If you are running on Windows, download the Win32DiskImager utility from here and use it to flash the iso image to the SD card. Refer to this guide for more details.
If you are running on Linux or MaxOS look here.

Now you can insert the SD card into the Raspberry PI slot and power it on.

Basic configuration

To avoid the need of connecting a display and keyboard, I typically just plug a LAN cable from my home router to the PI and get it's IP address from the router administrative console which typically is accessible at or

You can now use any SSH client like Putty to connect to the PI. The default user and passwords are pi/raspberry.

Expand filesystem (IMPORTANT)

The Raspbian ISO image is not configured to use all the SD card available memory so you need to expand the filesystem to use all the available space.
Enter the raspi-config utility:
sudo raspi-config

Choose option ‘1 Expand Filesystem’.

Exit raspi-config and it should ask to reboot. You can also manually reboot the Raspberry PI with this command:
sudo reboot

Set keyboard (optional)

Run raspi-config again if needed.

Choose ‘5 Internationalisation Options’.
Set the correct timezone and keyboard layout.
I typically leave the default locale en_GB.UTF-8 UTF-8.

Install VNC server

Next step is to install and configure a VNC server to be able to access the PI graphical UI through a network connection.
To install the TightVNC package type:
sudo apt-get install tightvncserver

Run the VNC Server which will prompt you to enter a password and an optional view-only password:
vncserver :1 -geometry 1280x800 -depth 16

Set your password and don't forget it. I typically do no specify a view-only password.

Now the VNC server on port 1 should be started and you can use any VNC client to connect to the PI. I personally use the RealVNC client.

To automatically start the VNC server when the PI boots follow this instructions.

Log into a terminal on the Pi as root:
sudo su

Navigate to the directory /etc/init.d/:
cd /etc/init.d/

Crete a vncboot file using vi command
vi vncboot

The vi editor commands (more info) are very cryptic, follow the instructions below:
  • Press i to enter insert mode.
  • Paste the script below (right click on the console to paste).
  • Exit vi saving the file by typing: ESC :wq

#! /bin/sh
# /etc/init.d/vncboot

# Provides: vncboot
# Required-Start: $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start VNC Server at boot time
# Description: Start VNC Server at boot time.


export USER HOME

case "$1" in
  echo "Starting VNC Server"
  #Insert your favoured settings for a VNC session
  su - $USER -c "/usr/bin/vncserver :1 -geometry 1280x800 -depth 16"

  echo "Stopping VNC Server"
  /usr/bin/vncserver -kill :1

  echo "Usage: /etc/init.d/vncboot {start|stop}"
  exit 1

exit 0

Make this file executable:
chmod 755 vncboot

Enable dependency-based boot sequencing:
update-rc.d -f lightdm remove
update-rc.d vncboot defaults

Reboot your Raspberry Pi

Wait for 1 or 2 minuter for the PI to restart and try connecting to the VNC server to check if it automatically starts.
Look here for more details about VNC setup.

If you have a RasPI 3 you can now easily configure the WiFi connection from the desktop. After having configured the WiFi, disconnect the LAN cable. Don't forget that a new IP address will be assigned.

Port Mapping (optional)

If you have installed the Raspberry PI at your house and want to access it remotely you can define port mappings on your router.
  • SSH: 22 > 10022
  • VNC: 5901 > 15901
  • HTTP: 80 > 10080
I prefer to change the ports for security reasons and to allow more than one device to be mapped.

May 4, 2016

IoT and IIoT

The Internet of Things (IoT) is one of the most significant trends in technology today. A melding of innovations in the fields of computing and communication, IoT and its “smart” devices are poised to revolutionize not only user-machine interaction but also the way in which machines engage with one another.

IoT is now permeating in every industry energy, healthcare, automotive, and other industries are beginning to grapple with the Industrial of Internet of Things (IIoT), where devices such as sensors, robots, mixing tanks, and insulin pumps are becoming increasingly more connected.

But what’s the difference between IoT and IIoT? It’s not a difficult distinction, but many people incorrectly use them interchangeably.

IoT vs. IIoT: Consumer vs. Industrial Applications
If your refrigerator or wearable device is connected to the Internet, then it is part of the IoT. It’s a consumer application. If your factory floor has machinery connected to each other and to a centralized data center, it is an M2M application. If your factory floor has an ecosystem of sensors, machinery and people connected to processes and to the Internet, then it is part of IIoT. It’s an industrial application.

Many analysts say that IIoT will drive the next industrial revolution (Industry 4.0) where intelligent, interconnected systems will seamlessly support activities along the entire value chain and boost efficiency and productivity.

A major concern surrounding the Industrial IoT is interoperability between devices and machines that use different protocols and have different architectures. The nonprofit Industrial Internet Consortium, founded in 2014, focuses on creating standards that promote open interoperability and the development of common architectures.

Industrial IoT has far more stringent requirements than the consumer IoT, including the need for no-compromise control, rock-solid security, unfailing reliability even in harsh (extremely hot or cold, dusty, humid, noisy, inconvenient) environments, and the ability to operate with little or no human intervention. And unlike more recently designed consumer-level devices, many of the billion or so industrial devices already operating on existing networks were put in place to withstand the test of time, often measured in decades.

The differences between the IIoT and IoT are not just a matter of slight degree or semantics. If your Fitbit or Nest device fails, it might be inconvenient. But if a train braking system fails, it could be a matter of life and death.

TechCrunch - Making Sense Of The Internet Of Things
Tripwire - 5 Key Challenges for the Industrial Internet of Things (IIoT)
IoT Agenda - Industrial Internet of Things (IIoT)
The Industrial IoT isn’t the same as the consumer IoT