Learn how to get started with Cellular, Wi-Fi, LoRa, and Satellite using Blues Notecard on September 25th

Blues Developers
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our Forum
Button IconSign In
Docs Home
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
API Reference
Glossary
System Notefiles
Notecard API
Introduction
card Requests
card.attncard.auxcard.aux.serialcard.binarycard.binary.getcard.binary.putcard.carriercard.contactcard.dfucard.illuminationcard.iocard.ledcard.locationcard.location.modecard.location.trackcard.monitorcard.motioncard.motion.modecard.motion.synccard.motion.trackcard.powercard.randomcard.restartcard.restorecard.sleepcard.statuscard.tempcard.timecard.tracecard.transportcard.triangulatecard.usage.getcard.usage.testcard.versioncard.voltagecard.wificard.wirelesscard.wireless.penalty
dfu Requests
env Requests
file Requests
hub Requests
note Requests
ntn Requests
var Requests
web Requests
Notehub API
API Introduction
Authorization API
Billing Account API
Device API
Event API
Monitor API
Project API
Route API
homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_rightcard Requests - API Reference

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.

Notecard Firmware Version:
3.x

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.

Arguments

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

"auxgpio" CellCell+WiFiLoRaWiFi

When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using -auxgpio.

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

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

verify

boolean (optional)

When true, returns the current attention mode configuration, if any.

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

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

note

Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces.

Arguments

connected

boolean (optional)

Cell Cell+WiFi WiFi

If true, defers the sync of the state change Notefile to the next sync as configured by the hub.set request.

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.

file

string (optional)

Cell Cell+WiFi WiFi

The name of the Notefile used to report state changes when used in conjunction with "sync": true. Default Notefile name is _button.qo.

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.

limit

boolean (optional)

If true, along with "mode":"track" and gps:true the Notecard will disable concurrent modem use during GPS tracking.

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.

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

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

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

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

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

rate

integer (optional, default 115200)

The AUX UART baud rate for debug communication over the AUXRX and AUXTX pins.

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.

sensitivity

integer (optional)

Cell Cell+WiFi WiFi

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.

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.

sync

boolean (optional)

Cell Cell+WiFi WiFi

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.

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.

"input-pulldown" CellCell+WiFiLoRaWiFi

to set the pin as a pull-down input.

"input-pullup" CellCell+WiFiLoRaWiFi

to set the pin as a pull-up 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.

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.

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.

Example Response
{
  "mode": "gpio",
  "state": [
    {},
    {
      "low": true
    },
    {
      "high": true
    },
    {
      "count": [
        3
      ]
    }
  ],
  "time": 1592587637,
  "seconds": 2
}

card.aux.serial CellCell+WiFiWiFi

Configure various uses of the AUXTX and AUXRX pins on the Notecard's edge connector.

note

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

Arguments

duration

integer (optional)

If using "mode": "accel", specify a sampling duration for the Notecard accelerometer.

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

mode

string (optional)

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

"notify": Used along with one or more of the notify options to send streaming data or notification data over the AUX pins. When used alone, preserves existing notification settings.

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

ms

integer (optional)

The delay in milliseconds before sending a buffer of max size.

{
  "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"
rsp = card.Transaction(req)

Configure AUX serial for external GPS communication. 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,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"] = 5
rsp = card.Transaction(req)

Configure AUX serial for DFU notifications with timeout.

{
  "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"
rsp = card.Transaction(req)

Configure AUX serial for environment variable change notifications.

{
  "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"
rsp = card.Transaction(req)

Set AUX serial to request mode for command/response communication.

{
  "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"] = "notify,accel"
req["duration"] = 500
rsp = card.Transaction(req)

Send raw readings from the onboard accelerometer over AUX every 500 ms.

{
  "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"
rsp = card.Transaction(req)

Turn on Inbound Signals from Notehub for low-latency communication.

{
  "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
rsp = card.Transaction(req)

Subscribe to multiple notifications at once.

Response Members

mode

string

The current AUX mode.

Example Response
{
  "mode": "req",
  "rate": 115200
}

card.binary CellCell+WiFiWiFi

note

This request is not available in the currently selected Notecard firmware version.

card.binary.get CellCell+WiFiWiFi

note

This request is not available in the currently selected Notecard firmware version.

card.binary.put CellCell+WiFiWiFi

note

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

Arguments

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.

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

Arguments

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.

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

Arguments

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.

Example Response
{
  "name": "stm32"
}

card.illumination CellCell+WiFiWiFi

note

This request is not available in the currently selected Notecard firmware version.

card.io CellCell+WiFiLoRaWiFi

note

This request is not available in the currently selected Notecard firmware version.

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.

note

The Notecard must first be configured for the appropriate LED type using card.aux. For monochromatic LEDs, use {"req": "card.aux", "mode": "led"}. For NeoPixels, use {"req": "card.aux", "mode": "neo"}.

Arguments

mode

string (optional)

Used to specify the color of the LED to turn on or off.

Note: Notecard LoRa does not support monochromatic LED modes, only NeoPixels.

"red": Supports LED & NeoPixel

"green": Supports LED & NeoPixel

"yellow": Supports LED & NeoPixel

"blue": Supports NeoPixel

"cyan": Supports NeoPixel

"magenta": Supports NeoPixel

"orange": Supports NeoPixel

"white": Supports NeoPixel

"gray": Supports NeoPixel

off

boolean (optional)

Set to true to turn the specified LED or NeoPixel off.

on

boolean (optional)

Set to true to turn the specified LED or NeoPixel on.

{
  "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"
rsp = card.Transaction(req)

req = {"req": "card.led"}
req["mode"] = "red"
req["on"] = True
rsp = 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.aux"}
req["mode"] = "neo"
rsp = card.Transaction(req)

req = {"req": "card.led"}
req["mode"] = "blue"
req["on"] = True
rsp = card.Transaction(req)

As shown above, the Notecard must also be in neo, neo-monitor, or track-neo-monitor mode and the NeoPixel(s) wired according to the instructions provided in the guide on Using Neo-Monitor Mode.

Response Members
None: an empty object {} 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.

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

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

Arguments

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.

threshold

integer (optional, default 0)

When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.

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.

threshold

integer

When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.

vseconds

string

If specified, the voltage-variable period.

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

Arguments

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.

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

note

Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's M.2 connector.

Arguments

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
None: an empty object {} 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 {}.

Arguments

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

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

Arguments

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.

sensitivity

integer (optional, 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

0: Not specified. Do not modify the current sample rate.

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

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
None: an empty object {} means success.

card.motion.sync CellCell+WiFiWiFi

Configures automatic sync triggered by Notecard movement.

Arguments

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
None: an empty object {} means success.

card.motion.track CellCell+WiFiWiFi

Configures automatic capture of Notecard accelerometer motion in a Notefile.

Arguments

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
None: an empty object {} means success.

card.power CellCell+WiFiWiFi

note

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

Arguments

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.

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

warning

Calls to card.restart are not supported for use in production applications as they can cause increased cellular data and consumption credit usage.

Arguments
None
{
  "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
None: an empty object {} 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.

Arguments

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
None: an empty object {} 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.

note

This API is only valid for Notecard WiFi v2. Additionally, card.sleep will not activate while USB-connected.

Arguments

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

Example Response
{
  "seconds": 10,
  "mode": "accel",
  "on": true
}

card.status CellCell+WiFiLoRaWiFi

Returns general information about the Notecard's operating status.

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

gps

boolean

true if Notecard's GPS module is currently powered on.

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.

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

Arguments

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.

Example Response
{
  "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"}.

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

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

Arguments

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
None: an empty object {} 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.

Arguments

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.

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

note

See Using Cell Tower & Wi-Fi Triangulation for more information.

Arguments

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.

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

note

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

Arguments

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.

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

Arguments

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.

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

Arguments

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.

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

Arguments

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.

usb

boolean (optional, default false)

When enabled, the Notecard will monitor for changes to USB power state.

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.

usb

boolean

true if the Notecard is connected to USB power.

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.

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

note

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

Arguments

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.

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

Arguments

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.

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

warning

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

Arguments

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.

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

Introduction dfu Requests
Can we improve this page? Send us feedback
© 2025 Blues Inc.
© 2025 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with the Notecard's API on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up