Route Tutorial

In previous tutorials you’ve learned about the Blues Wireless Notecard, and used it to collect data and send it to Notehub, the Blues Wireless cloud service.

One powerful feature of Notehub is routes, which allow you to forward your data from Notehub to a public cloud like AWS, Azure, or Google Cloud, a messaging platform like MQTT, or a custom HTTP endpoint. The tutorial below guides you through sending data to several popular services, and teaches you how to build data visualizations using that data. Select your service of choice below to get started.

Don’t see a cloud or backend that you need? Rest assured that Notehub is able to route data to virtually every provider. If you’re having trouble setting things up feel free to reach out in our forum and we can help you out.

Introduction

This tutorial should take approximately 30-40 minutes to complete.

In this tutorial, you’ll learn how to connect your Notecard-powered app to Datacake, and learn how to start creating simple visualizations with sensor data.

This tutorial assumes you’ve already completed the initial Sensor Tutorial to capture sensor data, saved it in a Notefile called sensors.qo and sent 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 Add Route.

   

4. Select the General HTTP/HTTPS Request/Response route type.

   

5. Give the route a name (for example, "Health").

   

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

   

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

   

8. Make sure the Enabled switch remains selected, and click Create Route.

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

More About JSONata

To learn more about JSONata, have a look at the Blues Wireless JSONata Guide.

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

In this section of the tutorial, you'll connect your app to Datacake, which is a low-code platform for creating cloud-based IoT applications and reporting dashboards.

Create a Datacake Account

If you haven't already, create your Datacake account. The free account option includes accessing data from two devices, unlimited team members, and unlimited workspaces.

Create a Device in Datacake

After completing the registration process, you will be redirected to your default workspace in Datacake. A workspace is a collection of products, devices, team members, and dashboard reports.

A product is comprised of one or more devices and includes your dashboards, database fields, and payload decoder for processing inbound data.

A device can be thought of as a literal hardware device (in this case, a Notecard). A device can be part of multiple products, but for the purposes of this tutorial you will associate a single device with a single product.

1. Navigate to the Devices menu and click on Add Device.

   

2. Choose the API device type, select New Product to create a new Datacake product to hold your data, and provide a Product Name.

   

3. Next, you need to associate your Notecard with this Datacake device. An easy way to do this is by using the Notecard's globally unique Device UID. Open Notehub and navigate to the Devices menu. Copy the relevant Device UID.

   

4. Back in the Datacake device creation screen, paste your Device UID in the Serial Number field and provide a Name to label the device.

   

5. In the next step, choose the Datacake plan most appropriate for your needs. You can always start with a free account and upgrade later.

   

Upon successful creation of your first device, you will be redirected to an overview of all your Datacake devices. Click on the newly-created device to open the device view.

Datacake doesn't dictate the structure of the data you send. Therefore, you need to configure a payload decoder to accept sensor data from Notehub and process it for your custom dashboard.

1. Within the device view, click on the Configuration tab to configure this device to communicate with Notehub.

   

2. Look for the Fields section and click on Add Fields. You will now create multiple database fields to hold data that comes from Notehub.

   

3. Create the following fields in Datacake that correspond to the sensor data sent from Notehub. Be sure to match the type with the data type you are sending.

   

4. With the database fields in place, it's time to configure the payload decoder. Scroll to the HTTP Payload Decoder section, which contains a code editor with syntax highlighting.

   Decoder is a JavaScript function that converts the payload from Notehub into a JSON object corresponding to the database fields you just created. The function will return a one-dimensional array of values pulled from the decoded object.

   Copy and paste the following function into the code editor, replacing any existing code.

   COPY
   function Decoder(request) {
      var data = JSON.parse(request.body);
      var device = data.device; // this is your Device UID
   
      var decoded = {};
      decoded.temp = data.body.temp;
      decoded.humidity = data.body.humidity;
      decoded.location = "(" + data.tower_lat + "," + data.tower_lon + ")";
      decoded.time = data.when;
   
      return [
         {
               device: device,
               field: "TEMP",
               value: decoded.temp
         },
         {
               device: device,
               field: "HUMIDITY",
               value: decoded.humidity
         },
         {
               device: device,
               field: "LOCATION",
               value: decoded.location
         },
         {
               device: device,
               field: "TIME",
               value: decoded.time
         }
      ];
   }
   

At this point, you have configured your Datacake device to receive arbitrary sensor data from Notehub and process it according to the database fields (data types) you specified. The next step is to create a Route in Notehub to securely transmit new events to Datacake.

Create a Route in Notehub

1. Before creating your Notehub route, you'll need to copy the provided HTTP Endpoint URL from Datacake.

   

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

   

3. Select the General HTTP/HTTPS Request/Response route type.

   

4. Provide a Route name, and paste in the HTTP Endpoint URL you copied earlier for the URL.

5. In the Notefiles dropdown, choose Select Notefiles and specify sensors.qo.

6. Click the Create Route button to save your new route.

As new sensor readings are delivered to Notehub, they will be actively routed to your Datacake device. Your next step is to create a dashboard report using the Datacake UI.

Build Data Visualizations

1. Navigate to the Dashboard tab in Datacake and click the toggle button to enable editing of your dashboard. Then click the Add Widget button to add your first widget.

   You have the option of building either a desktop or mobile dashboard. Either is fine for the purposes of this tutorial.

   

2. In the provided dialog, click to create a Map widget. You may optionally provide a title and custom styling, and then select the location field to populate the map. Before saving the widget, you may also specify a timeframe of data to display.

   

3. Proceed to add another widget to your dashboard, this time a chart that includes the temp field. You can experiment with labels, colors, and timeframes to achieve the look and feel you desire.

   

4. Back in your nearly-complete dashboard, click the duplicate icon to make a copy of your temp widget. Use the humidity field to complete the widget, but this time in the Kind dropdown, choose Bar Chart.

   

5. After re-sizing your widgets, your dashboard is complete! Be sure to also click the edit toggle to save your changes.

   

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

Looking for some next steps?

• Try diving into one of our detailed routing references.
• Follow the Notehub Walkthrough to get more out of Notehub.io.
• Learn how to set up a Notecard and Notecarrier-A as a standalone asset tracker.