Route Tutorial - InitialState

Introduction

In this tutorial, you’ll learn how to connect your Notecard-powered app to an external cloud provider or service, InitialState, and how to start creating simple visualizations with sensor data.

This tutorial assumes you’ve already completed the initial Sensor Tutorial to capture sensor data, save it in a Notefile called sensors.qo and send that data through the Notecard to Notehub; or, that you’ve already created your own app with sensor data and are ready to connect your app to external services.

In order to complete this guide, you’ll need the following:

• A Notehub project with at least one Notecard sending sensor-reading Notes at regular intervals.
• An account with the external service you plan to use to complete this tutorial.

Create a Route

A Route is an external API, or Server location, where Notes will be forwarded for a Device or Fleet upon receipt.

Routes are defined in Notehub for a Project, and can target a single Fleet or all devices in a Project. A Project can have multiple routes defined and active at any one time. Before you create a Route, ensure the data you want to route is available in Notehub, by navigating to the Events view.

We’ll start with a simple route that will pass Notecard events through to webhook.site, where you can view the full payload sent by Notehub. Using this service is a useful way to debug routes, add a simple health-check endpoint to your app, and/or familiarize yourself with Notehub's Routing service.

1. Navigate to webhook.site. When the page loads, you'll be presented with a unique URL that you can use as a Route destination. Copy that URL for the next step.

   

2. Navigate to the Notehub.io project for which you want to create a route and click on the Routes menu item in the left nav.

3. Click the "Add Route."

   

4. Give the route a name (for example, "Health"), and select "General HTTP/HTTPS Request/Response" for the Route Type.

   

5. For the Route URL, use the unique URL you obtained from webhook.site.

   

6. In the Notefiles dropdown, choose "Select Notefiles" and enter the name of the notefile to monitor. For example, we used sensors.qo for the sensor tutorial.

   

7. Make sure the Enabled checkbox is checked and click "Save."

   

8. Return to webhook.site. This page will update automatically with data from your Notecard as it is received in Notehub. The data from your sensor is contained within the body attribute. Notice that Notehub provides you with a lot of information, by default. In the next section, we’ll look at using transformations to customize what Notehub sends in a Route.

   

Use JSONata to Transform JSON

Before you move on to adding a route to another external service, let's briefly explore using JSONata to transform the data Notehub sends to a Route. As mentioned above, Notehub provides a lot of information in each Route request. You may want to trim down what you send to your external service, or you might need to transform the payload to adhere to a format expected by that service. Either way, Notehub supports shaping the data sent to a Route using JSONata.

About JSONata

JSONata is "a lightweight query and transformation language for JSON data." According to their docs, JSONata was inspired by XPath 3.1, so if you’ve done XML querying or transformation in the past, JSONata will feel familiar to you. Even if you’re unfamiliar, the syntax is simple and the docs are comprehensive, so you’ll find JSONata a great, flexible way to shape Routes as you need them. The JSONata team even provides a browser-based playground, which you can use to see what your query will produce. Simply paste a payload into the JSON window at the left, write your query at the right, which the lower-right window will evaluate live.

Transform Your Data

Let’s try a simple query to the webhook.site route you created in the last section.

1. Navigate to the Routes page in Notehub and click the edit (pencil) icon for your Route.

   

2. In the "Transform JSON" drop-down, select "JSONata Expression"

   

3. In the JSONata expression text area, add the following query to select the temp and humidity from the body, create a location field that concatenates the tower_location and tower_country fields, and create a time field.

{
 "temp": body.temp,
 "humidity": body.humidity,
 "location": tower_location & ', ' & tower_country,
 "time": when
}

4. Click Save. Then, navigate back to your webhook.site url. As requests come in, you’ll see your custom, JSONata-transformed payload in the Raw Content section.

   

JSONata is simple, powerful, and flexible, and will come in handy as you create Routes for your external services. To explore JSONata further, check out the docs at JSONata.org.

Route to an External Service

Now that you’ve created your first Route and learned how to use JSONata to shape the data sent by a Route, you'll connect Notehub to an external service.

For this tutorial, you’ll connect your app to Initial State, a data streaming and visualization tool that's easy to set-up and configure for IoT applications.

Set a Serial Number On Your Notecard

This tutorial uses a Serial Number set on the Notecard to name the bucket of event data stored by Initial State. The Notecard Serial Number is an optional, customer-defined string that can be used to uniquely identify a single Notecard that belongs to a Fleet or Product.

If your Notecard doesn't already have an assigned Serial Number, set one by making a hub.set request to the Notecard and passing the Serial Number into the sn field.

{
 "req": "hub.set",
 "sn": "scranton-12"
}

Create an Initial State Account

If you don't have one already, create an Initial State account.

Find Your Initial State API Key

1. Once you've logged-in, you'll need your Initial State API Key in order to create a Route in Notehub. Find it by clicking on the Manage My Settings link on your dashboard.

2. You'll find your default access key under the Access Keys heading. Copy that key, or click the Create A New Key button if you want to use a new key.

Create Routes in Notehub

When using Initial State with Notecard-based projects, you'll create two routes. The first provisions the Device with Initial State and creates a bucket to hold event data. This route will only run once per session when Notehub sees a _session.qo file from the Notecard. The second runs each time your Notecard syncs and adds sensor data to the Initial State bucket.

Create a Provisioning Route for Device Onboarding

1. Open the Routes dashboard in Notehub and click the "Add Route" button.

2. Give the Route a name, like "Device Provisioning," and keep the Route Type default of "General HTTP/HTTPS Request/Response".

3. In the "HTTP Headers" dropdown, select "Additional Headers" and enter the following header names and values:

4. In the "Route URL" field, enter https://groker.init.st/api/buckets.

5. To ensure that this Route only runs once per session, change the "Notefiles" dropdown to "Select Notefiles" and enter _session.qo in the "Select Notefiles" input box. Click "Save."

6. In the "Transform JSON" field, select "JSONata Expression" and enter the following expression to set your DeviceUID as the bucketKey and Device Serial Number as the bucketName:

{
  "bucketKey":$substringAfter(device,":"),"bucketName":sn
}

7. To start a new session, restart your host, remove power, or send a card.restart request to the Notecard. After your Notecard initiates a new session, the provisioning Route runs and the bucket is created. Once created, the bucket displays on your Initial State dashboard.

Create a Route for Streaming Data

Next, create a Route for streaming data. This Route runs each time you sync data from the sensors.qo Notefile.

1. Open the Routes dashboard in Notehub and click the "Add Route" button.

2. Give the Route a name, like "Device Data" and keep the Route Type default of "General HTTP/HTTPS Request/Response".

3. In the "HTTP Headers" dropdown, select "Additional Headers" and enter the following header names and values. These are the same three headers from your provisioning Route, plus your Bucket Key, which is the DeviceUID. The [device] value is a replacement string that Notehub uses to swap in your DeviceUID as it executes the Route.

4. For "Route URL", enter https://groker.init.st/api/events.

5. In the "Notefiles" field, choose "Select Notefiles" and enter sensors.qo in the text input.

6. In the "Transform JSON" field, select "Flattened Body Keys/Values." This transforms each Note body into a flattened list of key-value pairs for processing by Initial State.

7. Change the "Rate Limit" to "Limited Request Rate" and set the "Requests per Second" value to 3, which is Initial State's limit.

8. Make sure "Enabled" is checked and click "Save."

9. Navigate back to your Initial State dashboard and click on your bucket in the left menu.

10. As data flows into Initial State from Notehub, the bucket dashboard updates with sensor data!

Build Data Visualizations

Initial State provides default tile visualization for each key (referred to as a "signal") you provide, but there's a lot more you can do to customize the dashboard to your liking.

Moving and Resizing Dashboard Tiles

1. To move dashboard tiles, click the "Edit Tiles" menu item at the top left of the screen.

   

2. Once it edit mode, you can click a tile corner to resize it, or drag it to a new location on the screen.

   

Modifying Tiles

Next, modify the default temp and humidity tiles.

1. While in edit mode, click on the temp tile. A modal appears with a number of options.

   

2. Change the "Tile Type" to a "Line Graph". Then, click on the settings icon next to the temp signal key. Set the label to "Temperature" and click the "Show Area Fill" checkbox. The sample graph at the top of the modal updates as you make changes.

3. Finally, change the "Path Style" to "Straight Line" and click the x icon to close the modal.

   

4. Next, click on the humidity tile, and repeat the steps above. Be sure to set the signal key label to "Humidity."

   

Adding New Tiles

Finally, add a new title. This one will use the temperature signal, and show the current temp on a thermometer with color thresholds.

1. While in edit mode, click the "Add Tile" menu item. An empty modal loads.

   

2. Set the Title to "Current Temp" and select "Gauge Chart" for the "Tile Type."

   

3. Set the "Gauge Style" to "Thermometer" and select temp.

4. Add three color threshold values with colors blue, green and red to indicate where the current temperature falls in the range. Set values for each threshold as you see fit. For instance, in the image below, the blue range is set to greater than or equal to -17 degrees centigrade, green greater than or equal to 10 degrees, and red greater than or equal to 28.

5. Set a "Minimum Value" and "Maximum Value" you expect to see from the sensor.

   

6. Click the x icon to close the modal. You now have a real-time view of data routed from Notehub to Initial State!

   

Congratulations, you’ve created your first Route and connected your Notecard app to an external service!