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.
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 Brave).
To install the Notecard CLI, visit the
releases page of the note-go repository
and download the binary for your operating system. Extract the notecard
utility and place it in your PATH
.
Alternatively, if you have Go and the Go tools installed and want to build from source, you can clone the note-go repo and build the Notecard CLI directly with the following commands:
$ go get -u . && go build .
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.
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.
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.
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
.
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"}
{}
To manually initiate a sync between the Notecard and Notehub, use the
sync
flag.
$ notecard -sync
{"req":"hub.sync"}
{}
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
Finally, 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:
{"req":"hub.set","product":"org.soda-cola.vending-machine.v2"}
{"req":"hub.set","mode":"periodic","outbound":60,"inbound":1440,"align":true}
{"req":"card.aux","mode":"track"}
{"req":"card.location.mode","mode":"periodic","seconds":5}
{"req":"card.location.track","start":true,"heartbeat":true,"hours":4}
Then, use the setup
flag and the JSON file on each connected Notecard:
$ notecard -setup config-tracker.json