Route Tutorial - Ubidots

Introduction

In this tutorial, you’ll learn how to connect your Notecard-powered app to an external cloud provider or service, Ubidots, 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 Ubidots, which provides data collection, analysis, and visualization tooling for connected IoT projects.

Create an Ubidots Account

If you don’t have one already, you'll first want to create a free 30-day Ubidots trial account. Note that if you attempt to sign up through the Ubidots home page, you will be asked to create either an Educational/Personal account (known as Ubidots STEM) or a Business account. The instructions provided here are specific to the free trial of the Business Account, in order for you to get access to Ubidots full platform scope.

Create a Device/Variable to Store Sensor Data

In Ubidots-speak, a device represents a data source that stores your sensor data. Likewise a variable is a set of data points stored within a given Ubidots device.

1. Once you've created your account, navigate to the Devices dashboard and add a new Blank Device.

2. Enter a name and an API label for the device. Please note that API labels for both devices and variables are case-sensitive. Notehub will not preserve casing in the Route URL though, so we recommend using lowercase strings for your labels.

3. Click on your newly-created Ubidots device and add a new raw variable.

4. Provide a name for your variable, again keeping in mind usage of lowercase text.

Note: If the naming of your devices and variables does not match perfectly with your Notehub route, Ubidots will create them automatically after receiving data from Notehub. So if you are not seeing data in Ubidots where you expect, navigate to your dashboard and look for orphan devices and/or variables.

Create a Route in Notehub

1. To send data to your Ubidots device and variable, you'll need your default token. Click on your profile and choose API Credentials. Copy your default token for the next steps.

2. Back in Notehub, open the Routes dashboard and click the Add Route button.

3. Give the Route a name, keep the Route Type default (General HTTP/HTTPS Request/Response), and choose to add Additional Headers. Add a header name of X-Auth-Token with a value of the default token you copied earlier.

4. For the Route URL, enter https://industrial.api.ubidots.com/api/v1.6/devices/[device-name]/[variable-api-label]/values, substituting in the device name and the variable API label you created earlier (without brackets).

5. In the Notefiles dropdown, choose Select Notefiles and specify sensors.qo. Then, in the Transform JSON option, select JSONata Expression and enter the following expression.

COPY
{
  "value": body.temp,
  "timestamp": when * 1000
}

Please note that we are using value to designate the key. Ubidots variable data is populated by the values you send. Ubidots uses timestamp as the exact date/time of the data point in Unix epoch time (in milliseconds).

6. Click Save and navigate back to your Ubidots dashboard. If everything is wired up correctly, the default data visualization will update with the temperature readings sent from Notehub.

Build Data Visualizations

The default line chart visualization provided by Ubidots is great for a quick read of your temperature sensor data. However, you can also add additional visualizations to your Ubidots dashboard.

1. Navigate to your main Ubidots dashboard. Click the + icon to Add new widget and choose Histogram. This widget will group your temperature data in a bar chart display so you can see which temperature ranges are most often recorded.

2. In the histogram configuration screen, click on Add Variables and choose the Ubidots variable you'd like to display.

3. Save all of the changes you've made and enjoy your first Ubidots data visualization!

4. Let's build one more data visualization. Again, click the + icon to Add new widget, but this time add a Thermometer.

5. Add the Ubidots variable as you did earlier, but this time before saving, look at the Aggregation method dropdown and choose which value you'd like to display.

6. Save your changes and enjoy your complete Ubidots data visualization dashboard.

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