Skill Level: Any Skill Level



1. A Bluemix account in U.S South

2. Eclipse with Node.js  

3. An Android device with a flash light



  1. Install the Android app on your phone

    1. Enable 3rd party applications on your phone (this might be different for specific devices)

    – Go to your phone settings and select securirty (system section)

    – Check the box next to Unkown sources (if not already checked)

    – If needed, OK the pop up dialog

    2. Download the .apk file from https://mobilectrlapp1.mybluemix.net/app-debug.apk or simply scan the QR code directly from your phone to navigate to the same URL directly from your phone.

    3. Run the APK file to complete the installation.

    4. Make sure you see the application’s UI. We will get back to it later.

    Note 1: a zip file containing the sources can be downloaded from here: https://mobilectrlapp1.mybluemix.net/IoTMobileAPKSources.zip

    Note 2: this is based on the APK described in https://www.ibm.com/developerworks/library/iot-mobile-phone-iot-device-bluemix-apps-trs/#N10214 which has more capabilities than used in this tutorial, so some of the UI will not be used such as sending text messages or alerts.

  2. Create the solution in IoT Workbench

    1. Login to Bluemix and go to your Dashboard, make sure you are in the U.S South region

    2. Create a new space in your Bluemix organization

    3. Go to the Bluemix catalog, scroll all the way down and open the Bluemix Labs Catalog

    4. Locate the Internet of Things Workbench service (IoT Section), click to create the service in your space

    5. After the service is created your should see the IoT Workbench page for creating and opening solution (aka “All Solutions page”)

    6. Type a solution name (e.g. AndroidTutorial1) and click CREATE SOLUTION FROM LIB

    7. In the LIBRARY page search for TutorialWithMobile, click on it and add the element to the solution

    8. The IoT Workbench should switch to the ARCHITECTURE page, and the “DEPLOY TO BLUMIX” dialog should open. This will deploy the first version of the application on Bluemix:

    – Make sure to set the application name so it is unique

    – Make sure to set the right organization and space to which you want to deploy

    – Click Deploy and follow the deployment process (this may take a while)

    – After SUCCESS, close the dialog

    Note 1: You can click on the text of each completed phase to switch to the delivery piplien and watch the process

    Note 2: If it fails make sure you have enough quota of services and memory in your space and try again.

    Note 3: If after fail the CLOSE button is still disabled, refresh the web page, select the application in the diagram and do deploy again (right side bar)

  3. Review the solution’s architecture

    1. In the architecture page, one specifies the various elements types and how to connect them. On the left you see a drawing tool bar from which you can drag new elements types to your solution, on the right side bar you see the selected element feature (after you click an element)

    In our case, the archecture is looks like:

    A device type called Android is connected to a cloud application which is in turn connected to an HTTP client. The device is connected via MQTT and client is connected via HTTP.

    2. Select the Android device, on the right hand side you can see a list of all its attributes: accelerometer values (for x,y,z axis), roll, pitch and yaw, a geo location (lat and lon) and a light attribute (1 means light on, 0 means light off). All attributes in our case are Numbers.

    Open the BEHAVIOUR section (right side bar) and review the code of onMessageReception. This simulates toggling the flash light upon receiving a message called “light”

    3. Select the MQTT connector, you see two messages:

    – accel: event sent from the device to the application, carrying all attributes except light. This message is sent periodically (pattern is set to periodic) every second

    – light: command sent from the application to device which toggles the light to on and off

    4. Select the application (MobileCtrlApp1) – you see a set of URLs pointing to the dashboard of the application in Bluemix, the application page URL and the GIT URL. Clicking on an arrow next to the URL opens it. You can try them out, your application should alreayd be running.

    5. Click on the HTTP connector. You should see messages exposing the REST API of the application towards the client, which is mainly used for debug purposes.

  4. Setting up the credentials to connect with IoT Platform service

    1. Select the application (MobileClientApp1) and click on the arrow to open the APPLICATION DASHBOARD URL

    2. In IoT Workbench, click the menu button ( on the top right) and select MQTT settings, here we will need to specify the API Key and Auth Token after generarting them in the IoT Platform service

    3. Switch to the application dashboard tab and click the IoT Platform service (iotf-service) and launch its dashboard

    4. On the left side bar click on ACCESS

    5. Click on API Keys and then on Generate API Key button (right side) – do no close the dialog

    6. Copy the API key Authetication token to the Workbench settings dialoag (via the clipboard) and close the dialogs

  5. Simulating devices

    1. Switch to the SIMULATION page in IoT Worbench


    3. Add 1-3 instances (use ADD INSTANCE), select all of them and click CONNECT

    4. Back to the ARCHITECTUR tab, select the application and open the APPLICATION URL (right sidebar). Wait for a login dialog: use ADMIN as username and password. (A table showing incoming MQTT messages from the simulated devices will be displayed)

    6. Replace /admin/messagesMonitor with /main in the web page URL (for example: https://mobilectrlapp34.mybluemix.net/admin/messagesMonitor should be replaced with https://mobilectrlapp34.mybluemix.net/main)

    7. In the Select device menu you can select a device by its ID (you should see the simulated devices IDs), the graph should show some lines

    8. Back in Workbench, switch to the simulation tab and set some values for the selected device – see that your changes are reflected in the web page of the application UI (with the graph)

    9. In the application web page click Light Toggle and switch back to the simulation page to see if the light value was changed. Similarly use All Lights Toggle button to see the effect on all simulated devices (Note: the light column is the right most one, you may need to scroll the table)

  6. Connecting your Android device to the IoT Platform

    1. Switch to IoT Platfrom dashboard and click DEVICES (right hand side) – you should see your simulated devices already there.

    2. Click Add Device

    3. Choose Android as device type (same as the simulated devices) and click Next

    4. For device id, usually one enters the MAC address, however, for our purpose any 12 digits (Hex) ID should work as long as it is unique for the IoT Platform organization. Type a 12 digit ID and hit Next until you reach Security phase.

    5. In the Security page there is a way to provide the device token. It is recommended you provide an easy to remember 8 digit token since the auto generated ones are hard to remember and type. Please specify your token and hit next and then Add

    6. Capture the Organization ID, Device ID and Authentication Token – you will need it for your device app

    7. Open the application you’ve installed in the first step on your Android device (skip the tutorial) and fill in the login page with the IDs you have from the IoT Platform. Then tap on Activate Sensor.

    8. Switch back to the application UI, select your phone device and make sure it works (move your phone to see the data on the graph and toggle lights)

    9. Add additional Android (physical) devices if you like….

  7. Next steps…

    In the next steps we will modify the application so one may turn on and off the lights of all connected devices by shaking the phone (shaking and then stopping). For that you will need to use Eclipse with Node.js

  8. Setting up the project in Eclipse and running locally

    1. Importing the Git repository to your local disk

    – Open Eclipse

    – Do File->Import and click Git->Projects from Git and choose Clone URI

    – Copy the Git URL from the application in Bluemix and paste in the Eclipse wizard (Source Git Repository page)

    – Enter your credentials (usually the same as Bluemix) and complete the wizard

    2. Install the Node.js packages for your local project

    – Locate package.json under the project’s root folder (important… not other package.json file)

    – Right click on the file and do Run As->npm install (wait until it is done)

    – Right click on the root note of the project and do Refresh

    – Locate the node_modules folder, right click on it and do Team->Ignore to prevent these files to be pushed to the Bluemix Git repository

    3. Set your credentials for local debug:

    – Switch to the IoT Platfrom dashboard and generate new API Keys as done above (Setting up credentials….), leave the dialog open so you can copy the key and token

    – In Eclipse, open the _debug file under the root and copy/paste the key and token values to the apiKey and apiToken variables, i.e. in the line var apoKey…. (also the values should be between double quotes as these are strings)

    – Make sure to uncomment the entire content of this file

    – Save, right click on this file (_debug) and do Team->Ignore since these credentials should only be used locally

    4. Run your server locally:

    – Open your Eclipse preferences, go to Nodeclipse and make sure to check “pass all environment variables of Eclipse to launched Node.js app”, OK the dialog

    – Right click on app.js and do Run As->Node Application

    – See the port number in the Eclipse Console

    – Open a new web page and go to localhost:[portNumber]/main (e.g. localhost:6004/main)

    – Make sure you see the UI and can interact with the devices (simulated and real)

  9. Turning the lights on by shaking a phone

    1. Create and view the auto generated documentation for your project in Eclipse:

    – Right click on the README.md and do Generate Markdown Preview

    – Go to the docs folder under the root, and do the same for all .md files there (you can multiple select)

    – Go back to the README.md file and do Show in GFM View

    – Skim through the documentation to gain some understanding of the generated code

    2. Copy the content of the file main_Tutorial_Solution.js into the file main.js (both under the root). Review the content of the file based on what you’ve read on device cache and handling MQTT messages in the generated documentation.

    3. Go to your Bluemix application dashboard and stop the application (since it may conflict with your local one)

    4. Run your local application as before and try controlling the lights by shaking the phone (light toggles after you stop shaking)

  10. Summary

    We demonstrated how to develop a simple application over IoT Platform while using an Android app as device.

    We showed how IoT Workbench can be used to design a solution, simulated devices and deploy applications to Bluemix

    We showed how one can re-use library elements (patterns in this case) and modify them

Join The Discussion