Locate Devices on a Map

Internet of Things Workbench

In this tutorial I will show you how to use Internet of Things Workbench service in IBM Bluemix to quickly develop an app which can be used to locate devices on a map, with a possibility to retrieve sensor values by clicking on a marker that represents certain device. For this purpose, we will specify fixed coordinates that will be sent from our device. If you have static devices, this would be fine, but if you need to track moving devices, than you can add a GPS module to obtain coordinates, but the principle remains the same.

At the moment, IoT Workbench is experimental service, and it is supported only in US South region. You can find this service in Bluemix Labs catalog, which you can find at the bottom of the catalog.

Labs Catalog

In the Labs catalog, scroll to the Internet of Things section and click on Internet of Things Workbench.

IoT Workbench

Choose your space, give it a name and click create button (right now, you can select only experimental plan). First thing we need to do is to create a new solution. Enter solution name and click create new solution button.

Creating a New Solution

After you open the solution you have just created, you will see in architecture tab an example of app that is automatically created.

IoT Workbench Editor

In the editor you place different components and wire them together to make an app. You can delete the flow that has been created and open the library tab. Select Devices on Maps and click add element to solution.

Devices on Maps


Since we are using only one device type, you can delete one device element. Also, give appropriate names to app and device elements.

App Flow

Click on the device element and you can see properties that our device sends to the app. Lat and lon represent latitude and longitude values that the app uses to locate devices. We will add one more property for ADC values. A payload our device will be publishing will consist of four parameters: device name, ADC value and latitude and longitude values. 

Payload Properties

Now click on the connection line between device and app elements and configure format of MQTT messages that will be used. NAME field will be used in publish topic. Add ADC in payload field.

Configuration of MQTT Messages

Deploying the App

In order to deploy the app, you need to register here. Your apps will be located in separate repositories. Bluemix should ask you to register if you don’t have an account already, and it will set everything up for you when deploying apps using IoT Workbench service.

You are ready to deploy the app. Click on the app element and then click deploy to Bluemix button.

Deploying the App

After the process of deploying finishes, you should see a new app in the main dashboard.

You can see that a new IoT platform service is automatically bound to the app. You can register devices to it by following the same steps explained in the 3rd part, or if you already have set up an IoT Platform service, you can use that one, just bind it to the app. Whichever instance of IoT platform service you want to use, you will need API key and AUTH token. Launch IoT platform dashboard, go to ACCESS > API keys and generate key – token pair. In the right corner of your IoT Workbench solution open MQTT Settings and enter key and token.


MQTT Settings

Click on the app element, enter your GIT user name and password and click deliver button.

Delivering the App

You can open delivery pipeline and track the delivery process.

Delivery Pipeline

After this process finishes, open your app by clicking on the <appName>.mybluemix.net. If the redirection message appears and window asking for user name and password pops up, enter ‘ADMIN’ in both fields. You should see the following page.

Messages Monitor

There aren’t any MQTT messages published yet.

Uploading the Firmware to the ESP8266

Now we need to upload code to the ESP8266. The only difference from previous examples is that now our device is sending additional lat and lon values that the app uses to locate the device. As I have already said, for this purpose these values will be fixed and generated within the code. Make sure that publish topic correspond to the name value in MQTT configuration in IoT Workbench.

#include <ESP8266WiFi.h>
#include <PubSubClient.h> // https://github.com/knolleary/pubsubclient/releases/tag/v2.3

const char* ssid = "";
const char* password = "";

#define ORG "<yourOrganization>"
#define DEVICE_TYPE "ESP8266"
#define DEVICE_ID "<yourDeviceID>"
#define TOKEN "<yourToken>"

char server[] = ORG ".messaging.internetofthings.ibmcloud.com";
char topic[] = "iot-2/evt/SendData/fmt/json";
char authMethod[] = "use-token-auth";
char token[] = TOKEN;
char clientId[] = "d:" ORG ":" DEVICE_TYPE ":" DEVICE_ID;

WiFiClient wifiClient;
PubSubClient client(server, 1883, callback, wifiClient);

const double lat = 42.444299;
const double lon = 19.236563;

//converting lat and lon values to strings
String lat_str = String((int)lat) + "." + ((int)(1000000 * lat))%1000000;
String lon_str = String((int)lon) + "." + ((int)(1000000 * lon))%1000000;

void setup() {

 Serial.print("Connecting to ");
 WiFi.begin(ssid, password);
 while (WiFi.status() != WL_CONNECTED) {

 Serial.print("WiFi connected, IP address: ");

void loop() {

 if (!client.connected()) {
 Serial.print("Reconnecting client to ");
 while (!client.connect(clientId, authMethod, token)) {

 String payload = "{\"d\":{\"Name\":\"18FE34D81E46\"";
 payload += ",\"ADC\":";
 payload+= analogRead(A0);
 payload += ",\"lat\":";
 payload += lat_str;
 payload += ",\"lon\":";
 payload += lon_str;
 payload += "}}";

 Serial.print("Sending payload: ");
 if (client.publish(topic, (char*) payload.c_str())) {
 Serial.println("Publish ok");
 } else {
 Serial.println("Publish failed");



void callback(char* topic, byte* payload, unsigned int length) {
 Serial.println("callback invoked");

If your device is successfully publishing events, you should see them when you open the app.

Published MQTT Messages

To see the map, you have to add ‘/maps’ to the address of your app. Go to <appName>.mybluemix.net/maps and you should be able you see your device on the map on the location specified by latitude and longitude values. If you click on the marker you can see details as well as ADC value that device publishes.

Device on a Map

That’s the end of the 7th part. You have seen how you can use IoT Workbench to quickly develop an app that is used to visualize devices on a map.

Lessons of this Series



Subscribe to our newsletter for good news, sent out every month.