Integrate Watson IoT with HERE Tracking for real-time IoT device management and tracking

With the Watson IoT Platform and HERE Tracking you can plan and monitor the safe and timely delivery of goods and supplies (e.g., food, medicine, livestock, etc.) in real-time.

Learn how to develop an IoT application with the Watson IoT Platform and Node-RED that will gather data received from IoT sensors (e.g. vehicle GPS, edge devices, etc.). The geolocation data can then be integrated with HERE Tracking for route planning, geofencing, and visualization.

IBM Watson IoT service provides a platform that lets you manage, communicate with, and consume data from connected devices and gateways.

Node-RED is an open source visual programming tool that offers a browser-based flow editor for wiring together devices, APIs, and online services.

HERE Tracking is a location platform that makes it quick and easy to track your devices indoor and outdoor, see traces on a map, create geofences and get custom notifications.

Learning Objective

In this tutorial, you will learn how to:

Create an IoT application on IBM Cloud using Node-RED and Watson IoT
Add and manage IoT devices with the Watson IoT Platform
Integrate location awareness using cloud-to-cloud connection with HERE Tracking
Add and manage virtual devices with HERE Tracking
Send data from Watson IoT to HERE Tracking using Node-RED

To keep the focus primarily on the platforms and tools and not hardware or specific IoT devices, sample data will be coming from a simulator instead of an actual device.

Prerequisites

Clone the GitHub repository for this tutorial
Register for an IBM Cloud account
Register for a HERE account
(for simulating data) Laptop/workstation with Node.js installed

Steps

Create an Internet of Things Platform application
Add an IoT Device Type and Device to Watson IoT
Simulate IoT data
Set up HERE Tracking
Add a Virtual Device to HERE Tracking
Route Watson IoT messages to HERE Tracking
Test the integration

Create an Internet of Things Platform application

The first step is to create an IoT application on IBM Cloud using the IBM Watson IoT Platform service and the Node-RED App Starter Kit.

Follow the instructions in this tutorial to provision a Node-RED App and Watson IoT Platform service.

Add an IoT Device Type and Device to Watson IoT

After completing the previous step, you will have a Node-RED Starter Kit application connected to the IBM Watson IoT Platform. You can now proceed to adding a device to Watson IoT.

From your browser, access the IBM Watson IoT Platform service created in the first step. Be sure to select your org:

Add a Device Type in the IBM Watson IoT Platform service

From the sidebar, select Devices
In the Devices page, select the Device Types tab
Click Add Device Type to open the Add Type form
Select Device for the Type
Enter a unique Name for the device type (e.g., wiotp-device-type-01)
Click Next
Click Finish

Add a Device in the IBM Watson IoT Platform service

From the sidebar, select Devices
In the Devices page, select the Browse tab
Click Add Device to open the Add Device form
For Device Type, select the device type created earlier (e.g., wiotp-device-type-01)
Enter a unique Device ID for the device (e.g., wiotp-device-01)
Click Next
Click Next on the Device Information screen
Enter an optional Authentication Token or leave blank to be assigned a generated token
Click Next on the Security screen
Click Finish

Make note of the Organization ID and also the Authentication Token for the device.

Note: You will not be able to retrieve the Authentication Token later. This will be different from the service Authentication Token you will create in the below step.

Generate an API Key

From the sidebar, select Apps
In the App page, select the Browse tab
Click Generate API Key to open the Generate API Key form
(optional) Enter a Description for the key
(optional) Enable and set a date for API Key Expires
Click Next
Select Standard Application for the Role
Click Generate Key

Make note of the API Key and also the Authentication Token for the Watson IoT Platform service.

Note: You will not be able to retrieve the Authentication Token later. This will be different from the device Authentication Token you created in the above step.
Click Close

Simulate IoT data

The tutorial provides some sample data and a basic simulator to send the data to the IoT platform. This can provide quick and easy testing of your set up.

View recent messages

From your browser
1. Go back into the IBM Watson IoT Platform dashboard
2. In the sidebar, select Devices
3. In the Devices page, select the Browse tab
4. In the Devices list table, click the → button for your device
5. In the Device Drilldown page, click on Recent Events
  
  Recent events/messages received by the device can be viewed in this section

Send messages using the simulator

To configure and run the simulator application

Go into the simulator directory of the cloned repo
Copy the .env.example file in the simulator directory, and create a new file named .env
Edit the newly created .env file and update the environment variables with values noted in the earlier steps:
- WIOTP_ORG_ID: set to the Organization ID of your Watson IoT Platform service
- WIOTP_TYPE_ID: set to the Name of your device type (e.g., wiotp-device-type-01)
- WIOTP_DEVICE_ID: set to the Device ID of your device (e.g., wiotp-device-01)
- WIOTP_AUTH_TOKEN: set to the Authentication Token of your device (not the service Authentication Token)
From a terminal:
1. Go into the simulator directory of the cloned repo
2. Install the dependencies: npm install
3. Run the command: node device-simulator.js sample-data/sample-data.json
  
  The simulator will connect to your instance of Watson IoT Platform and the contents of the sample-data/sample-data.json file will be sent (mimicking possible data coming from a device).

After a few seconds, you should be able to see the messages show up in the device's Recent Events table. Seeing these messages should confirm your set up is correct.

Set up HERE Tracking

Sign in to the HERE Tracking Admin Portal
If you do not already have one, create a project in the Admin Portal: https://developer.here.com/documentation/tracking/dev_guide/topics/projects.html
1. Click the Create new project button
2. Enter a Project name in the Create new project form
3. Click the I agree to the Developer Service Terms checkbox
4. Click the Create button
  
  After a few seconds your project will be ready.
Click on the App IDs tab
Click on the View App ID button for the Cloud-to-Cloud Connector

Make note of the APP ID.

Add a Virtual Device to HERE Tracking

HERE Tracking is hardware-agnostic and can be used by any device that produces conforming telemetry. For devices that cannot make direct connections to HERE Tracking or do not provide proper telemetry data, cloud-to-cloud connectivity is available.

In this tutorial, we will a set up cloud-to-cloud connection from IBM Cloud to HERE Tracking so messages received by Watson IoT platform can be converted into the proper format and sent to HERE Tracking.

For cloud-to-cloud connectivity, a virtual device is defined and registered. The hardware device would send its data to an external service (in the case, the Watson IoT Platform service), the data is properly formatted and forwarded to HERE Tracking (using the virtual device credentials).

Create a virtual device and obtain a license

From a terminal:

Login in to HERE Tracking and obtain an Access Token, with the command:
```
curl -X POST \
  https://tracking.api.here.com/users/v2/login \
  -H 'Content-Type: application/json' \
  -d '{ "email": "<here_account_email>", "password": "<here_account_password>" }'
```
Replace <here_account_email> and <here_account_password> with your HERE account credentials.

Make note of the accessToken returned in the response
Request a license for a virtual device by running:
```
curl -X POST \
  https://tracking.api.here.com/registry/v2/<app_id>/devices?autoclaim=true \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{ "devices": [ { "id": "<device_id>" } ] }'
```
Replace <app_id> in the URL with your HERE Tracking project Cloud-to-Cloud Connector APP ID obtained earlier in HERE Admin Portal. Replace <access_token> in the Authorization header with the HERE API accessToken obtained in the previous step and replace <device_id> with the ID of your device created earlier (e.g., wiotp-device-01) in Watson IoT Platform.

Make note of the jobId returned in the response.
Get the license from the job results by calling:
```
curl -X GET \
  'https://tracking.api.here.com/registry/v2/<job_id>/results' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json'
```
Replace <job_id> in the URL with the jobId obtained in the previous response. Replace <access_token> in the Authorization header with the HERE API accessToken obtained earlier.

Make note of the deviceId returned in the response.

View and configure the virtual device

Log in to the HERE Tracking Workspace
In the sidebar, select Devices
In the Devices panel, select the newly registered device (i.e., undefined)
In the Device details panel, click Options > Edit device details
Enter a Name (e.g., here-device-01) for the device
Click Save setup
In the Device details panel, in the Report Location section, click EDIT
Set how you want the data reported in the Workspace dashboard. For example:
Click Save

Your HERE Tracking virtual device is now ready to start receiving messages and the report will update according to its Report Location settings.

Route Watson IoT messages to HERE Tracking

To forward the messages received by Watson IoT to HERE Tracking you will use Node-RED. The Node-RED application will be notified of events received by the Watson IoT Platform, convert the data to conform to HERE Tracking, and then send the updated data to HERE Tracking.

Add credentials node

Launch and access your Node-RED application provisioned in the beginning
Click the Menu button in the top right
Click Manage palette
In the User Settings panel, select the Palette tab
Select the Install tab
Search for node-red-contrib-credentials
Click the install button of for the node-red-contrib-credentials in the results
Click Install in the warning dialog
Click Close to close the User Settings panel

Import the Node-RED flow

From the Node-RED editor, click the Menu button in the top right
Click Import
In the Import nodes dialog, select the Clipboard tab
Click the select a file to import button, then browse and open the flow/wiotp-to-here-flows.json file in the cloned repo
For Import to, select new flow
Click Import

The Node-RED flows should get loaded into your Node-RED editor.

Configure & deploy the Node-RED flows

In the WIoTP to HERE Tracking flow, double click the IBM IoT node
In the Edit ibmiot in node panel, update the fields accordingly:
Click the Edit icon for the API Key field and update the credentials:
1. Enter a Name (e.g., WIoTP credentials) for the credentials
2. Enter the API Key and API Token you generated earlier for the Watson IoT Platform service
3. For Server-Name, enter <org_id>.messaging.internetofthings.ibmcloud.com replacing <org_id> with your Watson IoT Platform service Organization ID
4. Click Update
Click Done
Double click the Set Credentials node:
1. Update the HERE_ACCOUNT_EMAIL and HERE_ACCOUNT_PASSWORD values with your specific HERE account credentials
2. Update the HERE_APP_ID value to your HERE Tracking project Cloud-to-Cloud Connector APP ID obtained earlier in HERE Admin Portal
3. Click Done
Click the Deploy button in the top right to deploy the flows on IBM Cloud

Test the integration

With the Watson IoT Platform service set up, the HERE Tracking configured, and the Node-RED flows deployed, you are ready to test and run the integration.

From a terminal, run the device simulator:

$ node device-simulator.js sample-data/boston-cambridge.json

If you look at the Node-RED editor, you should see in the Debug sidebar responses from HERE Tracking after each message is sent. If everything is properly configured, the statusCode in the responses should be 200.

In the HERE Tracking Workspace page for your virtual device, you should see the location of the device on the map. The location and map should update periodically depending on your report setting.

At this point, you should be able to add rules or geofencing information for your device in HERE Tracking and receive the appropriate notifications.

You may also replace the sample-data/sample-data.json file with other files containing sample data you wish to send.

Note: You can generate your own sample data file to test by running the generate-sample-data.js. For example,
node generate-sample-data.js -o "boston, ma" -d "cambridge, ma"
Run node generate-sample-data.js --help for available options and usage information.

To run the script you'll need a HERE Location Services API key. Follow the instructions outlined in the HERE Developer Portal to obtain a JavaScript API key. Then update the HERE_API_KEY variable in .env with your assigned API Key.

Summary

Congratulations! You have now created a Node-RED and Watson IoT Platform application hosted in the IBM Cloud and integrated with HERE Tracking for location awareness.

In this tutorial, you learned how to provision the Watson IoT Platform service, create a Node-RED application, and configure cloud-to-cloud connectivity with HERE Tracking.

The integration between Watson IoT and HERE Tracking not only allows you to manage, plan, and monitor your IoT devices, but also incorporate geolocation information for real-time tracking, geofencing, and notification.

paritoshg / wiotp-here-tutorial Goto Github PK

wiotp-here-tutorial's Introduction