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.
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.
- 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
- 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
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.
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:
- 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
-
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 theAuthentication Token
for the device.Note: You will not be able to retrieve the
Authentication Token
later. This will be different from the serviceAuthentication Token
you will create in the below step.
-
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 theAuthentication 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 deviceAuthentication Token
you created in the above step. -
Click Close
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.
-
From your browser
-
Go back into the IBM Watson IoT Platform dashboard
-
In the sidebar, select Devices
-
In the Devices page, select the Browse tab
-
In the Devices list table, click the → button for your device
-
In the Device Drilldown page, click on Recent Events
Recent events/messages received by the device can be viewed in this section
-
To configure and run the simulator application
-
Go into the
simulator
directory of the cloned repo -
Copy the
.env.example
file in thesimulator
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 serviceWIOTP_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:
-
Go into the
simulator
directory of the cloned repo -
Install the dependencies:
npm install
-
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.
-
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
-
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
.
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).
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 APIaccessToken
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 thejobId
obtained in the previous response. Replace<access_token>
in the Authorization header with the HERE APIaccessToken
obtained earlier.Make note of the
deviceId
returned in the response.
-
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.
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.
- 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
- 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.
-
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:
- Enter a Name (e.g.,
WIoTP credentials
) for the credentials - Enter the API Key and API Token you generated earlier for the Watson IoT Platform service
- For Server-Name, enter
<org_id>.messaging.internetofthings.ibmcloud.com
replacing<org_id>
with your Watson IoT Platform serviceOrganization ID
- Click Update
- Enter a Name (e.g.,
-
Click Done
-
Double click the Set Credentials node:
-
Click the Deploy button in the top right to deploy the flows on IBM Cloud
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.
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.