Notecard CLI

The Notecard CLI is a command-line utility for interaction with a Notecard connected directly to a computer over USB. It is meant to serve as a development and debugging aid as you build Notecard-powered applications.

note

Use the Notecard Playground to interact with your Device

This site provides an in-browser terminal that emulates much of the functionality of the Notecard CLI. Access the terminal via the Notecard Playground or the expansion button at the top right of your screen, assuming you're using a supported browser (Chrome, Edge, or Opera).

Installation

To install the Notecard CLI, you can use either a pre-built binary, or build the binary from source.

Option 1: Download a Pre-Built Binary (Recommended)

To install the Notecard CLI, visit the releases page of the note-cli repository and download the binary for your operating system. Extract the notecard utility and place it in your PATH.

Option 2: Build a Binary From Source

Alternatively, if you have Go and the Go tools installed and want to build from source, you can clone the note-cli repo and build the Notecard CLI directly with the following commands:

cd notecard && go get -u . && go build .

Usage

Once the Notecard CLI is installed, use the notecard command to view available arguments, as well as a list of available serial ports detected by the utility.

The Notecard will show up as tty.usbmodemNOTE1, ttyACM0, and COMx on macOS, Linux, and Windows respectively. The three asterisks (***) next to a device name indicates the default device that will be used, if the port flag is not provided.

If the CLI detects a single Notecard available via serial, it will issue all of the commands below directly on that device. If you have multiple Notecards connected and wish to specify a serial port, use the port flag, followed by the device address for your OS.

notecard -port /dev/cu.usbmodem3 -info

The rest of this guide details a number of common CLI commands.

Obtain Notecard Info

Use the info flag to obtain a view of Notecard configuration, network state, sensors, and onboard storage.

notecard -info

This command returns a formatted view of data.

Make a Single Request

To make a single request, use the req flag, followed by the full JSON request string, as outlined in the Notecard API Reference.

notecard -req '{"req":"hub.get"}'

This command sends the specified request to the Notecard and returns the result.

warning

When using the Notecard CLI with the Windows Command Prompt (cmd.exe), make sure to escape any double quotes used in the request before executing the command, like so:

COPY
notecard -req "{\"req\":\"hub.get\"}"

Use Interactive Request Mode

If you need to issue a number of requests to the Notecard, you can also use the play flag to enter interactive mode. In this mode, the Notecard expects direct JSON requests and returns JSON responses. Note: This is the same mode supported in our in-browser terminal and the Notecard Playground.

notecard -play

Exit interactive mode by typing q.

Set the ProductUID and Serial number

The product and sn flags provide a shorthand way to set the ProductUID and Serial Number on the Notecard. Both flags issue a hub.set request to the Notecard.

notecard -product 'org.soda-cola.vending-machine.v2'

{"req":"hub.set","product":"org.soda-cola.vending-machine.v2"}
{}

notecard -sn 'Scranton-12'

{"req":"hub.set","sn":"Scranton-12"}
{}

Manually Initiate a Notehub Sync

To manually initiate a sync between the Notecard and Notehub, use the sync flag.

notecard -sync

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

Trace Notecard Output

To trace the Notecard's activity, use the trace flag. This mode is similar to play in that it accepts interactive JSON requests, but also outputs trace messages from the Notecard.

notecard -trace

> t
on
> {"req":"hub.sync"}
{}
S9705:14.08 sync: sync triggered by manual sync request
S9705:14.08 sync: work: begin (anything pending) {sync-begin}
S9705:14.08 sync: request: get notebox change summary
S9705:15.64 sync: work: completed (nothing was pending) {sync-end}
S9705:15.64 sync: advancing last sync time from 16:05:45Z to 16:08:00Z

Run a Setup Script

You can instruct the CLI to send a series of requests to the Notecard with the setup flag. This command is useful for simplifying some of the Notecard configuration requests across a number of similar devices.

The requests should be defined in a file with a .json extension and a request on each line of the file. For example, the following script contains a series of requests for configuring the Notecard as a standalone asset tracker:

note

Be sure to remove any comments (denoted by #) in the JSON below before running the script!

COPY
# Tracking Device setup script version no. is published in an env var so
# that it's visible within the Notehub's Device Environment Variable UI
{"req":"env.default","name":"setup_script_version","text":"1.1.1"}
 
# Set product UID to one that's registered in our product
{"req":"hub.set","product":"org.soda-cola.vending-machine.v2"}
 
# Hourly sync if data is available, with weekly inbound as a backup
{"req":"hub.set","mode":"periodic","outbound":60,"inbound":1440,"align":true}
 
# Daily sampling of the tracker's location
{"req":"card.location.mode","mode":"periodic","seconds":86400}
 
# Track location in the _track.qo Notefile and add a weekly heartbeat if no movement
{"req":"card.location.track","start":true,"heartbeat":true,"hours":168}
 
# Configure voltage monitoring for a Notecarrier-AA with three L91 batteries
{"req":"card.voltage","mode":"l91"}

Then, use the setup flag and the JSON file on each connected Notecard:

notecard -setup config-tracker.json

Wrap A Binary for Outboard Firmware Update

You use the Notecard utility to create a binpack image, which is a thin wrapper around a base binary that the Notecard uses to optimize binary installation to a known memory address, or package multiple binaries and their destination memory addresses into a single file. This capability is typically used when performing Notecard Outboard Firmware Updates on a host MCU.

The syntax of binpack is as follows:

COPY
notecard -binpack <host_arch> <memory_addr>:<binary.bin> [<memory_addr>:<binary.bin> ...]

• <host_arch> - Replace with the architecture of your host MCU. (See the card.dfu request's name argument for a list of possible values.)
• <memory_addr> - The address* where the binary should be installed.
• <binary.bin> - The binary file to package.

* Minimally, the page of memory associated with the address provided will be completely erased and rewritten.

Targeting an STM32 device and performing binpack on the Arduino example provided above would result in the following syntax:

COPY
notecard -binpack stm32 0x8000000:Example1_NotecardBasics.ino.bin

After the command executes, you will see output similar to the following:

COPY
2022-10-20-205150.binpack now incorporates 1 files and is 28999 bytes:

HOST: stm32
LOAD: Example1_NotecardBasics.ino.bin,0x08000000,0x70a8,0x70a8

Output Notecard Details into a Text File

If you need to output device details or certificates from a single or batch of Notecards, you can use the scan flag, followed by the name of a file in which to output details. When run, the Notecard CLI will create the output JSON file, and a CSV file containing the DeviceUID for the Notecard.

notecard -scan configured.json

*** new file: configured.json
*** new file: configured.csv
 
dev:000000000000000
 
*** please remove the notecard

scan can be used with multiple devices in sequence, without rerunning the utility.

notecard -scan configured.json

dev:000000000000000
 
*** please remove the notecard
 
*** please insert the next notecard, or enter q to quit
 
dev:000000000000000
 
*** please remove the notecard

When used together, scan and setup allow developers to quickly configure a set of Notecards for deployment.

notecard -setup config-tracker.json -scan configured.json

Provisioning a Notecard with an Alternative Embedded SIM

If you are working with a variant of the Notecard that uses an alternative embedded SIM from a partner (for example, Twilio), you'll need to perform an additional provisioning step to ensure that the SIM on your device is properly registered with that carrier. You can do so with the provisioning flag, which embeds a token for your carrier onto the device.

As an example, for Twilio, your provisioning token is your Account SID and Auth Token, separated by a colon. This flag can be used with scan and setup to provision multiple Notecards at once.

notecard -provision <your_twilio_sid>:<your_twilio_token>

dev:000000000000000
twilio: device provisioned: status:new

Additional Resources

• Complete API Reference
• note-cli GitHub Repository