In this tutorial, you’ll learn how to connect your Notecard-powered app to an external cloud provider or service, AWS IoT Analytics, 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.
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.
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.
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.
Click the "Add Route."
Give the route a name (for example, "Health"), and select "General HTTP/HTTPS Request/Response" for the Route Type.
For the Route URL, use the unique URL you obtained from webhook.site.
In the Notefiles dropdown, choose "Select Notefiles" and enter the name of the notefile to monitor. For example, we used
sensors.qofor the sensor tutorial.
Make sure the Enabled checkbox is checked and click "Save."
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
bodyattribute. 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.
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.
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.
Let’s try a simple query to the webhook.site route you created in the last section.
Navigate to the Routes page in Notehub and click the edit (pencil) icon for your Route.
In the "Transform JSON" drop-down, select "JSONata Expression"
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_locationandtower_countryfields, and create a time field.
{
"temp": body.temp,
"humidity": body.humidity,
"location": tower_location & ', ' & tower_country,
"time": when
}
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.
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 AWS IoT Analytics, a secure, scalable IoT app platform that allows you to manage IoT devices, create dashboards and visualizations, and more.
If you don't have one already, first create an AWS account. Then, log in to your AWS Management Console.
You will need to specify a user, to which you can provide programmatic API access.
First, navigate to Identity and Access Management.
Click Access Management > Users from the left navigation bar.
Now, click Add user.
Give the new user a name (for example, "blues_notehub"). Ensure the Programmatic access checkbox is selected, as it is required for Notehub to speak to AWS IoT Analytics directly. Click Next: Permissions to continue.
Select the Attach existing policies directly button. Then, search for "awsiotanalytics", and select the AWSIoTAnalyticsFullAccess policy from the results.
Click Next: Tags. No tags are necessary, so click Next: Review.
Review your selection, and click Create user.
Click Show to view your Secret access key.
noteMake sure you save your secret access key. You will never be able to see its value again, and it is required when setting up the route through Notehub.
Before a Route can be created in Notehub, you will need to create an AWS IoT Analytics application, to which you shall route data.
As you work with AWS IoT Analytics, it's helpful to understand some terminology. Data flows into AWS IoT Analytics through a channel. Then, the data is updated as it flows through a pipeline. Your data will permanently reside in a datastore, and it will be queried with a dataset.
Navigate to the IoT Analytics Landing Page.
In the Quick create IoT Analytics resources panel, enter a resource prefix (for example "notecard_sensors"). Then, press Quick Create.
The corresponding resources will be created on your behalf; a channel, pipeline, data store, and data set.
At this point, it's time to send data into AWS IoT Analytics from Notehub. Not only will this confirm your Notehub route has been configured correctly, but it will also enable AWS IoT Analytics to infer field names from sample data.
With your IoT Application set-up and middleware configured, the next step is to create a Route in Notehub. Once you've completed this step, you'll have successfully connected your IoT app from sensor to cloud application!
Navigate to your project at Notehub.io.
Open the Routes dashboard in Notehub and click the "Add Route" button.
Give the Route a name and select "AWS IoT Analytics" for Route Type.
Fill in the AWS Region, AWS Access Key ID, AWS Key Secret, and AWS IoT Analytics Channel (i.e. the name of the channel you just created) fields with the values generated during AWS IoT Analytics application creation.
noteYou can find the AWS Region by viewing the details of any channel, pipeline, or datastore you just created in the AWS console. Each has an Amazon Resource Name (ARN) that includes the AWS region.
For example, in this ARN:
arn:aws:iotanalytics:us-east-1:7348937:pipeline/notecard_pipeline, "us-east-1" is the AWS region.
For the Notefiles field, select the "Select Notefiles" option and enter
sensors.qoin the Select Notefiles field.
For the Transform JSON field, select "JSONata Expression." Then in the JSONata Expression field, enter the following transformation and click the Save button.
{
"device": {
"deviceId": device
},
"measurements": {
"temp": body.temp,
"humidity": body.humidity
},
"timestamp": $fromMillis(when * 1000)
}
The AWS IoT Analytics API requires the following message format:
channelName is loaded from the configuration you supplied to Notehub. Notehub
sends each message individually, so the messages array contains one element.
messageId is used to uniquely identify each element of the array (always one
in this case), and is created on your behalf. Finally, the JSONata expression
crafted above, equates to the "value" associated with the payload key.
Navigate to the Events page, and wait for a sensor event to show up from your Device. Once it does, you can click on the event, then the "Route Log" tab to make sure everything is properly configured. If the response object contains a status of
200, then you are ready to move onto the final step: configuring the pipeline channel in your AWS IoT Analytics application.
Now that you have data available in AWS IoT Analytics, you need to configure a pipeline to transform the data into the values that should be held in your data store. Select Pipelines from the navigation bar on the left.
Click on the name of your pipeline from the list.
Click Edit to the right of the Activities heading.
AWS IoT Analytics will make use of the data routed from Notehub and automatically infer field names, which is less error prone than entering the field names manually.
After the pipeline has inferred the field names, you will need to select which of the incoming fields we would like to retain in your data store. Select the
deviceId,humidity,temp, andtimestampfields from the list and click Next.
Now that you have selected your fields, it's time to add them to an activity. Click on Add activity.
Select Select attributes from the message from the list of available transforms.
Under the Select message attributes section, select the fields
deviceId,humidity,temp, andtimestamp. Click on Update preview, validate the output, and click Save changes.
Now that the pipeline has been configured, you will be prompted to reprocess your messages. Before reprocessing, update the range of messages to reprocess.
noteThe default values in the range fields are backward. The date on the top is the
start time, and the date on the bottom is end time. Set the start time (top) to
00:00 and the end time (bottom) to 23:00 to reprocess all the messages you
have sent today.
Back at the IoT Analytics Landing Page, select Data sets from the navigation bar on the left.
Click on the name of your data set from the list.
Select Actions > Run Now to populate the data set. This makes your data available to other AWS services, such as AWS QuickSight.
As soon as the data set finishes processing, you will be able to see a sample displayed in a new section named Result preview will be displayed beneath the Delta window section.
Congratulations, your AWS IoT Analytics application is set up and ready to send data throughout the Amazon ecosystem!
Now that you have connected your Notecard to AWS IoT Analytics, you can leverage the power of the AWS Ecosystem and set up an AWS QuickSight Dashboard to visualize your data.
First navigate the AWS QuickSight page, and sign up for an AWS QuickSight account.
Choose the Standard Plan.
Configure your account. Match the value in the QuickSight region field to the region where your IoT Analytics account was created. Also, be sure to select the AWS IoT Analytics checkbox. Finally, give your account a name, and click the Finish button.
Now let's add a simple line chart to show historical readings, over time. Click the New analysis button from your AWS Quicksight Landing Page.
Initially, your IoT Analytics won't show up in Your Data Sets, so you need to click the New dataset button.
Select AWS IoT Analytics from the list of possible data sources.
Choose your data set from the available list ("notecard_sensors_dataset" shown below).
Review the "Finish data set creation" screen, and click Visualize.
Now, it's time to create a graph for viewing data over time, as well as gauge to view of the average of the values we have obtained. In this final section, we'll add cards to show multiple view of the temperature and humidity values.
After selecting your data set, you will see the analysis home screen.
Select the line chart icon from the Visual types section.
Drag both
tempandhumidityfrom the Field list in the left navigation bar to the Value box in the Field wells section, and dragtimestampfrom the Field list to the X axis box.
To better visualize your readings, select Aggregate: > Minute for
timestamp.
Time to add another visual to our dashboard. Click the Duplicate visual from the options on the visual itself.
Create a average temperature visual on your dashboard.
In the Field wells section, remove
humidityfrom the Value box, and removetimefrom the X axis box. Then, select the gauge chart icon from the Visual types section.
Select Aggregate: > Average for
tempin the Field wells section.
Now duplicate the temperature gauge, and change
temp (Average)tohumidity (Average). Then resize and arrange your visualizations, and you have completed your dashboard!
Congratulations, you’ve created your first Route and connected your Notecard app to an external service!
