Notehub Walkthrough

The Notehub Walkthrough is intended to assist with tasks that will encountered frequently, when utilizing Notehub's rich feature set to accomplish your application's IoT objectives.

What is Notehub?

Notehub is a server-side service designed to connect to, and synchronize Notefiles with Notecard devices.

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 features tailored to your specific business needs.

Notehub.io provides a UI which allows you to explore the vast collection of data and metadata created by the Notecard/Notehub infrastructure. Notehub also provides functionality for interacting with Notecards, routing data, managing firmware, as well as managing projects, fleets, and teams.

This document will detail and describe the features and functionality of the Blues Wireless 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 either JSON or .csv format.

Create a Notehub Account

1. Navigate your browser to Notehub.io, and you will be greeted with the sign-in screen.

2. 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 instead, then you may click the Sign up with Github button.

   

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

   

4. Once you have created your account, you will be forwarded to the projects page. However, you will not be able to create your first project until you have successfully verified your email. An email will be sent to the email you provide, or the email associated with your GitHub account, during the account creation process.

   

5. Finalize your account by clicking on the link in the email you receive from support@blues.io. The text of the email will be similar to the following:

Hi, please verify your account by clicking the following link: https://notehub.io/auth/self-service/verification/methods/link?token=AdW...

The link will return you to the project page of 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 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.

1. Navigate to Notehub.io, and click on the Create Project button in the upper right corner.

   

2. The Create Project dialog will open.

   

3. Provide a name for the project in the Project Name input box.

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

5. Click the Create Project button.

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:

1. Select Settings > Members from the left navigation bar.

   

2. Click the Invite members button.

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

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.

1. Select Fleets from the left navigation bar.

   

2. Click the Add fleet option, in the upper right corner.

   

3. Give the new fleet a name in the Fleet name field.

   

4. Click Add fleet.

Add a Device to a Fleet

Upon first connection to Notehub.io, a device is routed to the default fleet associated with the ProductUID.

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, New, a temporary holding place. Then, once a new device appears in the default fleet, it can be triaged and properly associated with its production fleet.

1. Select Devices from the left navigation bar.

   

2. Select a device from the list of devices.

   

3. Select Details from the available options.

   

4. Select the Device Info tab.

   

5. Click the pencil near the fleet name.

   

6. Select the new fleet from the drop-down list.

   

Add a Favorite

Favorites are a way of both saving and organizing your favorite query filters.

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 or difficult to enter, and you may find you are constantly creating the same filters as part of your workflow.

To facilitate your 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.

Troubleshooting Cellular Coverage

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

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.

Deploy Firmware

1. Select Devices from the left navigation bar.

   

2. Select a device from the list of devices in the Notecard Firmware tab.

   

3. Select Update from the available options.

   

4. Confirm you wish to update the Notecard firmware.

   

5. Select the firmware you wish to apply from the list of available firmware, and click Apply.

   

6. Now that you have selected your firmware, you will see it in the Requested Version field.

   

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

   

Manage Host Firmware

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.

Upload Host MCU Firmware

1. Select Settings > Firmware from the left navigation bar.

   

2. Select Upload firmware from the available options.

   

3. Upload firmware via the upload page.

   

Deploy Firmware

1. Select Devices from the left navigation bar.

   

2. Select a device from the list of devices in the Host Firmware tab.

   

3. Select Update from the available options.

   

4. Confirm you wish to update the Notecard firmware.

   

5. Select the firmware you wish to apply from the list of available firmware, and click Apply.

   

Publish Data 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, Inbound Queues and Environment Variables.

Queue Inbound Notes

Inbound Notes are those going from a cloud app or external service and propagating down to the Notecard.

This data is called "inbound data" 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 inbound data from the Notecard, and respond accordingly.

Typical use cases:

• Share state between the Notecard and Notehub.
• Notify the host that new data is available.

Update Environment Variables

In IoT applications, products often require configuration variables or settings that can be used on an end device, but managed and updated once the product is deployed in the field. 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.

Update Project Environment Variables

1. Select Settings > Environment from the left navigation bar.

   

2. Add a Key and Value to establish a new environment variable, or to override the default value of an environment variable.

   

3. Click the Save button.

Update Fleet Environment Variables

1. Select the caret on Devices from the left navigation bar.

   

2. Select the fleet you wish to update from the list.

   

3. Select the Settings option.

   

4. Add a Key and Value to establish a new environment variable, or to override the default value or project value of an environment variable.

   

5. Click the Save button.

Update Device Environment Variables

1. Select Devices from the left navigation bar.

   

2. Select a device from the list of devices.

   

3. Select Details from the available options.

   

4. Select the Environment tab.

   

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

   

6. Click the Save button.

Adding Contact Information

Contact information appears in the device JSON and will be queryable and updatable using the Notecard API card.contact.

1. Select Settings > Project from the left navigation bar.

   

2. Add your contact information into the Contacts form.