Rate this page
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
Notehub is a cloud-based service designed to connect to Notecard devices and synchronize Notefiles.
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.
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.
This document details and describes the features and functionality of the Blues Wireless SaaS product, Notehub.io.
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.io
. The link will return you to Notehub.io and you will
be ready to create your first project.
Projects are core to the functionality of Notehub. They provide a way to organize a group of products, 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.
Projects may also be managed via the Notehub API.
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 of com.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.
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 a single fleet or all devices. A Notehub project can have multiple routes defined and active at any one time.
There are a variety of different route types available in Notehub, exposing different configuration options depending on the service and protocol.
Allows you to send Notecard events to external HTTP/HTTPS endpoints, including webhooks.
View the General HTTP/HTTPS Route Tutorial
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
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 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 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.
Allows you to send Notecard web requests to external HTTP/HTTPS endpoints, using the Notehub as a proxy.
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
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 enables data storage, processing, and analytic solutions that are faster, easier to use, and far more flexible than traditional offerings.
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):
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.
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.
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:
Each attempt at routing an event consumes one consumption credit, regardless of whether it's the first attempt or a retry.
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.
Team members can take the role of Owner, Developer, or Viewer. The permissions granted to each role are defined as follows:
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 | ✅ | ❌ | ❌ |
Subscription | |||
Plans | |||
Read | ✅ | ✅ | ✅ |
Update | ✅ | ❌ | ❌ |
Payment Methods | |||
Create | ✅ | ❌ | ❌ |
Read | ✅ | ❌ | ❌ |
Update | ✅ | ❌ | ❌ |
Delete | ✅ | ❌ | ❌ |
Invoices | |||
Read | ✅ | ❌ | ❌ |
Usage | |||
Read | ✅ | ❌ | ❌ |
Environment Variables | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ✅ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Firmware | |||
Notecard | |||
Read | ✅ | ✅ | ❌ |
Deploy | ✅ | ✅ | ❌ |
Host MCU | |||
Create | ✅ | ✅ | ❌ |
Read | ✅ | ✅ | ❌ |
Update | ✅ | ✅ | ❌ |
Delete | ✅ | ✅ | ❌ |
Deploy | ✅ | ✅ | ❌ |
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.
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.
Select Devices from the left navigation bar, and then select a single device from the list provided.
Select View from the available options.
Under the Summary tab, click the pencil near the fleet name.
Choose a new fleet from the dropdown list provided.
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 Favorite 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 Search name box, click Save, and your newest favorite will appear in your Favorites list.
The Cellular Notecard is designed to hide the complexity of cellular. This allows you to simply send your data to the Notecard and forget about it. However, in locations where cellular data is unreliable, you may still need to be aware of cellular diagnostic information. Fortunately, quite a bit of information about towers and your connection is captured in the session data.
Use the Navigating to Session Data instructions to find the session data related to the Notecard in question. Session data can provide you with a deeper understanding about how the Notecard is attempting to communicate with Notehub.io, and hopefully offer insights into your connection issues.
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.
Make sure you read and understand the Blues Firmware Release Policies and Procedures before updating Notecard 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.
Confirm you wish to update the Notecard firmware.
Select the firmware you wish to apply from the list of available firmware, and click Apply.
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.
Notehub has the ability to manage firmware for whole projects or individual devices. Notehub has the ability to upload and deploy the custom firmware for your host MCU.
Select Settings > Firmware from the left navigation bar.
Select Upload firmware from the available options.
Upload firmware via the upload page.
Select Devices from the left navigation bar and select a device from the list of devices in the Host Firmware tab.
Select Update from the available options.
Confirm you wish to update the host firmware.
Select the firmware you wish to apply from the list of available firmware, and click Apply.
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: Inbound Queues and Environment Variables.
Inbound Notes are those going from a cloud app or external service and propagating 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.
Typical use cases:
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 enables 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.
Environment variables can be defined in a number of locations, from the Notecard, to Notehub device settings, the device's Fleet, and the Notehub project. Variables set at different levels of this hierarchy can override one another. When obtaining an environment variable, the Notecard uses the following priority order, where the fist matched result is returned:
env.set
request.env.default
request.Select Settings > Environment from the left navigation bar.
Add a Key and Value to establish a new environment variable, or to override the default value of an environment variable.
Click the Save button.
Select the fleet you wish to update from the list provided.
Select the Settings option.
On the Environment tab, add a Key and Value to establish a new environment variable, or to override the default value or project value of an environment variable.
Click the Save button.
Select Devices from the left navigation bar and select a device from the list provided.
Select View from the available options.
Select the Environment tab.
Add a Key and Value to establish a new environment variable, or to override the default value, project value, or fleet value of an environment variable.
Click the Save button.
Contact information appears in the device JSON and will be queryable and updatable using the Notecard API card.contact.
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 samples
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.
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.
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.
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.
As discussed on our Pricing page, Notehub is free to use, and every Notecard comes with Consumption Credits that you can use while you explore the service. Many applications, however, will require additional Consumption Credits for Notehub services, and you can manage 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.
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.
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.
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.
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.