Data Platform Plot Reference Application

Data Platform Temperature Sensor Plotting

Get the SFDP Plot Reference App On GitHub
This reference application demonstrates the use of Itron Networked Solutions' Data Platform APIs to build a web application to fetch devices and observations and plot them on a graph.

Overview

This sample application demonstrates how to use Starfish JavaScript SDK to build a simple web application to fetch devices and observations from Data Platform. The application plots temperature sensor measurements (observations) that have been stored in the Data Platform for any device owned by your Tenant Group.

Requirements

  • Chrome web browser (Starfish Studio is currently only compatible with Chrome)
  • GitHub account
  • Itron Networked Solutions Developer Portal account
  • API key ClientID and Secret (retrieved from Account Settings tab in your developer portal account view)

 

Getting the Application and Source Code

The source code is provided as open source under the MIT license. You will find it on the Itron Networked Solutions GitHub repository. Once you have created your GitHub repository, you can run the application by simply opening "index.html' provided in a web browser.

Download the reference app from GitHub:  Starfish Example Plot Application

 

Terminology used in this application

DeviceA device can be an Itron Networked Solutions Milli or an Access Point (AP). It can also be an external device, such as a sensor. A Milli is a low-cost, small-form-factor Itron Networked Solutions NIC used in battery-powered or constantly powered devices. An AP is a gateway device that can communicate with devices over NAN and the back office network over WAN. A sensor is a device that can detect and record environmental changes.

When we refer to devices those could be either virtual or physical devices. Within Starfish Studio you have the ability to generate virtual device configurations for use in simulation and prototyping. Physical devices could be in the form of an HDK which you are using for development and that has been provisioned to your account. Once provisioned to your account you can view data streams from your device by using our API's to retrieve devices and then specifically call a device by the deviceID.

Physical devices could also be devices which are part of a deployed, real-world solution and to which you know the deviceID, or MAC ID.

 

Provisioning: When you purchase an HDK the device will be provisioned to you as part of the fulfillment process. If you are simulating a virtual device that device will be provisioned to your account as part of the solution being simulated. When you are ready to deploy a real-world solution part of the steps of deployment will involve provisioning the device to the network in a production environment.

 

Observation: Sensors gather information or "observations" about environmental changes, such as temperature, humidity, and location. The observations APIs enable you to upload observations to the Data Platform and retrieve it as needed. 

 

SolutionA Itron Networked Solutions IoT solution is a combination of hardware and software components that address a specific need. For example, the Itron Networked Solutions Logistics solution offers a track-and-trace subscription service to companies that need to keep track of containters in their warehouses. You can design and test your solutions in Starfish Studio before implementing them in the real world. Solution names are case sensitive.

 

Starfish Studio: is a sandbox where you can test, and validate simulated devices with for your solution before deploying your application with real devices. Starfish Studio provides a set of sensors to use in testing your solution.

 

Tenantis a device owner in Starfish Studio.

Application Use

 

Starting the Application

1. Download or clone the Git repo to your local machine: Starfish Example Plot Application

git clone https://github.com/silverspringnetworks/developer_program.git

 

 

2. After downloading the source code from GitHub navigate to the file: developer_program/SDK/Starfish Example Plot Application/index.html, and open it in a web browser. When you cloned the repository it installed all of the resources you should need, so a localhost is not necessary. You should something that looks like this:
Starfish Data Platform Temperature Sensor Plot Application

 

3. Retrieve your client credentials from the account settings tab in the developer portal

 

4. Enter your API ClientID and Secret retrieved from the Account Settings tab of the My Account Overview area in the Developer Portal.

5. Where you are prompted to enter a solution name you have two options.

1) The default of 'sandbox' solution will allow you to return observations from your physical HDK (Hardware Kit) device. This is a device that you have purchased which was provisioned to your tenant upon order fulfillment, once you have your device on the network and configured with a temperature sensor you will be able to stream that data through the reference application.  

2) Use the 'StudioSimulation' solution. This is essentially a set of virtual devices that are invoked when you run a simulation using starfish studio. While the simulation is running you can call the 'StudioSimulation' solution which is by default associated with your tenant and ClientID and also gives you access to the available APIs.

6. Enter a Solution name and click the "Connect" button. The application will retrieve all devices provisioned in the Data Platform for that solution. 

 

Data Sources and Solutions

Virtual Devices

Devices and observations can be simulated using Starfish Studio.  These are referred to as virtual because they do not physically exist but are data generated in a simulation. In the current implementation of the Data Platform all simulated data is in the solution named StudioSimulation. for example, If you are using our reference application to plot sensor data you would use your credentials and call the StudioSimulation solution.

Physical Devices

Temperature observations can also come from physical temperature sensors deployed on the network. When developer kits are ordered from the Developer Portal they are provisioned in the sandbox solution for your account in the Data Platform. Once you connect your temperature sensor to the device you can retrieve devices that are part of your sandbox solution, and then specifically view observations using the deviceID.

Retrieving Device Data

Once you have entered your ClientID, Secret and Solution and click the "Connect" button the application queries the Data Platform with a GET method of the Devices API. All devices provisioned in the data platform will be returned in the table below the "Connect" button. All devices, virtual and physical, are displayed. Clicking any of the devices listed in the table will initiate an API call using the GET method of the Observations API to retrieve the temperature observations for the selected device. 

The observations will be presented in JSON format:

{
  "observations": [
    {
      "temperature": -31.4215,
      "timestamp": "2017-03-21T22:04:08.667Z"
    }
  ]
}

 

Virtual (Simulated) Devices

It is easy to generate simulated temperature data using Starfish Studio as follows:

  1. Start Starfish Studio
  2. Enter a Device name in the box labeled "Type of thing this device will be used with".
  3. Select the "Temperature" radio button (currently the reference app only plots temperature data).
  4. A representative temperature measurement (aka Observation) will be displayed in the window on the right. (Note: The deviceID is the unique identifier for the device in the data platform.)

​​

  1. Click Save.
  2. You will be presented with a screen where you can enter the number of devices to simulate in the upper right corner. 
  3. Click Run to begin the simulation. Once your simulation is running the virtual devices will be provisioned and available to the reference application.
  4. Navigate to the Temperature Plot application you downloaded from Github by opening file index.html in a web browser.
  5. Enter your ClientID, Secret and the name "StudioSimulation" as the Solution. Click Connect. This is making the authentication call to your account and the Get Devices calls behind the scenes.
  6. You will see devices listed in the table below the Connect button. You should see the number of devices entered in the step above.
  7. Click on one of the devices returned in the table and the simulated temperature measurements will be plotted dynamically as the simulation runs.

 

The device and observation data can be queried using the API's either from the API View in Starfish Studio or by calling the API's using Curl or from application code you write. 

The curl call to retrieve devices would look like this:

curl -X GET --header 'Accept: application/json' --header 'Authorization: {token}' 'https://api.data-platform.developer.ssni.com/api/solutions/StudioSimulation/devices' 

And the response would look like:

 

{
  "devices": [
    {
      "deviceType": "VirtualDevice",
      "domainInfo": {
        "location": {
          "latitude": 25.1215,
          "longitude": -129.388
        }
      },
      "id": "5c4fe6f2-429b-4020-ae2e-0e64ab73379d"
    },
    {
      "deviceType": "VirtualDevice",
      "domainInfo": {
        "location": {
          "latitude": 83.0474,
          "longitude": 160.036
        }
      },
      "id": "ac697f1f-8abf-4f35-b3ed-30189445c563"
    },
    {
      "deviceType": "VirtualDevice",
      "domainInfo": {
        "location": {
          "latitude": 6.1202,
          "longitude": 29.8677
        }
      },
      "id": "b068d785-601d-458e-839d-b4c8a7b36ca3"
    },
    {
      "deviceType": "VirtualDevice",
      "domainInfo": {
        "location": {
          "latitude": -63.9522,
          "longitude": 19.2524
        }
      },
      "id": "d0d42a57-bbef-4cb7-b030-e99ed2488431"
    }
  ]
}

 

The latest observations can be retrieved with the Observations API. For example, this API call

 

curl -X GET --header 'Accept: application/json' --header 'Authorization: {token}' 'https://api.data-platform.developer.ssni.com/api/solutions/StudioSimulation/observations'

 

Returns results that look like this:

[
  {
    "observations": [
      {
        "temperature": -26.5785,
        "timestamp": "2017-03-26T01:59:48.603Z"
      }
    ],
    "deviceId": "0c2fa1f1-bf0d-472f-9998-044a4937ccc0"
  },
  {
    "observations": [
      {
        "temperature": -64.5993,
        "timestamp": "2017-03-26T01:59:48.595Z"
      }
    ],
    "deviceId": "1add54ae-f96b-45e5-aa84-539c48e0ef00"
  },
  {
    "observations": [
      {
        "temperature": 54.852,
        "timestamp": "2017-03-26T01:59:48.607Z"
      }
    ],
    "deviceId": "6234c1f3-4d31-4a5d-8eaf-523fe31c5fad"
  },
  {
    "observations": [
      {
        "temperature": 11.7931,
        "timestamp": "2017-03-26T01:59:48.597Z"
      }
    ],
    "deviceId": "bc34bf4c-b7d5-4f7b-bdce-6013b9bb223b"
  }
]

 

Physical Devices

The plotting application can also be used for temperature sensors from physical devices. The Milli Dev Kit Temperature Sensor Reference Application and the IOT Router BLE Temperature Sensor Snappy Application are examples of physical device temperature sensor implementations. The temperature sensor observation data is ingested into the Data Platform in the same JSON schema as described for Virtual sensors above.

When Mill Dev Kits, IOT Edge Router Dev Kits and other devices are provisioned they have a special taxonomy "provisioningInfo" which identifies their mac address, device type, provisioned status, and timestamp of provisioning. The devices are provisioned to the solution sandbox.

The curl call to retrieve devices would look like this:

curl -X GET --header 'Accept: application/json' --header 'Authorization: {token}' 'https://api.data-platform.developer.ssni.com/api/solutions/sandbox/devices' 

An example response of this GET Devices API call for a Milli Dev Kit physical device might look like:

 

{
  "devices": [
    {
      "deviceType": "NICDevKit",
      "domainInfo": {
      },
      "provisioningInfo": {
        "status": "provisioned",
        "timestamp": "2016-09-14T00:21:40.000Z",
        "ssniMacAddress": "00135003005c2704",
        "ssniNetworkDeviceType**" : "MILLI"
      },
      "id": "065e8ec3-e665-4218-a7c0-13c931fcd135"
    }
  ]
}