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 Google Cloud Platform, 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.

   

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.

   

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

   

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.

   JSON
   COPY

   {
      "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, 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 Google Cloud Platform by using serverless Cloud Functions.

Create a Google Cloud Platform Project

As this is a Google service, you'll need a free Google account to access Google Cloud Platform (GCP).

Navigate to the GCP Console and create a new project, naming it whatever you'd like:

Create a Cloud Firestore Instance

GCP offers a variety of data storage mechanisms:

• Bigtable (a NoSQL database with low latency and replication for high availability)
• Datastore (a legacy NoSQL document database)
• Firestore (the "next generation" of Datastore)
• Memorystore (a managed Redis service)
• Spanner (relational database with unlimited scale and consistency)
• SQL (relational MySQL, PostgreSQL, and SQL Server databases)

For the purposes of this tutorial, we are going to use Firestore as it's most modern of all the data storage options and arguably the most developer-friendly. You are certainly welcome to use another option if already invested elsewhere.

1. From the main menu in the GCP Console, navigate to Databases > Firestore.

2. When you create a new Firestore instance, you're prompted to choose between "Native" and "Datastore" mode. You may read about the differences, but generally speaking, "Native" mode provides the richest set of features:

   

3. Next, choose a database location close to you for optimal performance. Click to Create Database.

4. You'll then be prompted to start a new collection to store data. Name your collection something memorable (e.g. "notecard-data").

   

5. Click Save and the creation of the Firestore collection is complete.

One advantage of using NoSQL databases is that we don't have to pre-define fields or data elements in the collection.

Create a Cloud Function

Google Cloud Functions are serverless functions that are hosted and executed in the Google Cloud. We will use a Cloud Function to populate the Firestore collection just created.

1. Navigate to the Serverless > Cloud Functions menu item and create your first function. (You may have to expand More Products at the bottom of the menu to see this option.)

2. Name your function whatever you like. You can check "Allow unauthenticated invocations" under Authentication if you don't want to authenticate a service account to use this function.

   Alternatively, you may want to Require authentication to require an authorization token to be sent along with the Notehub route request.

   

   Copy the provided URL as you'll need it when configuring the route in Notehub.

3. On the subsequent page, you may be prompted to enable Cloud Build API. Once that is enabled, return to the Create Function window.

4. At this point, you may choose the serverless runtime of your Cloud Function. There are a lot of language options available, but for the purposes of this tutorial we will use the Python 3.9 runtime. This will create two default files, main.py and requirements.txt.

5. While numerous pre-installed packages are available, in order to interface with Firestore we need the google-cloud-firestore package. Open the requirements.txt file and add:

   Text
   COPY

   google-cloud-firestore==2.11.1

6. Back in main.py we can create a new Python function. This function will accept JSON data from a Notehub route and populate the Firestore collection.

   Python
   COPY

   from google.cloud import firestore
   
   def add_data(request):
       request_json = request.get_json()
       db = firestore.Client()
       try:
           db.collection(u'notecard-data').document().set(request_json)
           return '', 200
       except:
           return '', 500

   In this function, the request parameter will be the JSON payload sent from the Notehub route. Here is an example payload that may be sent:

   JSON
   COPY

   {
      "temp": 35.8,
      "timestamp": 1614116793000
   }

7. Next, change the Entry Point to be the same name as the function and then click to Deploy.

   

8. It's time to test the cloud function! After deploying the function, click on the Testing menu and paste in the sample JSON payload provided above.

9. After it's parsed, click the Test in Cloud Shell button.

10. Provided the test was successful, navigate back to your Firestore collection and view the test data:

    

11. Finally, to make sure Notehub is authorized to use your new function, click Permissions in the top menu and then the Grant Access button.

    

12. In the dialog that comes up, type allUsers for New members, set the role to Cloud Functions > Cloud Functions Invoker, and then click the Save and Allow Public Access buttons.

    

Create a Route in Notehub

1. Back in your Notehub project, open the Routes dashboard and click the Create Route button.

   

2. Select Google Cloud Function as a route type.

   

3. Provide a name for your route and paste in the cloud function "Trigger URL" as the URL.

   

4. If you selected Require authentication when creating the Cloud Function, you will need to enter the Authorization Token for the appropriate service account.

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

   JSONATA
   COPY

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

6. Make sure your route is marked as Enabled and click the Create Route button.

Build Data Visualizations

Google Cloud Platform doesn't provide a means for directly generating data visualizations from Firestore. However, you can use BigQuery combined with Google Looker Studio to create a point-in-time dashboard.

1. In the GCP Console, navigate to Storage > Cloud Storage and create a bucket using the default settings. This cloud storage bucket will store an export of your Firestore data.

2. To create the export of your Firestore collection, use the Cloud Shell, which can be activated via the terminal icon in the top menu:

   

3. Run the following command in the Cloud Shell, substituting in the name of the storage bucket you just created along with the name of the Firestore collection:

   Text
   COPY

   gcloud firestore export gs://[bucket-name] --collection-ids=[collection-name]

4. Once the export is complete, head to BigQuery from the main menu. Add a new dataset in the active project, using the option of Google Cloud Storage as the source:

   

5. Next, let's add a table to the dataset. There are a lot of options in the dialog provided, but the most important ones to update are:

   • Create table from: should be "Google Cloud Storage"
   • Select file from GCS bucket: is the metadata file corresponding to the collection you exported, ending in [collection name].export_metadata.

   

6. With the dataset table created, head to Google Looker Studio to create the dashboard. Choose to create a Blank Report:

   

7. From the Data Connectors that next appear, choose BigQuery. Then choose the appropriate project, dataset, and table from your GCP instance.

8. With a blank Looker Studio canvas, you can now add individual data visualization widgets. Let's start with a bar chart:

   

9. Add a Breakdown Dimension of temp and we can see a quick visualization of recorded temperatures:

   

10. Next, add a Scorecard widget and choose the Max aggregation to show the maximum recorded temperature:

    

11. This provides you the start of a full data dashboard using Looker Studio which can optionally be themed to match a desired color scheme:

    

Next Steps

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

If you're following the Blues Quickstart, you're done! But we do have some suggestions for next steps:

1. Browse the Blues Accelerators to find purpose-built, free and open source IoT solutions.
2. Bookmark the Notecard API for quick reference.
3. Follow the Notehub Walkthrough to get more out of using Notehub.

At any time, if you find yourself stuck, please reach out on the community forum.