🚀 Browse our open source reference applications to accelerate your IoT project!

Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
Sign In
Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
×
HomeGuides & Tutorials
Welcome
Collecting Sensor Data
Routing Data to CloudIntroductionCreate a RouteUse JSONata to Transform JSONRoute to an External ServiceBuild Data Visualizations
Building Edge ML Applications
Twilio SMS Guide
Fleet Admin Guide
Using the Notehub API
Notecard Guides
Guide Listing
Asset Tracking
Attention Pin Guide
Connecting to a Wi-Fi Access Point
Debugging with the FTDI Debug Cable
Diagnosing Cellular Connectivity Issues
Encrypting Data With the Notecard
Minimizing Latency
Notecard Outboard Firmware Update
Remote Command and Control
Serial-Over-I2C Protocol
Understanding Environment Variables
Understanding Notecard Penalty Boxes
Updating ESP32 Host Firmware
Using External SIM Cards
Using JSONata to Transform JSON
Rate this page  
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★

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, a data cloud like Snowflake, or a custom HTTP endpoint. The tutorial below guides you through sending data to several popular services, and teaches you how to build visualizations using that data.

Get started with:
AWS IoT AnalyticsAzure IoT CentralDatacakeGeneral HTTP/HTTPSGoogle Cloud PlatformInitial StateMQTTSnowflakeThingSpeakThingWorxUbidots

Don't see a cloud or backend that you need? Notehub is able to route data to virtually any provider. If you're having trouble setting up a route, reach out in our forum and we will 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 ThingSpeak, 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).

Create a Route

A Route is an external API, or server location, where Notes can be forwarded upon receipt.

Routes are defined in Notehub for a Project and can target Notes from one or more Fleets or all Devices. 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 familiarize yourself with Notehub's Routing capabilities.

  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.

    webhook.site service

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

    create a route button in notehub

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

    general https request route

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

    name notehub route

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

    url for notehub route

  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.

    name of the notefile

  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.

    notehub data in webhook.site

Use JSONata to Transform JSON

Before moving on to routing data to another external service, let's briefly explore using JSONata to transform the data Notehub routes.

As mentioned above, Notehub provides a lot of information in each Route request. You may want to trim down what you send to the 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 created in the last section.

  1. Navigate to the Routes page in Notehub and click View next to the Route you wish to edit.

    view a route

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

    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.

    transformed data routed to webhook.site

JSONata is simple, powerful, and flexible, and will come in handy as you create Routes for your external services. To explore JSONata further, visit our JSON Fundamentals guide.

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 ThingSpeak , a simple IoT analytics tool from MathWorks that provides simple dashboards and built-in visualizations for your projects.

Create a ThingSpeak Account

If you don’t have one already, first create a ThingSpeak account .

Create a Channel for Sensor Data

  1. Once you’ve created an account and have signed in, head to the Channels dashboard and click on New Channel

  1. On the New Channel screen, give your channel a name. Then, in each Field text box, add Temperature (C), Humidity, Location, and Time, respectively.

  1. Click Save Channel. You’ll be taken to your Channel dashboard, which includes some pre-built, but empty charts. The next step is to get these connected to your Notehub project with a Route.

Create a Route in Notehub

  1. To write to your ThingSpeak channel, you’ll first need your Write API key, which you can get from the "API Keys" tab. Copy your Write API Key for the next steps.

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

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

  2. Give the Route a name, and enter https://api.thingspeak.com/update.json for the URL.

  3. In the notefiles dropdown, select Select Notefiles and specify sensors.qo. Then, in the Transform JSON option, select JSONata Expression and enter the following expression. Be sure to change the api_key placeholder to match the value from your ThingSpeak channel.

{
    "api_key":"L7F5G2R4HAU3HUIO",
    "field1": body.temp,
    "field2": body.humidity,
    "field3": tower_location & ', ' & tower_country,
    "field4": when
}

Notice that we’re using field1, etc. to designate each key. ThingSpeak requires this structure when writing data to a channel, and anything beyond these values and api_key are ignored. field1 et al correspond to the field name you specified on the New Channel screen above.

  1. Click Create Route and navigate back to your ThingSpeak channel dashboard. If everything is wired up correctly, the built-in field-specific charts will update as new values come in.

Build Data Visualizations

ThingSpeak has built-in visualizations for time-series data, which makes it an easy tool to get started with. You can edit the built-in visualizations to add a title, change the visualization type, and more. To check it out for yourself, click the pencil icon in the top-right of each chart widget.

It’s also possible to add your own widgets, or build complex visualizations using MATLAB. Let’s take a look at creating a simple gauge for the temperature value.

  1. Click on the "Add Widgets" button on your channel dashboard.

  1. Next, click the Gauge card and click Next.

  1. Give the widget a name like "Current Temp", select "Field 1" as the data source, set the min to -20, max to 40, and use the plus sign button to add color-coded temperature ranges.

  1. Click Save and the widget will be placed on your channel dashboard.

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

Looking for some next steps?

  • Follow the Notehub Walkthrough to get more out of Notehub.io.
  • Visit the Blues Wireless Developer Forum to ask (and answer!) questions.
  • Get inspired by the tutorials on Hackster that utilize the Notecard and Notehub.
Can we improve this page? Send us feedbackRate this page
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
© 2023 Blues Inc.Terms & ConditionsPrivacy
blues.ioTwitterLinkedInGitHubHackster.io
Disconnected
Notecard Disconnected
Having trouble connecting?

Try changing your Micro USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up