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.

Prerequisites

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:
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):

Create an new connection on MQTT Spy (replace [OrgId] with your Organization ID).

 


Now you can publish the first MQTT message.



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):
An application can publish events as if they came from any registered device.


Create an new connection with your MQTT client.


Now you can publish a message on behalf of device TestDev1 used before.



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.



Gateway


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.


Gateways use the following identification/authentication information (detailed documentation):
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.

Create an new connection with your MQTT client.


Publish an event for the gateway:
Publish an event for the device:
Note haw the App1 subscription is receiving the events from the device. You can also try to subscribe to the gateway's events.


References


IBM Watson IoT Platform documentation
MQTT Spy tutorial


Labels: , , ,