Notehub Walkthrough
This walkthrough covers what Notehub is, how to get started, and how to utilize Notehub's rich feature set to accomplish your application's IoT objectives.
What is Notehub?
Notehub is available as a feature rich software as a service (SaaS) platform, implemented as Notehub.io. Notehub is also made available as open-source software (OSS), allowing you to implement your own UI and features tailored to your specific business needs.
Notehub.io provides a UI and a RESTful API which allow you to explore the vast collection of data and metadata created by the Notecard/Notehub infrastructure. Notehub also provides functionality for interacting with Notecards, securely routing data, managing Notecard and host firmware, as well as managing projects, fleets, and teams.
The remainder of this document details and describes the features and functionality of the Blues SaaS product, Notehub.io.
Features
- Detailed information about Notecard Devices, Events, and Sessions.
- Event routing to external services (such as AWS, Azure, MQTT servers, as well as most HTTPS endpoints).
- Over-the-Air (OTA) Notecard firmware and host firmware updates.
- Ability to view and modify Team, Project, Fleet, and Product settings.
- Quick and easy filtering of information by device, session, or event details.
- Ability to set cascading environment variables to enable scalable state updates to projects, fleets, and devices.
- Downloadable device information in JSON format.
Create a Notehub Account
-
Navigate your browser to Notehub.io, and you will be greeted with the sign-in screen.
-
Click the Sign up button at the bottom of the display. Alternatively, if you already have a GitHub account and you would prefer to sign up using GitHub, you may click the Sign in with GitHub button.
-
If you chose to create an account using email, enter your name, email address, and create a password. Then click Sign up.
Otherwise, if you chose to create an account using GitHub, then follow the prompts to authorize Notehub.
-
Verify your email address by clicking on the link in the email you receive from
support@blues.com
. The link will return you to Notehub.io and you will be ready to create your first project.
Create a New Project
Projects are core to the functionality of Notehub. They provide a way to organize fleets of devices, distribute firmware, organize teams, and provide team access controls.
A Project is composed of one or more identifiers called ProductUIDs. Each Project is created with an initial ProductUID, enabling you to associate your Notecard(s) to your Project as soon as it is created.
New projects may also be created by cloning an existing Notehub project.
-
Navigate to Notehub.io, and click on the Create Project button in the upper right corner.
-
The Create Project dialog will open.
-
Provide a name for the project in the Project Name input box.
-
Provide a unique identifier for the default ProductUID. In order to help ensure your ProductUID is unique, every ProductUID is prepended with the reverse domain name notation of your account email.
For example, if you signed up with
winston.smith@oceania.com
, then your product would take the form ofcom.oceania.winston.smith:your_product_uid
. -
By default, projects will be associated with the Billing Account tied to your Notehub account. If you wish to associate the project with a billing account other than your main account - for instance a company account - you can select it in the Billing Account dropdown.
-
Click the Create Project button.
Cloning an Existing Notehub Project
As an alternative to creating a new Notehub project from scratch, you may instead clone an existing project.
Follow these instructions to clone a project, noting that only high-level project details, fleets, and routes will be cloned (devices, events, and route logs cannot be cloned.)
-
Navigate to the Settings view of your Notehub project and click on the Clone Project button in the upper-right corner.
-
In the modal dialog provided, choose whether or not to include existing Fleets and Routes. You'll also be prompted to choose a Billing account, provide a name for the cloned project, and enter a new ProductUID.
-
Once you click the Clone Project button, the current project will be cloned and you will automatically be redirected to the new Notehub project.
Sending Data to Notehub from Notecard
Data is sent to Notehub (from Notecard devices or via the Notehub API) in the form of JSON objects called Notes.
This is an example of a Note containing arbitrary temperature
and humidity
data in the body
of the Note, along with metadata about the Note and the
device's location:
{
"event": "df9f5e04-7aa4-44d1-bd7f-068b6b576ffc",
"session": "6facb2b9-b4af-4790-bc70-a8c3b566c1f3",
"best_id": "dev:868050040247343",
"device": "dev:868050040247343",
"product": "product:com.blues.name:project",
"app": "app:911ee04e-cd6d-469a-8379-de05062aa5r3",
"received": 1670791362.736713,
"req": "note.add",
"when": 1670790603,
"file": "data.qo",
"body": {
"temperature": 24.56,
"humidity": 68.22
},
"best_location_type": "tower",
"best_location_when": 1670791362,
"best_lat": 41.83748,
"best_lon": -89.183298,
"best_location": "Shorewood Hills WI",
"best_country": "US",
"best_timezone": "America/Chicago",
"tower_when": 1670791362,
"tower_lat": 41.83748,
"tower_lon": -89.183298,
"tower_country": "US",
"tower_location": "Shorewood Hills WI",
"tower_timezone": "America/Chicago",
"tower_id": "310,410,17169,77315594",
"status": "success"
}
Notes are stored in Notefiles, which are also named JSON files. Notefiles are automatically created when a Note is first added, are persisted to Notecard flash, and are managed by the Notecard's synchronization policies with Notehub.
Notecard and Notehub work together to provide bidirectional wireless communication capabilities. In this diagram, Notes are sent from a host microcontroller (or single-board computer) to an arbitrary cloud endpoint.
The Notehub UI displays a list of Events that contains Notes, along with other session and environment-specific data sent automatically by the Notecard.
A hands-on example of the outbound data flow from Notecard to Notehub is available as part of the Notecard quickstart experience.
Notehub retains event data for 7 days after it is created.
Routing Data with Notehub
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/HTTPS endpoint. Routes are defined in a Notehub for a single project, and can target any fleet(s) and/or device(s). A Notehub project can have multiple routes defined and active at any one time.
Routed events will always come from one of a set of dedicated IP addresses
assigned to Blues Notehub servers. If needed, you may whitelist the IP range of
216.245.146.0
through 216.245.146.63
(or 216.245.146.0/26
in CIDR
notation).
- Available Route Types
- Available Route Tutorials
- Manually Routing Events
- Bulk Event Retries
- Automatic Retry of Failed Route
- Using Placeholder Variable Substitution/Interpolation
- Transforming JSON when Routing with JSONata
Available Route Types
There are a variety of different route types available in Notehub, exposing different configuration options depending on the service and protocol.
General HTTP/HTTPS Request/Response
Allows you to send Notecard events to external HTTP/HTTPS endpoints, including webhooks.
View the General HTTP/HTTPS Route Tutorial
AWS
Amazon Web Services (AWS) is the world's most comprehensive and broadly adopted cloud platform, offering over 200 fully featured services from data centers globally. Millions of customers—including the fastest-growing startups, largest enterprises, and leading government agencies are using AWS to lower costs, become more agile, and innovate faster.
View the AWS IoT Analytics Route Tutorial
Azure
The Azure cloud platform is more than 200 products and cloud services designed to help you bring new solutions to life to solve today's challenges and create the future. Build, run, and manage applications across multiple clouds, on-premises, and at the edge, with the tools and frameworks of your choice.
View the Azure IoT Central Route Tutorial
Google Cloud Function
Google Cloud Functions is a serverless execution environment for building and connecting cloud services. With Cloud Functions you write simple, single-purpose functions that are attached to events emitted from your cloud infrastructure and services. Your function is triggered when an event being watched is fired.
View the Google Cloud Platform Route Tutorial
MQTT
MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth.
Proxy for Device Web Requests
Allows you to send Notecard web requests to external HTTP/HTTPS endpoints, using the Notehub as a proxy.
ThingWorx API
ThingWorx is an ultra-versatile IoT software platform used for enterprise applications in all varieties of industries. Think of ThingWorx as the foundation on which to build a powerful tool that's perfectly matched to meet your business' needs.
View the ThingWorx Route Tutorial
RadNote RadResponder
RadResponder is a free radiological data management and sharing tool provided by FEMA in partnership with EPA and DOE. It allows you to manage your own events and exercises, upload data, perform basic assessment, and securely share data with regional partners and federal assets.
Snowflake
Snowflake enables data storage, processing, and analytic solutions that are faster, easier to use, and far more flexible than traditional offerings.
Twilio
Twilio allows developers to send text messages, and perform other communication functions using its web service APIs.
Slack
Slack is a cloud-based set of team collaboration tools and services.
S3 Archive
Amazon S3 or Amazon Simple Storage Service is a service offered by Amazon Web Services that provides object storage through a web service interface.
Datacake
Datacake is a multi-purpose, low-code IoT platform that requires no programming skills and minimal time to create custom IoT applications that can be brought into a white label IoT solution at the push of a button.
View the Datacake Route Tutorial
Available Route Tutorials
The provided Routing Data to Cloud tutorials walk you through routing Notecard data to a variety of big clouds and IoT platforms (including those listed above, and others):
- AWS IoT Analytics
- Azure IoT Central
- Datacake
- General HTTP/HTTPS
- Google Cloud Platform
- Initial State
- MQTT
- ThingSpeak
- ThingWorx
- Ubidots
There is also a Twilio SMS guide that demonstrates the ability to send SMS messages with the Twilio API, a Slack guide for routing data to Slack, and an Amazon S3 guide for archiving Notefile data to an S3 bucket.
Manually Routing Events
After a Notehub route is created, all future events that match the route parameters will be routed. However, you may wish to manually route an event to test a route, or to route an existing event after the Notehub route was created.
To manually route a single event, navigate to the event detail screen and click on the "Route event" button. You will be presented with a modal dialog of routes to use. All routing attempts will be captured in event's route log with a date/time stamp.
Bulk Event Retries
From the Events screen, you may choose one or more events and manually route them to one or more routes. Any events can be selected, regardless of whether or not they were previously routed successfully.
To route multiple events, navigate to the Events screen and select the event(s) you wish to route. In the modal dialog provided, specify whether you only want to retry routing events that previously failed or all selected events.
Each attempt at routing an event consumes one consumption credit, regardless of whether it's the first attempt or a retry.
Automatic Retry of Failed Route
If the routing of an event fails for any reason, you may wish to have Notehub automatically retry the route. To enable this feature, simply check the "automatic reroute on failure" box when creating or editing a Notehub route.
If enabled, Notehub will attempt to retry routing the event up to three times: at 5 seconds, 1 minute, and 5 minute intervals. All retry attempts will be captured in the route log with a date/time stamp.
Event routing is considered a "failure" if one of the following occurs:
- Notehub is unable to connect to the remote endpoint after 30 seconds.
- After connecting to the endpoint, Notehub does not receive a response after 30 seconds.
- Notehub receives an invalid HTTP response from the endpoint.
- A 5XX-level HTTP status code is returned from the endpoint.
Each attempt at routing an event consumes one consumption credit, regardless of whether it's the first attempt or a retry.
Using Placeholder Variable Substitution/Interpolation
If a Route setting (e.g. endpoint URL, MQTT topic, etc) needs to include data from a device, event, or environment variable, you can use string-based substitution placeholders when defining the Route.
Placeholder variables are denoted using a string inside of square brackets:
[string]
. A placeholder string either begins with a period .
(for event
attributes), a $
(for environment variables), or from a list of reserved
strings. Multiple placeholder strings may be used in a single Route field.
Variable substitution occurs after events have already been transformed by JSONata expressions. See Examples of Using Placeholder Variable Substitution for an example of using placeholder variables with JSONata transforms.
Placeholder substitutions will fail if the string being replaced contains square
brackets ([
or ]
). This applies to string data in Notes and environment
variable names.
Where to Use Placeholder Variable Substitution
Many of the open text fields in the Route creation process are supported. These include:
- URL
- HTTP Headers
- MQTT Broker, Port, Username, Password, Topic, and Client ID
- Twilio Routes: From Number, To Number, and Message
- AWS Routes: SQS FIFO and IoT Analytics Channel
Event Attribute Placeholders
Event attribute placeholders are identified by a .
immediately after the first
square bracket. Event attribute placeholders can substitute data from an event
visible in Notehub. Inner fields and array elements can be referenced using
standard JSON syntax.
For example, given the following (simplified) event in Notehub:
{
"best_id": "My Test Device",
"device": "dev:123456789",
"body": {
"temp": 24.5
}
}
The following event attribute placeholders could be used when defining the Route:
[.best_id]
// "My Test Device"
[.device]
// "123456789"
[.body.temp]
// 24.5
Environment Variable Placeholders
Environment variable
placeholders are identified by a $
immediately after the first square bracket.
For example, [$phone_number]
or [$_contact_name]
.
Reserved Placeholder Strings
Certain reserved placeholder variables allow you to substitute in Notecard- or event-specific data:
- [device] - Replace this portion of the string with the Notecard's DeviceUID.
- [device_no_prefix] - Same as above, but strips the
dev:
prefix from the DeviceUID. - [product] - Replace this portion of the string with the ProductUID to which the Notecard is associated.
- [product_no_prefix] - Same as above, but strips the
product:
prefix from the ProductUID. - [sn] - Replace this portion of the string with the Device Serial Number.
- [file] Replace this portion of the string with the full Notefile name (e.g. data.qo).
- [filebase] Replace this portion of the string with the name of the Notefile to the left of the first non-alphanumeric (and non-underscore) character.
For example, an event from a DeviceUID of "dev:1234" using this endpoint URL:
https://webhook.site/89bd3bc4-f8bb-4f7d-b888-3683af6da958/[device]
...will resolve to the following URL when routed:
https://webhook.site/89bd3bc4-f8bb-4f7d-b888-3683af6da958/dev:1234
Unrecognized Placeholder Strings
Any string inside square brackets that isn't syntactically valid won't be
replaced. For example, [This text in brackets]
would be left as-is. However,
if a referenced field is valid, but not available for substitution (i.e. the
field is missing from the event) the placeholder string would be replaced by an
empty string.
For example, given the example event above and the following endpoint URL:
https://webhook.site/123456/[tower_location]
...will replace [tower_location]
with an empty string. This is because
tower_location
is a syntactically valid variable, but is absent from the
provided event:
https://webhook.site/123456/
Examples of Using Placeholder Variable Substitution
-
Replace a portion of an endpoint URL with the DeviceUID:
https://test.com/[.device]/ // resolves to: https://test.com/dev:1b7c56aa-1301-4142-accc-a69e1b077146/
-
Replacing a portion of a Twilio API endpoint with the Twilio Account SID, set in an environment variable:
https://api.twilio.com/2010-04-01/Accounts/[$TWILIO_ACCOUNT_SID]/Messages.json // resolves to: https://api.twilio.com/2010-04-01/Accounts/1234567890/Messages.json
-
Substituting the
To
,From
, andBody
SMS variables in a Twilio route with variables from thebody
of an event:https://api.twilio.com/2010-04-01/Accounts/1234567890/Messages.json?To=[.body.phoneTo]&From=[.body.phoneFrom]&Body=[.body.message] // resolves to: https://api.twilio.com/2010-04-01/Accounts/1234567890/Messages.json?To=%2B11234567890&From=%2B10987654321&Body=Hello%20World%21
-
Using a JSONata expression to conditionally transform the body of a Twilio SMS. In this scenario, the
Message
field of the Twilio route would be set to[.body.twilioMessage]
(wheretwilioMessage
is an arbitrary variable that is not present in thebody
of the event prior to the transform):// JSONata expression { "body":{ "twilioMessage": $contains(body.text, "USB" )? "USB string found" : "USB string not found" } }
-
Replacing authentication header values in HTTP Header fields:
Authorization: Basic [$TWILIO_BASIC_AUTH_HEADER] // resolves to: Authorization: Basic am9obkBleGFtcGxlLmNvbTphYmqyusa=
Transforming JSON when Routing with JSONata
JSONata expressions allow you to transform Notecard-generated JSON into a new structure before it's routed to an external service.
Many Notehub Routes provide a setting to apply a JSONata expression to relevant Notes under the Data tab:
You can also apply a JSONata expression to all events in a project. This allows
for project-wide application (and consistency) of transforms to the body
and/or payload
, in lieu of copy-pasting across individual routes. This feature
is available in the Settings for each Notehub project:
Learn more about JSONata in our guide on Using JSONata to Transform JSON.
Data Notehub Appends to Events
Notehub automatically appends a variety of metadata fields when it creates an event from an incoming Note. All fields that Notehub adds are eligible for routing.
best_id
The best identifier for a device. Notehub sets this to the device's serial number if one has been defined.
{
"best_id": "tracker1",
...
}
And to the device's DeviceUID if no serial number is available.
{
"best_id": "dev:1234567890",
...
}
best_location
Notehub appends the best-known location of a device to all events in the following format.
{
"best_location_type": "gps",
"best_olc": "86JQQ972+FQ2H",
"best_when": 1674749529,
"best_lat": 42.2636375,
"best_lon": -84.24809765624,
"best_location": "Lansing MI",
"best_country": "US",
"best_timezone": "America/Detroit",
...
}
Devices in Notehub may have locations retrieved by different means. For example, a device may have a GPS/GNSS location, a triangulated location, and a location of the cell tower that most recently handled a cellular request.
Notehub uses a two-step process for determining which of these locations is "best". First,
Notehub checks whether any of the available locations are stale. By default, Notehub considers
any locations over three days old as stale, but you can override this behavior using the
_stale_gps_mins
, _stale_tri_mins
, and _stale_tower_mins
environment variables.
After Notehub has excluded any stale locations, Notehub next selects the best location in
the following order: GPS/GNSS, triangulated, cell tower. Notehub sets the
best_location_type
field to "gps"
, "triangulated"
, or "tower"
to indicate which
location it selected, and which location it used to populate the remaining best_*
location fields.
transport
Notehub automatically appends the type of radio (or source) used to create/send the associated event. Possible values include:
Value | Source |
---|---|
api:http | Notehub API |
cell:emtc | Cellular (LTE-M) |
cell:gsm | Cellular (GSM) |
cell:lte | Cellular (LTE Cat-1) |
cell:nbiot | Cellular (NB-IoT) |
hub | Generated by Notehub (e.g. a System Notefile) |
lorawan:ttn | LoRaWAN via The Things Network |
ntn:skylo | Starnote for Skylo |
ntn:udp | UDP via NTN simulation mode |
webhook:myWebhook | Generated by a webhook or simulator |
wifi | Wi-Fi |
tri_location
If available, Notehub appends the last-known triangulated location of a device to all events in the following format.
{
"tri_when": 1706126581,
"tri_lat": 30.404954,
"tri_lon": -97.721145,
"tri_location": "Wells Branch TX",
"tri_country": "US",
"tri_timezone": "America/Chicago",
"tri_points": 14,
...
}
You can learn about how to enable triangulation on a Notecard in Using Cell Tower and Wi-Fi Triangulation.
where_location
If available, Notehub appends the last-known GPS/GNSS location of a device to all events in the following format.
{
"where_olc": "86JQQ723+WQ22",
"where_when": 1704717310,
"where_lat": 42.7522525,
"where_lon": -84.74562109375,
"where_location": "Grand Ledge MI",
"where_country": "US",
"where_timezone": "America/Detroit",
...
}
You can learn about how to enable GPS/GNSS tracking on a Notecard in Working with GPS on the Notecard.
Sending Data from Notehub to Notecard
Not only does Notehub receive communications from the Notecard, but it is also capable of sending communications back down to the Notecard. This takes two forms:
Queue Inbound Notes
Inbound Notes are Notes that start from a cloud app or external service and propagate down to the Notecard.
This data is called "inbound" because it originates somewhere else and is synchronized to the Notecard. In other words, it is "inbound" from the perspective of the Notecard. Once synchronized, a host can retrieve this data from the Notecard and respond accordingly.
A typical use case of inbound Notes is to remotely communicate with (and/or control) a device. See our Remote Command and Control guide for more information.
Again, Notecard and Notehub work together to provide bidirectional wireless communication capabilities, both outbound (as documented above) and inbound (from the cloud to your microcontroller or single-board computer):
Inbound Notes in Action
You can use either the Notehub UI or Notehub API to send Notes to your Notecard. Once you've added a Note to Notehub, you'll learn how to retrieve Notes with simple JSON requests.
If using Notecard LoRa, all inbound Notes (sent via the UI or API), must use Note templates.
Running the following two commands will set up the necessary template to complete the tutorial below. You can learn how to create your own inbound Note templates in the Notecard LoRa Quickstart.
{"req":"note.template","file":"data.qi","port":50,"format":"compact","body":{"key1":"50"}}
{"req":"hub.sync"}
Compose via the Notehub UI
Navigate to Notehub.io, and select your project to see the Device list.
Click on the check mark next to your Device, and then click on the Note button.
You will see a window for adding a Note meant for the selected Device. Select
data.qi
from the Select Notefile drop-down menu.
Notehub will place Notes you create in a Notefile called data.qi
. The .qi
extension means that the file is an "inbound queue," or a queue that originates
in Notehub and is synchronized with the Notecard.
Copy and paste the following object into the Note JSON section:
{"key1":"val1"}
Now, click the Add Note button, and Notehub will queue the Note to be sent to your Notecard during the next sync operation.
To confirm your note was successfully enqueued by Notehub, click on Events in the sidebar and you should see your Note at the top of the table.
Compose via the Notehub API
Sending data via the Notehub UI may be useful for a human, but sending data programmatically through the Notehub API is how your cloud services will communicate with your Notecard and, ultimately, your product.
Find your ProjectUID and DeviceUID
First you'll need to gather your project and device identifiers so that Notehub knows where to send the data. Copy and paste this request into the in-browser terminal:
{"req":"hub.get"}
{
"outbound": 60,
"mode": "periodic",
"host": "a.notefile.net",
"product": "com.your-company.your-name:your_product",
"device": "dev:000000000000000"
}
The string in the device
field is your
DeviceUID: dev:000000000000000
. Save this
value for later.
Next, you need the string identifier assigned to your Notehub project, the
ProjectUID. Your ProjectUID can be found in
the Settings tab of your project in Notehub (e.g.
app:00000000-0000-0000-0000-000000000000
). Be sure to copy the ProjectUID and
not the ProductUID!
Obtain a Bearer Token
Before sending Notes to the Notehub API, you need to obtain an authentication
token with a request to the /oauth2/token
endpoint, like so:
curl -X POST
-L 'https://notehub.io/oauth2/token'
-H 'content-type: application/x-www-form-urlencoded'
-d grant_type=client_credentials
-d client_id=your-client-id
-d client_secret=your-client-secret
The client_id
and client_secret
values can be obtained from the Settings
of your Notehub project, under Programmatic API access. Consult the
Notehub API Introduction if you run
into any issues.
If you're using Linux or macOS, you should have a tool called cURL installed and accessible from a terminal application to send API requests to the Notehub API.
If you are a Windows user, you can either use the Windows Subsystem for Linux, or follow this guide to install cURL on your Windows PC.
Another option is to use a tool like Postman to send these requests.
In response to the request to /oauth2/token
, the Notehub API will return a
JSON object with an access_token
in its body. You'll need that token for the
next step.
Queue your Note
Now, you can send another request to queue a Note. Copy and paste the following
command into your terminal, and be sure to replace access_token
, projectUID
,
and deviceUID
fields with your specific values:
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/data.qi'
-H 'Authorization: Bearer <access_token>'
-d '{"body":{"key1":"val1"}}'
- The
-X POST
option tells cURL to make a POST request instead of its default GET request. - The API URL is specified by
-L 'https://api.notefile.net/'
. -H 'Authorization: Bearer <access_token>'
must include a token to authorize the request.- The
-d '{...}'
option must be filled in with thebody
of the Note you are sending.
If all goes well, you will receive {}
in response. Otherwise, you will receive
a JSON object containing an "err":
key, along with a message describing the
error.
Sync your Note to the Notecard
Once you've queued a Note on Notehub, the Notecard will need to sync again with the service in order to obtain the Note and place it in internal storage.
Copy and paste the following request into the in-browser terminal to sync the data from Notehub onto the Notecard.
{"req":"hub.sync"}
{}
Once hub.sync.status
reports a completed time, the sync is complete.
{"req":"hub.sync.status"}
{
"time": 1615585299,
"completed": 4
}
Read your Note from the Notecard
Your Note should now be on your Notecard! To confirm, copy the following request into your in-browser terminal. The request looks at the Notefile in "files", and determines whether there are changes.
{"req":"file.changes","files":["data.qi"]}
{
"info": {
"data.qi": {
"total": 1
}
},
"total": 1
}
Read the Note out of the Notefile by sending the following request to the Notecard:
{"req":"note.get", "file":"data.qi"}
{
"body": {
"key1": "val1"
},
"time": 1589309597
}
You should see the Note you sent from Notehub as the response to your request.
Notes synced from Notehub to the Notecard are held in storage until explicitly deleted. This extra step ensures Notes queued on the Notecard are not accidentally deleted just because they were read out.
In software engineering terms, note.get
performs a peek of the queue by
default, but will perform a pop if you specify "delete":true
.
{"req":"note.get", "file":"data.qi","delete":true}
{
"body": {
"key1": "val1"
},
"time": 1589309597
}
Sending the file.changes
request at this point should tell you that there are
no more pending notes inside of data.qi
.
{"req":"file.changes","files":["data.qi"]}
{
"info": {
"data.qi": {}
}
}
Update Environment Variables
In IoT applications, products often require configuration variables or settings that can be used on an end device, but then be managed and updated once the product is deployed. In addition, these products often need the ability to manage these values at multiple levels, from the device to a fleet or even an entire product and all of its deployed devices.
Environment variables are a Notecard and Notehub feature that enable settings synchronization that "just work," with no special setup or configuration needed. These variables are key-value pairs, can be set in Notehub and propagate to devices in a project or fleet, or set on the Notecard directly using the same synchronization mechanism used for Notes and Notefiles.
Learn more about the use of environment variables in our guide on Understanding Environment Variables.
Exporting Data
Notehub provides the ability to export data from your projects in JSON or CSV format. Follow these instructions to export your data:
-
Within your Notehub project, select Events from the left navigation bar.
-
(Optional) Apply filters to your data, such as adding a time range, or selecting a device or Notefile name.
-
Click the Export button in the top-right corner of the screen.
-
In the dialog, select the event fields you wish to export using the Fields to Export dropdown. (If you wish to export all fields pick the Select All option.)
-
For Export Format select either JSON or CSV, and then click Export.
If all went well, your browser should immediately start downloading your data in JSON or CSV format.
-
Exporting data uses one consumption credit per event. See Blues pricing for more information.
-
Exporting data is also available through the Notehub Event API.
Add Collaborators to a Project
If you wish to delegate administration of your Project, share your Project with other developers, or provide read-only access, you can do so by adding team members. Members are easy to add and can be granted varying levels of access explained below.
To add new members to your Notehub project:
-
Select Settings > Members from the left navigation bar.
-
Click the Invite members button.
-
Enter the email address(es) of the new members and choose the appropriate role from the dropdown provided.
Collaborator Roles
Team members can take the role of Owner, Developer, or Viewer. The permissions granted to each role are defined as follows:
owner | developer | viewer | |
---|---|---|---|
ProductUIDs | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Devices | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Fleets | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Events | |||
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Notes | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Notefiles | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Routes | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Route Details | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ❌ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Favorites | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Settings | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Members | |||
Create | ✅ | ❌ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ❌ | ❌ |
Delete | ✅ | ❌ | ❌ |
Environment Variables | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Firmware | |||
Notecard | |||
Read | ✅ | ✅ | ❌ |
Deploy | ✅ | ✅ | ❌ |
Host MCU | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ❌ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Deploy | ✅ | ✅ | ❌ |
Invite Blues Support to a Project
If you require support from the Blues Support team, you may need to share access to your Notehub project. Once shared, you can remove Blues Support access at any time.
Follow these instructions to grant access to your Notehub project:
-
Within the main menu of your Notehub project, click on Members under the Settings heading.
-
Click on the Invite Support button in the upper-right corner of the Members view.
-
In the modal dialog that appears, select the reason for granting this access along with a date range for expiration of access.
-
Upon clicking Send, the Blues Support team will immediately be granted access to your Notehub project. At any time, you may use the Remove button to revoke access (otherwise access will automatically expire on the date listed).
Create a New Fleet
Fleets are a useful tool for grouping and managing devices in a Project. In their simplest form, fleets provide a filtering mechanism for a set of devices. Perhaps more importantly, fleets provide an intermediate level for the creation and application of environment variables.
Fleets may also be managed via the Notehub API.
-
Select Fleets from the left navigation bar.
-
Click the Add fleet option, in the upper right corner.
-
Give the new fleet a name in the Fleet name field.
-
Click Add fleet.
Add a Device to a Fleet
Upon first connection to Notehub.io, a device is associated with the default fleet of the Notehub project.
The concept of a fleet in Notehub.io is very flexible and can be adapted to
meet most use cases. The standard fleet scheme is to consider the
default fleet, My fleet
, a temporary holding place. Then, once a new device
appears in the default fleet, it can be triaged and properly associated with a
production fleet or whatever nomenclature you choose to use.
Devices may also be added to fleets via the Notehub API.
-
From the Devices menu, select the device(s) you would like to assign to one or more fleets and click the Move button.
-
Choose the fleet(s) and click Move to save the assignments.
Manage Notecard Firmware
Notehub has the ability to manage the firmware running on your Notecards as well as your host MCU. You can easily choose between the available firmware and deploy to one or more devices.
Along with using the Notehub UI to manage firmware releases, the Notehub API provides methods for initiating and monitoring both Notecard and host firmware updates.
Make sure you read and understand the Blues Firmware Release Policies and Procedures before updating Notecard firmware.
Notecard LoRa does not support management of host or device firmware updates via Notehub.
Deploy Firmware
-
Select Devices from the left navigation bar and select a device from the list of devices in the Notecard Firmware tab.
-
Select Update from the available options.
-
Select the firmware you wish to apply from the list of available firmware, and click Apply.
-
Confirm you wish to update the Notecard firmware.
-
Now that you have selected your firmware, you will see it in the Requested Version field.
-
The next time the Notecard syncs with Notehub, it will begin the download and installation process. No further action is needed on your part as the Notecard will update itself after it downloads the binary. You can view the current status of the update any time in the DFU Status field, by navigating to the device details and clicking on the Notecard Firmware tab, or by using the Notehub API to get the status of the DFU.
Manage Host Firmware
Notehub has the ability to manage host firmware for whole projects or individual devices. You can use Notehub to upload and deploy the custom firmware for your host MCU.
Along with using the Notehub UI to manage firmware releases, the Notehub API provides methods for initiating and monitoring both Notecard and host firmware updates.
Notehub supports two methods of updating host firmware:
- Notecard Outboard Firmware Update (supported by most modern STM32- and ESP32-based microcontrollers)
- IAP Firmware Update
The Notecard LoRa does not support management of host or device firmware updates via Notehub.
Notecard Outboard Firmware Update allows the Notecard to utilize new capabilities of modern MCUs to perform firmware updates "from the outside", and not involve the firmware running on the MCU. It can update firmware regardless of RTOS or language, and can be used to switch between them, even modifying flash memory layout and partitioning any time after-the-fact, at the developer's discretion.
Information on enabling Notecard Outboard Firmware Update can be found in this guide.
IAP (In Application Programming) is a more traditional form of DFU that performs firmware updates while the program is running.
Read more about IAP vs ISP (In System Programming) in this kanda.com article.
Upload Host MCU Firmware
-
Select Settings > Firmware from the left navigation bar and click Upload Firmware.
-
Upload your new firmware binary with the form provided.
Deploy Firmware
-
Select Devices from the left navigation bar, select a device from the list of devices in the Host Firmware tab, and then click Update.
-
Select the firmware you wish to apply from the list of available firmware, and click Apply.
-
Consult the Host Firmware Update Requests section of the Notecard Walkthrough to configure how Notecards process DFU requests.
Configuring Your Billing Account
Every new Notehub account is automatically assigned to the free Essentials Edition. In this subscription tier, event egress (i.e. routed data) is limited only by available Consumption Credits. Accounts in the Essentials Edition are automatically topped-up to 5,000 Consumption Credits each month.
Many applications, however, will require additional Consumption Credits for Notehub services, priority support, and/or advanced features available through a variety of subscription tiers. You can manage all of these purchases in your billing account.
From the account menu at top-right, select Billing to access your billing account.
From the billing account section, you can purchase Consumption Credits, view credit usage, purchase history, add members to your account, and add any information needed on your invoices and receipts.
Adding Consumption Credits
To purchase Consumption Credits, you'll first need to add a payment method to your account. Once you've done so, select the amount of credits you wish to add and click the Purchase Credits button.
For volume discounts on Credits, consult the volume discount tiers table at the bottom of the credits page.
Confirm the payment method and amount and click Pay now to complete the purchase.
Once purchased, Consumption Credits are available for immediate use in any project associated with your billing account.
Configuring Credit Auto-Recharge
To ensure that your projects always have credits available, you can use the Set up Auto-recharge section to enable or disable auto-recharge, as well as the balance below which to trigger the purchase of additional Credits, as well as the number of Credits to purchase when below the threshold.
Adding Billing Account Members
From the Member tab, you can add additional members to your account with permission to create projects in the account, manage, or administer the account on your behalf. Invited members will receive an invitation email and will need to create a Notehub account if they do not already have one.
Notehub Subscription Tiers
Blues is focused on providing a simple pricing model that matches your stage of development and business model.
-
For prototyping and low-scale device deployments we offer the Essentials Edition. This is a $0/month offering that includes routing and event management, and is limited only by your usage of Consumption Credits.
-
Projects that start to scale will benefit from access to the Development Edition. This edition provides access to advanced mapping and alerting features of Notehub, Amazon S3 integration, and also provides 5,000 Consumption Credits per device per month.
-
Our customers who are scaling with 100s of devices will find the Analyze & Scale Edition most useful. This edition includes all features of the Development Edition, plus a Snowpipe integration and Snowflake-powered data analysis features.
-
The Enterprise Edition is for companies with specific requirements for multi-project controls, centralized billing and administration, and compliance needs.
Additional information about all of the Notehub subscription tiers is available on the Blues pricing page.
Understanding Consumption Credits
Consumption Credits (CCs) are used to pay for Notehub services such as event routing, Notehub API usage, and web requests. Notehub billing accounts are automatically "topped-up" to 5,000 CCs every month, and each Notecard purchased and connected to Notehub includes a one-time 5,000 CC credit. Additional CCs may be purchased through Notehub.
With the Consumption Credit model, you only pay for what you use:
- Sending an Event to Notehub: 0 CC (Free)
- Routing an Event from Notehub: 1 CC
- Pulling an Event via the Notehub API: 1 CC
- All other Notehub API requests: 0.001 CC
More information about Consumption Credits is available on the Blues pricing page.
Viewing Historical Consumption Credit Usage
To view your history of Consumption Credit usage, navigate to the Billing settings for your Notehub account. Click on the Usage tab to see a list of Notehub projects, how many Consumption Credits each has used during the date range specified, and a link to see detailed usage events.
Managing Connectivity Assurance
When a Notecard runs low on data, Connectivity Assurance will automatically add data to the Notecard SIM's data plan.
Connectivity Assurance is enabled by default if the Notehub Billing Account associated with the Notecard has a payment method on file. When a Notecard reaches 100MB of remaining data, Connectivity Assurance will add 500MB of data to the Notecard's data plan. The additional 500MB of data costs $10 for North America Notecards (e.g. NBNA and WBNA) and $15 for international Notecards (e.g. NBGL and WBEX).
If the Notecard SIM's data plan runs out of data due to an invalid or missing payment method (or if Connectivity Assurance is disabled) the data flow from the Notecard will be paused.
Disabling Connectivity Assurance
Connectivity Assurance can be disabled at the following levels:
Disabling Connectivity Assurance at the Billing Account Level
In Notehub, navigate to the Billing menu, select the Information tab, and uncheck the Connectivity Assurance checkbox.
If Connectivity Assurance is disabled for the Billing Account, it cannot be overwritten and re-enabled at the Project or Device levels.
Disabling Connectivity Assurance at the Project Level
Within a Notehub project, navigate to the Settings menu and uncheck the Connectivity Assurance checkbox.
If Connectivity Assurance is disabled for the Project, it cannot be overwritten and re-enabled at the Device level.
Disabling Connectivity Assurance at the Device Level
Within a Notehub project, navigate to the Devices menu, select a Device to edit, navigate to the Summary tab, and uncheck the Connectivity Assurance checkbox.
Adding Contact Information
Contact information for a Notehub project appears in the device JSON and is queryable and updatable using the Notecard API card.contact.
Select Settings from the left navigation bar and add your contact information in the Contacts form.
Add a Favorite
Favorites are a way of both saving and organizing query filters you plan on reusing regularly.
By default, the Devices, Fleets, and Events views provide a list of every device, fleet, or event, respectively. To help refine these lists into useful information, a filter box is provided. These filters can become complex and difficult to enter, and you may find you are constantly creating the same filters as part of your workflow.
-
To facilitate a more efficient workflow, there is a Save button located at the bottom right of your filter box.
-
When you click the button, you will be prompted to add a new favorite.
-
Type in the name for your Favorite in the box provided, click Save, and the favorite will appear in your Favorites list.
Creating a Device Dashboard
Deployed IoT devices often provide a QR code that users can scan for device configuration. For example, the Blues Airnote has a printed QR code that users can scan to change an Airnote's settings, and to view a dashboard of device data.
Using Notehub you can create your own dashboard URLs for printing on devices via QR codes. Let's look at how it works.
How It Works
Notehub provides a domain, qrgo.org
, that redirects requests for qrgo.org/id/[deviceUID]
to a dashboard URL that you can configure. This workflow allows you to print QR codes that
point to qrgo.org/id/[deviceUID]
on physical devices, and configure the final resolved
URL in Notehub.
This workflow also gives you the ability to change your dashboard URLs anytime—even after you deploy your devices. Let's look at how to set a dashboard URL for your Notehub project.
How to Set Up a Device Dashboard
-
Within your Notehub project, select Settings from the left navigation bar, and scroll down to the Device Dashboard URL.
-
Enter a URL in the Edit Device Dashboard URL textbox.
In the URL you can use [device]
as a shorthand for a device's UID, and [product]
as a
shorthand for a device's product UID. For example, the following is a valid Device
Dashboard URL that includes shorthands for device UID and product UID.
https://mydomain.test/[device]?product=[product]
Given a device with a UID of dev:123456
, and a product UID of com.blues.hello
, a request
to https://qrgo.org/id/dev:123456
would resolve to
https://mydomain.test/dev:123456?product=com.blues.hello
using the Device Dashboard URL above.
Once you have a Device Dashboard URL configured, you can test it by clicking the Dashboard link while viewing a device in Notehub.
And when you're ready to deploy devices, you can print QR codes that point to
https://qrgo.org/id/[device]
on each device—for example https://qrgo.org/id/dev:123456
,
https://qrgo.org/id/dev:7890123
, etc.
Finding a ProductUID
A ProductUID is an immutable user-generated string generated when you create a new project. After you create a project, you can copy the ProductUID directly from the project tile after logging in to Notehub:
The ProductUID is also available from the project's settings page:
Once you have your ProductUID, you can assign it to one or many Notecards using
the hub.set
request.
{
"req": "hub.set",
"product": "com.blues.testing:test"
}
A ProductUID is also used in many Notecard example apps
to associate a Notecard with a cloud-based Notehub project. For example, the
Notecard's C, C++, and Arduino samples include the following line of code that
asks you to provide a PRODUCT_UID
.
#define PRODUCT_UID "" // "com.my-company.my-name:my-project"
Once you have your ProductUID copied from Notehub, you can paste it into your sample's code.
#define PRODUCT_UID "com.blues.testing:test"
Assigning a ProductUID to a device in host firmware, as many of the Notecard samples do, is a development convenience. For production workflows we recommend loading Notecard configuration through a setup script, and to avoid placing ProductUIDs in source code.
Creating a New ProductUID
Each Notehub project must have at least one ProductUID and may optionally have multiple ProductUIDs. Devices assigned to any of a projects' ProductUIDs will all sync data to the same project. However, it can be useful to utilize multiple ProductUIDs in scenarios where:
- You need to allocate new devices to specific fleets by ProductUID.
- You need to block network connections for all devices by ProductUID.
Follow these steps to add a new ProductUID to an existing Notehub project:
-
Click the Settings option in the main menu of your Notehub project. Scroll to the ProductUIDs section and click New ProductUID.
-
Select the desired ProductUID prefix, likely using the same prefix used for other ProductUIDs in the same Notehub project. Specify the new ProductUID, add an optional Description, and optionally assign devices associated with this ProductUID to a specific fleet.
-
If so desired, click the checkbox next to Temporarily block incoming connections to prevent devices with this ProductUID from connecting to Notehub. Learn more about this feature in the Notehub Walkthrough section, Temporarily Block Incoming Connections.
Reserving a ProductUID Prefix
Since a ProductUID is a globally-unique
identifier for your product, Notehub will prompt you to create ProductUIDs using
a prefix that matches your email address domain (e.g. com.blues
). You can also
request to reserve your own set of custom ProductUID prefixes to match your
company/organization domain and prevent them from being used by any other
accounts in Notehub.
Follow these instructions to request a custom ProductUID prefix for you and/or your company:
-
In Notehub, click on your name in the upper-right corner and navigate to the Billing menu option.
-
Click on the Prefixes tab.
-
Enter your desired ProductUID prefix and the reason for this reservation request. Be sure your prefix follows the requirements listed and click Submit request when ready.
-
Once your request has been sent, you will receive an email confirmation and a list of pending/accepted requests at the bottom of the page. A representative from Blues will be in touch with you within approximately 1-2 business days.
Temporarily Block Device Connections
The Notehub UI allows you to block individual Notecards from connecting to Notehub. The intended use of this feature is to block connections from misbehaving devices until a root cause can be diagnosed.
Under the Summary tab of the device details, scroll down to the "Danger Zone" section. To temporarily block incoming connections from the selected device, check the appropriate box.
When a Notecard is "blocked", it will likely continue to periodically re-attempt a connection with Notehub. Until it is "unblocked", no data will be received on Notehub. However, each time a Notecard attempts to connect it will use a small amount of its cellular data plan. Since these re-attempts are likely to occur periodically, this setting should not be used to disable a device for a long or indefinite period of time.
Configuring Notehub Alerts
Notehub alerts allow you to set threshold values on inbound data that, when met,
will generate email, Slack, or SMS notifications. Alerts are fully configurable
by setting operators on the values in the body
of a given Notefile.
Creating a Notehub alert requires access to the Development Edition of Notehub. Learn more about Notehub pricing.
Configuring an Alert Monitor
-
To configure a new Notehub alert monitor, navigate to the top-level Alerts menu within a Notehub project and click on the Create Monitor button.
-
Provide a Name and optional Description of the monitor, then choose the Notefile that contains the data you want the alert to be based on. TIP: Make sure you've already sent at least one Note to Notehub that utilizes the data structure you want to utilize for the alert!
-
The Field will be a field within the
body
of the Notefile that you want to monitor. For instance, if your Note includes abody
like this:"body": { "temp": 72.22, "humidity": 34.2, "voltage": 4.1 },
...you have the option of choosing from
temp
,humidity
, orvoltage
for the alert. -
Next, you need to set the Conditions at which alerts will be generated by this monitor. Choose the operator you wish to apply and the value at which the alert should be triggered.
-
Lastly, enter the contact information for the individuals who will be receiving the alerts and click the Create Monitor button to save your changes.
Disabling or Muting Alert Monitors
Individual alert monitors can be disabled or muted. Disabling a monitor tells Notehub to completely ignore the specified alert. Muting a monitor, on the other hand, allows you to temporarily suppress notifications from a given alert. This can be useful if your product is in an alert state and you wish to briefly suspend notifications.
Alert Logging
By default, all alert notifications are logged and visible under the Logs tab: