In this tutorial, you’ll learn how to connect your Notecard-powered app to an external cloud provider or service, Azure, 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 Azure IoT Central, a secure, scalabe 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 Azure account. Then, log in to your Azure Portal.
Once you're logged in, click the "Create a resource" link on the Portal dashboard.
On the "New" resource page, click the "Internet of Things" category and select "IoT Central application."
On the configuration screen, give your project a name and unique URL, choose your subscription, and select (or create) a resource group. Then, select a pricing plan and choose "Custom application" in the Template drop-down. Finally, click "Create."
The resources needed for your IoT Central application will be created in the background. When the deployment complete screen loads, click the "Go to resource" button.
On the Overview page for your IoT Central app resource, you'll see the "IoT Central Application URL" in the top-right corner. Click it to open your IoT Central Application.
In order to begin ingesting sensor data into your IoT Central application, you'll need to create a device template.
Click the "Device Templates" button on your IoT Central dashboard.
On the "Select template type" screen, select the "IoT device" custom device template button and click the "Next: Customize" button.
Give the template a name and click "Next: Review."
On the Review screen, click "Create."
The primary purpose of the device template is to create a set of interfaces, capabilities, and telemetry that IoT Central uses to describe physical devices that connect to it. As such, the first thing we need to create is a Capability model. Click the "Custom" button to create a capability model from scratch.
Next, create a component by clicking the "Add component" button on the main screen for your device template.
On the "Add a component interface" screen, click "Custom."
Now, let's create capabilities to represent telemetry data. Specifically, you'll create capabilities for the temperature and humidity values captured from the Adafruit BME680. On the Capabilities screen, click the "Add capability" link.
A form will appear on the screen asking for capability details. Enter the following values in the respective fields:
- Display name:
Temperature - Name:
temp - Capability type:
Telemetry - Semantic type:
Temperature - Schema:
Double - Unit:
ºC
- Click the "Add Capability" button and repeat this process for the humidity capability, using the values below:
- Display name:
Humidity - Name:
humidity - Capability type:
Telemetry - Semantic type:
Humidity - Schema:
Double - Unit:
%
When done, click "Save."
Finally, you'll want to publish your template so that devices can be associated with it. Click the "Publish" link on the top toolbar, and "Publish" again in the confirmation modal.
Now that you have a published template, you are ready to create a device bridge application to connect Notehub to your IoT Central Application.
The Azure IoT Central Device Bridge is a middleware application that runs in Azure and forwards messages from your IoT devices to your IoT central app. You can create your own middleware if you prefer, but we recommend the IoT Central Device Bridge because it provides a one-click deployment approach that includes a secure key-vault for storing your IoT Central SAS tokens and a simple Node.js application for ingesting data.
To create a device bridge instance for your app, visit the Device Bridge GitHub repository and click the "Deploy to Azure" button.
That link will take you to a Custom deployment configuration screen in the Azure Portal, where you'll need to select a subscription, resource group, and region for deployment.
Next, you'll need to provide a Scope ID and IoT Central SAS key for the middleware application to securely store. This allows it to route Notehub data into IoT Central. You can find this in your IoT Central application under Administration > Device connection. Copy the "ID scope" value and paste it into the "Scope ID" field on the "Custom deployment" screen.
Now, click on the "SAS-IoT-Devices" enrollment group in the "Device Connection" setting screen of your IoT Central app. Copy the SAS Primary Key and enter it into the "Iot Central SAS Key" field of the "Custom deployment" screen.
After you've added all of the required fields on the Custom deployment screen, click "Review + create." Then, click "Create" on the next screen.
The deployment will take a few moments, during which time you'll see, "Deployment is in progress" on the overview page. Once the deployment completes, click on the "Go to resource group" button.
Now you'll need to open the "Function App" created during the last step and install a number of dependencies. On your resource group dashboard, find your Function App and click its name to load it.
In the left menu, find the Development Tools group and click the "Console" menu item. This will load a sandboxed console environment in the browser.
At the prompt, type the following to install your application:
$ cd IoTCIntegration && npm installNote: The process will take a few moments to complete and you may see a few warnings.
After the installation finishes, restart the Function App by clicking the "Restart" button on the Overview page.
Finally, you'll need the Function URL of your Function App in order to create a route in Notehub. On your Function App dashboard, click the Functions menu item, then the name of your Function. Click the "Get Function Url" item on the top menu and copy the default Url for the next step.
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 "Azure Function" for the type. Then, in the Route URL field, paste the Function URL for your Azure Function App function.
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, which formats the incoming Note to conform to an structure that Azure IoT Central expects. Note that the
timestampfield is used to align the data ingested to IoT Central with the time it was captured on the Notecard, not when it was Routed. After adding this expression, click "Save".
{
"device": {
"deviceId": device
},
"measurements": {
"temp": body.temp,
"humidity": body.humidity
},
"timestamp": $fromMillis(when * 1000)
}
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: approving your Device in the IoT Central app.
If events are making it from the device bridge to your IoT Central app, the last step is to approve your device and associate it to your template.
On the Overview page for your IoT Central app resource, you'll see the "IoT Central Application URL" in the top-right corner. Click it to open your IoT Central Application.
Click on the "Devices" item in the left navigation. You should see your Notecard as an unassociated device under the "All devices" view.
Select your device and click the "Migrate" menu item above the device list.
In the modal, click the "Blues Notecard" device template and click "Migrate."
Your Notecard is now fully connected into your IoT Central application. Now, let's create some dashboards to visualize sensor data.
Once you've connected your Notecard to IoT Central, you'll want to confirm that the telemetry interfaces you set-up are being captured correctly. In your IoT Central application, click on the Devices left menu item, select your device and click on the "Raw data" link on your device page.
You'll see a listing of events ingested into IoT Central. If you see values under the Humidity and Temperature columns, you're ready to create some visualizations. If, on the other hand, those sensor values are showing up in the "Unmodeled data" column, make sure that the field names in your Notehub Route match the telemetry names you configured in your IoT Central device template.
To create visualizations, you'll start by creating a new dashboard. Click on the Dashboard left menu item, then click the "New dashboard" link.
Give the dashboard a name and click "Save."
Now let's add a simple line chart to show historical readings, over time. Click the "Edit dashboard" button on your new Dashboard.
In the "Add a tile" section, select your Device group, then your device.
In the Telemetry section, select "Humidity" and "Temperature" and click the "Add tile" button. A simple graph tile will appear to the right of the settings screen.
Click the box icon on the chart and select "3 x 3" to increase the chart in size.
Next, click the gear icon to open the chart configuration window. Change the Title. Change the display range to "Past 12 hours." If you want, you can also change the line colors for each sensor. When finished, click the "Update" button.
Click "Update" to save your dashboard. As readings come in from your Notecard, the graph will update automatically.
A graph is useful for viewing data over time, but it's often helpful to also have a view of the last sensor values we obtain. In this final section, we'll add cards to show the last known temperature and humidity values.
Select the dashboard you created and then click the "Edit dashboard" button.
In the "Add a tile" section, select your device group and device. Under "Telemetry" select Temperature and click "Add tile."
On the new tile, click the ruler icon to change the visualization and select "Last Known Value."
Click the gear icon and in the Configuration screen, change the Title to "Current Temperature."
Finally, click the box icon and change the size to "2 x 1." Now, you'll see a numeric tile with the last temperature, and the time since update.
Repeat this process for the humidity reading.
Click "Save" and revel in your data visualization skills!
Congratulations, you’ve created your first Route and connected your Notecard app to an external service!
