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 use serial requests (from our in-browser terminal or the Notecard CLI) to configure the Notecard, simulate sending data from sensors to the Notecard, and 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.
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):
To complete this quickstart, make sure you have access to the following:
- Notecard and Notecarrier-Pi.
If you want to use your PC's browser to complete the quickstart:
Micro USB to USB-A data cable (not a charge-only cable).
Mac, Windows, or Linux PC with an available USB port.
A browser that supports the Web Serial API, like Chrome 89+, Edge 89+, or Opera. If you prefer to not use one of these browsers you can follow-along with this guide by installing the Notecard CLI and using the play command to send Notecard requests interactively.
If you want to use only your Raspberry Pi to complete the quickstart:
Install the Notecard CLI and use the play command to send Notecard requests interactively.
Issue the following Notecard CLI command to connect to the Notecard over I2C instead of serial:
./notecard -interface i2c
.Ignore any instructions below that refer to connecting to the Notecarrier-Pi to your PC over serial!
- If you're using a Cellular Notecard, make sure you're in a location with stable cellular coverage.
- An internet connection that allows access to Notehub.
The Raspberry Pi Starter Kit includes a Notecarrier-Pi, a Molex cellular antenna, and a Notecard.
The USB port on the Notecarrier-Pi is a data-only port and does not provide power to the Notecarrier. Make sure to plug your Notecarrier into a Raspberry Pi before attempting to connect to the Notecard over serial.
Remove the screw from the mounting receptacle on the Notecarrier-Pi.
Place the Notecard into the M.2 slot on the Notecarrier. Once inserted, press gently until the Notecard is inserted and the screw receptacle hole is completely visible.
Re-insert the screw into the mounting receptacle and secure the Notecard to the Notecarrier. Be sure to not overtighten the screw.
Secure the U.FL connector of the Molex antenna to the
MAIN
socket on the Notecard.Turn the Notecarrier-Pi over and verify that all three dip switches are in the "off" position for this quickstart. For future reference:
ACTIVE GPS
should be "on" if you are connecting an active GPS antenna.SERIAL TXRX
should be "on" if you want to use UART instead of I2C.ATTN
should be "on" if you want to enable the ATTN pin on the Notecard.
With the Notecard facing up, plug the Notecarrier-Pi into the 40-pin header of your Raspberry Pi or Pi-compatible device.
Now you're ready connect to the Notecard over USB and continue with the Quickstart!
The USB port on the Notecarrier-Pi is a data-only port and does not provide power to the Notecarrier. Make sure to plug your Notecarrier into a Raspberry Pi before attempting to connect to the Notecard over serial.
Connect a USB cable from the Notecarrier's USB port to your computer's USB port.
If you're using a Wi-Fi Notecard you have one additional step: complete our guide to connecting to a Wi-Fi Access Point, as you'll need a network connection to complete the rest of this tutorial.
If you want to use the in-browser terminal for this guide, take notice of the window to the right or below. You will be using this interface to communicate over USB with your Notecard.
In the in-browser terminal, click the USB Notecard button. A browser prompt will appear asking for permission to connect to a USB Serial device:
If you're on a Mac, select either
Notecard (cu.usbmodemNOTE1)
orNotecard (tty.usbmodemNOTE1)
.On Windows, the option will show up as
USB Serial Device (COMx)
.On Linux the option will show up as
Notecard (ttyACM0)
.
Having trouble connecting?
Try using a different micro USB cable. Some micro USB cables are only capable of transferring power, not data.
If Linux is your operating system, try adding your user to the
dialout
group. Run the commandsudo usermod -aG dialout $USER
and restart your computer for the change to take effect (as logging out and back in may not be enough).
Prefer to use the Notecard CLI instead?
Once installed, use the
notecard -play
command to begin interactive request mode.
- Issue the following Notecard CLI command to connect to the Notecard over
I2C instead of serial:
./notecard -interface i2c
.
- Copy each request from this guide into your CLI console to run it against your connected Notecard.
Now, you're ready to send your first request. Copy and paste the following request 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.3.1",
"ver_major": 3,
"ver_minor": 3,
"ver_patch": 1,
"ver_build": 14612,
"built": "May 18 2022 11:21:51"
},
"version": "notecard-3.3.1.14612",
"device": "dev:868050040247765",
"name": "Blues Wireless Notecard",
"sku": "NOTE-WBNA-500",
"board": "1.11",
"api": 3
}
The JSON response above provides version information of the firmware on the Notecard, as well as device-specific information.
Well done! You have properly set up, configured, and validated your hardware. Next, you'll configure your Notecard to communicate with 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.
- Sign in or sign up for Notehub using the links below.
Create a Notehub Account
Already have an account? Sign in 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.Take note of your ProductUID. This identifier is used by Notehub to associate your Notecard to your project.
In this part of the exercise you'll configure your Notecard so that it knows where to send data. You do this by assigning the ProductUID created in the last step to your Notecard.
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"}
{}
In this section, you'll validate your Notecard configuration by performing a manual synchronization to Notehub and sending synchronization status requests to the Notecard.
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:
Sync not completing, or having trouble connecting?
If you're having trouble connecting there are a few things you can try. First, check if your status includes "no project was found" or "can't open Notehub" errors.
{"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
}
If so, you may have a typo, or may have passed a project name to your
hub.set
request's product
instead of a ProductUID. If this is the case,
run another hub.set
request with the correct product
, and then issue
another hub.sync
request.
REMINDER: The ProductUID is typically in the form of
com.your-company.your-name:your_product
.
If your ProductUID seems correct there are a few other things you can try:
Ensure your cellular antenna is properly connected. An antenna must be properly connected to the Notecard's
MAIN
U.FL socket for the Notecard to successfully connect to a cellular network. When you attach the U.FL connector properly you will feel it "click" into place.Ensure antenna signal is not interfered. Antennas that are too close to metal objects or other devices that can produce electro-magnetic interference (EMI) may prevent establishing a connection to the cellular network. Ensure your cellular antenna is away from metal objects.
Try a different location. If the signal reception is weak, then it is difficult to establish a network connection. Deep inside large buildings, metal buildings, shipping containers, or buildings designed to block wireless signals prevent the cellular signals from getting to the Notecard. Try moving to a location where you can obtain stronger cell signals. For example, move close to an external window or outside in the case of large buildings.
If you've tried these troubleshooting steps and are still having issues,
email our support team for further assistance.
When you contact support, please include a trace log, which you can obtain by
running sync-trace
from the in-browser terminal. The command runs a hub.sync
request with extra logging enabled, and generates a log you can save and include
in your support email.
sync-trace
Why doesn't the Notecard sync data immediately?
We designed the Notecard to be low-power friendly
by default. The Notecard is extremely low power in its idle state (consuming
only ~8uA when idle), and when staging data with note.add
requests, but uses
a nontrivial amount of energy when the cellular modem is on and transmitting data
to and from a network.
However, the Notecard is also very configurable, and you can easily set up a Notecard to synchronize data immediately. You can read more about that approach in Minimizing Latency.
You're doing great! You have now configured your Notecard and are ready to send Notes to your Notehub Project!
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!
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!
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.
In this section, you'll learn how to view and interact with your Note on Notehub.
Create a Notehub Account
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!
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.
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
}
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!
Control your Notecard from a microcontroller or single-board computer! Check out our sensor tutorials for your favorite language or board.
When you're ready to connect your Notecard project to your cloud app, take a look at our routing tutorials, which cover a number of popular cloud applications and data visualization tools.
For a little inspiration, and to see what developers are building with the Notecard and Notehub, visit our Hackster.io Hub.