Rate this page  

Get Started with the Notecard and a

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

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

note

If you're new to Blues Wireless, you may also be interested in our recurring webinar series, Getting Started with the Notecard , where you can ask questions and get live help.

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 guide, 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 in this guide.

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 secure, reliable cellular. 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, and many include onboard Cellular and GPS antennas, as well as a USB port for Serial access to the Notecard.

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

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

  • Notecard and Notecarrier-AF.

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

  • Computer with a USB-A port or a computer with a USB-C port with a USB-A to USB-C adapter.

  • A browser that supports the Web Serial API, like Chrome 89+, Edge 89+, or Brave. No problem if you prefer not to use one of these browsers, though. You can follow-along with this guide by installing the Notecard CLI and using the play command to send Notecard requests interactively.

  • An internet connection that allows access to Notehub .

  • A location with cellular coverage. For instance, avoid a closed room in a cellar where you might have trouble getting a signal.

The Feather Starter Kit includes a Notecarrier-AF, a pre-seated Adafruit HUZZAH32 ESP32 Feather, two u.FL cables for cellular and GPS (each with one side connected to the Notecarrier and one side free) an allen wrench for the Notecarrier screw-down post, and a Notecard.

Picture of Notecarrier-AF, Notecard, and allen wrench

  1. Use the allen wrench to remove the screw from the mounting receptacle on the Notecarrier-AF, and rotate the u.FL cables away from the m.2 socket.

    Image of mounting receptacle on Notecarrier

  2. Place the Notecard into the M.2 slot on the Notecarrier. The wider portion of the edge connector slots in on the left. Once inserted, press gently until the Notecard is inserted and the screw receptacle hole is completely visible.

    Image of notecard plugged into Receptacle

  3. Using the allen wrench, re-insert the screw into the mounting receptacle and tighten to secure the Notecard to the Notecarrier. Be sure to not overtighten the screw.

    Image of Notecard affixed to Notecarrier

  4. Secure the free end of the u.FL cable connected to the socket labeled MAIN on the Notecarrier to the MAIN socket on the Notecard.

    Image of MAIN u.FL cable

  5. Secure the free end of the u.FL cable connected to the socket labeled GPS on the Notecarrier to the GPS socket on the Notecard.

    Image of GPS u.FL cable

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

Connect a USB cable from the Notecarrier-AF's USB port to your PC's USB port.

After plugging in the Notecard, you should see a red LED on the Notecard blink rapidly and then stop. This is normal and signifies the Notecard is performing its initialization steps. The green LED will also periodically blink, which signifies the cellular modem is active.

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 Connect link. A browser prompt will appear asking for permission to connect to a USB Serial device:

Browser prompt for connecting serial

  • If you're on a Mac, select either Notecard (cu.usbmodemNOTE1) or Notecard (tty.usbmodemNOTE1).

  • On Windows, the option will show up as USB Serial Device (COMx).

  • On Linux the option will show up as Notecard (ttyACM0).

Once you are connected, you will see the connection indicator change from Disconnected to Connected.

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

Prefer to use the Notecard CLI instead?
  • 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-1.5.2",
  "ver_major": 1,
  "ver_minor": 5,
  "ver_patch": 2,
  "ver_build": 12200,
  "built": "Dec  7 2020 19:28:29"
 },
 "version": "notecard-1.5.2.12200",
 "device": "dev:8376474736362",
 "name": "Blues Wireless Notecard",
 "type": 11,
 "sku": "NOTE-NBGL500"
}

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 cloud service that receives data from the Notecard and allows you to manage fleets of devices, and route that data to your own cloud apps and services.

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 to a Notehub Project, and ensure that data from the Notecard ends up in the right location.

  1. Sign in or sign up to Notehub.io.

    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.

    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.

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.

Start by sending a JSON request to your Notecard to configure it. 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
}
Responses don't match?

If instead of any of the status messages above, you see:

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

Then you may have a simple typo, or have selected the project name as opposed ProductUID.

REMINDER: The ProductUID is typically in the form of com.your-company.your-name:your_product.

If, on the other hand, your status looks like this:

> 
{"req":"hub.sync.status"}
{
 "status": "connect: connection aborted {host-unreachable} {notehub-open-failure}",
 "requested": 10
}

It's possible that your Notecard has lost its cellular connection. Make sure the cellular cable is properly connected to the U.FL connector on the Notecard, or move your Notecard to another location and try again. If you see this error repeatably, you may need to perform a factory reset on your Notecard. Do so with a card.restore request in the console:

{
 "req": "card.restore",
 "delete": true
}

After issuing this request, your Notecard will disconnect from the in-browser console. After it powers back on, click "Connect" to re-connect, send a hub.set to set your ProductUID again, and retry a hub.sync.

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 Host MCU reads from a sensor that can measure temperature and humidity information. Your sample data might look like this: {"temp":35.5,"humid":56.23}.

Copy and paste the following request into the Notecard Web Serial Interface, 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 cellular service 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!

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

Sign in or sign up to Notehub.io.

Create a Notehub Account

Already have an account? Sign in

Navigate to Notehub.io .

You will see your project dashboard:

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.

Devices screen

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.

Events screen

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.

    Navigate to Notehub.io , and select your project to see the Device list.

    Devices screen

    Click on the check mark next to your Device.

    Devices screen checked

    Click on Note (at the right, above the tab menu), and 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:

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

    Send data screen

    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.

    Events screen

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

    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.

    First you’ll need to gather some data so that Notehub knows where to send the data. Copy and paste this request into the in-browser terminal:

    > 
    {"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 product field is your ProductUID and the string in the device field is your DeviceUID So in this example, the ProductUID is com.your-company.your-name:your_product and the DeviceUID is dev:000000000000000. You will need both of these to send notes to your Notecard via the API.

    Before sending Notes to the Notehub API, you need to obtain an authentication token with a request to the auth/login endpoint. You'll provide your username and password to this endpoint, which returns a token that you can use with subsequent requests.

    If you're using Linux or Mac OS, you should have a tool called cURL installed and accessible from a terminal application to send API requests to the Notehub API. However, if you are a Windows user, then you can either use the Windows Subsystem for Linux , or follow this guide to install cURL on your Windows PC.

    Copy and paste the following command into your terminal, replacing the username and password values in the JSON object with your login credentials:

    $ 
    curl --request POST --location 'https://api.notefile.net/auth/login' \
--data '{"username":"[you@youremail.com]", "password": "[your_password]"}'
    {"session_token": "00000000000000000000000000000000"}

    In response, the Notehub API will return a JSON object with a session_token in its body. You'll need that token for the next step.

    Now, you can send another request to queue a Note. Copy and paste the following command into your terminal, and be sure to replace the X-SESSION-TOKEN, product, and device fields with your specific values:

    $ 
    curl --request POST --location 'https://api.notefile.net/req' \
--header 'X-SESSION-TOKEN: [your_session_token]' \
--data '{"req":"note.add","file":"data.qi","body":{"api-key1":"api-val1"},
"product":"[com.your-company.your-name:your_product]","device":"[dev:000000000000000]"}'

    {}

    The --request POST option tells cURL to make a POST request instead of its default GET request.

    The API URL is specified by --location 'https://api.notefile.net/req'.

    The --header 'X-SESSION-TOKEN: [your_session_token]' must include your session token in order to authorize your request.

    The --data '{...}' option must be filled in with the details of your Notehub request. Make sure you populate both the "product": and "device": keys with the respective ProductUID and DeviceUID, which were queried from your Notecard earlier.

    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!

    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.

    One helpful thing to know about Notes synced from Notehub to the Notecard is that they 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 .

    note

    Don't forget to disconnect Your Notecard!

    Once you're done using the in-browser terminal, be sure to disconnect it by clicking the "Disconnect" link in the terminal header.

    Gif of clicking the Disconnect button on the in-browser terminal