card Requests
The Notecard provides a number of requests that can be used to
configure the behavior of the Notecard, its pins, its use of GPS and
accelerometer data, and to query the state of the Device, its network connection
and peripherals. All of these requests begin with the card prefix.
card.attn CellCell+WiFiLoRaWiFi
Configure hardware notification from the Notecard to MCU host. Note: Requires a connection between the notecard ATTN pin and a GPIO pin on the host MCU.
See
card.attnin action as part of the Low-Power Digital Signage, Valve Monitor, and Flow-Rate Monitor accelerator projects.
mode
string
A comma-separated list of one or more of the following keywords. Some keywords are only supported on certain types of Notecards.
"" CellCell+WiFiWiFi
Fetches currently pending events in the "files" collection.
"arm" CellCell+WiFiLoRaWiFi
Clear "files" events and cause the ATTN pin to go LOW. After an event occurs or
"seconds" has elapsed, the ATTN pin will then go HIGH (a.k.a. "fires"). If
"seconds" is 0, no timeout will be scheduled. If ATTN is armed, calling arm
again will disarm (briefly pulling ATTN HIGH), then arm (non-idempotent).
"auxgpio" CellCell+WiFiLoRaWiFi
When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using
-auxpgio.
"connected" CellCell+WiFiWiFi
When armed, will cause ATTN to fire whenever the module connects
to cellular. Disable with -connected.
"disarm" CellCell+WiFiLoRaWiFi
Causes ATTN pin to go HIGH if it had been LOW.
Passing both "disarm" and "-all" clears all ATTN monitors currently set.
"env" CellCell+WiFiLoRaWiFi
When armed, causes ATTN to fire if an environment variable changes on the
Notecard. Disable by using -env.
"files" CellCell+WiFiLoRaWiFi
When armed, will cause ATTN to fire if any of the "files" are
modified. Disable by using -files.
"location" CellCell+WiFiWiFi
When armed, will cause ATTN to fire whenever the Notecard GPS module makes
a position fix. Disable by using -location.
"motion" CellCell+WiFiWiFi
When armed, will cause ATTN to fire whenever the accelerometer
detects module motion. Disable with -motion.
"motionchange" CellCell+WiFiWiFi
When armed, will cause ATTN to fire whenever the card.motion,mode changes
from "moving" to "stopped" (or vice versa). Learn how to configure this feature
in this guide.
"rearm" CellCell+WiFiWiFi
Will arm ATTN if not already armed. Otherwise, resets the values of mode,
files, and seconds specified in the initial arm or rearm request
(idempotent).
"signal" CellCell+WiFiWiFi
When armed, will cause ATTN to fire whenever the Notecard receives a signal.
"sleep" CellCell+WiFiWiFi
Instruct the Notecard to pull the ATTN pin low for a period of time, and optionally keep a payload in memory. Can be used by the host to sleep the host MCU.
"usb" CellCell+WiFiLoRaWiFi
When armed, will enable USB power events firing the ATTN pin. Disable with
-usb.
"watchdog" CellCell+WiFiWiFi
Not an "arm" mode, rather will cause the ATTN pin to go from HIGH to LOW, then HIGH if the notecard fails to receive any JSON requests for "seconds." In this mode, "seconds" must be >= 60.
"wireless" CellCell+WiFiWiFi
Instruct the Notecard to fire the ATTN pin whenever the
card.wireless status
changes.
files
array (optional)
A list of Notefiles to watch for file-based interrupts.
seconds
integer (optional)
To set an ATTN timeout when arming, or when using sleep.
NOTE: When the Notecard is in continuous mode, the seconds timeout is serviced by
a routine that wakes every 15 seconds. You can predict when the device will
wake, by rounding up to the nearest 15 second interval.
payload
base64 string (optional)
When using sleep mode, a payload of data from the host that the Notecard
should hold in memory until retrieved by the host.
start
boolean (optional)
When using sleep mode and the host has reawakened, request the Notecard to
return the stored payload.
verify
boolean (optional)
When true, returns the current attention mode configuration, if any.
off
boolean (optional)
When true, completely disables ATTN processing and sets the pin OFF. This
setting is retained across device restarts.
on
boolean (optional)
When true, enables ATTN processing. This setting is retained across device
restarts.
{
"req": "card.attn",
"mode": "arm,connected"
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm, connected");
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "arm, connected"
card.Transaction(req)Configure the Notecard to perform an interrupt on a successful connection to Notehub.
{
"req": "card.attn",
"mode": "arm,files",
"files": ["data.qi", "my-settings.db"]
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm, files");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("data.qi"));
JAddItemToArray(files, JCreateString("my-settings.db"));
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "arm, files"
req["files"] = ["data.qi", "my-settings.db"]
card.Transaction(req)Configure the Notecard to perform an interrupt on the data.qi and
my-settings.db Notefiles.
{
"req": "card.attn",
"mode": "arm,location"
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm, location");
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "arm, location"
card.Transaction(req)Configure the Notecard to perform an interrupt when the Notecard makes a position fix.
{
"req": "card.attn",
"mode": "arm,motion"
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm, motion");
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "arm, motion"
card.Transaction(req)Configure the Notecard to perform an interrupt when the Notecard detects motion.
{
"req": "card.attn",
"mode": "arm,signal"
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm, signal");
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "arm, signal"
card.Transaction(req)Configure the Notecard to perform an interrupt when the Notecard receives a signal.
{
"req": "card.attn",
"mode": "watchdog",
"seconds": 60
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "watchdog");
JAddNumberToObject(req, "seconds", 60);
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "watchdog"
req["seconds"] = 60
card.Transaction(req)Configure the Notecard to function as a watchdog timer with a 60 second timeout.
{
"req": "card.attn",
"mode": "sleep",
"seconds": 3600,
"payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "sleep");
JAddNumberToObject(req, "seconds", 3600);
JAddStringToObject(req, "payload", "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ==");
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "sleep"
req["seconds"] = 3600
req["payload"] = "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
card.Transaction(req)Configure the Notecard to instruct the host MCU to sleep for a period of time.
{
"req": "card.attn",
"start": true
}J *req = NoteNewRequest("card.attn");
JAddBoolToObject(req, "sync", true);
NoteRequest(req);req = {"req": "card.attn"}
req["start"] = True
card.Transaction(req)Retrieve a payload from the Notecard after sleep.
{
"req": "card.attn",
"mode": "disarm,-all"
}J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "disarm,-all");
NoteRequest(req);req = {"req": "card.attn"}
req["mode"] = "disarm,-all"
card.Transaction(req)Disarm all interrupts.
Response Members
set
boolean
Reflects the state of the attention pin. The set field is true when the
attention pin is HIGH, otherwise the set field will not be present when
the attention pin is LOW.
files
array
A list of files changed since file attention mode was set. In addition, this
field will include keywords to signify the occurrence of other attention mode
triggers:
"connected"
"env"
"files"
"location"
"motion"
"timeout"
"watchdog"
payload
base64 string
When using sleep mode with a payload, the payload provided by the host
to the Notecard.
time
UNIX Epoch time
When using sleep mode with a payload, the time that the payload was stored
by the Notecard.
off
boolean
This field is present and set to true if ATTN processing has been disabled with
the off argument.
{
"files": ["data.qi", "modified"],
"set": true
}card.aux CellCell+WiFiLoRaWiFi
Configure various uses of the general-purpose I/O (GPIO) pins AUX1-AUX4 on
the Notecard edge connector for tracking applications and simple GPIO sensing
and counting tasks.
See
card.auxin action as part of the Refrigerator Monitor, Motor Monitor and Vibration, and Sump Level Monitor accelerator projects.
noteUtilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces.
mode
string
The AUX mode. Must be one of the following keywords. Some keywords are only supported on certain types of Notecards.
"dfu" CellCell+WiFiWiFi
Enable the Notecard's AUX1 pin for Outboard Firmware Updates.
When enabled, AUX1 is active LOW when a DFU is in progress, and HIGH otherwise.
See Using DFU Mode
for more information.
"gpio" CellCell+WiFiLoRaWiFi
Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output
LOW, AUX3 as an output HIGH, and AUX4 as an input. See
Using AUX GPIO Mode
for more information.
"led" CellCell+WiFiWiFi
When wiring LEDs to the Notecard's AUX pins (as is done when using monitor mode), use this mode along with the card.led API to manually enable/disable individual red, green, and/or yellow LEDs.
"monitor" CellCell+WiFiWiFi
If you plan to place your Notecard in an enclosure, monitor mode can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity.
"motion" CellCell+WiFiWiFi
Supplement autonomous tracking with digital inputs and a status output. See Using AUX Motion Mode for more information.
"neo" CellCell+WiFiWiFi
When wiring a NeoPixel or NeoPixel strip to the Notecard's AUX2 pin (as is done when using neo-monitor mode), use this mode along with the card.led API to manually enable/disable a single NeoPixel.
"neo-monitor" CellCell+WiFiLoRaWiFi
Similar to monitor mode, neo-monitor mode supports NeoPixel LEDs that can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity.
"off" CellCell+WiFiLoRaWiFi
Disable AUX mode.
"track" CellCell+WiFiWiFi
Enhance Notes in the
_track.qo Notefile
with temperature, pressure, and humidity readings from a connected BME280 sensor.
See Using AUX Track Mode
for more information.
"track-monitor" CellCell+WiFiWiFi
Combines the functionality of the track and monitor AUX modes.
"track-neo-monitor" CellCell+WiFiWiFi
Combines track and monitor modes while also supporting NeoPixel LEDs that
allow for monitoring Notecard activity. See the
neo-monitor mode
documentation for additional context.
"-" CellCell+WiFiLoRaWiFi
Resets the AUX mode to its default value ("off").
usage
array of strings (required for gpio mode)
An ordered list of pin modes for each AUX pin when in GPIO mode. The following values can be used on all Notecards:
"" to leave the pin unchanged.
"off" to disable the pin.
"high" to set the pin as a HIGH output.
"low" to set the pin as a LOW output.
"input" to set the pin as an input.
"input-pulldown" to set the pin as a pull-down input.
"input-pullup" to set the pin as a pull-up input.
And the following values can be used on Notecard Cellular, Notecard Cell+WiFi, and Notecard WiFi:
"count" to set the pin as an input (interrupt) that increments a counter for
each rising edge pulse on the pin. It is up to the device's designer to make
sure that the signal is either HIGH or LOW at any time, and is never left
floating.
"count-pulldown" Same as count usage, but a pull-down resistor internal to
the Notecard will automatically keep the pin from floating.
"count-pullup" Same as count usage, but a pull-up resistor internal to the
Notecard will automatically keep the pin from floating and falling edges of
pulses are counted.
seconds
integer (optional)
When in gpio mode, if an AUX pin is configured as a count type, the
count of rising edges can be broken into samples of this duration.
Passing 0 or omitting this field will total into a single sample.
max
integer (optional)
When in gpio mode, if an AUX pin is configured as a count type, the
maximum number of samples of duration seconds, after which all subsequent
counts are added to the final sample. Passing 0 or omitting this value will
provide a single incrementing count of rising edges on the pin.
start
boolean (optional)
When in gpio mode, if an AUX pin is configured as a count type, set to
true to reset counters and start incrementing.
gps
boolean (optional)
Deprecated
If true, along with "mode":"track" the Notecard supports the use of an
external GPS module.
This argument is deprecated. Use the
card.aux.serial request with a mode of "gps" instead.
rate
integer (optional)
The AUX UART baud rate for debug communication over the AUXRX and AUXTX pins.
sync
boolean (optional)
This argument is not available on Notecard LoRa.
If true, for pins set as input by usage, the Notecard will autonomously
report any state changes as new notes in file. For pins
used as counter, the Notecard will use an interrupt to count pulses and will
report the total in a new note in file unless it has been noted in the
previous second.
file
string (optional)
This argument is not available on Notecard LoRa.
The name of the Notefile used to report state changes when used in conjunction
with "sync": true. Default Notefile name is _button.qo.
connected
boolean (optional)
If true, defers the sync of the state change Notefile to the next sync as
configured by the hub.set request.
limit
boolean (optional)
If true, along with "mode":"track" and gps:true the Notecard will disable
concurrent modem use during GPS tracking.
sensitivity
integer (optional)
When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this
controls the brightness of NeoPixel lights, where 100 is the maximum
brightness and 1 is the minimum.
ms
integer (optional)
When in gpio mode, this argument configures a debouncing interval. With a
debouncing interval in place, the Notecard excludes all transitions with a
shorter duration than the provided debounce time, in milliseconds. This interval
only applies to GPIOs configured with a usage of count, count-pulldown, or
count-pullup.
count
integer (optional)
Cell Cell+WiFi WiFi
When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this
controls the number of NeoPixels to use in a strip. Possible values are 1,
2, or 5. See
Using Neo-Monitor Mode
for more information.
offset
integer (optional)
Cell Cell+WiFi WiFi
When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this is
the 1-based index in a strip of NeoPixels that determines which single NeoPixel
the host can command. See
Using Neo-Monitor Mode
for more information.
{
"req": "card.aux",
"mode": "dfu"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "dfu");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "dfu"
card.Transaction(req)Enable the Notecard's AUX1 pin for Outboard Firmware Updates.
When enabled, AUX1 is active LOW when a DFU is in progress, and HIGH otherwise.
See Using DFU Mode
for more information.
{
"req": "card.aux",
"mode": "gpio",
"usage": ["off", "low", "high", "input"]
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("off")); // AUX1
JAddItemToArray(pins, JCreateString("low")); // AUX2
JAddItemToArray(pins, JCreateString("high")); // AUX3
JAddItemToArray(pins, JCreateString("input")); // AUX4
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
"off", # AUX1
"low", # AUX2
"high", # AUX3
"input" # AUX4
]
card.Transaction(req)Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output
LOW, AUX3 as an output HIGH, and AUX4 as an input. See
Using AUX GPIO Mode
for more information.
{
"req": "card.aux",
"mode": "gpio",
"usage": ["off", "low", "high", "count"],
"seconds": 2,
"max": 5,
"start": true
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("off")); // AUX1
JAddItemToArray(pins, JCreateString("low")); // AUX2
JAddItemToArray(pins, JCreateString("high")); // AUX3
JAddItemToArray(pins, JCreateString("count")); // AUX4
JAddNumberToObject(req, "seconds", 2);
JAddNumberToObject(req, "max", 5);
JAddBoolToObject(req, "start", true);
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
"off", # AUX1
"low", # AUX2
"high", # AUX3
"input" # AUX4
]
req["seconds"] = 2
req["max"] = 5
req["start"] = True
card.Transaction(req)Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output
LOW, AUX3 as an output HIGH, and AUX4 as a count.
{
"req": "card.aux",
"mode": "gpio",
"usage": ["off", "low", "high", "input"],
"sync": true,
"file": "statechange.qo"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("off")); // AUX1
JAddItemToArray(pins, JCreateString("low")); // AUX2
JAddItemToArray(pins, JCreateString("high")); // AUX3
JAddItemToArray(pins, JCreateString("input")); // AUX4
JAddBoolToObject(req, "sync", true);
JAddStringToObject(req, "file", "statechange.qo");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
"off", # AUX1
"low", # AUX2
"high", # AUX3
"input" # AUX4
]
req["sync"] = True
req["file"] = "statechange.qo"
card.Transaction(req){
"req": "card.aux",
"mode": "monitor"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "monitor");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "monitor"
card.Transaction(req)If you plan to place your Notecard in an enclosure, monitor mode can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity.
{
"req": "card.aux",
"mode": "neo-monitor"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "neo-monitor");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "neo-monitor"
card.Transaction(req)Similar to monitor mode, neo-monitor mode supports NeoPixel LEDs that can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity.
{
"req": "card.aux",
"mode": "motion"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "motion");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "motion"
card.Transaction(req)Supplement autonomous tracking with digital inputs and a status output. See Using AUX Motion Mode for more information.
{
"req": "card.aux",
"rate": 9600
}J *req = NoteNewRequest("card.aux");
JAddNumberToObject(req, "rate", 9600);
NoteRequest(req);req = {"req": "card.aux"}
req["rate"] = 9600
card.Transaction(req){
"req": "card.aux",
"mode": "track"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "track");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "track"
card.Transaction(req)Enhance Notes in the
_track.qo Notefile
with temperature, pressure, and humidity readings from a connected BME280 sensor.
See Using AUX Track Mode
for more information.
Response Members
mode
string
The current AUX mode, or off if not set.
state
array of JSON objects
When in AUX gpio mode, the state of each AUX pin. Possible values are:
{} when the pin is off.
{"high": true}
{"low": true}
{"input": true}
{"count": [4]} where each item in the array is the count per sample.
time
UNIX Epoch time
When in AUX gpio mode, and if count is enabled on an AUX pin, the time
that counting started.
seconds
integer
When in AUX gpio mode, and if count is enabled on an AUX pin, the number
of seconds per sample.
power
boolean
If true, indicates the Notecard has USB (main) power. This parameter only
appears in the body of the Note in Notehub if using "sync":true.
{
"mode": "gpio",
"state": [
{}, // AUX1
{ "low": true }, // AUX2
{ "high": true }, // AUX3
{ "count": [3] } // AUX4
],
"time": 1592587637,
"seconds": 2
}card.aux.serial CellCell+WiFiWiFi
Configure various uses of the AUXTX and AUXRX pins on the Notecard's edge
connector.
noteUtilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces. See this guide for an example of connecting to the Notecard AUX pins using an FTDI cable.
See
card.aux.serialin action as part of the Power Quality Monitoring, Generator Activity Monitor, and Remote Power Control accelerator projects.
mode
string
The AUX mode. Must be one of the following:
"req" (Default) for request/response monitoring on the AUX pins.
"gps" Use an external GPS/GNSS module on the AUX pins.
"notify" Used along with one or more of the options below to send streaming
data or notification data over the AUX pins:
"notify,accel" Used to stream readings from the onboard accelerometer over
AUX.
"notify,signals" Used to notify the host of any
Inbound Signals
from Notehub.
"notify,env" Used to notify the host of Environment Variable changes over AUX.
"notify,dfu" Used to notify the host that the Notecard has downloaded updated
host firmware.
duration
integer (optional)
If using "mode": "accel", specify a sampling duration for the Notecard
accelerometer.
rate
integer (optional)
The baud rate or speed at which information is transmitted over AUX serial. The default
is 115200 unless using GPS, in which case the default is 9600.
limit
boolean (optional)
If true, along with "mode":"gps" the Notecard will disable concurrent modem
use during GPS tracking.
max
integer (optional)
The maximum amount of data to send per session, in bytes. This is typically set
to the size of the receive buffer on the host minus 1. For example,
note-arduino uses a buffer size of (SERIAL_RX_BUFFER_SIZE - 1).
ms
integer (optional)
The delay in milliseconds before sending a buffer of max size.
minutes
integer (optional)
When using "mode": "dfu", specify an interval for notifying the host.
{
"req": "card.aux.serial",
"mode": "req"
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "req");
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "req"
card.Transaction(req){
"req": "card.aux.serial",
"mode": "gps"
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "gps");
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "gps"
card.Transaction(req)Use an external GPS/GNSS module connected to the AUX pins. Using an external
GPS/GNSS module allows you to acquire GPS/GNSS location while Notecard is
connected to Notehub in continuous mode. Learn more at
Using AUX Serial GPS Mode.
{
"req": "card.aux.serial",
"mode": "notify,accel",
"duration": 500
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,accel");
JAddNumberToObject(req, "duration", 500);
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "accel"
req["duration"] = 500
card.Transaction(req)Send raw readings from the onboard accelerometer over AUX every 500 ms. Data is
sent in the format: {"type":"accel","x":-29,"y":-122,"z":976}
{
"req": "card.aux.serial",
"mode": "notify,signals"
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,signals");
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "notify,signals"
card.Transaction(req)Turn on Inbound Signals from Notehub for low-latency communication.
{
"req": "card.aux.serial",
"mode": "notify,env"
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,env");
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "notify,env"Notify host of Environment Variable changes over AUX.
{
"req": "card.aux.serial",
"mode": "notify,dfu",
"minutes": 5
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,dfu");
JAddNumberToObject(req, "minutes", 5);
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "notify,dfu"
req["minutes"] = 5Notify the host that the Notecard has downloaded host firmware.
{
"req": "card.aux.serial",
"mode": "notify,accel,env",
"duration": 500
}J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,accel,env");
JAddNumberToObject(req, "duration", 500);
NoteRequest(req);req = {"req": "card.aux.serial"}
req["mode"] = "notify,accel,env"
req["duration"] = 500
card.Transaction(req)Subscribe to multiple notifications at once.
Response Members
mode
string
The current AUX mode.
rate
integer
The baud rate or speed at which information is transmitted over AUX serial.
{
"mode": "req",
"rate": 115200
}card.binary CellCell+WiFiWiFi
View the status of the binary storage area of the Notecard and optionally clear
any data and related card.binary variables.
See the guide on
Sending and Receiving Large Binary Objects
for best practices when using card.binary.
delete
boolean (optional)
Clear the COBS area on the Notecard and reset all related arguments previously
set by a card.binary request.
{
"req": "card.binary"
}J *req = NoteNewRequest("card.binary");
NoteRequest(req);req = {"req": "card.binary"}
card.Transaction(req){
"req": "card.binary",
"delete": true
}J *req = NoteNewRequest("card.binary");
JAddBoolToObject(req, "delete", true);
NoteRequest(req);req = {"req": "card.binary"}
req["delete"] = True
card.Transaction(req)Response Members
cobs
integer
The size of COBS-encoded data stored in the reserved area (without the trailing
\n).
connected
boolean
Returns true if the Notecard is connected to the network.
err
string
If present, a string describing the error that occurred during transmission.
length
integer
The amount of unencoded data currently stored (in bytes).
max
integer
The space available (in bytes) for storing unencoded data on the Notecard.
status
string
The MD5 checksum calculated for the entire unencoded buffer.
{
"connected": true,
"max": 130554,
"status": "ce6fdef565eeecf14ab38d83643b922d",
"length": 4,
"cobs": 5
}card.binary.get CellCell+WiFiWiFi
Returns binary data stored in the binary storage area of the Notecard. The response to this API command first returns the JSON-formatted response object, then the binary data.
See the guide on
Sending and Receiving Large Binary Objects
for best practices when using card.binary.
cobs
integer (optional)
The size of the COBS-encoded data you are expecting to be returned (in bytes).
offset
integer (optional)
Used along with length, the number of bytes to offset the binary payload from
0 when retrieving binary data from the binary storage area of the Notecard.
Primarily used when retrieving multiple fragments of a binary payload from the
Notecard.
length
integer (optional)
Used along with offset, the number of bytes to retrieve from the binary
storage area of the Notecard.
{
"req": "card.binary.get"
}J *req = NoteNewRequest("card.binary.get");
NoteRequest(req);req = {"req": "card.binary.get"}
card.Transaction(req)Response Members
status
string
The MD5 checksum of the data returned, after it has been decoded.
err
string
If present, a string describing the error that occurred during transmission.
{
"status":"ce6fdef565eeecf14ab38d83643b922d"
}card.binary.put CellCell+WiFiWiFi
Adds binary data to the binary storage area of the Notecard. The Notecard expects to receive binary data immediately following the usage of this API command.
See the guide on
Sending and Receiving Large Binary Objects
for best practices when using card.binary.
offset
integer (optional)
The number of bytes to offset the binary payload from 0 when appending the binary data to the binary storage area of the Notecard. Primarily used when sending multiple fragments of one binary payload to the Notecard.
cobs
integer
The size of the COBS-encoded data (in bytes).
status
string
The MD5 checksum of the data, before it has been encoded.
{
"req": "card.binary.put",
"cobs": 5,
"status": "ce6fdef565eeecf14ab38d83643b922d"
}J *req = NoteNewRequest("card.binary.put");
JAddNumberToObject(req, "cobs", 5);
JAddStringToObject(req, "status", "ce6fdef565eeecf14ab38d83643b922d");
NoteRequest(req);req = {"req": "card.binary.put"}
req["cobs"] = 5
req["status"] = "ce6fdef565eeecf14ab38d83643b922d"
card.Transaction(req)Response Members
err
string
If present, a string describing the error that occurred during transmission.
card.carrier CellCell+WiFiWiFi
Uses the AUX_CHARGING pin on the Notecard edge connector to notify the
Notecard that the pin is connected to a Notecarrier that supports charging,
using open-drain.
Once set, {"charging":true} will appear in a response if the Notecarrier is
currently indicating that charging is in progress.
mode
string
The AUX_CHARGING mode. Set to "charging" to tell the Notecard that
AUX_CHARGING is connected to a Notecarrier that supports charging on
AUX_CHARGING. Set to "-" or "off" to turn off the AUX_CHARGING detection.
{
"req": "card.carrier",
"mode": "charging"
}J *req = NoteNewRequest("card.carrier");
JAddStringToObject(req, "mode", "charging");
NoteRequest(req);req = {"req": "card.carrier"}
req["mode"] = "charging"
card.Transaction(req)Response Members
mode
string
The current AUX_CHARGING mode, or off if not set.
charging
boolean
Will display true when in AUX_CHARGING "charging" mode.
{
"mode": "charging",
"charging": true
}card.contact CellCell+WiFiWiFi
Used to set or retrieve information about the Notecard maintainer. Once set, this information is synced to Notehub.
name
string (optional)
Set the name of the Notecard maintainer.
org
string (optional)
Set the organization name of the Notecard maintainer.
role
string (optional)
Set the role of the Notecard maintainer.
email
string (optional)
Set the email address of the Notecard maintainer.
{
"req": "card.contact",
"name": "Tom Turkey",
"org": "Blues",
"role": "Head of Security",
"email": "tom@blues.com"
}J *req = NoteNewRequest("card.contact");
JAddStringToObject(req, "name", "Tom Turkey");
JAddStringToObject(req, "org", "Blues");
JAddStringToObject(req, "role", "Head of Security");
JAddStringToObject(req, "email", "tom@blues.com");
NoteRequest(req);req = {"req": "card.contact"}
req["name"] = "Tom Turkey"
req["org"] = "Blues"
req["role"] = "Head of Security"
req["email"] = "tom@blues.com"
rsp = card.Transaction(req)Response Members
name
string
Name of the Notecard maintainer.
org
string
Organization name of the Notecard maintainer.
role
string
Role of the Notecard maintainer.
email
string
Email address of the Notecard maintainer.
{
"name": "Tom Turkey",
"org": "Blues",
"role": "Head of Security",
"email": "tom@blues.com"
}card.dfu CellCell+WiFiWiFi
Used to configure a Notecard for Notecard Outboard Firmware Update.
name
string
One of the supported classes of host MCU. Supported MCU classes are "esp32",
"stm32", "stm32-bi", "mcuboot" (added in v5.3.1), and "-", which
resets
the configuration.
The "bi" in "stm32-bi" stands for "boot inverted", and the "stm32-bi" option
should be used on STM32 family boards where the hardware boot pin is assumed to
be active low, instead of active high.
Supported MCUs can be found on the Notecarrier F datasheet.
on
boolean (optional)
Set to true to enable Notecard Outboard Firmware Update.
off
boolean (optional)
Set to true to disable Notecard Outboard Firmware Update from occurring.
seconds
integer (optional)
When used with "off":true, disable Notecard Outboard Firmware Update
operations for the specified number of seconds.
stop
boolean (optional)
Set to true to disable the host RESET that is normally performed on the host
MCU when the Notecard starts up (in order to ensure a clean startup), and also
when the Notecard wakes up the host MCU after the expiration of a card.attn
"sleep" operation. If true, the host MCU will not be reset in these two
conditions.
start
boolean (optional)
Set to true to enable the host RESET if previously disabled with "stop":true.
mode
string (optional)
"altdfu" Cell+WiFi
Enable the Notecard Cell+WiFi's ALT_DFU pins (instead of the AUX pins) for use
with
Notecard Outboard Firmware Update.
"off" Cell+WiFi
Return the Notecard Cell+WiFi's ALT_DFU pins to their default state.
{
"req": "card.dfu",
"name": "stm32",
"on": true
}J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "stm32");
JAddBoolToObject(req, "on", true);
NoteRequest(req);req = {"req": "card.dfu"}
req["name"] = "stm32"
req["on"] = True
card.Transaction(req)Response Members
name
string
The class of MCU that the Notecard is currently configured to support for Outboard DFU.
{
"name": "stm32"
}card.illumination CellCell+WiFiWiFi
This request returns an illumination reading (in lux) from an OPT3001 ambient light sensor connected to Notecard's I2C bus. If no OPT3001 sensor is detected, this request returns an “illumination sensor is not available” error.
{
"req": "card.illumination"
}J *req = NoteNewRequest("card.illumination");
NoteRequest(req);req = {"req": "card.illumination"}
card.Transaction(req)Response Members
value
decimal
An illumination reading (in lux) from the attached OPT3001 sensor.
{
"value": 8806.4
}card.io CellCell+WiFiLoRaWiFi
Can be used to override the Notecard's I2C address from its default of 0x17
and change behaviors of the onboard LED and USB port.
i2c
decimal (optional)
The alternate address to use for I2C communication. Pass -1 to
reset
to the default address.
mode
string (optional)
"-usb"
Set to "-usb" to disable the Notecard's USB port. Re-enable the USB port with
"usb" or "+usb".
"+busy"
If set to "+busy", the Notecard's LED will be on when the Notecard is awake,
and off when the Notecard goes to sleep.
"-busy"
Resets "+busy" to its default, making the onboard LED blink only during
Notecard flash memory operations.
"i2c-master-disable"
Disables Notecard acting as an I2C master. Re-enable by using
"i2c-master-enable".
{
"req": "card.io",
"i2c": 24
}J *req = NoteNewRequest("card.io");
JAddNumberToObject(req, "i2c", 24);
NoteRequest(req);req = {"req": "card.io"}
req["i2c"] = 24
card.Transaction(req)Set the I2C address to 0x18.
{
"req": "card.io",
"mode": "+busy"
}J *req = NoteNewRequest("card.io");
JAddStringToObject(req, "mode", "+busy");
NoteRequest(req);req = {"req": "card.io"}
req["mode"] = "+busy"
card.Transaction(req)Response Members
{} means success.card.led CellCell+WiFiLoRaWiFi
Used along with the card.aux API to turn connected LEDs on/off or to manage a single connected NeoPixel.
If using monochromatic LEDs, they must be wired according to the instructions provided in the guide on Using Monitor Mode. Please note that the use of monochromatic LEDs is not supported by Notecard for LoRa.
If using NeoPixels, the NeoPixel (or strip of NeoPixels) must be wired according to the instructions provided in the guide on Using Neo-Monitor Mode.
See
card.ledin action as part of the Using LEDs and NeoPixels to Monitor Notecard Status sample app.
mode
string
Cell Cell+WiFi WiFi
LEDs: Used to specify the color of the LED to turn on or off. Possible
values are "red", "green", and "yellow".
Cell Cell+WiFi LoRa WiFi
NeoPixels: Used to specify the color of a single NeoPixel. Possible values
are "red", "green", "blue", "yellow", "cyan", "magenta", "orange",
"white", and "gray".
on
boolean
Set to true to turn the specified LED or NeoPixel on.
off
boolean
Set to true to turn the specified LED or NeoPixel off.
{
"req": "card.aux",
"mode": "led"
}
{
"req": "card.led",
"mode": "red",
"on": true
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "led");
NoteRequest(req);
req = NoteNewRequest("card.led");
JAddStringToObject(req, "mode", "red");
JAddBoolToObject(req, "on", true);
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "led"
card.Transaction(req)
req = {"req": "card.led"}
req["mode"] = "red"
req["on"] = True
card.Transaction(req)As shown above, the Notecard must also be in led mode and the LED(s) wired
according to the instructions provided in the guide on
Using Monitor Mode.
{
"req": "card.aux",
"mode": "neo"
}
{
"req": "card.led",
"mode": "blue",
"on": true
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "neo");
NoteRequest(req);
req = NoteNewRequest("card.led");
JAddStringToObject(req, "mode", "blue");
JAddBoolToObject(req, "on", true);
NoteRequest(req);req = {"req": "card.led"}
req["mode"] = "neo"
card.Transaction(req)
req = {"req": "card.led"}
req["mode"] = "blue"
req["on"] = True
card.Transaction(req)As shown above, the Notecard must also be in neo, neo-monitor, or
track-neo-monitor mode and wired according to the instructions provided in the
guide on
Using Neo-Monitor Mode.
Response Members
{} means success.card.location CellCell+WiFiLoRaWiFi
Retrieves the last known location of the Notecard and the time at which it was acquired. Use card.location.mode to configure location settings.
This request will return the cell tower location or triangulated location of the most recent session if a GPS/GNSS location is not available.
On Notecard LoRa this request can only return a location set through the
card.location.mode
request's "fixed" mode.
See
card.locationin action as part of the Cold Chain Monitor accelerator project.
{ "req": "card.location" }J *req = NoteNewRequest("card.location");
NoteRequest(req);req = {"req": "card.location"}
rsp = card.Transaction(req)Response Members
status
string
The current status of the Notecard GPS/GNSS connection.
mode
string
The GPS/GNSS connection mode. Will be continuous, periodic, or off.
lat
decimal
The latitude in degrees of the last known location.
lon
decimal
The longitude in degrees of the last known location.
time
UNIX Epoch time
The time of location capture.
max
integer
If a geofence is enabled by card.location.mode, meters from the geofence
center.
count
integer
The number of consecutive recorded GPS/GNSS failures.
dop
decimal
The "Dilution of Precision" value from the latest GPS/GNSS reading. The lower the value, the higher the confidence level of the reading. Values can be interpreted in this Wikipedia table.
{
"status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active}
{gps-signal} {gps-sats} {gps}",
"mode": "periodic",
"lat": 42.577600,
"lon": -70.871340,
"time": 1598554399,
"max": 25
}card.location.mode CellCell+WiFiLoRaWiFi
Sets location-related configuration settings. Retrieves the current location mode when passed with no argument.
See
card.location.modein action as part of the Piston Pump Motion Monitoring and Cold Chain Monitor accelerator projects.
mode
string (optional)
Must be one of:
"" to retrieve the current mode.
"off" to turn location mode off. Approximate location may still be
ascertained from Notehub.
"periodic" to sample location at a specified interval, if the device has
moved.
"continuous" to enable the Notecard's GPS/GNSS module for continuous sampling.
When in continuous mode the Notecard samples a new GPS/GNSS reading for every
new Note.
"fixed" to report the location as a fixed location using the specified lat
and lon coordinates. This is the only supported mode on Notecard LoRa.
seconds
integer (optional)
When in periodic mode, location will be sampled at this interval, if
the Notecard detects motion. If seconds is < 300, during periods of sustained
movement the Notecard will leave its onboard GPS/GNSS on continuously to avoid
powering the module on and off repeatedly.
vseconds
string (optional)
In periodic mode, overrides seconds with a voltage-variable value.
delete
boolean (optional)
Set to true to delete the last known location stored in the Notecard.
max
integer (optional)
Meters from a geofence center. Used to enable geofence location tracking.
lat
decimal (Default: last known location)
When in periodic or continuous mode, providing this value enables geofencing. The value you provide for this argument should be the latitude of the center of the geofence, in degrees.
When in fixed mode, the value you provide for this argument should be the latitude location of the device itself, in degrees.
lon
decimal (Default: last known location)
When in periodic or continuous mode, providing this value enables geofencing. The value you provide for this argument should be the longitude of the center of the geofence, in degrees.
When in fixed mode, the value you provide for this argument should be the longitude location of the device itself, in degrees.
minutes
int (Default: 5)
When geofence is enabled, the number of minutes the device should be outside the geofence before the Notecard location is tracked.
threshold
int (Default: 0)
When in periodic mode, the number of motion events (registered by the built-in
accelerometer) required to trigger GPS to turn on.
{
"req": "card.location.mode",
"mode": "continuous"
}J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "continuous");
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "continuous"
rsp = card.Transaction(req){
"req": "card.location.mode",
"mode": "periodic",
"seconds": 3600
}J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "seconds", 3600);
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["seconds"] = 3600
rsp = card.Transaction(req){
"req": "card.location.mode",
"mode": "periodic",
"vseconds": "usb:3600;high:14400;normal:43200;low:86400;dead:0"
}J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddStringToObject(req, "vseconds", "usb:3600;high:14400;normal:43200;low:86400;dead:0");
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["vseconds"] = "usb:3600;high:14400;normal:43200;low:86400;dead:0"
rsp = card.Transaction(req){
"req": "card.location.mode",
"mode": "periodic",
"lat": 42.5776,
"lon": -70.87134,
"max": 100,
"minutes": 2
}J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "lat", 42.577600);
JAddNumberToObject(req, "lon", -70.871340);
JAddNumberToObject(req, "max", 100);
JAddNumberToObject(req, "minutes", 2);
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["lat"] = 42.577600
req["lon"] = -70.871340
req["max"] = 100
req["minutes"] = 2
rsp = card.Transaction(req){
"req": "card.location.mode",
"mode": "fixed",
"lat": 42.5776,
"lon": -70.87134
}J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "fixed");
JAddNumberToObject(req, "lat", 42.577600);
JAddNumberToObject(req, "lon", -70.871340);
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "fixed"
req["lat"] = 42.577600
req["lon"] = -70.871340
rsp = card.Transaction(req)Response Members
mode
string
The current location mode.
seconds
integer
If specified, the periodic sample interval.
vseconds
string
If specified, the voltage-variable period.
max
integer
If geofence is enabled, the meters from geofence center.
lat
decimal
If geofence is enabled, the geofence center latitude in degrees.
lon
decimal
If geofence is enabled, the geofence center longitude in degrees.
minutes
integer
If geofence is enabled, the currently configured geofence debounce period.
threshold
integer
When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.
{
"mode": "continuous",
"max": 100,
"lat": 42.5776,
"lon": -70.87134,
"minutes": 2,
"threshold": 4
}card.location.track CellCell+WiFiWiFi
Store location data in a Notefile at the periodic interval, or using
a specified heartbeat.
This request is only available when the card.location.mode request has been set to
periodic—e.g. {"req":"card.location.mode","mode":"periodic","seconds":300}. If you
want to track and transmit data simultaneously consider
using an external GPS/GNSS module with the Notecard.
If you connect a BME280 sensor on the I2C bus, Notecard will include a temperature, humidity, and pressure reading with each captured Note. If you connect an ENS210 sensor on the I2C bus, Notecard will include a temperature and pressure reading with each captured Note. Learn more in _track.qo.
See
card.location.trackin action as part of the Cargo Tracker, Freight Car Door Motion and Location, and Animal Tracker accelerator projects.
start
boolean
Set to true to start Notefile tracking.
heartbeat
boolean
When start is true, set to true to enable tracking even when motion is
not detected. If using heartbeat, also set the hours below.
hours
integer
If heartbeat is true, add a heartbeat entry at this hourly interval. Use a
negative integer to specify a heartbeat in minutes instead of hours.
sync
boolean
Set to true to perform an immediate sync to the Notehub each time
a new Note is added.
stop
boolean
Set to true to stop Notefile tracking.
file
string (Default: _track.qo)
The Notefile in which to store tracked location data. See the
_track.qo Notefile's documentation
for details on the format of the data captured.
payload
string
A base64-encoded binary payload to be included in the next _track.qo Note. See
the guide on
Sampling at Predefined Intervals
for more details.
{
"req": "card.location.track",
"start": true
}J *req = NoteNewRequest("card.location.track");
JAddBoolToObject(req, "start", true);
NoteRequest(req);req = {"req": "card.location.track"}
req["start"] = True
rsp = card.Transaction(req){
"req": "card.location.track",
"stop": true
}J *req = NoteNewRequest("card.location.track");
JAddBoolToObject(req, "stop", true);
NoteRequest(req);req = {"req": "card.location.track"}
req["stop"] = True
rsp = card.Transaction(req){
"req": "card.location.track",
"start": true,
"sync": true,
"heartbeat": true,
"hours": 2
}J *req = NoteNewRequest("card.location.track");
JAddBoolToObject(req, "start", true);
JAddBoolToObject(req, "sync", true);
JAddBoolToObject(req, "heartbeat", true);
JAddNumberToObject(req, "hours", 2);
NoteRequest(req);req = {"req": "card.location.track"}
req["start"] = True
req["sync"] = True
req["heartbeat"] = True
req["hours"] = 2
rsp = card.Transaction(req)Response Members
start
boolean
true if tracking is enabled.
stop
boolean
true if tracking is disabled.
heartbeat
boolean
true if heartbeat is enabled.
seconds
integer
If tracking is enabled and a heartbeat hours value is not set, the
tracking interval set in card.location.mode.
minutes
integer
The heartbeat interval in minutes, if provided.
file
string
The tracking Notefile, if provided.
{
"start": true,
"heartbeat": true,
"file": "locations.qo",
"minutes": 120
}card.monitor CellCell+WiFiWiFi
When a Notecard is in
monitor mode,
this API is used to configure the general-purpose AUX1-AUX4 pins to test and
monitor Notecard activity.
noteUtilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's M.2 connector.
mode
string (optional)
Can be set to one of green, red or yellow to temporarily override the
behavior of an AUX pin LED.
See Using Monitor Mode for additional details.
count
integer (optional)
The number of pulses to send to the overridden AUX pin
LED. Set this value to 0 to return the LED to its default behavior.
usb
boolean (optional)
Set to true to configure LED behavior so that it
is only active when the Notecard is connected to USB power.
{
"req": "card.monitor",
"mode": "green",
"count": 5
}J *req = NoteNewRequest("card.monitor");
JAddStringToObject(req, "mode", "green");
JAddNumberToObject(req, "count", 5);
NoteRequest(req);req = {"req": "card.monitor"}
req["mode"] = "green"
req["count"] = 5
card.Transaction(req)Response Members
{} means success.card.motion CellCell+WiFiWiFi
Returns information about the Notecard accelerometer's motion and orientation.
Motion tracking must be enabled first with card.motion.mode. Otherwise, this
request will return {}.
See
card.motionin action as part of the Cold Chain Monitor accelerator project.
minutes
integer (optional)
Amount of time to sample for buckets of accelerometer-measured movement. For
instance, 5 will sample motion events for the previous five minutes and return
a movements string with motion counts in each bucket.
{
"req": "card.motion",
"minutes": 2
}J *req = NoteNewRequest("card.motion");
JAddNumberToObject(req, "minutes", 2);
NoteRequest(req);req = {"req": "card.motion"}
req["minutes"] = 2
rsp = card.Transaction(req)Response Members
count
integer
The number of accelerometer motion events since the card.motion request was
last made.
alert
boolean
true if the Notecard's accelerometer detected a free-fall since the last
request to card.motion.
motion
UNIX Epoch time
Time of the last accelerometer motion event.
status
string
Comma-separated list of accelerometer orientation events that ocurred since the
last request to card.motion. One or more of the following:
"face-up"
"face-down"
"portrait-up"
"portrait-down"
"landscape-right"
"landscape-left"
seconds
integer
If the minutes argument is provided, the duration of each bucket of sample
accelerometer movements.
movements
string
If the minutes argument is provided, a string of base-36 characters, where
each character represents the number of accelerometer movements in each bucket
during the sample duration. Each character will be a digit 0-9, A-Z to indicate
a count of 10-35, or * to indicate a count greater than 35.
mode
string
Returns the current motion status of the Notecard (e.g. "stopped" or
"moving"). Learn how to configure this feature
in this guide.
{
"count": 17,
"status": "face-up",
"alert": true,
"motion": 1599741952,
"seconds": 5,
"movements": "520000000000000000000A"
}card.motion.mode CellCell+WiFiWiFi
Configures accelerometer motion monitoring parameters used when providing
results to card.motion.
See
card.motion.modein action as part of the Cold Chain Monitor accelerator project.
start
boolean (optional)
true to enable the Notecard accelerometer and start motion tracking.
stop
boolean (optional)
true to disable the Notecard accelerometer stop motion tracking.
seconds
integer (optional)
Period for each bucket of movements to be accumulated when minutes is used
with card.motion.
sensitivity
integer (Default -1)
Used to set the accelerometer sample rate. The default sample rate of 1.6Hz
could miss short-duration accelerations (e.g. bumps and jolts), and free fall
detection may not work reliably with short falls. The penalty for increasing the
sample rate to 25Hz is increased current consumption by ~1.5uA relative to the
default -1 setting.
-1 : 1.6Hz, +/-2G range, 1 milli-G sensitivity
1 : 25Hz, +/- 16G range, 7.8 milli-G sensitivity
2 : 25Hz, +/- 8G range, 3.9 milli-G sensitivity
3 : 25Hz, +/- 4G range, 1.95 milli-G sensitivity
4 : 25Hz, +/- 2G range, 1 milli-G sensitivity
5 : 25Hz, +/- 2G range, 0.25 milli-G sensitivity
motion
integer
If motion is > 0, a
card.motion request
will return a "mode" of "moving" or "stopped". The motion value is the
threshold for how many motion events in a single bucket will trigger a motion
status change.
Learn how to configure this feature in this guide.
{
"req": "card.motion.mode",
"start": true,
"seconds": 10,
"sensitivity": 2
}J *req = NoteNewRequest("card.motion.mode");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "seconds", 10);
JAddNumberToObject(req, "sensitivity", 2);
NoteRequest(req);req = {"req": "card.motion.mode"}
req["start"] = True
req["seconds"] = 10
req["sensitivity"] = 2
card.Transaction(req)Response Members
{} means success.card.motion.sync CellCell+WiFiWiFi
Configures automatic sync triggered by Notecard movement.
See
card.motion.syncin action as part of the Piston Pump Motion Monitoring, Sign and Door Tilt Sensor, and Motor Monitor and Vibration accelerator projects.
start
boolean (optional)
true to start motion-triggered syncing.
stop
boolean (optional)
true to stop motion-triggered syncing.
minutes
integer (optional)
The maximum frequency at which sync will be triggered. Even if a threshold
is set and exceeded, there will only be a single sync for this amount of time.
count
integer (optional)
The number of most recent motion buckets to examine.
threshold
integer (optional)
The number of buckets that must indicate motion in order to trigger a sync.
If set to 0, the Notecard will only perform a sync when its orientation
changes.
{
"req": "card.motion.sync",
"start": true,
"minutes": 20,
"count": 20,
"threshold": 5
}J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "minutes", 20);
JAddNumberToObject(req, "count", 20);
JAddNumberToObject(req, "threshold", 5);
NoteRequest(req);req = {"req": "card.motion.sync"}
req["start"] = True
req["minutes"] = 20
req["count"] = 20
req["threshold"] = 5
card.Transaction(req)Response Members
{} means success.card.motion.track CellCell+WiFiWiFi
Configures automatic capture of Notecard accelerometer motion in a Notefile.
See
card.motion.trackin action as part of the Piston Pump Motion Monitoring and Motor Monitor and Vibration accelerator projects.
start
boolean (optional)
true to start motion capture.
stop
boolean (optional)
true to stop motion capture.
minutes
integer (optional)
The maximum period to capture Notes in the Notefile.
count
integer (optional)
The number of most recent motion buckets to examine.
threshold
integer (optional)
The number of buckets that must indicate motion in order to capture.
file
string (Default _motion.qo)
The Notefile to use for motion capture Notes. See the
_motion.qo Notefile's documentation
for details on the format of the data captured.
now
boolean (optional)
Set to true to trigger the immediate creation of a _motion.qo event if the
orientation of the Notecard changes (overriding the minutes setting).
{
"req": "card.motion.track",
"start": true,
"minutes": 20,
"count": 20,
"threshold": 5,
"file": "movements.qo"
}J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "minutes", 20);
JAddNumberToObject(req, "count", 20);
JAddNumberToObject(req, "threshold", 5);
JAddStringToObject(req, "file", "movements.qo");
NoteRequest(req);req = {"req": "card.motion.track"}
req["start"] = True
req["minutes"] = 20
req["count"] = 20
req["threshold"] = 5
req["file"] = "movements.qo"
card.Transaction(req)Response Members
{} means success.card.power CellCell+WiFiWiFi
The card.power API is used to configure a connected Mojo device or to manually
request power consumption readings in firmware.
minutes
integer (optional)
How often, in minutes, Notecard should log power consumption in a _log.qo
Note. The default value is 720 (12 hours).
reset
boolean (optional)
Set to true to reset the power consumption counters back to 0.
{
"req": "card.power"
}J *req = NoteNewRequest("card.power");
NoteRequest(req);req = {"req": "card.power"}
card.Transaction(req){
"req": "card.power",
"minutes": 60
}J *req = NoteNewRequest("card.power");
JAddNumberToObject(req, "minutes", 60);
NoteRequest(req);req = {"req": "card.power"}
req["minutes"] = 60
card.Transaction(req){
"req": "card.power",
"reset": true
}J *req = NoteNewRequest("card.power");
JAddBoolToObject(req, "reset", true);
NoteRequest(req);req = {"req": "card.power"}
req["reset"] = true
card.Transaction(req)Response Members
temperature
decimal
The temperature from Notecard's onboard sensor in degrees centigrade, including the calibration offset.
voltage
decimal
The current voltage.
milliamp_hours
decimal
The cumulative number of milliamp hours (mAh) consumed. You can reset this number
with this request's reset argument.
{
"temperature": 26.028314208984398,
"voltage": 4.200970458984375,
"milliamp_hours": 3.9566722000000007
}card.random CellCell+WiFiWiFi
Obtain a single random 32 bit unsigned integer modulo count or count bytes
of random data from the Notecard hardware random number generator.
mode
string (optional)
Accepts a single value "payload" and, if specified, uses the count value
to determine the number of bytes of random data to generate and return to
the host.
count
integer
If the mode argument is excluded from the request, the Notecard uses this
as an upper-limit parameter and returns a random unsigned 32 bit integer between zero and
the value provided.
If "mode":"payload" is used, this argument sets the number of random bytes of
data to return in a base64-encoded buffer from the Notecard.
{
"req": "card.random",
"count": 100
}J *req = NoteNewRequest("card.random");
JAddNumberToObject(req, "count", 100);
NoteRequest(req);req = {"req": "card.random"}
req["count"] = 100
rsp = card.Transaction(req){
"req":"card.random",
"mode": "payload",
"count":100
}J *req = NoteNewRequest("card.random");
JAddStringToObject(req, "mode", "payload");
JAddNumberToObject(req, "count", 100);
NoteRequest(req);Response Members
count
integer
A random number generated by the Notecard's onboard hardware random number generator.
payload
bas64 string
If using "mode":"payload", a base64-encoded string with random values, the length
of which is specified by the count argument.
{
"count": 86
}card.restart CellCell+WiFiLoRaWiFi
Performs a firmware restart of the Notecard.
warningCalls to card.restart are not supported for use in production applications as
they can cause increased cellular data and consumption credit usage.
{
"req": "card.restart"
}J *req = NoteNewRequest("card.restart");
NoteRequest(req);req = {"req": "card.restart"}
card.Transaction(req)Response Members
{} means success.card.restore CellCell+WiFiLoRaWiFi
Performs a factory reset on the Notecard and restarts.
Sending this request without either of the optional arguments below will only reset the Notecard's file system, thus forcing a re-sync of all Notefiles from Notehub.
On Notecard LoRa there is no option to retain configuration settings, and providing
"delete": true is required. The Notecard LoRa retains LoRaWAN configuration
after factory resets.
delete
boolean (optional)
Set to true to reset most Notecard configuration settings. Note that this does
not reset stored Wi-Fi credentials or the
alternate I2C address
(if previously set) so the Notecard can still contact the network after a reset.
The Notecard will be unable to sync with Notehub until the ProductUID is
set again.
connected
boolean (optional)
Set to true to reset the Notecard on Notehub. This will delete and deprovision
the Notecard from Notehub the next time the Notecard connects. This also removes
any Notefile templates used by this device.
Conversely, if connected is false (or omitted), the Notecard's settings and
data will be restored from Notehub the next time the Notecard connects to
the previously used Notehub project.
{
"req": "card.restore",
"delete": true,
"connected": true
}J *req = NoteNewRequest("card.restore");
JAddBoolToObject(req, "delete", true);
JAddBoolToObject(req, "connected", true);
NoteRequest(req);req = {"req": "card.restore"}
req["delete"] = True
req["connected"] = True
card.Transaction(req)Response Members
{} means success.card.sleep WiFi
Only valid when used with Notecard WiFi v2.
Allows the ESP32-based Notecard WiFi v2 to fall back to a low current draw when
idle (this behavior differs from the STM32-based Notecards that have a STOP
mode where UART and I2C may still operate). Note that the Notecard WiFi v2 will
not enable a "sleep" mode while plugged in via USB.
Read more in the guide on using Deep Sleep Mode on Notecard WiFi v2.
on
boolean (optional)
Set to true to enable the Notecard WiFi v2 to sleep once it is idle for >= 30
seconds.
off
boolean (optional)
Set to true to disable the sleep mode on the Notecard WiFi v2.
seconds
integer (optional)
The number of seconds the Notecard will wait before entering sleep mode (minimum value is 30).
mode
string (optional)
Set to "accel" to wake from deep sleep on any movement detected by the onboard
accelerometer. Set to "-accel" to reset to the default setting.
{
"req": "card.sleep",
"on": true
}J *req = NoteNewRequest("card.sleep");
JAddBoolToObject(req, "on", true);
NoteRequest(req);req = {"req": "card.sleep"}
req["on"] = True
rsp = card.Transaction(req)Response Members
on
boolean
true if sleep mode is enabled.
off
boolean
true if sleep mode is disabled.
seconds
integer
The number of seconds the Notecard will wait before entering sleep mode (only included if default settings are overridden).
mode
string
Returns "accel" if the Notecard is configured to wake from deep sleep on any
movement detected by the onboard accelerometer.
{
"seconds": 10,
"mode": "accel",
"on": true
}card.status CellCell+WiFiLoRaWiFi
Returns general information about the Notecard's operating status.
{
"req": "card.status"
}J *req = NoteNewRequest("card.status");
NoteRequest(req);req = {"req": "card.status"}
rsp = card.Transaction(req)Response Members
status
string
General status information.
usb
boolean
true is the Notecard is being powered by USB.
storage
integer
The percentage of storage in use on the Notecard.
time
UNIX Epoch time
The UNIX Epoch Time of approximately when the Notecard was first powered up.
connected
boolean
true if connected to Notehub.
cell
boolean
true if the modem is currently powered on.
gps
boolean
true if Notecard's GPS module is currently powered on.
wifi
boolean
true if the Notecard's Wi-Fi radio is currently powered on.
sync
boolean
true if the Notecard has ever connected to Notehub.
inbound
integer
The effective inbound synchronization period being used by the device. See Configuring Synchronization Modes for details on how Notecard synchronization modes work.
outbound
integer
The effective outbound synchronization period being used by the device. See Configuring Synchronization Modes for details on how Notecard synchronization modes work.
{
"status": "{normal}",
"usb": true,
"storage": 8,
"time": 1599684765,
"connected": true,
"cell": true,
"sync": true,
"inbound": 60,
"outbound": 360
}card.temp CellCell+WiFiLoRaWiFi
Get the current temperature from the Notecard's onboard calibrated temperature sensor.
When using a Notecard Cellular or Notecard Cell+WiFi, if you connect a BME280
sensor on the I2C bus the Notecard will add temperature, pressure, and humidity
fields to the response. If you connect an ENS210 sensor on the I2C bus the Notecard
will add temperature and pressure fields to the response.
See
card.tempin action as part of the Refrigerator Monitor, Smart CO2 Sensor, and Heat Index Monitor accelerator projects.
minutes
integer (optional)
If specified, creates a templated _temp.qo file that gathers Notecard
temperature value at the specified minutes interval. When using
card.aux track mode,
the sensor temperature, pressure, and humidity is also included with each Note.
status
string (optional)
Overrides minutes with a voltage-variable value. For example:
"usb:15;high:30;normal:60;720". See
Voltage-Variable Sync Behavior
for more information on configuring these values.
stop
boolean (optional)
If set to true, the Notecard will stop logging the temperature value at the
interval specified with the minutes parameter (see above).
sync
boolean (optional)
If set to true, the Notecard will immediately sync any pending _temp.qo
Notes created with the minutes parameter (see above).
{
"req": "card.temp"
}float temp;
J *req = NoteNewRequest("card.temp");
if (J *rsp = NoteRequestResponse(req))
{
temp = JGetNumber(rsp, "value");
NoteDeleteResponse(rsp);
}req = {"req": "card.temp"}
rsp = card.Transaction(req)
print(rsp){
"req": "card.temp",
"minutes": 30
}J *req = NoteNewRequest("card.temp");
JAddNumberToObject(req, "minutes", 30);
NoteRequest(req);req = {"req": "card.temp"}
req["minutes"] = 30
rsp = card.Transaction(req)Response Members
value
decimal
The current temperature from the Notecard's onboard sensor in degrees centigrade, including the calibration offset.
calibration
decimal
The calibration differential of the Notecard's onboard sensor.
temperature
decimal
If the Notecard finds a BME280 or ENS210 sensor on the I2C bus, this field will be set to the temperature value from the connected sensor in degrees centigrade.
humidity
decimal
If the Notecard finds a BME280 sensor on the I2C bus, this field will be set to the humidity percentage value from the connected sensor.
pressure
decimal
If the Notecard finds a BME280 or ENS210 sensor on the I2C bus, this field will be set to the atmospheric pressure value from the connected sensor in Pascals.
usb
boolean
true if the Notecard is connected to USB power.
voltage
decimal
The current voltage.
{
"value": 27.625,
"calibration": -3.0
}card.time CellCell+WiFiLoRaWiFi
Retrieves current date and time information in UTC. Upon power-up, the Notecard
must complete a sync to Notehub in order to obtain time and location data.
Before the time is obtained, this request will return {"zone":"UTC,Unknown"}.
See
card.timein action as part of the Car Detector and Cellular Speed Radar and Camera accelerator projects.
{
"req": "card.time"
}J *req = NoteNewRequest("card.time");
NoteRequest(req);req = {"req": "card.time"}
rsp = card.Transaction(req)Response Members
time
UNIX Epoch time
The current time in UTC. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.
area
string
The geographic area of the Notecard, if the cell tower is recognized.
zone
string
The time zone of the Notecard, if the cell tower is recognized.
minutes
integer
Number of minutes East of GMT, if the cell tower is recognized.
lat
decimal
Latitude of the Notecard, if the cell tower is recognized.
lon
decimal
Longitude of the Notecard, if the cell tower is recognized.
country
string
The country where the Notecard is located, if the cell tower is recognized.
{
"time": 1599769214,
"area": "Beverly, MA",
"zone": "CDT,America/New York",
"minutes": -300,
"lat": 42.5776,
"lon": -70.87134,
"country": "US"
}card.transport CellCell+WiFiWiFi
Specifies the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard.
method
string
The connectivity method to enable on the Notecard.
- CellCell+WiFiWiFi
Resets the transport mode to the device default.
wifi-cell Cell+WiFi
Prioritizes Wi-Fi connectivity while falling back to cellular if a Wi-Fi connection cannot be established. This is the default behavior on Notecard Cell+WiFi.
dual-wifi-cell Deprecated
Deprecated form of "wifi-cell".
wifi Cell+WiFiWiFi
Enables Wi-Fi only on the device.
cell CellCell+WiFi
Enables cellular only on the device.
ntn CellCell+WiFiWiFi
Enables NTN (Non-Terrestrial Network) mode on the device for use with Starnote.
wifi-ntn Cell+WiFiWiFi
Prioritizes Wi-Fi connectivity while falling back to NTN if a Wi-Fi connection cannot be established.
cell-ntn CellCell+WiFi
Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established.
wifi-cell-ntn Cell+WiFi
Prioritizes Wi-Fi connectivity while falling back to cellular, and lastly to NTN.
seconds
integer
The amount of time a Notecard will spend on any fallback transport before
retrying the first transport specified in the method. The default is 3600 or
60 minutes.
allow
boolean (Default: false)
Set to true to allow adding Notes to non-compact Notefiles while connected over a non-terrestrial network.
See Define NTN vs non-NTN Templates.
umin
boolean (Default: false)
Set to true to force a longer network transport timeout when using Wideband Notecards.
{
"req": "card.transport",
"method": "wifi-cell"
}J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "wifi-cell");
NoteRequest(req);req = {"req": "card.transport"}
req["method"] = "wifi-cell"
rsp = card.Transaction(req)Response Members
method
string
The connectivity method currently enabled on the device.
{
"method":"wifi-cell"
}card.triangulate CellCell+WiFiWiFi
Enables or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or Wi-Fi access points with each new Notehub session.
mode
string
The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order.
cell enables cell tower scanning to determine the position of the Device.
wifi enables the use of nearby Wi-Fi access points to determine the
position of the Device. To leverage this feature, the host will need to
provide access point information to the Notecard via the text argument in
subsequent requests.
- to clear the currently-set triangulation mode.
See Using Cell Tower & Wi-Fi Triangulation for more information.
on
boolean (Default: false)
true to instruct the Notecard to triangulate even if the module has not moved.
Only takes effect when set is true.
usb
boolean (Default: false)
true to use perform triangulation only when the Notecard is connected to USB
power. Only takes effect when set is true.
set
boolean (Default: false)
true to instruct the module to use the state of the on and usb arguments.
minutes
integer (Default: 0)
Minimum delay, in minutes, between triangulation attempts. Use 0 for no
time-based suppression.
text
string (Optional)
When using Wi-Fi triangulation, a newline-terminated list of Wi-Fi access points obtained by the external module. Format should follow the ESP32's AT+CWLAP command output.
See Using Cell Tower & Wi-Fi Triangulation for more information.
time
UNIX Epoch time (Optional)
When passed with text, records the time that the Wi-Fi access point scan
was performed. If not provided, Notecard time is used.
{
"req": "card.triangulate",
"mode": "cell",
"on": true,
"set": true
}J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "cell");
JAddBoolToObject(req, "on", true);
JAddBoolToObject(req, "set", true);
NoteRequest(req);req = {"req": "card.triangulate"}
req["mode"] = "cell"
req["on"] = True
req["set"] = True
rsp = card.Transaction(req){
"req": "card.triangulate",
"mode": "wifi,cell",
"on": true,
"usb": true,
"set": true
}J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "wifi,cell");
JAddBoolToObject(req, "on", true);
JAddBoolToObject(req, "usb", true);
JAddBoolToObject(req, "set", true);
NoteRequest(req);req = {"req": "card.triangulate"}
req["mode"] = "wifi,cell"
req["on"] = True
req["usb"] = True
req["set"] = True
rsp = card.Transaction(req){
"req": "card.triangulate",
"text": "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
}J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "text", "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:16:15:f8\",1)\n+CWLAP:(3,\"CBCI-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:16:16:80\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:b9:16:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:13:90:31\",6)\n+CWLAP:(5,\"GO\",-84,\"02:18:4a:13:90:30\",6)\n+CWLAP:(3,\"\",-84,\"7a:8a:20:51:da:c7\",6)\n+CWLAP:(4,\"CBCI-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"PBW\",-85,\"78:8a:20:51:da:c7\",6)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n");
NoteRequest(req);req = {"req": "card.triangulate"}
req["text"] = "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
rsp = card.Transaction(req){
"req": "card.triangulate",
"mode": "-"
}J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "-");
NoteRequest(req);req = {"req": "card.triangulate"}
req["mode"] = "-"
rsp = card.Transaction(req)Response Members
motion
UNIX Epoch time
Time of last detected Notecard movement.
time
UNIX Epoch time
Time of last triangulation scan.
mode
string
A comma-separated list indicating the active triangulation modes.
on
boolean
true if triangulation scans will be performed even if the device has not
moved.
usb
boolean
true if triangulation scans will be performed only when the device is
USB-powered.
length
integer
The length of the text buffer provided in the current or a previous request.
{
"usb": true,
"mode": "wifi,cell",
"length": 443,
"on": true,
"time": 1606755042,
"motion": 1606757487
}card.usage.get CellCell+WiFiWiFi
Returns the card's network usage statistics.
noteUsage data is updated by the Notecard at the end of each network connection. If
connected in continuous mode, usage data will not be updated until the current
session ends, which you can configure with the
hub.set duration argument.
mode
string (Default: "total")
The time period to use for statistics. Must be one of:
"total" for all stats since the Notecard was activated.
"1hour"
"1day"
"30day"
offset
integer (optional)
The number of time periods to look backwards, based on the specified mode.
To accurately determine the start of the calculated time period when using
offset, use the time value of the response. Likewise, to calculate the end
of the time period, add the seconds value to the time value.
{
"req": "card.usage.get",
"mode": "1day",
"offset": 5
}J *req = NoteNewRequest("card.usage.get");
JAddStringToObject(req, "mode", "1day");
JAddNumberToObject(req, "offset", 5);
NoteRequest(req);req = {"req": "card.usage.get"}
req["mode"] = "1day"
req["offset"] = 5
rsp = card.Transaction(req)Response Members
seconds
integer
Number of seconds in the analyzed period.
time
UNIX Epoch time
Start time of the analyzed period or, if mode="total", the time of activation.
bytes_sent
integer
Number of bytes sent by the Notecard to Notehub.
bytes_received
integer
Number of bytes received by the Notecard from Notehub.
notes_sent
integer
Approximate number of notes sent by the Notecard to Notehub.
notes_received
integer
Approximate number of notes received by the Notecard from Notehub.
sessions_standard
integer
Number of standard Notehub sessions.
sessions_secure
integer
Number of secure Notehub sessions.
{
"seconds": 1291377,
"time": 1598479763,
"bytes_sent": 163577,
"bytes_received": 454565,
"notes_sent": 114,
"notes_received": 26,
"sessions_standard": 143,
"sessions_secure": 31
}card.usage.test CellCell+WiFiWiFi
days
integer (optional)
Number of days to use for the test.
hours
integer (optional)
If you want to analyze a period shorter than one day, the number of hours to use for the test.
megabytes
integer (Default: 1024)
The Notecard lifetime data quota (in megabytes) to use for the test.
{
"req": "card.usage.test",
"days": 7,
"megabytes": 500
}J *req = NoteNewRequest("card.usage.test");
JAddNumberToObject(req, "days", 7);
JAddNumberToObject(req, "megabytes", 500);
NoteRequest(req);req = {"req": "card.usage.test"}
req["days"] = 7
req["megabytes"] = 500
rsp = card.Transaction(req)Response Members
max
integer
The days of projected data available based on test.
days
integer
The number of days used for the test.
bytes_per_day
integer
Average bytes per day used during the test period.
seconds
integer
Number of seconds in the analyzed period.
time
UNIX Epoch time
Time of device activation.
bytes_sent
integer
Number of bytes sent by the Notecard to Notehub.
bytes_received
integer
Number of bytes received by the Notecard from Notehub.
notes_sent
integer
Number of notes sent by the Notecard to Notehub.
notes_received
integer
Number of notes received by the Notecard from Notehub.
sessions_standard
integer
Number of standard Notehub sessions.
sessions_secure
integer
Number of secure Notehub sessions.
{
"max": 12730,
"days": 7,
"bytes_per_day": 41136,
"seconds": 1291377,
"time": 1598479763,
"bytes_sent": 163577,
"bytes_received": 454565,
"notes_sent": 114,
"notes_received": 26,
"sessions_standard": 143,
"sessions_secure": 31
}card.version CellCell+WiFiLoRaWiFi
Returns firmware version information for the Notecard.
api
integer (Optional)
Deprecated
Specify a major version of the Notecard firmware that a host expects to use.
{
"req": "card.version"
}J *req = NoteNewRequest("card.version");
NoteRequest(req);req = {"req": "card.version"}
rsp = card.Transaction(req)Response Members
body
JSON object
An object containing Notecard firmware details for programmatic access.
version
string
The full version number of the Notecard firmware.
device
string
The DeviceUID of the Notecard.
name
string
The official name of the device.
board
integer
The Notecard board version number.
sku
string
The Notecard SKU.
api
integer
The current Notecard API major version in use.
wifi
If true, indicates the Notecard supports Wi-Fi connectivity.
cell
If true, indicates the Notecard supports cellular connectivity.
gps
If true, indicates the Notecard has an onboard GPS module.
{
"version": "notecard-5.3.1",
"device": "dev:000000000000000",
"name": "Blues Wireless Notecard",
"sku": "NOTE-NBGL-500",
"board": "1.11",
"cell": true,
"gps": true,
"api": 5,
"body": {
"org": "Blues Wireless",
"product": "Notecard",
"target": "r5",
"version": "notecard-5.3.1",
"ver_major": 5,
"ver_minor": 3,
"ver_patch": 1,
"ver_build": 371,
"built": "Sep 5 2023 12:21:30"
}
}card.voltage CellCell+WiFiLoRaWiFi
Provides the current V+ voltage level on the Notecard, and provides
information about historical voltage trends. When used with the mode
argument, configures voltage thresholds based on how the device
is powered.
See
card.voltagein action as part of the Power Outage Detection, Refrigerator Monitor, and Temperature and Humidity Monitor accelerator projects.
hours
integer (Default: all available data)
The number of hours to analyze, up to 720 (30 days).
mode
string (Default: default)
Used to set voltage thresholds based on how the Notecard will be powered, and
which can be used to
configure voltage-variable Notecard behavior.
Each value is shorthand that assigns a battery voltage reading
to a given device state like high, normal, low, and dead.
NOTE: Setting voltage thresholds is not supported on the Notecard XP.
One of:
"lipo" for LiPo batteries. Equivalent to
"usb:4.6;high:4.0;normal:3.5;low:3.2;dead:0".
"l91" for L91 batteries. Equivalent to
"high:5.0;normal:4.5;low:0".
"alkaline" for Alkaline batteries. Equivalent to
"usb:4.6;high:4.2;normal:3.6;low:0".
"tad" for Tadiran HLC batteries. Equivalent to
"usb:4.6;normal:3.2;low:0".
"lic" for Lithium-ion capacitors. Equivalent to
"usb:4.6;high:3.8;normal:3.1;low:0".
"default" for the default behavior. Equivalent to
"normal:2.5;dead:0".
"?" to query the Notecard for its currently-set thresholds.
offset
integer (Default: 0)
Number of hours to move into the past before starting analysis.
vmax
integer (Default: 4.5)
Ignore voltage readings above this level when performing calculations.
vmin
integer (Default: 2.5)
Ignore voltage readings below this level when performing calculations.
name
string
Specifies an environment variable to override application default timing values.
usb
boolean (Default: false)
When enabled, the Notecard will monitor for changes to USB power state,
which you can act upon with alert and sync arguments.
alert
boolean (Default: false)
When enabled and the usb argument is set to true, the Notecard will add
an entry to the health.qo Notefile when USB power is connected or disconnected.
sync
boolean (Default: false)
When enabled and the usb argument is set to true, the Notecard will perform
a sync when USB power is connected or disconnected.
calibration
float (Default: 0.35)
The offset, in volts, to account for the forward voltage drop of the diode used between the battery and Notecard in either Blues- or customer-designed Notecarriers.
set
boolean (Default: false)
Used along with calibration, set to true to specify a new calibration value.
{
"req": "card.voltage",
"hours": 300,
"vmax": 4,
"vmin": 2.2
}J *req = NoteNewRequest("card.voltage");
JAddNumberToObject(req, "hours", 300);
JAddNumberToObject(req, "vmax", 4);
JAddNumberToObject(req, "vmin", 2.2);
NoteRequest(req);req = {"req": "card.voltage"}
req["hours"] = 300
req["vmax"] = 4
req["vmin"] = 2.2
rsp = card.Transaction(req){
"req": "card.voltage",
"mode": "lipo"
}J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "lipo");
NoteRequest(req);req = {"req": "card.voltage"}
req["mode"] = "lipo"
rsp = card.Transaction(req){
"req": "card.voltage",
"mode": "?"
}J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "?");
NoteRequest(req);req = {"req": "card.voltage"}
req["mode"] = "?"
rsp = card.Transaction(req){
"req": "card.voltage",
"usb": true,
"alert": true,
"sync": true
}J *req = NoteNewRequest("card.voltage");
JAddBoolToObject(req, "usb", true);
JAddBoolToObject(req, "alert", true);
JAddBoolToObject(req, "sync", true);
NoteRequest(req);req = {"req": "card.voltage"}
req["usb"] = true
req["alert"] = true
req["sync"] = true
rsp = card.Transaction(req)Response Members
mode
string
The current voltage-variable threshold value returned from Notecard.
For example, if the voltage threshold is "usb:4.6;normal:3.5;dead:0" and the
power source returns a voltage of 3.9, the mode value would be "normal".
usb
boolean
true if the Notecard is connected to USB power.
value
decimal
The current voltage.
hours
integer
The number of hours used for trend analysis.
vmin
decimal
The lowest voltage value captured during the measurement period.
vmax
decimal
The highest voltage value captured during the measurement period.
vavg
decimal
The average voltage value during the measured period.
daily
decimal
Change of moving average in the last 24 hours, if relevant to the time period analyzed.
weekly
decimal
Change of moving average in the last 7 days, if relevant to the time period analyzed.
monthly
decimal
Change of moving average in the last 30 days, if relevant to the time period analyzed.
{
"usb": true,
"hours": 120,
"mode": "usb",
"value": 5.112190219747135,
"vmin": 4,
"vmax": 4,
"vavg": 4
}card.wifi Cell+WiFiWiFi
Sets up a Notecard WiFi to connect to a Wi-Fi access point.
noteUpdates to Notecard WiFi credentials cannot occur while Notecard is in
continuous mode, as a new session is required to change the credentials. If
you have a Notecard WiFi in continuous mode, you must change to another mode
such as periodic or off, using a hub.set request
before calling card.wifi.
ssid
string (optional)
The SSID of the Wi-Fi access point. Alternatively, use - to clear an already
set SSID.
password
string (optional)
The network password of the Wi-Fi access point. Alternatively, use - to clear
an already set password or to connect to an open access point.
name
string (optional)
By default, the Notecard creates a SoftAP (software enabled access point) under
the name "Notecard". You can use the name argument to change the name of the
SoftAP to a custom name.
If you include a - at the end of the name (for example "name": "acme-"),
the Notecard will append the last four digits of the network's MAC address (for
example acme—025c). This allows you to distinguish between multiple Notecards
in SoftAP mode.
org
string (optional)
If specified, replaces the Blues logo on the SoftAP page with the provided name.
start
boolean (optional)
Specify true to activate SoftAP mode on the Notecard programatically.
text
string (optional)
A string containing an array of access points the Notecard should attempt to use. The access points should be provided in the following format:
["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"]
You may need to escape any quotes used in this argument before passing it to the Notecard. For example, the following is a valid request to pass to a Notecard through the In-Browser Terminal.
{"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"]"}
{
"req": "card.wifi",
"ssid": "<ssid name>",
"password": "<password>"
}J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "ssid", "<ssid name>");
JAddStringToObject(req, "password", "<password>");
NoteRequest(req);req = {"req": "card.wifi"}
req["ssid"] = "<ssid name>"
req["password"] = "<password>"
rsp = card.Transaction(req){
"req": "card.wifi",
"ssid": "-",
"password": "-"
}J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "ssid", "-");
JAddStringToObject(req, "password", "-");
NoteRequest(req);req = {"req": "card.wifi"}
req["ssid"] = "-"
req["password"] = "-"
rsp = card.Transaction(req){
"req": "card.wifi",
"name": "ACME Inc",
"org": "ACME Inc"
}J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "name", "ACME Inc");
JAddStringToObject(req, "org", "ACME Inc");
NoteRequest(req);req = {"req": "card.wifi"}
req["name"] = "ACME Inc"
req["org"] = "ACME Inc"
rsp = card.Transaction(req){
"req": "card.wifi",
"name": "acme-",
"org": "ACME Inc"
}J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "name", "acme-");
JAddStringToObject(req, "org", "ACME Inc");
NoteRequest(req);req = {"req": "card.wifi"}
req["name"] = "acme-"
req["org"] = "ACME Inc"
rsp = card.Transaction(req)Response Members
secure
boolean
true means that the Wi-Fi access point is using Management Frame Protection.
version
string
The Silicon Labs WF200 Wi-Fi Transceiver binary version.
ssid
string
The SSID of the Wi-Fi access point.
security
string
The security protocol the Wi-Fi access point uses.
{
"secure": true,
"version": "3.12.3",
"ssid": "<ssid name>",
"security": "wpa2-psk"
}card.wireless CellCell+WiFiWiFi
View the last known network state, or customize the behavior of the modem. Note: Be careful when using this mode with hardware not on hand as a mistake may cause loss of network and Notehub access.
mode
string
Network scan mode. Must be one of:
"-" to reset
to the default mode.
"auto" to perform automatic band scan mode (this is the default mode).
"m" to restrict the modem to Cat-M1.
"nb" to restrict the modem to Cat-NB1.
"gprs" to restrict the modem to EGPRS.
apn
string
Access Point Name (APN) when using an external SIM. Use "-" to reset to the
Notecard default APN.
method
Used when configuring a Notecard to failover to a different SIM.
"-" resets the Notecard to the default method.
"dual-primary-secondary" will attempt to register with the internal SIM first,
then failover to the external SIM.
"dual-secondary-primary" will attempt to register with the external SIM first,
then failover to the internal SIM.
"primary" will exclusively use the internal SIM.
"secondary" will exclusively use the external SIM.
hours
When using the method argument with "dual-primary-secondary" or
"dual-secondary-primary", this is the number of hours after which the Notecard
will attempt to switch back to the preferred SIM.
{
"req": "card.wireless"
}J *req = NoteNewRequest("card.wireless");
NoteRequest(req);req = {"req": "card.wireless"}
rsp = card.Transaction(req){
"req": "card.wireless",
"mode": "nb"
}J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "mode", "nb");
NoteRequest(req);req = {"req": "card.wireless"}
req["mode"] = "nb"
rsp = card.Transaction(req){
"req": "card.wireless",
"mode": "-"
}J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "mode", "-");
NoteRequest(req);req = {"req": "card.wireless"}
req["mode"] = "-"
rsp = card.Transaction(req){
"req": "card.wireless",
"apn": "myapn.nb"
}J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "apn", "myapn.nb");
NoteRequest(req);req = {"req": "card.wireless"}
req["apn"] = "myapn.nb"
rsp = card.Transaction(req){
"req": "card.wireless",
"apn": "myapn.nb",
"method": "dual-primary-secondary"
}J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "apn", "myapn.nb");
JAddStringToObject(req, "method", "dual-primary-secondary");
NoteRequest(req);req = {"req": "card.wireless"}
req["apn"] = "myapn.nb"
req["method"] = "dual-primary-secondary"
rsp = card.Transaction(req)Response Members
status
string
The current status of the wireless connection and modem.
count
integer
Number of bars of signal quality.
net
JSON object
An object with detailed modem, radio access technology, and signal information (details will differ depending on the type of Notecard).
{
"status": "{modem-off}",
"count": 1,
"net": {
"iccid": "00000000000000000000",
"imsi": "000000000000000",
"imei": "000000000000000",
"modem": "EG91NAXGAR07A03M1G_BETA0415_01.001.01.001",
"band": "LTE BAND 2",
"rat": "lte",
"rssir": -69,
"rssi": -70,
"rsrp": -105,
"sinr": -3,
"rsrq": -17,
"bars": 1,
"mcc": 310,
"mnc": 410,
"lac": 28681,
"cid": 211150856,
"updated": 1599225076
}
}card.wireless.penalty CellCell+WiFiWiFi
View the current state of a Notecard Penalty Box, manually remove the Notecard from a penalty box, or override penalty box defaults.
warningThe misuse of this feature may result in the cellular carrier preventing the Notecard from future connections because it's effectively "spamming" the network. The cellular carrier may blacklist devices that it thinks are attempting to connect too frequently.
reset
boolean
Set to true to remove the Notecard from certain types of penalty boxes.
set
boolean
Set to true to override the default settings of the
Network Registration Failure Penalty Box.
rate
float (Default 1.25)
The rate at which the penalty box time multiplier is increased over successive
retries. Used with the set argument to override the Network Registration
Failure Penalty Box defaults.
add
integer (Default 15)
The number of minutes to add to successive retries. Used with the set argument
to override the Network Registration Failure Penalty Box defaults.
max
integer (Default 4320)
The maximum number of minutes that a device can be in a Network Registration
Failure Penalty Box. Used with the set argument to override the Network
Registration Failure Penalty Box defaults.
min
integer (Default 15)
The number of minutes of the first retry interval of a Network Registration
Failure Penalty Box. Used with the set argument to override the Network
Registration Failure Penalty Box defaults.
{
"req": "card.wireless.penalty"
}J *req = NoteNewRequest("card.wireless.penalty");
NoteRequest(req);req = {"req": "card.wireless.penalty"}
rsp = card.Transaction(req){
"req": "card.wireless.penalty",
"reset": true
}J *req = NoteNewRequest("card.wireless.penalty");
JAddBoolToObject(req, "reset", true);
NoteRequest(req);req = {"req": "card.wireless.penalty"}
req["reset"] = True
rsp = card.Transaction(req){
"req": "card.wireless.penalty",
"set": true,
"rate": 2.0,
"add": 10,
"max": 720,
"min": 5
}J *req = NoteNewRequest("card.wireless.penalty");
JAddBoolToObject(req, "set", true);
JAddNumberToObject(req, "rate", 2.0);
JAddNumberToObject(req, "add", 10);
JAddNumberToObject(req, "max", 720);
JAddNumberToObject(req, "min", 5);
NoteRequest(req);req = {"req": "card.wireless.penalty"}
req["set"] = True
req["rate"] = 2.0
req["add"] = 10
req["max"] = 720
req["min"] = 5
rsp = card.Transaction(req)Response Members
minutes
integer
The time since the first network registration failure.
count
integer
The number of consecutive network registration failures.
status
string
If the Notecard is in a Penalty Box, this field provides the associated Error and Status Codes.
seconds
integer
If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends.
{
"seconds": 3324,
"minutes": 69,
"status": "network: can't connect (55.4 min remaining) {registration-failure}{network}{extended-network-failure}",
"count": 6
}