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 notifications from a Notecard to a host MCU.
NOTE: Requires a connection between the Notecard ATTN pin and a GPIO pin on the host MCU.
files
array of string (optional)
A list of Notefiles to watch for file-based interrupts.
mode
string (optional)
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).
"connected" CellCell+WiFiWiFi
When armed, will cause ATTN to fire whenever the module connects to cellular. Disable with -connected.
"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.
"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.
on
boolean (optional)
When true, enables ATTN processing. This setting is retained across device restarts.
payload
string (format: binary) (optional)
When using sleep mode, a payload of data from the host that the Notecard should hold in memory until retrieved by the host.
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.
start
boolean (optional)
When using sleep mode and the host has reawakened, request the Notecard to return the stored payload.
{
"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"
rsp = 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"]
rsp = 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"
rsp = 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"
rsp = 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"
rsp = 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
rsp = 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=="
rsp = 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, "start", true);
NoteRequest(req);req = {"req": "card.attn"}
req["start"] = True
rsp = 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"
rsp = card.Transaction(req)Disarm all interrupts.
Response Members
files
array of string
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.
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.
time
UNIX Epoch time
When using sleep mode with a payload, the time (UNIX Epoch time) that the payload was stored by the Notecard.
{
"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.
noteUtilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces.
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.
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.
mode
string (optional)
The AUX mode. Must be one of the following keywords. Some keywords are only supported on certain types of Notecards.
"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.
"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.
"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.
"-" CellCell+WiFiLoRaWiFi
Resets the AUX mode to its default value (off).
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.
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.
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.
usage
array of string (optional)
An ordered list of pin modes for each AUX pin when in GPIO mode.
"" CellCell+WiFiLoRaWiFi
to leave the pin unchanged.
"off" CellCell+WiFiLoRaWiFi
to disable the pin.
"high" CellCell+WiFiLoRaWiFi
to set the pin as a HIGH output.
"low" CellCell+WiFiLoRaWiFi
to set the pin as a LOW output.
"input" CellCell+WiFiLoRaWiFi
to set the pin as an input.
"count" CellCell+WiFiWiFi
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" CellCell+WiFiWiFi
Same as count usage, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating.
"count-pullup" CellCell+WiFiWiFi
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.
{
"req": "card.aux",
"mode": "dfu"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "dfu");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "dfu"
rsp = 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.
{
"req": "card.aux",
"mode": "gpio",
"usage": [
"off",
"low",
"high",
"input"
]
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *usage = JAddArrayToObject(req, "usage");
JAddItemToArray(usage, JCreateString("off"));
JAddItemToArray(usage, JCreateString("low"));
JAddItemToArray(usage, JCreateString("high"));
JAddItemToArray(usage, JCreateString("input"));
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = ["off", "low", "high", "input"]
rsp = 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.
{
"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 *usage = JAddArrayToObject(req, "usage");
JAddItemToArray(usage, JCreateString("off"));
JAddItemToArray(usage, JCreateString("low"));
JAddItemToArray(usage, JCreateString("high"));
JAddItemToArray(usage, JCreateString("count"));
JAddNumberToObject(req, "seconds", 2);
JAddNumberToObject(req, "max", 5);
JAddBoolToObject(req, "start", true);
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = ["off", "low", "high", "count"]
req["seconds"] = 2
req["max"] = 5
req["start"] = True
rsp = 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 *usage = JAddArrayToObject(req, "usage");
JAddItemToArray(usage, JCreateString("off"));
JAddItemToArray(usage, JCreateString("low"));
JAddItemToArray(usage, JCreateString("high"));
JAddItemToArray(usage, JCreateString("input"));
JAddBoolToObject(req, "sync", true);
JAddStringToObject(req, "file", "statechange.qo");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = ["off", "low", "high", "input"]
req["sync"] = True
req["file"] = "statechange.qo"
rsp = card.Transaction(req)Configure GPIO mode with automatic state change reporting to a Notefile.
{
"req": "card.aux",
"mode": "monitor"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "monitor");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "monitor"
rsp = card.Transaction(req)Configure inputs and outputs typically placed on the faceplate of a device for technicians 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"
rsp = card.Transaction(req)Enable neo-monitor mode which supports NeoPixel LEDs for monitoring 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"
rsp = card.Transaction(req)Supplement autonomous tracking with digital inputs and a status output.
{
"req": "card.aux",
"rate": 9600
}J *req = NoteNewRequest("card.aux");
JAddNumberToObject(req, "rate", 9600);
NoteRequest(req);req = {"req": "card.aux"}
req["rate"] = 9600
rsp = card.Transaction(req)Configure the AUX UART baud rate for debug communication.
{
"req": "card.aux",
"mode": "track"
}J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "track");
NoteRequest(req);req = {"req": "card.aux"}
req["mode"] = "track"
rsp = card.Transaction(req)Enhance Notes with temperature, pressure, and humidity readings from a connected BME280 sensor.
Response Members
mode
string
The current AUX mode, or off if not set.
seconds
integer
When in AUX gpio mode, and if count is enabled on an AUX pin, the number of seconds per sample.
state
array of object
When in AUX gpio mode, the state of each AUX pin.
"" CellCell+WiFiLoRaWiFi
{} when the pin is off.
"high" CellCell+WiFiLoRaWiFi
{"high": true} when the pin is high.
"low" CellCell+WiFiLoRaWiFi
{"low": true} when the pin is low.
"input" CellCell+WiFiLoRaWiFi
{"input": true} when the pin is input.
"count" CellCell+WiFiWiFi
{"count": [4]} where each item in the array is the count per sample.
time
integer (format: unix-time)
When in AUX gpio mode, and if count is enabled on an AUX pin, the time that counting started.
{
"mode": "gpio",
"state": [
{},
{
"low": true
},
{
"high": true
},
{
"count": [
3
]
}
],
"time": 1592587637,
"seconds": 2
}card.aux.serial CellCell+WiFiWiFi
noteThis request is not available in the currently selected Notecard firmware version.
card.binary CellCell+WiFiWiFi
noteThis request is not available in the currently selected Notecard firmware version.
card.binary.get CellCell+WiFiWiFi
noteThis request is not available in the currently selected Notecard firmware version.
card.binary.put CellCell+WiFiWiFi
noteThis request is not available in the currently selected Notecard firmware version.
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 (optional)
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"
rsp = card.Transaction(req)Set the AUX_CHARGING mode to charging.
Response Members
charging
boolean
Will display true when in AUX_CHARGING "charging" mode.
mode
string
The current AUX_CHARGING mode, or off if not set.
{
"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.
email
string (format: email) (optional)
Set the email address of the Notecard maintainer.
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.
{
"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)Set contact information for the Notecard maintainer.
Response Members
email
string (format: email)
Email address of the Notecard maintainer.
name
string
Name of the Notecard maintainer.
org
string
Organization name of the Notecard maintainer.
role
string
Role 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.
mode
string (optional)
The mode argument allows you to control whether a Notecard's AUX pins (default) or ALT_DFU pins are used for Notecard Outboard Firmware Update. This argument is only supported on Notecards that have ALT_DFU pins, which includes all versions of Notecard Cell+WiFi, non-legacy versions of Notecard Cellular, and Notecard WiFi v2.
"altdfu": Enable the Notecard's ALT_DFU pins (instead of the AUX pins) for use with Notecard Outboard Firmware Update.
"off": Return the Notecard's ALT_DFU pins to their default state.
name
string (optional)
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.
"esp32": ESP32 microcontroller family.
"stm32": STM32 microcontroller family.
"stm32-bi": STM32 microcontroller family with boot inverted (boot pin active low).
"mcuboot": MCUboot compatible microcontroller (added in v5.3.1).
"-": Resets the configuration.
off
boolean (optional)
Set to true to disable Notecard Outboard Firmware Update from occurring.
on
boolean (optional)
Set to true to enable Notecard Outboard Firmware Update.
seconds
integer (optional)
When used with "off":true, disable Notecard Outboard Firmware Update operations for the specified number of seconds.
start
boolean (optional)
Set to true to enable the host RESET if previously disabled with "stop":true.
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.
{
"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
rsp = card.Transaction(req)Enable DFU for STM32 microcontroller.
{
"cmd": "card.dfu",
"name": "esp32",
"on": true
}J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "esp32");
JAddBoolToObject(req, "on", true);
NoteRequest(req);req = {"cmd": "card.dfu"}
req["name"] = "esp32"
req["on"] = True
card.Transaction(req)Enable DFU for ESP32 microcontroller.
{
"req": "card.dfu",
"mode": "altdfu"
}J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "mode", "altdfu");
NoteRequest(req);req = {"req": "card.dfu"}
req["mode"] = "altdfu"
rsp = card.Transaction(req)Use ALT_DFU pins instead of AUX pins on Cell+WiFi.
{
"req": "card.dfu",
"off": true,
"seconds": 3600
}J *req = NoteNewRequest("card.dfu");
JAddBoolToObject(req, "off", true);
JAddNumberToObject(req, "seconds", 3600);
NoteRequest(req);req = {"req": "card.dfu"}
req["off"] = True
req["seconds"] = 3600
rsp = card.Transaction(req)Disable DFU for 3600 seconds.
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
noteThis request is not available in the currently selected Notecard firmware version.
card.io CellCell+WiFiLoRaWiFi
noteThis request is not available in the currently selected Notecard firmware version.
card.led CellCell+WiFiLoRaWiFi
noteThis request is not available in the currently selected Notecard firmware version.
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.
{
"req": "card.location"
}J *req = NoteNewRequest("card.location");
NoteRequest(req);req = {"req": "card.location"}
rsp = card.Transaction(req)Retrieve the last known location of the Notecard.
Response Members
count
integer
The number of consecutive recorded GPS/GNSS failures.
dop
number
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.
lat
number
The latitude in degrees of the last known location.
lon
number
The longitude in degrees of the last known location.
max
integer
If a geofence is enabled by card.location.mode, meters from the geofence center.
mode
string
The GPS/GNSS connection mode. Will be continuous, periodic, or off.
status
string
The current status of the Notecard GPS/GNSS connection.
time
UNIX Epoch time
UNIX Epoch time. The time of location capture.
{
"status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active} {gps-signal} {gps-sats} {gps}",
"mode": "periodic",
"lat": 42.5776,
"lon": -70.87134,
"time": 1598554399,
"max": 25
}card.location.mode CellCell+WiFiLoRaWiFi
Sets location-related configuration settings. Retrieves the current location mode when passed with no argument.
delete
boolean (optional)
Set to true to delete the last known location stored in the Notecard.
lat
number (optional, default last known latitude)
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
number (optional, default last known longitude)
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.
max
integer (optional)
Meters from a geofence center. Used to enable geofence location tracking.
minutes
integer (optional, default 5)
When geofence is enabled, the number of minutes the device should be outside the geofence before the Notecard location is tracked.
mode
string (optional)
Sets the location mode.
"": Retrieves the current mode.
"off": Turns location mode off. Approximate location may still be ascertained from Notehub.
"periodic": Samples location at a specified interval, if the device has moved.
"continuous": Enables 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": Reports 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.
{
"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)Enable continuous GPS/GNSS sampling.
{
"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)Enable periodic location sampling at 1-hour intervals.
{
"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.5776);
JAddNumberToObject(req, "lon", -70.87134);
JAddNumberToObject(req, "max", 100);
JAddNumberToObject(req, "minutes", 2);
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["lat"] = 42.5776
req["lon"] = -70.87134
req["max"] = 100
req["minutes"] = 2
rsp = card.Transaction(req)Enable geofencing with specific location and radius.
{
"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.5776);
JAddNumberToObject(req, "lon", -70.87134);
NoteRequest(req);req = {"req": "card.location.mode"}
req["mode"] = "fixed"
req["lat"] = 42.5776
req["lon"] = -70.87134
rsp = card.Transaction(req)Set a fixed location for the device.
Response Members
lat
number
If geofence is enabled, the geofence center latitude in degrees.
lon
number
If geofence is enabled, the geofence center longitude in degrees.
max
integer
If geofence is enabled, the meters from geofence center.
minutes
integer
If geofence is enabled, the currently configured geofence debounce period.
mode
string
The current location mode.
seconds
integer
If specified, the periodic sample interval.
vseconds
string
If specified, the voltage-variable period.
{
"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.
file
string (optional, 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.
heartbeat
boolean (optional)
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 (optional)
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.
start
boolean (optional)
Set to true to start Notefile tracking.
stop
boolean (optional)
Set to true to stop Notefile tracking.
sync
boolean (optional)
Set to true to perform an immediate sync to the Notehub each time a new Note is added.
{
"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)Start location tracking.
{
"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)Stop location tracking.
{
"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)Start tracking with heartbeat mode and immediate sync.
Response Members
file
string
The tracking Notefile, if provided.
heartbeat
boolean
true if heartbeat is enabled.
minutes
integer
The heartbeat interval in minutes, if provided.
seconds
integer
If tracking is enabled and a heartbeat hours value is not set, the tracking interval set in card.location.mode.
start
boolean
true if tracking is enabled.
stop
boolean
true if tracking is disabled.
{
"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.
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.
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.
usb
boolean (optional, default false)
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
rsp = card.Transaction(req)Configure the green LED to pulse 5 times.
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 {}.
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)Request motion information with 2-minute sampling buckets.
Response Members
alert
boolean
true if the Notecard's accelerometer detected a free-fall since the last request to card.motion.
count
integer
The number of accelerometer motion events since the card.motion request was last made.
mode
string
Returns the current motion status of the Notecard (e.g. "stopped" or "moving"). Learn how to configure this feature in this guide.
motion
integer
Time of the last accelerometer motion event.
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.
seconds
integer
If the minutes argument is provided, the duration of each bucket of sample accelerometer movements.
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", "angled".
{
"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.
motion
integer (optional)
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.
seconds
integer (optional)
Period for each bucket of movements to be accumulated when minutes is used with card.motion.
start
boolean (optional)
true to enable the Notecard accelerometer and start motion tracking.
stop
boolean (optional)
true to disable the Notecard accelerometer and stop motion tracking.
{
"req": "card.motion.mode",
"start": true
}J *req = NoteNewRequest("card.motion.mode");
JAddBoolToObject(req, "start", true);
NoteRequest(req);req = {"req": "card.motion.mode"}
req["start"] = True
rsp = card.Transaction(req)Enable motion tracking with default settings.
{
"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
rsp = card.Transaction(req)Enable motion tracking with custom sensitivity and bucket duration.
{
"req": "card.motion.mode",
"stop": true
}J *req = NoteNewRequest("card.motion.mode");
JAddBoolToObject(req, "stop", true);
NoteRequest(req);req = {"req": "card.motion.mode"}
req["stop"] = True
rsp = card.Transaction(req)Disable motion tracking.
{
"req": "card.motion.mode",
"motion": 5,
"seconds": 60
}J *req = NoteNewRequest("card.motion.mode");
JAddNumberToObject(req, "motion", 5);
JAddNumberToObject(req, "seconds", 60);
NoteRequest(req);req = {"req": "card.motion.mode"}
req["motion"] = 5
req["seconds"] = 60
rsp = card.Transaction(req)Set motion threshold for status change detection.
Response Members
{} means success.card.motion.sync CellCell+WiFiWiFi
Configures automatic sync triggered by Notecard movement.
count
integer (optional)
The number of most recent motion buckets to examine.
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.
start
boolean (optional)
true to start motion-triggered syncing.
stop
boolean (optional)
true to stop motion-triggered syncing.
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
}J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "start", true);
NoteRequest(req);req = {"req": "card.motion.sync"}
req["start"] = True
rsp = card.Transaction(req)Enable motion-triggered syncing with default settings.
{
"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
rsp = card.Transaction(req)Set motion sync with specific timing and threshold parameters.
{
"req": "card.motion.sync",
"stop": true
}J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "stop", true);
NoteRequest(req);req = {"req": "card.motion.sync"}
req["stop"] = True
rsp = card.Transaction(req)Disable motion-triggered syncing.
{
"req": "card.motion.sync",
"start": true,
"threshold": 0,
"minutes": 10
}J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "threshold", 0);
JAddNumberToObject(req, "minutes", 10);
NoteRequest(req);req = {"req": "card.motion.sync"}
req["start"] = True
req["threshold"] = 0
req["minutes"] = 10
rsp = card.Transaction(req)Configure sync to trigger only on orientation changes.
Response Members
{} means success.card.motion.track CellCell+WiFiWiFi
Configures automatic capture of Notecard accelerometer motion in a Notefile.
count
integer (optional)
The number of most recent motion buckets to examine.
file
string (optional, 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.
minutes
integer (optional)
The maximum period to capture Notes in the Notefile.
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).
start
boolean (optional)
true to start motion capture.
stop
boolean (optional)
true to stop motion capture.
threshold
integer (optional)
The number of buckets that must indicate motion in order to capture.
{
"req": "card.motion.track",
"start": true
}J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "start", true);
NoteRequest(req);req = {"req": "card.motion.track"}
req["start"] = True
rsp = card.Transaction(req)Enable motion tracking with default settings.
{
"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"
rsp = card.Transaction(req)Set motion tracking with custom parameters and Notefile.
{
"req": "card.motion.track",
"stop": true
}J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "stop", true);
NoteRequest(req);req = {"req": "card.motion.track"}
req["stop"] = True
rsp = card.Transaction(req)Disable motion tracking.
{
"req": "card.motion.track",
"start": true,
"now": true,
"minutes": 15
}J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "start", true);
JAddBoolToObject(req, "now", true);
JAddNumberToObject(req, "minutes", 15);
NoteRequest(req);req = {"req": "card.motion.track"}
req["start"] = True
req["now"] = True
req["minutes"] = 15
rsp = card.Transaction(req)Configure motion tracking with immediate orientation change capture.
Response Members
{} means success.card.power CellCell+WiFiWiFi
noteThis request is not available in the currently selected Notecard firmware version.
card.random CellCell+WiFiWiFi
Obtain a single random 32 bit unsigned integer modulo or count number of bytes of random data from the Notecard hardware random number generator.
count
integer (optional)
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.
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.
{
"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)Request a random integer between 0 and count-1.
{
"req": "card.random",
"mode": "payload",
"count": 100
}J *req = NoteNewRequest("card.random");
JAddStringToObject(req, "mode", "payload");
JAddNumberToObject(req, "count", 100);
NoteRequest(req);req = {"req": "card.random"}
req["mode"] = "payload"
req["count"] = 100
rsp = card.Transaction(req)Request random bytes returned as base64-encoded payload.
Response Members
count
integer
A random number generated by the Notecard's onboard hardware random number generator.
payload
base64 string
If using "mode":"payload", a base64-encoded string with random values, the length of which is specified by the count argument.
{
"count": 86
}Example response with a random integer.
{
"payload": "SGVsbG8gV29ybGQ="
}Example response with base64-encoded random data.
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.
{
"cmd": "card.restart"
}J *req = NoteNewRequest("card.restart");
NoteRequest(req);req = {"cmd": "card.restart"}
card.Transaction(req)Perform a firmware restart of the Notecard.
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.
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.
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.
{
"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
rsp = card.Transaction(req)Reset Notecard configuration and deprovision from Notehub.
{
"req": "card.restore"
}J *req = NoteNewRequest("card.restore");
NoteRequest(req);req = {"req": "card.restore"}
rsp = card.Transaction(req)Reset only the file system, forcing re-sync from Notehub.
Response Members
{} means success.card.sleep WiFi
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 this power state is not available if the Notecard is plugged in via USB.
Read more in the guide on using Deep Sleep Mode on Notecard WiFi v2.
noteThis API is only valid for Notecard WiFi v2. Additionally, card.sleep will not activate while USB-connected.
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.
"accel": Wake from deep sleep on any movement detected by the onboard accelerometer.
"-accel": Reset to the default setting.
off
boolean (optional)
Set to true to disable the sleep mode on Notecard.
on
boolean (optional)
Set to true to enable Notecard to sleep once it is idle for >= 30 seconds.
seconds
integer (optional)
The number of seconds the Notecard will wait before entering sleep mode (minimum value is 30).
{
"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)Enable sleep mode with default settings.
{
"req": "card.sleep",
"on": true,
"mode": "accel"
}J *req = NoteNewRequest("card.sleep");
JAddBoolToObject(req, "on", true);
JAddStringToObject(req, "mode", "accel");
NoteRequest(req);req = {"req": "card.sleep"}
req["on"] = True
req["mode"] = "accel"
rsp = card.Transaction(req)Enable sleep mode with accelerometer wake functionality.
{
"req": "card.sleep",
"seconds": 60
}J *req = NoteNewRequest("card.sleep");
JAddNumberToObject(req, "seconds", 60);
NoteRequest(req);req = {"req": "card.sleep"}
req["seconds"] = 60
rsp = card.Transaction(req)Set custom wait time before entering sleep mode.
{
"cmd": "card.sleep",
"off": true
}J *req = NoteNewRequest("card.sleep");
JAddBoolToObject(req, "off", true);
NoteRequest(req);req = {"cmd": "card.sleep"}
req["off"] = True
card.Transaction(req)Disable sleep mode functionality.
Response Members
mode
string
Returns "accel" if the Notecard is configured to wake from deep sleep on any movement detected by the onboard accelerometer.
off
boolean
true if sleep mode is disabled.
on
boolean
true if sleep mode is enabled.
seconds
integer
The number of seconds the Notecard will wait before entering sleep mode (only included if default settings are overridden).
{
"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)Request general information about the Notecard's operating status.
Response Members
cell
boolean
true if the modem is currently powered on.
connected
boolean
true if 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
string
General status information.
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.
usb
boolean
true if the Notecard is being powered by USB.
wifi
boolean
true if the Notecard's Wi-Fi radio is currently powered on.
{
"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.
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"
}J *req = NoteNewRequest("card.temp");
NoteRequest(req);req = {"req": "card.temp"}
rsp = card.Transaction(req)Get current temperature from Notecard's onboard sensor.
{
"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)Set up automatic temperature logging at 30-minute intervals.
{
"cmd": "card.temp",
"stop": true
}J *req = NoteNewRequest("card.temp");
JAddBoolToObject(req, "stop", true);
NoteRequest(req);req = {"cmd": "card.temp"}
req["stop"] = True
card.Transaction(req)Stop automatic temperature logging.
{
"cmd": "card.temp",
"sync": true
}J *req = NoteNewRequest("card.temp");
JAddBoolToObject(req, "sync", true);
NoteRequest(req);req = {"cmd": "card.temp"}
req["sync"] = True
card.Transaction(req)Immediately sync pending temperature notes.
Response Members
calibration
number
The calibration differential of the Notecard's onboard sensor.
humidity
number
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
number
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.
temperature
number
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.
usb
boolean
true if the Notecard is connected to USB power.
value
number
The current temperature from the Notecard's onboard sensor in degrees centigrade, including the calibration offset.
voltage
number
The current voltage.
{
"value": 27.625,
"calibration": -3.0
}Example response with onboard sensor temperature and calibration.
{
"value": 25.5,
"calibration": -2.5,
"temperature": 24.8,
"humidity": 45.2,
"pressure": 101325,
"usb": true,
"voltage": 4.95
}Example response with BME280 sensor data and power information.
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"}.
{
"req": "card.time"
}J *req = NoteNewRequest("card.time");
NoteRequest(req);req = {"req": "card.time"}
rsp = card.Transaction(req)Retrieve current date and time information in UTC with location data if available.
Response Members
area
string
The geographic area of the Notecard, if the cell tower is recognized.
country
string
The country where the Notecard is located, if the cell tower is recognized.
lat
number
Latitude of the Notecard, if the cell tower is recognized.
lon
number
Longitude of the Notecard, if the cell tower is recognized.
minutes
integer
Number of minutes East of GMT, if the cell tower is recognized.
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.
zone
string
The time zone of the Notecard, 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"
}Example response with full time and location information.
{
"zone": "UTC,Unknown"
}Example response when time is available but location data hasn't been obtained yet.
card.trace CellCell+WiFiLoRaWiFi
Enable and disable trace mode on a Notecard for debugging.
mode
string (optional)
Set to "on" to enable trace mode on a Notecard, or "off" to disable it.
{
"req": "card.trace",
"mode": "on"
}J *req = NoteNewRequest("card.trace");
JAddStringToObject(req, "mode", "on");
NoteRequest(req);req = {"req": "card.trace"}
req["mode"] = "on"
rsp = card.Transaction(req)Enable trace mode for debugging the Notecard.
{
"cmd": "card.trace",
"mode": "off"
}J *req = NoteNewRequest("card.trace");
JAddStringToObject(req, "mode", "off");
NoteRequest(req);req = {"cmd": "card.trace"}
req["mode"] = "off"
card.Transaction(req)Disable trace mode on the Notecard.
Response Members
{} means success.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 (optional)
The connectivity method to enable on the Notecard.
"-" CellCell+WiFiWiFi
Resets the transport mode to the device default.
"cell" CellCell+WiFi
Enables cellular only on the device.
"cell-ntn" CellCell+WiFi
Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established.
"dual-wifi-cell" Cell+WiFiDeprecated
Deprecated form of "wifi-cell"
"ntn" CellCell+WiFiWiFi
Enables NTN (Non-Terrestrial Network) mode on the device for use with Starnote.
"wifi" Cell+WiFiWiFi
Enables Wi-Fi only on the device.
"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.
"wifi-cell-ntn" Cell+WiFi
Prioritizes Wi-Fi connectivity while falling back to cellular, and lastly to NTN.
"wifi-ntn" Cell+WiFiWiFi
Prioritizes Wi-Fi connectivity while falling back to NTN if a Wi-Fi connection cannot be established.
{
"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)Configure Notecard Cell+WiFi to prioritize WiFi while falling back to cellular.
{
"req": "card.transport",
"method": "wifi"
}J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "wifi");
NoteRequest(req);req = {"req": "card.transport"}
req["method"] = "wifi"
rsp = card.Transaction(req)Configure device to use WiFi connectivity only.
{
"req": "card.transport",
"method": "cell"
}J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "cell");
NoteRequest(req);req = {"req": "card.transport"}
req["method"] = "cell"
rsp = card.Transaction(req)Configure device to use cellular connectivity only.
{
"cmd": "card.transport",
"method": "-"
}J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "-");
NoteRequest(req);req = {"cmd": "card.transport"}
req["method"] = "-"
card.Transaction(req)Reset the transport mode to device default settings.
{
"req": "card.transport",
"method": "ntn"
}J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "ntn");
NoteRequest(req);req = {"req": "card.transport"}
req["method"] = "ntn"
rsp = card.Transaction(req)Enable NTN (Non-Terrestrial Network) mode for Starnote connectivity.
{
"req": "card.transport",
"method": "wifi-cell-ntn",
"seconds": 1800
}J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "wifi-cell-ntn");
JAddNumberToObject(req, "seconds", 1800);
NoteRequest(req);req = {"req": "card.transport"}
req["method"] = "wifi-cell-ntn"
req["seconds"] = 1800
rsp = card.Transaction(req)Configure triple fallback: WiFi → cellular → NTN with custom timeout.
Response Members
method
string
The connectivity method currently enabled on the device.
{
"method": "wifi-cell"
}Response showing WiFi-cellular priority transport mode is active.
{
"method": "cell"
}Response showing cellular-only transport mode is active.
{
"method": "ntn"
}Response showing NTN (Non-Terrestrial Network) transport mode is active.
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.
noteSee Using Cell Tower & Wi-Fi Triangulation for more information.
minutes
integer (optional, default 0)
Minimum delay, in minutes, between triangulation attempts. Use 0 for no time-based suppression.
mode
string (optional)
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. See Using Cell Tower & Wi-Fi Triangulation for more information.
"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.
"-": Clear the currently-set triangulation mode.
on
boolean (optional, default false)
true to instruct the Notecard to triangulate even if the module has not moved. Only takes effect when set is true.
set
boolean (optional, default false)
true to instruct the module to use the state of the on and usb arguments.
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.
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.
usb
boolean (optional, default false)
true to use perform triangulation only when the Notecard is connected to USB power. Only takes effect when set is true.
{
"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)Enable triangulation using cell towers only.
{
"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)Enable triangulation using both Wi-Fi and cell towers when connected to USB power.
{
"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:12:12:f8\",1)
+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)
+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)
+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)
+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)
+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)
+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)
+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)
+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)
");
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)Send a newline-terminated list of Wi-Fi access points to the Notecard for triangulation.
{
"req": "card.triangulate",
"mode": "-"
}J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "-");
NoteRequest(req);req = {"req": "card.triangulate"}
req["mode"] = "-"
rsp = card.Transaction(req)Disable triangulation mode.
Response Members
length
integer
The length of the text buffer provided in the current or a previous request.
mode
string
A comma-separated list indicating the active triangulation modes.
motion
integer
Time of last detected Notecard movement.
on
boolean
true if triangulation scans will be performed even if the device has not moved.
time
UNIX Epoch time
Time of last triangulation scan.
usb
boolean
true if triangulation scans will be performed only when the device is USB-powered.
{
"usb": true,
"mode": "wifi,cell",
"length": 443,
"on": true,
"time": 1606755042,
"motion": 1606757487
}Response showing full triangulation configuration and status information.
{
"mode": "cell",
"on": false
}Response showing basic triangulation mode configuration.
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 (optional, default total)
The time period to use for statistics. Must be one of:
"total": All stats since the Notecard was activated.
"1hour": Statistics for the last hour period.
"1day": Statistics for the last day period.
"30day": Statistics for the last 30 days period.
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"
}J *req = NoteNewRequest("card.usage.get");
NoteRequest(req);req = {"req": "card.usage.get"}
rsp = card.Transaction(req)Retrieve all usage statistics since Notecard activation.
{
"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)Get usage statistics for a specific day, 5 days ago.
{
"req": "card.usage.get",
"mode": "1hour"
}J *req = NoteNewRequest("card.usage.get");
JAddStringToObject(req, "mode", "1hour");
NoteRequest(req);req = {"req": "card.usage.get"}
req["mode"] = "1hour"
rsp = card.Transaction(req)Get usage statistics for the current hour period.
{
"req": "card.usage.get",
"mode": "30day"
}J *req = NoteNewRequest("card.usage.get");
JAddStringToObject(req, "mode", "30day");
NoteRequest(req);req = {"req": "card.usage.get"}
req["mode"] = "30day"
rsp = card.Transaction(req)Get usage statistics for the last 30 days.
Response Members
bytes_received
integer
Number of bytes received by the Notecard from Notehub.
bytes_sent
integer
Number of bytes sent by the Notecard to Notehub.
notes_received
integer
Approximate number of notes received by the Notecard from Notehub.
notes_sent
integer
Approximate number of notes sent by the Notecard to Notehub.
seconds
integer
Number of seconds in the analyzed period.
sessions_secure
integer
Number of secure Notehub sessions.
sessions_standard
integer
Number of standard Notehub sessions.
time
UNIX Epoch time
Start time of the analyzed period or, if mode="total", the time of activation.
{
"seconds": 1291377,
"time": 1598479763,
"bytes_sent": 163577,
"bytes_received": 454565,
"notes_sent": 114,
"notes_received": 26,
"sessions_standard": 143,
"sessions_secure": 31
}Example response showing comprehensive network usage data.
{
"seconds": 3600,
"time": 1700000000,
"bytes_sent": 1024,
"bytes_received": 2048
}Example response with basic usage metrics.
card.usage.test CellCell+WiFiWiFi
Calculates a projection of how long the available data quota will last based on the observed usage patterns.
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 (optional, 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)Calculate data quota projection based on the last 7 days with 500MB quota.
{
"req": "card.usage.test",
"hours": 12
}J *req = NoteNewRequest("card.usage.test");
JAddNumberToObject(req, "hours", 12);
NoteRequest(req);req = {"req": "card.usage.test"}
req["hours"] = 12
rsp = card.Transaction(req)Calculate data quota projection based on the last 12 hours.
{
"req": "card.usage.test",
"days": 30
}J *req = NoteNewRequest("card.usage.test");
JAddNumberToObject(req, "days", 30);
NoteRequest(req);req = {"req": "card.usage.test"}
req["days"] = 30
rsp = card.Transaction(req)Test with default 1024MB quota using 30 days of data.
Response Members
bytes_per_day
integer
Average bytes per day used during the test period.
bytes_received
integer
Number of bytes received by the Notecard from Notehub.
bytes_sent
integer
Number of bytes sent by the Notecard to Notehub.
days
integer
The number of days used for the test.
max
integer
The days of projected data available based on test.
notes_received
integer
Number of notes received by the Notecard from Notehub.
notes_sent
integer
Number of notes sent by the Notecard to Notehub.
seconds
integer
Number of seconds in the analyzed period.
sessions_secure
integer
Number of secure Notehub sessions.
sessions_standard
integer
Number of standard Notehub sessions.
time
UNIX Epoch time
Time of device activation.
{
"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
}Example response showing comprehensive usage projection data.
{
"max": 1825,
"days": 30,
"bytes_per_day": 56832,
"seconds": 2592000,
"time": 1700000000
}Example response with essential projection metrics.
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)Retrieve firmware version and device information.
Response Members
api
integer
The current Notecard API major version in use.
board
string
The Notecard board version number.
body
object
An object containing Notecard firmware details for programmatic access.
cell
boolean
If true, indicates the Notecard supports cellular connectivity.
device
string
The DeviceUID of the Notecard.
gps
boolean
If true, indicates the Notecard has an onboard GPS module.
name
string
The official name of the device.
sku
string
The Notecard SKU.
version
string
The full version number of the Notecard firmware.
{
"version": "notecard-5.3.1",
"device": "dev:000000000000000",
"name": "Blues Wireless Notecard",
"sku": "NOTE-NBGL",
"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.
alert
boolean (optional, 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.
hours
integer (optional, default 720)
The number of hours to analyze, up to 720 (30 days).
mode
string (optional, 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.
"default": Default behavior. Equivalent to normal:2.5;dead:0.
"lipo": LiPo batteries. Equivalent to usb:4.6;high:4.0;normal:3.5;low:3.2;dead:0.
"l91": L91 batteries. Equivalent to high:5.0;normal:4.5;low:0.
"alkaline": Alkaline batteries. Equivalent to usb:4.6;high:4.2;normal:3.6;low:0.
"tad": Tadiran HLC batteries. Equivalent to usb:4.6;normal:3.2;low:0.
"lic": Lithium-ion capacitors. Equivalent to usb:4.6;high:3.8;normal:3.1;low:0.
"?": Query the Notecard for its currently-set thresholds.
name
string (optional)
Specifies an environment variable to override application default timing values.
offset
integer (optional, default 0)
Number of hours to move into the past before starting analysis.
set
boolean (optional, default false)
Used along with calibration, set to true to specify a new calibration value.
sync
boolean (optional, 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.
vmax
number (optional, default 4.5)
Ignore voltage readings above this level when performing calculations.
vmin
number (optional, default 2.5)
Ignore voltage readings below this level when performing calculations.
{
"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)Retrieve voltage information with trend analysis for 300 hours.
{
"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)Configure voltage thresholds for LiPo battery operation.
{
"req": "card.voltage",
"mode": "?"
}J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "?");
NoteRequest(req);req = {"req": "card.voltage"}
req["mode"] = "?"
rsp = card.Transaction(req)Query the Notecard for its currently-set voltage thresholds.
{
"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)Enable USB power state monitoring with alerts and sync.
Response Members
daily
number
Change of moving average in the last 24 hours, if relevant to the time period analyzed.
hours
integer
The number of hours used for trend analysis.
minutes
integer
Represents the Notecard's uptime in minutes. This field is not present when the device is powered via USB.
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".
monthly
number
Change of moving average in the last 30 days, if relevant to the time period analyzed.
value
number
The current voltage.
vavg
number
The average voltage value during the measured period.
vmax
number
The highest voltage value captured during the measurement period.
vmin
number
The lowest voltage value captured during the measurement period.
weekly
number
Change of moving average in the last 7 days, if relevant to the time period analyzed.
{
"usb": true,
"hours": 120,
"mode": "usb",
"value": 5.112190219747135,
"vmin": 4,
"vmax": 4,
"vavg": 4
}Example response when Notecard is powered via USB.
{
"mode": "normal",
"usb": false,
"value": 3.85,
"hours": 720,
"vmin": 3.2,
"vmax": 4.1,
"vavg": 3.75,
"daily": -0.05,
"weekly": -0.3,
"monthly": -0.8,
"minutes": 43200
}Example response showing battery voltage with trend analysis.
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.
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.
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.
ssid
string (optional)
The SSID of the Wi-Fi access point. Alternatively, use - to clear an already set SSID.
start
boolean (optional)
Specify true to activate SoftAP mode on the Notecard programmatically.
{
"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)Set Wi-Fi SSID and password to connect to an access point.
{
"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)Clear existing Wi-Fi credentials to disconnect.
{
"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)Configure SoftAP with custom name and organization branding.
{
"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)Configure SoftAP name with MAC address suffix for unique identification.
{
"req": "card.wifi",
"text": "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"
}J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "text", "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]");
NoteRequest(req);req = {"req": "card.wifi"}
req["text"] = "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"
rsp = card.Transaction(req)Set up multiple Wi-Fi access points for fallback connectivity.
Response Members
secure
boolean
true means that the Wi-Fi access point is using Management Frame Protection.
security
string
The security protocol the Wi-Fi access point uses.
ssid
string
The SSID of the Wi-Fi access point.
version
string
The Silicon Labs WF200 Wi-Fi Transceiver binary version.
{
"secure": true,
"version": "3.12.3",
"ssid": "<ssid name>",
"security": "wpa2-psk"
}Example response showing comprehensive Wi-Fi connection information.
{
"ssid": "HomeNetwork",
"security": "wpa3"
}Example response with basic Wi-Fi access point information.
{
"version": "3.12.3"
}Example response showing Wi-Fi transceiver version.
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.
apn
string (optional)
Access Point Name (APN) when using an external SIM. Use "-" to reset to the Notecard default APN.
hours
integer (optional)
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.
method
string (optional)
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.
mode
string (optional)
Network scan mode. Must be one of:
"-": Reset to the default mode.
"auto": Perform automatic band scan mode (this is the default mode).
"m": Restrict the modem to Cat-M1 (applies exclusively to Narrowband Notecard Cellular devices).
"nb": Restrict the modem to Cat-NB1 (applies exclusively to Narrowband Notecard Cellular devices).
"gprs": Restrict the modem to EGPRS (applies exclusively to Narrowband Notecard Cellular devices).
{
"req": "card.wireless"
}J *req = NoteNewRequest("card.wireless");
NoteRequest(req);req = {"req": "card.wireless"}
rsp = card.Transaction(req)Request current network state without any modifications.
{
"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)Restrict the modem to Cat-NB1 for narrowband connectivity.
{
"req": "card.wireless",
"mode": "-"
}J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "mode", "-");
NoteRequest(req);req = {"req": "card.wireless"}
req["mode"] = "-"
rsp = card.Transaction(req)Reset network scan mode to default behavior.
{
"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)Configure APN for external SIM card usage.
{
"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)Configure dual SIM failover with external SIM priority.
Response Members
count
integer
Number of bars of signal quality.
net
object
An object with detailed modem, radio access technology, and signal information (details will differ depending on the type of Notecard).
status
string
The current status of the wireless connection and modem.
{
"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
}
}Example response showing comprehensive wireless connection and signal information.
{
"status": "connected",
"count": 3
}Example response with basic signal strength and status.
{
"status": "searching",
"count": 2,
"net": {
"band": "LTE BAND 12",
"rat": "lte",
"rssi": -85,
"bars": 2,
"mcc": 310,
"mnc": 260
}
}Example response showing detailed network information.
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.
add
integer (optional, 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 (optional, 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 (optional, 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.
rate
number (optional, 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.
reset
boolean (optional)
Set to true to remove the Notecard from certain types of penalty boxes.
set
boolean (optional)
Set to true to override the default settings of the Network Registration Failure Penalty Box.
{
"req": "card.wireless.penalty"
}J *req = NoteNewRequest("card.wireless.penalty");
NoteRequest(req);req = {"req": "card.wireless.penalty"}
rsp = card.Transaction(req)Request current penalty box status and information.
{
"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)Reset and remove the Notecard from penalty box conditions.
{
"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)Configure custom penalty box parameters with modified defaults.
Response Members
count
integer
The number of consecutive network registration failures.
minutes
integer
The time since the first network registration failure.
status
string
If the Notecard is in a Penalty Box, this field provides the associated Error and Status Codes.
{
"seconds": 3324,
"minutes": 69,
"status": "network: can't connect (55.4 min remaining) {registration-failure}{network}{extended-network-failure}",
"count": 6
}Example response showing Notecard in penalty box with active network registration failure.
{
"minutes": 0,
"count": 0
}Example response when Notecard is not in a penalty box.
{
"count": 3,
"minutes": 15
}Example response with basic penalty metrics without active penalty.
