2021 Call for Code Awards: Live from New York, with SNL’s Colin Jost! Learn more

Connect Watson IoT and HERE Tracking

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

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.

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.

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 objectives

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

Steps

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:

Select ORG

Add a Device Type in the IBM Watson IoT Platform service

  1. From the sidebar, select Devices.
  2. On the Devices page, select the Device Types tab.
  3. Click Add Device Type to open the Add Type form.
  4. Select Device for the Type.
  5. Enter a unique Name for the device type (e.g., wiotp-device-type-01).
  6. Click Next.
  7. Click Finish.

Add a Device in the IBM Watson IoT Platform service

  1. From the sidebar, select Devices.
  2. On the Devices page, select the Browse tab.
  3. Click Add Device to open the Add Device form.
  4. For Device Type, select the device type created earlier (e.g., wiotp-device-type-01).
  5. Enter a unique Device ID for the device (e.g., wiotp-device-01).
  6. Click Next.
  7. Click Next on the Device Information screen.
  8. Enter an optional Authentication Token or leave blank to be assigned a generated token.
  9. Click Next on the Security screen.
  10. 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

  1. From the sidebar, select Apps.
  2. On the App page, select the Browse tab.
  3. Click Generate API Key to open the Generate API Key form.
  4. (optional) Enter a Description for the key.
  5. (optional) Enable and set a date for API Key Expires.
  6. Click Next.
  7. Select Standard Application for the Role.
  8. 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.

  9. 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

  1. From your browser.

    1. Go back into the IBM Watson IoT Platform dashboard.
    2. In the sidebar, select Devices.
    3. On the Devices page, select the Browse tab.
    4. In the Devices list table, click the button for your device.

      Select device

    5. On 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

  1. Go into the simulator directory of the cloned repo.
  2. Copy the .env.example file in the simulator directory, and create a new file named .env.
  3. 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).
  4. 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

  1. Sign in to the HERE Tracking Admin Portal.
  2. 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.

      here create project

      After a few seconds your project will be ready.

  3. Click on the App IDs tab.

  4. 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:

  1. 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.

  2. 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.

  3. 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

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

    Device report

  9. 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

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

Import the Node-RED flow

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

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

Configure & deploy the Node-RED flows

  1. In the WIoTP to HERE Tracking flow, double click the IBM IoT node.
  2. In the Edit ibmiot in node panel, update the fields accordingly:

    ibmiot node

  3. 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.
  4. Click Done.

  5. 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.

      credentials node

    3. Click Done.

  6. 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.

here tracking geofence

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.