Quickstart

Introduction

This tutorial should take approximately 20-30 minutes to complete.

This guide will introduce you to the Blues Wireless ecosystem of tools, including the Notecard, Notecarrier, and Notehub.

Throughout this guide you'll issue a series of requests to a simulated Notecard. The simulated Notecard has the same API as a physical Notecard, and completing this tutorial allows you to see how the Notecard works without having to purchase hardware. As part of this guide you'll learn how to configure a Notecard, how to simulate sending data from sensors, and how to synchronize that data with the cloud.

By the end of this tutorial, you'll have a basic understanding of the process for building connected solutions with Blues Wireless. The following video provides an overview of what you'll learn.

Key Concepts to Know

Before you dive in, it's important to understand a few key concepts:

• The Notecard is a device-to-cloud data pump that reduces the complexity of building connected solutions with a secure, reliable cellular or Wi-Fi connection. It's a 30x35 millimeter System-on-Module (SOM) that's ready for embedding into any project.

• Notecarriers are development boards that help you get started quickly with the Notecard. There are a variety of Notecarriers designed to fit different needs, from prototyping with a Feather-based MCU to deploying a production solution.

• Notehub is the cloud service the Notecard uses to securely send and receive data. Notehub also provides a console for fleet management and secure connectors for routing data to 3rd-party cloud applications.

Notecard and Notehub work together to provide bidirectional wireless communication capabilities, both outbound (from your microcontroller or single-board computer to the cloud):

And inbound (from the cloud to your microcontroller or single-board computer):

Before You Begin

To complete this quickstart, make sure you have access to the following:

• An internet connection that allows access to Notehub.

Connect Your Notecard and Notecarrier

The Notecard Simulator is available through the Notecard's in-browser terminal. If the terminal isn't open already, you may open it by clicking the "Disconnected" button in the top-right corner of your browser.

Within the terminal you'll see two options, connecting to a physical Notecard ("USB Notecard"), and trying a Notecard Simulator ("Sign In" or "Notecard Simulator", depending if you are signed into Notehub or not).

Using the Notecard Simulator allocates a new, cloud-based virtual Notecard, and allows you to send requests to the virtual Notecard directly in your web browser.

Using the simulator requires an account on the Notecard's backing cloud service, Notehub, so let's next look at how to set that up.

Set up Notehub

Notehub is a secure proxy cloud service that communicates with the Notecard, provides tooling for managing fleets of devices, allows you to perform over-the-air Notecard firmware updates, and makes it easy for you to securely route data to your own cloud applications or services.

In this section, you’ll start simple by setting up a Notehub Project and creating your first ProductUID. A ProductUID is the unique identifier you will use to associate a Notecard to a Notehub Project, and ensure that data from the Notecard ends up in the right location.

Create a Notehub Project

1. Sign in or sign up for Notehub using the links below.

   Create a Notehub Account

   Sign up

   Already have an account? Sign in

2. Click "Create Project" on the dashboard. In the New Project card, give your project a name and ProductUID.

   

   NOTE: The ProductUID must be globally unique. To reduce collisions, Notehub prepends a generated namespace based on your account email, for instance com.your-company.your-name:. Enter any identifier you like in the input on the right.

3. Take note of your ProductUID. This identifier is used by Notehub to associate your Notecard to your project.

   

Set up Notecard

Now that you have a Notehub account you're ready to get started with the Notecard Simulator. If you haven't already, click the Simulate Notecard button within the in-browser terminal to allocate a new Notecard Simulator.

To send your first request, copy and paste the following JSON into the in-browser terminal (click the COPY button below).

Hit Enter and you'll see a response similar to the example output.

{"req":"card.version"}

{
 "body": {
  "org": "Blues Wireless",
  "product": "Notecard",
  "version": "notecard-3.4.1",
  "ver_major": 3,
  "ver_minor": 4,
  "ver_patch": 1,
  "ver_build": 15105,
  "built": "Jul 19 2022 21:58:21"
 },
 "version": "notecard-3.4.1.15105",
 "device": "dev:default",
 "name": "Blues Wireless Notecard",
 "sku": "NOTE-SOFTCARD",
 "board": "0.0",
 "api": 3
}

The JSON response above provides version information of the firmware on the simulated Notecard.

Now that you know how to send requests to the Notecard, let's next configure the Notecard so it knows where to send data. You do this by assigning your Notecard a ProductUID.

Setting the ProductUID associates a Notecard to a given Project in Notehub. A Notecard can easily be moved between Projects over time, but it can only belong to one project at a time.

To set the ProductUID, you'll start by sending a hub.set JSON request to your Notecard. Once the Notecard has finished processing your request, it will send a JSON response back to your computer to let you know that the request is complete.

An empty JSON object ({}) from the Notecard indicates a successful request. If an error occurs, the Notecard will return a JSON object with an err key and a string describing the error that occurred.

Copy and paste the following Notecard request, making sure to replace com.your-company.your-name:your_product with the ProductUID you created in the last step (click the COPY button below).

{"req":"hub.set", "product":"com.your-company.your-name:your_product"}

{}

Validate Your ProductUID and Connection

In this section, you'll validate your Notecard configuration by performing a manual synchronization to Notehub and sending synchronization status requests to the Notecard.

Start a Sync

Initiate a synchronization between the Notecard and Notehub with a hub.sync request, as shown below.

{"req":"hub.sync"}

{}

Once a sync has started, you can check on the state of the sync with a hub.sync.status request. When the sync is ongoing, the response will return a status field with the current progress of the sync and a requested field with the number of seconds since the sync was initiated. You can call hub.sync.status multiple times to follow the process of your first sync if you wish.

{"req":"hub.sync.status"}

{
  "status": "starting communications {wait-module} {connecting}",
  "requested": 2
}
...
{
  "status": "modem now ON {modem-on}",
  "requested": 6
}
...
{
  "status": "waiting for wireless service 6 sec [+---] {cell-registration-wait}",
  "requested": 12
}

Once the sync has completed, the response to hub.sync.status includes the UNIX Epoch time of the last sync, and the number of seconds since the last completed sync.

{"req":"hub.sync.status"}

{
 "time": 1615585299,
 "completed": 4
}

You should now be able to return to Notehub, refresh the Devices page, and see that a device has been added to your project:

{"req":"hub.sync.status"}

{
  "status": "opening notehub: no project was found with product UID product:com.your-company.your-name:your_product {product-noexist} {notehub-open-failure}",
  "requested": 10
}
...
{
  "status": "can't open notehub: opening notehub: no project was found with product UID product:com.your-company.your-name:your_product {product-noexist} {notehub-open-failure}",
  "requested": 11
}

sync-trace

You're doing great! You have now configured your Notecard and are ready to send Notes to your Notehub Project!

Queue Notes to Your Notecard

In this section, you will add Notes simulating sensor data to your Notecard. Imagine your Notecard is connected to a Host MCU that reads temperature and humidity information from a sensor. Your sample data might look like this: {"temp":35.5,"humid":56.23}.

Copy and paste the following request into the Notecard Terminal, then press Enter to send it to the Notecard.

{"req":"note.add","body":{"temp":35.5,"humid":56.23}}

{"total":1}

This request will create a Note that includes your JSON body and additional metadata like creation time and location. In response, the Notecard returns a JSON object indicating the total number of Notes ready to sync to Notehub. You won't see your Note in Notehub just yet, because the Notecard queues your Notes until it is time to sync them to the cloud.

Excellent work! You have queued your first Note to the Notecard!

Send Notes from Notecard to Notehub

In this section, you'll perform another sync to send your Note to Notehub. As before, you can manually initiate a sync by entering the following JSON request in the in-browser terminal:

{"req":"hub.sync"}

{}

Behind the scenes, your Notecard will again search for a network connection and connect to Notehub. Once the connection is made, the Notecard uploads your Note and closes the connection. As before, you can use hub.sync.status to monitor your in-progress sync:

{"req":"hub.sync.status"}

{
  "status": "begin (anything pending) {sync-begin}",
  "requested": 1
}
...
{
  "status": "upload data.qo (1 changes) {sync-get-local-changes}",
  "requested": 2
}
...
{
  "status": "completed {sync-end}",
  "requested": 4
}

By default, the Notecard places Notes in a Notefile called data.qo. The .qo extension means that the file is an "outbound queue," or a queue that originates on the Notecard and is synchronized with Notehub.

Great work! Your Note has now been transferred from the Notecard to the cloud and stored in your Notehub project!

note

The Notecard is a low-power device (consuming only ~8uA when idle) and is built to be continuously powered. This is important to know because certain features of the Notecard require the current time, which is established upon the Notecard successfully connecting to a cellular network upon startup.

View Notes on Notehub

In this section, you'll learn how to view and interact with your Note on Notehub.

Navigate to Notehub.io.

You will see your project dashboard:

Click on the card with your Project, and the device dashboard for your Project will load. You'll see your Notecard in the Devices list.

Click Events in the left-side navigation. In the Events list, you should see your note in the list with a simulated sensor reading body. Your Note will be listed in the table, along with other session and environment-specific events sent automatically by the Notecard.

It's that simple, your product and data are now online!

Send Notes from Notehub to Notecard

In this section, you’ll learn how to use Notehub to send Notes to the Notecard. You can use either the Notehub UI or HTTP 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.

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:

COPY

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

That's it! You have now successfully queued a Note via the Notehub UI!

Compose via the HTTP API

Sending data via the Notehub UI may be useful for a human, but sending data programmatically through our 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:

COPY

>

{"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:

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

note

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:

COPY
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 the body 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.

That's it! You have now successfully queued a Note via the HTTP API!

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": {}
 }
}

Congratulations! You have now explored both ways to send Notes from the cloud to your Notecard. With that, you understand the basics of bi-directional communication using the Blues Wireless platform!

Next Steps

If you’re ready to get started with a physical Notecard, check out the Notecard development kits in our shop.

If you’re curious of the sort of things you can build with the Notecard, check out the Notecard projects on our Hackster.io Hub.

And if you have any questions, feel free to reach out on our forum anytime.