Browse our open source example apps to accelerate your wireless IoT project.

Blues Developers
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our Forum
Button IconSign In
Sign In
Sign In
Docs Home
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Quickstart
Cell+WiFi Quickstart
LoRaWAN Quickstart
Starnote Quickstart
Wireless for Opta Quickstart
Notecard Quickstart
Notecard LoRa Quickstart
IntroductionBefore You BeginConnect Your Notecard and NotecarrierSet up NotehubSet up NotecardQueue Notes to your NotecardSend Notes from Notecard to NotehubView Notes on NotehubSend Notes from Notehub to NotecardNext Steps
Cygnet Quickstart
Swan Quickstart
Mojo Quickstart
Sparrow Quickstart
homechevron_rightDocschevron_rightQuickstartchevron_rightNotecard LoRa Quickstart

Notecard LoRa Quickstart

Introduction

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

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

Throughout this guide, you'll issue serial requests to configure the Notecard, simulate sending data from sensors to the Notecard, and 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.

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, Wi-Fi, or LoRa connection. It's a 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.

  • A Note is a JSON object containing developer-provided content. A Note is the primary means of sending data to/from a Notecard.

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

animation of outbound communication from notecard to notehub to cloud

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

animation of inbound communication from cloud to notehub to notecard

Before You Begin

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

  • The contents of a Blues LoRaWAN Starter Kit , which include:

    • Notecard LoRa

    • Notecarrier B

    • Blues Indoor LoRaWAN Gateway. If your gateway is not already set up, complete Connecting to a LoRaWAN Gateway before continuing.

    • External LoRa antenna

  • Micro USB to USB-A data cable (not a charge-only cable).

  • Computer with an available USB port.

  • A browser that supports the Web Serial API, like Chrome, Microsoft Edge, or Opera.

  • An internet connection that allows access to Notehub .

Connect Your Notecard and Notecarrier

The Blues LoRaWAN Starter Kit includes three Notecard LoRa devices, three Notecarrier B boards, and three external antennas. To complete this tutorial you must assemble one set of these components using the steps below.

A Notecarrier B, Notecard LoRa, and antenna on a table

  1. First, remove the screw from the mounting receptacle on the Notecarrier B.

    The mounting receptacle on Notecarrier

  2. Next, 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, being sure not to overtighten the screw.

    A Notecard LoRa plugged into Notecarrier

  3. After that, push the cable end from the LoRa antenna onto the u.FL socket on the Notecard. When seated properly, you will feel it "click" into place.

    A u.FL cable connecting to Notecard LoRa

Now you're ready connect to the Notecard over USB and continue with the Quickstart!

Power the Notecard and Notecarrier

Connect a USB cable from the Notecarrier's USB port to your computer's USB port.

Notecard LoRa connecting to a laptop through a USB cable

note

You can also power your Notecard LoRa by plugging a LiPo battery into your Notecarrier's LIPO JST connector.

The USB connection is required for this tutorial as you'll use that connection to communicate with the Notecard in the next section.

Connect to the Notecard

With your Notecard connected your next step is to communicate with the Notecard over USB. To do so, first locate the panel on the right-hand side of your browser window, which we call the In-Browser Terminal.

Within the In-Browser Terminal click the USB Notecard button. A browser prompt will appear asking for permission to connect to a USB serial device. Select the Notecard, which displays as a “USB to UART” controller, and connect. If all went well you should see a "Connected to serial" message in the Terminal.

Browser prompt for connecting serial

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 command sudo usermod -aG dialout $USER and restart your computer for the change to take effect (as logging out and back in may not be enough).

  • If you're on Windows and unable to connect to the Notecard LoRa over serial, you may need to install the CP210x drivers from SILabs .

Prefer to use the Notecard CLI instead?
  • Visit the Notecard CLI Guide for installation instructions.

  • Once installed, use the notecard -play command to begin interactive request mode.

  • Copy each request from this guide into your CLI console to run it against your connected Notecard.

Validate Serial Connection

Now you're ready to send your first JSON request to the Notecard! All requests and responses to/from the Notecard are in JSON format and are structured with the command as the value of a req key. Additional arguments are written as additional key-value pairs. For example, {"req":"card.version"} or {"req":"hub.set", "mode":"continuous"}.

The first request you'll send invokes the card.version API, which returns metadata about your Notecard.

Copy and paste the following request into the In-Browser Terminal (click the TRY IT button below). Hit Enter and you'll see a response similar to the example output.

>
{"req":"card.version"}
{
 "device": "dev:0080e115004521c3",
 "name": "Blues Wireless Notecard",
 "board": "3",
 "version": "notecard-7.1.2.16389",
 "sku": "NOTE-LWUS",
 "body": {
  "org": "Blues Wireless",
  "product": "Notecard",
  "target": "wl",
  "version": "notecard-wl-7.1.2",
  "ver_major": 7,
  "ver_minor": 1,
  "ver_patch": 2,
  "ver_build": 16389,
  "built": "Feb  7 2024 19:38:11"
 }
}

Well done! You have properly set up, configured, and validated your hardware. Next, you'll configure your Notecard to communicate with Notehub.

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 and host MCU firmware updates, and makes it easy for you to route data to your own cloud applications.

In this section, you'll set up a Notehub Project and create your first ProductUID. A ProductUID is the unique identifier you will use to associate a Notecard with 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

    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.

    The dialog for creating a project in Notehub

    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.

    The location of the ProductUID within a Notehub project

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

To associate the Notecard with your Project in Notehub you must assign the ProductUID you created to your Notecard. 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 TRY IT button below).

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

The JSON object above consists of two key-value pairs. The first provides the name of the request, denoted with the key req and a value of hub.set. The second, product, is one of the arguments for the hub.set request. You can see all the arguments for this and all Notecard Requests in the API Documentation

Validate Your ProductUID and Connection

In this section, you'll validate your Notecard configuration by performing a manual sync with Notehub and then request sync status updates from 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 monitor the state of the sync by watching the status bar at the top of the In-Browser Terminal.

In-Browser Terminal sync pending

As soon as you see "Notehub sync attempt [x]s ago", the sync should be complete!

In-Browser Terminal sync complete

Optional: Manually check on the state of a sync with the hub.sync.status API

You can also manually check on the state of a 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.

Depending on the timing of your hub.sync.status requests, your responses may differ from what is displayed here:

>
{"req":"hub.sync.status"}
{
 "sync": true,
 "status": "sync in progress {sync}"
}

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": 1708111715,
 "completed": 4,
 "status": "completed {sync-end}"
}

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

device in notehub

Sync not completing, or having trouble connecting?

The Notecard LoRa sends data through a LoRaWAN gateway. If you're not seeing your device in Notehub, start by making sure your your LoRaWAN gateway is powered on and that you've completed the steps in Connecting to a LoRaWAN Gateway.

Next, make sure your Notecard LoRa is within range of your gateway. Although LoRa signals should be able to travel a hundred meters or more in indoor locations, it's a good idea to place your device near the gateway during setup to ensure interference isn't a problem.

If you've tried these troubleshooting steps and are still having issues, please reach out on our community forum .

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 ~8µA@5V when idle) and when queuing data with note.add requests, but uses a nontrivial amount of energy when 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 our guide on Minimizing Latency.

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 simulated sensor data to your Notecard. To understand how data flows throughout the Blues ecosystem it's helpful to to start with two concepts.

  • Notes: Notes are JSON objects containing developer-provided content.

  • Notefiles: Notefiles are named JSON files that contain one or more Notes.

Imagine your Notecard is connected to a Host MCU that reads temperature and humidity data from a sensor. In such a scenario, a Note on the Notecard might look like {"body:{"temp":35.5,"humid":56.23}}, and a Notefile would contain a list of all temperature/humidity Notes you've created.

Implementing this workflow on Notecard LoRa is a two-step process. First, you must define the format your Notes will take using the Notecard's note.template API, and then you can queue Notes on the Notecard using the note.add API.

Let's start by defining a template for the sample temperature and humidity data. To do so, copy and paste the following note.template request into the Notecard Terminal and press Enter to send it to your Notecard.

>
{"req":"note.template","file":"data.qo","port":1,"format":"compact","body":{"temp":14.1,"humid":14.1}}
{
 "bytes": 11,
 "format": "compact"
}

Let's break down this request in detail.


"file":"data.qo"

When you use the note.template request you define the format for a single Notefile. This file argument gives the Notefile a name of data.qo, where the .qo stands for "outbound queue". Learn more about Notefile naming conventions.


"port":1

The Notecard LoRa is a low-bandwidth friendly device that attempts to minimize bandwidth usage. The port argument is a unique integer that refers to a single Notefile. Providing this value allows the Notecard to send a numerical reference to the Notefile over the air, rather than the full Notefile name.


"format":"compact"

This is a required field for using the note.template request on Notecard LoRa. The "compact" value tells the Notecard to send a minimal amount of metadata with the Note.


"body":{"temp":14.1,"humid":14.1}}

The body arguments tells the Notecard about the contents of each Note in the Notefile, as well as their data types. These values tell the Notecard to expect two fields, "temp" and "humid", each of which have a value in 14.1 format, which represents a 4-byte floating-point number. View a full list of data types.


With the template of the Notefile defined, your next step is to queue a Note on the Notefile using the note.add request. To do so, run the request below in the Notecard terminal.

>
{"req":"note.add","file":"data.qo","body":{"temp":35.5,"humid":56.23}}
{
 "template": true,
 "bytes": 11,
 "total": 1
}

This request creates a Note that includes your JSON body, as well as additional metadata like creation time.

In response, the Notecard returns a JSON object that includes a total, which indicates the 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 monitor the state of the sync by watching the status bar at the top of the In-Browser Terminal, or use a hub.sync.status request.

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 ~8µA@5V 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 network upon startup.

View Notes on Notehub

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

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

Create a Notehub Account

Already have an account? Sign in

Navigate to Notehub.io .

You will see your project dashboard:

List of projects in Notehub

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.

List of devices in Notehub

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.

List of events in Notehub

Double click the event and click the JSON tab to view additional metadata the Notecard captured, such as identifiers and timestamps.

A single event showing in Notehub

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

Send Notes from Notehub to Notecard

It's important to remember that communication between the Notecard and Notehub is bi-directional, both outbound (from the Notecard to the cloud, as documented above) and inbound (from the cloud to the Notecard).

While not part of the quickstart, you can learn more about inbound data syncing in the Notehub Walkthrough.

Next Steps

Congratulations! You've now queued sensor data on a Notecard and sent that data to the cloud!

If you're following the LoRaWAN Quickstart, we next recommend completing our guide on building your first LoRa app.

  1. Set Up Your Gateway
  2. Use the Notecard to Send Data
  3. Build Your First LoRa App

At any time, if you find yourself stuck, please reach out on the community forum .

Can we improve this page? Send us feedback
© 2025 Blues Inc.
© 2025 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up