Fork me on GitHub

Overview

The IoT Starter Application allows you to easily turn a mobile device into a sensor with IoT.

The diagram to the right provides an overview of how a device might interact with the Watson IoT Platform. Your mobile device is registered with the Watson IoT Platform, and API keys are generated for the application that consumes the data from your device.

The IoT Starter application can be set up with the following steps:

  1. Set up your Bluemix application and Internet of Things Platform service
  2. Create a device in your IoT organization
  3. Install the IoT Starter application on your mobile device
  4. Use Node-RED (or build your own application) to extend the IoT Starter application
(approx time: 30 minutes)

The instructions for setting up Bluemix and IoT below are similar to the instructions provided for the traffic simulator.


Step 1: Set up Bluemix application

First, we need to create a Bluemix application so that we have something to consume the sensor data from the device.

  1. Sign up for IBM Bluemix with your IBM ID. A basic account is free for 30 days.
  2. From the dashboard, create a new application.
  3. Select the Internet of Things Platform Starter boilerplate application.
  4. The next page shows details for the application. On the right side of the page, provide a name for the application (ex. iot-starter). This will produce a default route of http://iot-starter.mybluemix.net for the application. Click Create.
  5. After creating the application, the application dashboard will load and your application will be automatically started.
  6. Once your application has finished staging, add the Internet of Things Platform service: from the application dashboard, click Add Service, then select the Internet of Things Platform (under the Internet of Things category). NOTE: If you already have an IoT service created, click Bind Service instead of Add Service.
  7. On the next screen, give the service a name (ex. iot-starter).
  8. Next, click on the Internet of Things service in the application dashboard. This will open the configuration page for the service. From here, you can click the 'launch' button to open the Watson Internet of Things Platform dashboard.

Step 2: IBM Watson Internet of Things (IoT) Platform

The next step is to create a registered device in your new IoT organization.

  1. After completing step 1, you should now see your Watson Internet of Things Platform dashboard.
  2. First, look for the 6-character ID string in the top right corner (ex. e3dp4x)— this is your IoT organization, which you will use when connecting to IoT.
  3. Next, you will register a device with your organization. A device is used to identify a unique connection from the IoT Starter application. Click Add Device and create a new device type.
    • For the iOS application, use 'iPhone'.
    • For the Android application, use 'Android'.
    • Note that for the IoT Starter application, these device types are case sensitive and must be entered as they appear here.
  4. Specify a unique deviceId (ex. AAA), then click Next.
  5. Setting device metadata is optional. Click Next.
  6. Specify an authentication token for the device. If a token is not specified, a random token will be generated. Make note of the auth-token, this will be used when connecting to IoT. (NOTE: copy and paste the auth-token rather than typing to avoid confusing values)

    In the example images to the right, we have:

    organization: e3dp4x
    deviceType: iPhone
    deviceId: AAA
    auth-token: 18FA+etA*cNq9CJjHz

  7. You will now see the device in the organization’s device table. Since we haven’t yet connected from the application, there will be no data or events for this device.

Step 3: Install the application

Once the Bluemix and Watson IoT Platform steps are complete, the last step is to install the iOS or Android IoT Starter application.

The source for each application is available on GitHub:


Running the IoT Starter application

When you first launch the application, a login screen will appear where you must enter the following information:

  • Your IoT Organization ID
  • Your device ID
  • Your device authorization token

Once you have entered the correct values, the device is ready to connect to your IoT service. Do so by pressing the activate sensor button.

While the application is connected, it can handle a few different kinds of inputs and outputs. All inputs come from IoT command topics. All outputs go to IoT event topics. For more information on IoT events and commands, refer to the IoT documentation and recipes. Below are examples of what the messages sent and received by the application will look like.

Inputs

Inputs are messages that the device receives from IoT. These messages may have been sent by an application or another device that is also registered with the same organization. The IoT Starter application will not be receiving any messages until you have created some application to publish messages to your device.

  • Color command messages: When the application receives a color command message, the background color of the IoT view will change based on the content of the color command message. The content of a color command message is:
    {
    	"d": {
    		"r":0.0<r<255.0,
    		"g":0.0<g<255.0,
    		"b":0.0<b<255.0,
    		"alpha":0.0<a<1.0
    	}
    }
    
  • Light command messages: When the application receives a light command message, the device torch will turn on or off depending on its current state. If no torch is available, the application will display an alert saying so. The fields of the JSON message data are currently ignored by the application. The content of a light command message is:
    {
    	"d": {
    		"text": "some text here",
    	}
    }
    
  • Text command messages: When the application receives a text command message, it will be added to the log view. The content of a text command message is:
    {
    	"d": {
    		"text": "your text here"
    	}
    }
    
  • Alert command messages: When the application receives an alert command message, it will display a dialog box on the current view of the application, as well as add the message to the log view. The content of an alert message is:
    {
    	"d": {
    		"text":"your text here"
    	}
    }
    

Outputs

Outputs are messages that the device publishes to IoT. These messages can then be received by an application or another device that is also registered with the same organization. The IoT Starter application will publish messages as long as it is connected, regardless of whether you have another application somewhere to process them.

  • Accel event messages: The application publishes its accelerometer data continuously while it is connected to the IoT service. The content of an accel message is:
    {
    	"d": {
    		"acceleration_x":#,
    		"acceleration_y":#,
    		"acceleration_z":#,
    		"roll":#,
    		"pitch":#,
    		"yaw":#,
    		"lat":#,
    		"lon":#
    	}
    }
    
  • Touchmove event messages: The application publishes touchmove event messages whenever the user touches the screen when viewing the IoT view of the application. The content of a touchmove message is:
    {
    	"d": {
    		"screenX":#,
    		"screenY":#,
    		"deltaX":#,
    		"deltaY":#,
    		"ended":0|1
    	}
    }
    
  • Text event messages: The application sends text messages when the send text button is pressed on the IoT view. The content of a text message is:
    {
    	"d": {
    		"text":"your text here"
    	}
    }
    

Connecting to IoT Quickstart

The IoT Starter application also has the option to connect to IoT Quickstart. To connect to Quickstart, specify quickstart in the Organization field and provide any valid device ID. When connected to Quickstart, the only event supported is the status event. Accel event messages will be published as status event messages, and all other events messages will not be published. The application will also not be subscribed to any events or commands while connected to Quickstart.

Connecting the app to IoT Quickstart allows for an easy way to visualize the data published by the device.


Extending the application with Node-RED

Node-RED is a visual tool for wiring the Internet of Things together. Node-RED allows you to design "flows" of logic that link a variety of inputs (MQTT, TCP, HTTP) to outputs (MQTT, HTTP, Twitter, MongoDB, Cloudant) to quickly add logic to an application.

Deploy Node-RED in Bluemix

  • Visit http://iot-starter.mybluemix.net/red/ (replace 'iot-starter' with your Bluemix app name) to access the Node-RED canvas for your application.

Sample 1: Basic flow

This first Node-RED flow is a short sample that will inject a message into an ibmiot output node, which will publish a message to your IoT organization. That message will then be received by an ibmiot input node, and displayed in the debug panel of your Node-RED application.

  1. In your IoT dashboard, create a new device of type 'Node-RED-sample' with device id 'noderedsample'.
  2. In your Node-RED application, drag an inject input node onto the canvas. Double click on the node and change 'payload' to String, then enter 'test message' in the payload field.
  3. Drag an ibmiot output node onto the canvas and wire it to the inject node. Double click on the node to edit the configuration. Set the following properties:
    • Authentication: Bluemix Service
    • Output Type: Device Command
    • Device Type: Node-RED-sample
    • Device ID: noderedsample
    • Command Type: test
    • Format: String
    • Data: test message
  4. Drag an ibmiot input node onto the canvas. Double click on the node to edit the configuration. Set the following properties:
    • Authentication: Bluemix Service
    • Input Type: Device Command
    • Device Type: Node-RED-sample
    • Device ID: noderedsample
    • Command: test
    • Format: All
  5. Drag a debug node onto the canvas and wire it to the ibmiot input node.
  6. Click Deploy to launch the application.
  7. On the right side of the screen, switch to the Debug tab.
  8. Finally, click on the button on the left side of the inject node to send a message.

If everything was done correctly, you should see an entry containing 'test message' appear in the Debug panel. You've just successfully published and received a message from your IoT organization. To import this example into your Node-RED application, select Import → Clipboard and paste in the following:

[{"id":"b122d8e0.c7246","type":"ibmiot in","authentication":"boundService","apiKey":"","inputType":"cmd","deviceId":"noderedsample","applicationId":"","deviceType":"Node-RED-sample","eventType":"test","commandType":"test","format":"json","name":"IBM IoT App In","service":"registered","allDevices":false,"allApplications":"","allDeviceTypes":false,"allEvents":false,"allCommands":"","allFormats":true,"x":139,"y":138,"z":"3f16d263.e01496","wires":[["fa295123.c7766"]]},{"id":"e42ef7a6.f0908","type":"ibmiot out","authentication":"boundService","apiKey":"","outputType":"cmd","deviceId":"noderedsample","deviceType":"Node-RED-sample","eventCommandType":"test","format":"String","data":"test message","name":"IBM IoT App Out","service":"registered","x":343,"y":67,"z":"3f16d263.e01496","wires":[]},{"id":"299a71f9.fb9af6","type":"inject","name":"test message","topic":"","payload":"test message","payloadType":"string","repeat":"","crontab":"","once":false,"x":137,"y":67,"z":"3f16d263.e01496","wires":[["e42ef7a6.f0908"]]},{"id":"fa295123.c7766","type":"debug","name":"","active":true,"console":"false","complete":"false","x":318,"y":138,"z":"3f16d263.e01496","wires":[]},{"id":"c9bd571b.e0e9f8","type":"comment","name":"Sample 1: Basic flow","info":"","x":133,"y":26,"z":"3f16d263.e01496","wires":[]}]

Sample 2: IoT Starter accel to color flow

Now that we have seen a basic flow that communicates with your IoT organization, you can create a new flow that actually interacts with the IoT Starter application. This next flow will receive accel event messages from the device and publish color command messages back to it.

  1. Drag an ibmiot input node onto the canvas. Double click on the node to edit the configuration. Set the following properties:
    • Authentication: Bluemix Service
    • Input Type: Device Event
    • Device Type: All
    • Device ID: All
    • Event: accel
    • Format: json
  2. Drag a function node onto the canvas and wire it to the ibmiot input node. Double click on the function node to edit the configuration. Enter the following code:
    var accelZ = msg.payload.d.acceleration_z;
    var r = 0.0;
    var b = 0.0;
    var g = 0.0;
    if (accelZ > 0) {
    	g = 255.0;
    } else if (accelZ < 0) {
    	r = 255.0;
    } else {
    	r = 104;
    	g = 109;
    	b = 115;
    }
    a = 1.0;
    
    msg.eventOrCommandType = "color";
    msg.payload = JSON.stringify({"d":{"r":r,"b":b,"g":g,"alpha":a}});
    
    return msg;
    
  3. Drag an ibmiot output node onto the canvas and wire it to the function node. Double click on the node to edit the configuration. Set the following properties:
    • Authentication: Bluemix Service
    • Output Type: Device Command
    • Device Type: iPhone
    • Device ID: AAA
    • Command Type: text
    • Format: json
    • Data: {"d":{"value":"text"}}
    NOTE: These properties are set based on the device that was created in Step 2: IBM Watson Internet of Things (IoT) Platform.
  4. Click on Deploy to launch the application.

If everything was done correctly, then when you connect your IoT Starter application to your IoT organization, you should see the background color of the application change. The function node in this flow is looking at the value of the acceleration_z property on the received message, and sending different color command messages depending on the value. If the value is positive (your phone is laying upright on your desk), the color green will be sent. If the value is negative (your phone is laying face down on your desk), the color red will be sent. If the device is completely vertical, the default gray background color will be sent. Some things to take note of:

  • The ibmiot output node configuration values do not really matter in this case as we are overriding them in the function node.
  • If you are using a simulated device, your accelerometer data will remain at 0 and the background will not change.
To import this example into your Node-RED application, select Import → Clipboard and paste in the following:

[{"id":"2a8baa.ecd60456","type":"comment","name":"Sample 2: IoT Starter accel to color flow","info":"","x":196,"y":275,"z":"3f16d263.e01496","wires":[]},{"id":"b83ddfdb.7b3368","type":"ibmiot in","authentication":"boundService","apiKey":"","inputType":"evt","deviceId":"","applicationId":"","deviceType":"+","eventType":"accel","commandType":"","format":"json","name":"IBM IoT App In","service":"registered","allDevices":true,"allApplications":"","allDeviceTypes":true,"allEvents":false,"allCommands":"","allFormats":false,"x":117,"y":313,"z":"3f16d263.e01496","wires":[["64ebf370.5a0b5c"]]},{"id":"64ebf370.5a0b5c","type":"function","name":"Handle accel","func":"msg.deviceId = msg.payload.d.deviceId;\nmsg.deviceType = msg.payload.d.deviceType;\nmsg.format = \"json\";\n\nvar accelZ = msg.payload.d.acceleration_z;\nvar r = 0.0;\nvar b = 0.0;\nvar g = 0.0;\nif (accelZ > 0) {\n\tg = 255.0;\n} else if (accelZ < 0) {\n\tr = 255.0;\n} else {\n\tr = 104;\n\tg = 109;\n\tb = 115;\n}\na = 1.0;\n\t\nmsg.eventOrCommandType = \"color\";\nmsg.payload = JSON.stringify({\"d\":{\"deviceId\":msg.deviceId, \"r\":r,\"b\":b,\"g\":g,\"alpha\":a}});\n\nreturn msg;","outputs":1,"x":287,"y":313,"z":"3f16d263.e01496","wires":[["56d70240.c2bd14"]]},{"id":"56d70240.c2bd14","type":"ibmiot out","authentication":"boundService","apiKey":"","outputType":"cmd","deviceId":"AAA","deviceType":"iPhone","eventCommandType":"text","format":"json","data":"{\"d\":{\"value\":\"text\"}}","name":"IBM IoT App Out","service":"registered","x":469,"y":313,"z":"3f16d263.e01496","wires":[]}]

Extending the application in other ways

It isn't required to create a Node-RED application to interact with the Watson IoT Platform. In your IoT dashboard, you can create an API Key and Token. With these, you can connect any application with an MQTT client to your IoT service and perform all the same functions you would from a Node-RED application.