card Requests
The Notecard provides a number of requests that can be used to
configure the behavior of the Notecard, its pins, its use of GPS and
accelerometer data, and to query the state of the Device, its network connection
and peripherals. All of these requests begin with the card
prefix.
card.attn
Configure hardware notification from the Notecard to MCU host. Note: Requires a connection between the notecard ATTN pin and a GPIO pin on the host MCU.
mode
string
A comma-separated list of one or more of the following keywords:
""
Fetches currently-pending events in the "files" collection.
"arm"
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"
(Added in v3.4.1)
When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using
-auxpgio
.
"connected"
When armed, will cause ATTN to fire whenever the module connects
to cellular. Disable with -connected
.
"disarm"
Causes ATTN pin to go HIGH if it had been LOW. As of v3.2.1, -all
can be used
with disarm
to clear all ATTN monitors currently set.
"env"
(Added in v3.4.1)
When armed, causes ATTN to fire if an environment variable changes on the
Notecard. Disable by using -env
.
"files"
When armed, will cause ATTN to fire if any of the "files" are
modified. Disable by using -files
.
"location"
When armed, will cause ATTN to fire whenever the Notecard GPS module makes a position fix.
"motion"
When armed, will cause ATTN to fire whenever the accelerometer
detects module motion. Disable with -motion.
"rearm"
(Added in v1.5.3)
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"
When armed, will cause ATTN to fire whenever the Notecard receives a signal.
"sleep"
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.
"watchdog"
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."
"wireless"
(Added in v1.5.3)
Instruct the Notecard to fire the ATTN pin whenever the
card.wireless
status
changes.
files
array (optional)
A list of Notefiles to watch for file-based interrupts.
seconds
int32 (optional)
To set an ATTN timeout when arming, or when using sleep
.
NOTE: When the Notecard is in continuous
mode, the seconds
timeout is serviced by
a routine that wakes every 15 seconds. You can predict when the device will
wake, by rounding up to the nearest 15 second interval.
payload
base64 string (optional)
When using sleep
mode, a payload of data from the host that the Notecard
should hold in memory until retrieved by the host.
start
boolean (optional)
When using sleep
mode and the host has reawakened, request the Notecard to
return the stored payload
.
verify
(Added in v3.2.1)
boolean (optional)
When true
, returns the current attention mode configuration, if any.
Response Members
set
boolean
true
if an attention mode is currently active. A response with no set
field
indicates false
.
files
array
A list of files changed since file
attention mode was set. In addition, this
field will include keywords to signify the occurrence of other attention mode
triggers:
"connected"
"files"
"location"
"motion"
"timeout"
"watchdog"
payload
base64 string
When using sleep
mode with a payload
, the payload provided by the host
to the Notecard.
time
UNIX Epoch time
When using sleep
mode with a payload
, the time that the payload was stored
by the Notecard.
{ "files": ["data.qi", "modified"], "set": true }
card.aux
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.
Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces.
mode
string
The AUX mode. Must be one of the following:
"dfu"
(Added in v3.5.1)
"gpio"
"motion"
"monitor"
"neo-monitor"
(Added in v3.5.1)
"off"
"track"
"-"
usage
array of strings (required for gpio
mode)
An ordered list of pin modes for each AUX pin when in GPIO mode. Possible values are:
""
to leave the pin unchanged.
"off"
to disable the pin.
"high"
to set the pin as a HIGH
output.
"low"
to set the pin as a LOW
output.
"input"
to set the pin as an input.
"input-pulldown"
to set the pin as a pull-down input. (Added in v3.3.1)
"input-pullup"
to set the pin as a pull-up input. (Added in v3.3.1)
"count"
to set the pin as an input (interrupt) that increments a counter for
each rising edge pulse on the pin. It is up to the device's designer to make
sure that the signal is either HIGH or LOW at any time, and is never left
floating.
"count-pulldown"
Same as count
usage, but a pull-down resistor internal to
the Notecard will automatically keep the pin from floating.
"count-pullup"
Same as count
usage, but a pull-up resistor internal to the
Notecard will automatically keep the pin from floating and falling edges of
pulses are counted.
seconds
int (optional)
When in gpio
mode, if an AUX
pin is configured as a count
type, the
count of rising edges can be broken into samples of this duration.
Passing 0
or omitting this field will total into a single sample.
max
int (optional)
When in gpio
mode, if an AUX
pin is configured as a count
type, the
maximum number of samples of duration seconds
, after which all subsequent
counts are added to the final sample. Passing 0
or omitting this value will
provide a single incrementing count of rising edges on the pin.
start
boolean (optional)
When in gpio
mode, if an AUX
pin is configured as a count
type, set to
true
to reset counters and start incrementing.
gps
boolean (optional)
If true
, along with "mode":"track"
the Notecard supports the use of an
external GPS module. See
Using AUX Track Mode with an External GPS
for more information.
rate
(Added in v3.2.1)
int (optional)
The AUX UART baud rate for debug communication over the AUXRX and AUXTX pins.
sync
(Added in v3.3.1, extended in v3.4.1)
boolean (optional)
If true
, for pins set as input
by usage
, the Notecard will autonomously
report any state changes as new notes in file
(Added in v3.3.1). 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. (Added in v3.4.1).
file
(Added in v3.3.1)
string (optional)
The name of the Notefile used to report state changes when used in conjunction
with "sync": true
. Default Notefile name is _button.qo
.
connected
(Added in v3.3.1)
boolean (optional)
If true
, defers the sync of the state change Notefile to the next sync as
configured by the hub.set
request.
limit
(Added in v3.4.1)
boolean (optional)
If true
, along with "mode":"track"
and gps:true
the Notecard will disable
concurrent modem use during GPS tracking.
sensitivity
(Added in v3.5.1)
int (optional)
When used with "mode":"neo-monitor"
, this controls the brightness of NeoPixel
lights, where 100
is the maximum brightness and 1
is the minimum.
ms
(Added in v5.1.1)
int (optional)
When in gpio
mode, this argument configures a debouncing interval. With a debouncing
interval in place, the Notecard excludes all transitions with a shorter duration than
the provided debounce time, in milliseconds. This interval only applies to GPIOs
configured with a usage
of count
, count-pulldown
, or count-pullup
.
Response Members
mode
string
The current AUX mode
, or off
if not set.
state
array of JSON objects
When in AUX gpio
mode, the state of each AUX pin. Possible values are:
{}
when the pin is off.
{"high": true}
{"low": true}
{"input": true}
{"count": [4]}
where each item in the array is the count per sample.
time
UNIX Epoch time
When in AUX gpio
mode, and if count
is enabled on an AUX pin, the time
that counting started.
seconds
integer
When in AUX gpio
mode, and if count
is enabled on an AUX pin, the number
of seconds per sample.
power
(Added in v3.3.1)
boolean
If true
, indicates the Notecard has USB (main) power. This parameter only
appears in the body of the Note in Notehub if using "sync":true
.
{ "mode": "gpio", "state": [ {}, // AUX1 { "low": true }, // AUX2 { "high": true }, // AUX3 { "count": [3] } // AUX4 ], "time": 1592587637, "seconds": 2 }
card.aux.serial
Added in v3.4.1. Configure various uses of the AUXTX
and AUXRX
pins
on the Notecard edge connector.
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.
mode
string
The AUX mode. Must be one of the following:
"req"
(Default) for request/response monitoring on the AUX pins
"gps"
"notify"
And one or more of the options below to send streaming data
or Notification data over the AUX pins.
"accel"
"signals"
"env"
"dfu"
(Added in v5.1.1)
duration
integer (optional)
If using mode: "accel"
, specify a sampling duration for the Notecard
accelerometer.
rate
integer (optional)
The baud rate or speed at which information is transmitted over AUX serial. The default
is 115200
unless using GPS, in which case the default is 9600
.
limit
boolean (optional)
If true
, along with mode:"gps"
the Notecard will disable
concurrent modem use during GPS tracking.
minutes
(Added in v5.1.1)
integer (optional)
When using mode: "dfu"
, specify an interval for notifying the host.
Response Members
mode
string
The current AUX mode
.
rate
(Added in v4.1.1)
integer
The baud rate or speed at which information is transmitted over AUX serial.
{ "mode": "req", "rate": 115200 }
card.carrier
Uses the AUX5
pin on the Notecard edge connector to notify the Notecard
that the pin is connected to a Notecarrier that supports charging, using
open-drain.
Once set, {"charging":true}
will appear in a response if the Notecarrier is
currently indicating that charging is in progress.
mode
string
The AUX5 mode. Set to "charging"
to tell the Notecard that AUX5 is connected
to a Notecarrier that supports charging on AUX5. Set to "-"
or "off"
to turn
off the AUX5 detection.
Response Members
mode
string
The current AUX5 mode
, or off
if not set.
charging
boolean
Will display true
when in AUX5 "charging"
mode.
{ "mode": "charging", "charging": true }
card.contact
Used to set or retrieve information about the Notecard maintainer.
Once set, this information is synched to Notehub and can be found in the
_env.dbs
file.
name
string (optional)
org
string (optional)
role
string (optional)
email
string (optional)
Response Members
name
string
Name of the Notecard maintainer.
org
string
Organization name of the Notecard maintainer.
role
string
Role of the Notecard maintainer.
email
string
Email address of the Notecard maintainer.
{ "name": "Tom Turkey", "org": "Blues", "role": "Head of Security", "email": "tom@blues.com" }
card.dfu
Added in v3.5.1
Used to configure a Notecard for Notecard Outboard Firmware Update.
name
string
One of the supported classes of host MCU. Supported MCU classes are "esp32"
,
"stm32"
, "stm32-bi"
, and "-"
, which resets the configuration.
The "bi" in "stm32-bi"
stands for "boot inverted", and the "stm32-bi"
option
should be used on STM32 family boards where the hardware boot pin is assumed to
be active low, instead of active high.
Supported MCUs can be found on the Notecarrier-F datasheet.
on
boolean (optional)
Set to true
to enable Notecard Outboard Firmware Update.
off
boolean (optional)
Set to true
to disable Notecard Outboard Firmware Update from occurring.
stop
boolean (optional)
Set to true
to disable the host RESET that is normally performed on the host
MCU when the Notecard starts up (in order to ensure a clean startup), and also
when the Notecard wakes up the host MCU after the expiration of a card.attn
"sleep" operation. If true
, the host MCU will not be reset in these two
conditions.
start
boolean (optional)
Set to true
to enable the host RESET if previously disabled with "stop":true
.
Response Members
name
string
The class of MCU that the Notecard is currently configured to support for Outboard DFU.
{ "name": "stm32" }
card.io
Can be used to override the Notecard's I2C address from its default of 0x17
.
i2c
decimal (optional)
The alternate address to use for I2C communication. Pass -1
to reset to the
default address.
Set the I2C address to 0x18
.
Response Members
{}
means success.card.location
Retrieves the last known GPS location of the Cellular Notecard and the time at which it was acquired. Use card.location.mode to configure GPS settings.
Response Members
status
string
The current status of the Notecard GPS connection.
mode
string
The GPS connection mode. Will be continuous
, periodic
, or off
.
lat
decimal
The latitude in degrees of the last known location.
lon
decimal
The longitude in degrees of the last known location.
time
UNIX Epoch time
The time of location capture.
max
integer
If a geofence is enabled by card.location.mode
, meters from the geofence
center.
{ "status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active} {gps-signal} {gps-sats} {gps}", "mode": "periodic", "lat": 42.577600, "lon": -70.871340, "time": 1598554399, "max": 25 }
card.location.mode
Sets location-related configuration settings. Retrieves the current location mode when passed with no argument.
mode
string (optional)
Must be one of:
""
to retrieve the current mode.
"off"
to turn location mode off.
"periodic"
to sample location at a specified interval, if the device has
moved.
"continuous"
to enable the Notecard's GNSS module for continuous sampling.
"fixed"
to report the location as a fixed location using the specified lat
and lon
coordinates.
seconds
int (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 the GPS on continuously to avoid powering GPS
on and off repeatedly.
vseconds
string (optional)
In periodic
mode, overrides seconds
with a voltage-variable value.
delete
boolean (optional)
Set to true
to delete the last known location stored in the Notecard.
max
int (optional)
Meters from a geofence center. Used to enable geofence location tracking.
lat
decimal (Default: last known location)
When geofence is enabled, latitude in degrees of the geofence center.
lon
decimal (Default: last known location)
When geofence is enabled, longitude in degrees of the geofence center.
minutes
int (Default: 5
)
When geofence is enabled, the number of minutes the device should be outside the geofence before the Notecard location is tracked.
threshold
int (Default: 0
)
When in periodic
mode, the number of motion events (registered by the built-in
accelerometer) required to trigger GPS to turn on.
Response Members
mode
string
The current location mode.
seconds
integer
If specified, the periodic sample interval.
vseconds
string
If specified, the voltage-variable period.
max
integer
If geofence is enabled, the meters from geofence center.
lat
decimal
If geofence is enabled, the geofence center latitude in degrees.
lon
decimal
If geofence is enabled, the geofence center longitude in degrees.
minutes
(Added in v1.5.3)
integer
If geofence is enabled, the currently configured geofence debounce period.
threshold
(Added in v3.4.1)
integer
When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.
{ "mode": "continuous", "max": 100, "lat": 42.5776, "lon": -70.87134, "minutes": 2, "threshold": 4 }
card.location.track
Store location data in a Notefile at the periodic
interval, or using
a specified heartbeat
. Only available
when card.location.mode
has been set to periodic
.
start
boolean
Set to true
to start Notefile tracking.
heartbeat
boolean
When start
is true
, set to true
to enable tracking even when motion is
not detected.
sync
(Added in v1.5.5)
boolean
Set to true
to perform an immediate sync to the Notehub each time
a new Note is added.
stop
boolean
Set to true
to stop Notefile tracking.
hours
integer
If heartbeat
is true, add a heartbeat entry at this interval.
file
string (Default: _track.qo
)
The Notefile in which to store tracked location data. See the
_track.qo
Notefile's documentation
for details on the format of the data captured.
Response Members
start
boolean
true
if tracking is enabled.
stop
boolean
true
if tracking is disabled.
heartbeat
boolean
true
if heartbeat is enabled.
seconds
integer
If tracking is enabled and a heartbeat hours
value is not set, the
tracking interval set in card.location.mode
.
hours
integer
The heartbeat interval, if provided.
file
string
The tracking Notefile, if provided.
{ "start": true, "heartbeat": true, "file": "locations.qo", "hours": 2 }
card.monitor
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.
Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's M.2 connector.
mode
string (optional)
Can be set to one of green
, red
or yellow
to temporarily override the
behavior of an AUX pin LED.
See Using Monitor Mode for additional details.
count
int (optional)
The number of pulses to send to the overridden AUX pin
LED. Set this value to 0
to return the LED to its default behavior.
usb
boolean (optional)
Set to true
to configure LED behavior so that it
is only active when the Notecard is connected to USB power.
Response Members
{}
means success.card.motion
Returns information about the Notecard accelerometer's motion and orientation.
Motion tracking must be enabled first with card.motion.mode
. Otherwise, this
request will return {}
.
minutes
integer (optional)
Amount of time to sample for buckets of accelerometer-measured movement. For
instance, 5
will sample motion events for the previous five minutes and return
a movements
string with motion counts in each bucket.
Response Members
count
integer
The number of accelerometer motion events since the card.motion
request was
last made.
alert
boolean
true
if the Notecard's accelerometer detected a free-fall since the last
request to card.motion
.
motion
UNIX Epoch time
Time of the last accelerometer motion event.
status
string
Comma-separated list of accelerometer orientation events that ocurred since the
last request to card.motion
. One or more of the following:
"face-up"
"face-down"
"portrait-up"
"portrait-down"
"landscape-right"
"landscape-left"
seconds
integer
If the minutes
argument is provided, the duration of each bucket of sample
accelerometer movements.
movements
string
If the minutes
argument is provided, a string of base-36 characters, where
each character represents the number of accelerometer movements in each bucket
during the sample duration. Each character will be a digit 0-9, A-Z to indicate
a count of 10-35, or *
to indicate a count greater than 35.
{ "count": 17, "status": "face-up", "alert": true, "motion": 1599741952, "seconds": 5, "movements": "520000000000000000000A" }
card.motion.mode
Configures accelerometer motion monitoring parameters used when providing
results to card.motion
.
start
boolean (optional)
true
to enable the Notecard accelerometer and start motion tracking.
stop
boolean (optional)
true
to disable the Notecard accelerometer stop motion tracking.
seconds
integer (optional)
Period for each bucket of movements to be accumulated when minutes
is used
with card.motion
.
sensitivity
(Added in v3.3.1)
integer (Default -1
)
Used to set the accelerometer sample rate. The default sample rate of 1.6Hz
could miss short-duration accelerations (e.g. bumps and jolts), and free fall
detection may not work reliably with short falls. The penalty for increasing the
sample rate to 25Hz is increased current consumption by ~1.5uA relative to the
default -1
setting.
-1
: 1.6Hz, +/-2G range, 1 milli-G sensitivity
1
: 25Hz, +/- 16G range, 7.8 milli-G sensitivity
2
: 25Hz, +/- 8G range, 3.9 milli-G sensitivity
3
: 25Hz, +/- 4G range, 1.95 milli-G sensitivity
4
: 25Hz, +/- 2G range, 1 milli-G sensitivity
5
: 25Hz, +/- 2G range, 0.25 milli-G sensitivity
Response Members
{}
means success.card.motion.sync
Configures automatic sync triggered by Notecard movement.
start
boolean (optional)
true
to start motion-triggered syncing.
stop
boolean (optional)
true
to stop motion-triggered syncing.
minutes
integer (optional)
The maximum frequency at which sync will be triggered. Even if a threshold
is set and exceeded, there will only be a single sync for this amount of time.
count
integer (optional)
The number of most recent motion buckets to examine.
threshold
integer (optional)
The number of buckets that must indicate motion in order to trigger a sync.
If set to 0
, the Notecard will only perform a sync when its orientation
changes.
Response Members
{}
means success.card.motion.track
Configures automatic capture of Notecard accelerometer motion in a Notefile.
start
boolean (optional)
true
to start motion capture.
stop
boolean (optional)
true
to stop motion capture.
minutes
integer (optional)
The maximum period to capture Notes in the Notefile.
count
integer (optional)
The number of most recent motion buckets to examine.
threshold
integer (optional)
The number of buckets that must indicate motion in order to capture.
file
string (Default _motion.qo
)
The Notefile to use for motion capture Notes. See the
_motion.qo
Notefile's documentation
for details on the format of the data captured.
now
boolean (optional)
Set to true
to trigger the immediate creation of a _motion.qo
event if the
orientation of the Notecard changes (overriding the minutes
setting).
Response Members
{}
means success.card.random
Added in v1.5.3
Obtain a single random 32 bit unsigned integer modulo count
or count
bytes
of random data from the Notecard hardware random number generator.
mode
string (optional)
Accepts a single value "payload" and, if specified, uses the count
value
to determine the number of bytes of random data to generate and return to
the host.
count
int
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.
Response Members
count
int
A random number generated by the Notecard's onboard hardware random number generator.
payload
bas64 string
If using "mode":"payload"
, a base64-encoded string with random values, the length
of which is specified by the count
argument.
{ "count": 86 }
card.restart
Performs a firmware restart of the Notecard.
Calls to card.restart
are not supported for use in production applications as
they can cause increased cellular data and consumption credit usage.
Response Members
{}
means success.card.restore
Performs a factory reset on the Notecard and restarts.
delete
boolean (optional)
true
to also clear out configuration settings (for example, the
ProductUID).
Please note that the Notecard will be unable to sync to notehub until the
ProductUID is re-set if this option is used.
connected
(Added in v1.5.5)
boolean (optional)
true
to request Notehub perform a device-specific factory reset (delete and
deprovision) the next time the Notecard connects. This would also remove any
Notefile templates used by this device.
Conversely, if connected
is false
(or omitted), then the Notecard's settings
and data will be restored from Notehub the next time the Notecard connects to
the previously used Notehub project.
Response Members
{}
means success.card.status
Returns general information about the Notecard's operating status.
Response Members
status
string
General status information.
usb
boolean
true
is the Notecard is being powered by USB.
storage
integer
The percentage of storage in use on the Notecard.
time
UNIX Epoch time
Set if the Notecard did not have the current UNIX Epoch time at startup.
connected
boolean
true
if connected to Notehub.
cell
boolean
true
if the modem is currently powered on.
gps
(Added in v3.3.1)
boolean
true
if Notecard's GPS module is currently powered on.
wifi
(Added in v3.3.1)
boolean
true
if the Wi-Fi Notecard's radio is currently powered on.
{ "status": "{normal}", "usb": true, "storage": 8, "time": 1599684765, "connected": true, "cell": true }
card.temp
Get the current temperature from the Notecard's onboard calibrated temperature sensor.
seconds
int (optional)
If specified, creates a templated _temp.qo
file that gathers Notecard
temperature value at the specified seconds interval. When using
card.aux track mode,
the sensor temperature, pressure, and humidity is also included with each Note.
stop
boolean (optional)
If set to true
, the Notecard will stop logging the temperature value at the
interval specified with the seconds
parameter (see above).
Response Members
value
decimal
The current temperature in degrees centigrade, including the calibration offset.
calibration
decimal
The calibration differential of the sensor.
{ "value": 27.625, "calibration": -3.0 }
card.time
Retrieves current date and time information. 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"}
.
Response Members
time
UNIX Epoch time
The current time. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.
area
string
The geographic area of the Notecard, if the cell tower is recognized.
zone
string
The time zone of the Notecard, if the cell tower is recognized.
minutes
integer
Number of minutes East of GMT, if the cell tower is recognized.
lat
decimal
Latitude of the Notecard, if the cell tower is recognized.
lon
decimal
Longitude of the Notecard, if the cell tower is recognized.
country
string
The country where the Notecard is located, if the cell tower is recognized.
{ "time": 1599769214, "area": "Beverly, MA", "zone": "CDT,America/New York", "minutes": -300, "lat": 42.5776, "lon": -70.87134, "country": "US" }
card.triangulate
Enables or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or Wi-Fi access points with each new Notehub session.
mode
string
The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order.
cell
enables cell tower scanning to determine the position of the Device.
wifi
enables the use of nearby Wi-Fi access points to determine the
position of the Device. To leverage this feature, the host will need to
provide access point information to the Notecard via the text
argument in
subsequent requests.
-
to clear the currently-set triangulation mode.
See Using Cell Tower & Wi-Fi Triangulation for more information.
on
boolean (Default: false
)
true
to instruct the Notecard to triangulate even if the module has not moved.
Only takes effect when set
is true
.
usb
boolean (Default: false
)
true
to use perform triangulation only when the Notecard is connected to USB
power. Only takes effect when set
is true
.
set
boolean (Default: false
)
true
to instruct the module to use the state of the on
and usb
arguments.
minutes
integer (Default: 0)
Minimum delay, in minutes, between triangulation attempts. Use 0
for no
time-based suppression.
text
string (Optional)
When using Wi-Fi triangulation, a newline-terminated list of Wi-Fi access points obtained by the external module. Format should follow the ESP32's AT+CWLAP command output.
See Using Cell Tower & Wi-Fi Triangulation for more information.
time
UNIX Epoch time (Optional)
When passed with text
, records the time that the Wi-Fi access point scan
was performed. If not provided, Notecard time is used.
Response Members
motion
UNIX Epoch time
Time of last detected Notecard movement.
time
UNIX Epoch time
Time of last triangulation scan.
mode
string
A comma-separated list indicating the active triangulation modes.
on
boolean
true
if triangulation scans will be performed even if the device has not
moved.
usb
boolean
true
if triangulation scans will be performed only when the device is
USB-powered.
length
integer
The length of the text
buffer provided in the current or a previous request.
{ "usb": true, "mode": "wifi,cell", "length": 443, "on": true, "time": 1606755042, "motion": 1606757487 }
card.usage.get
Returns the card's network usage statistics.
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.
mode
string (Default: "total"
)
The time period to use for statistics. Must be one of:
"total"
for all stats since the Notecard was activated.
"1hour"
"1day"
"30day"
offset
integer (optional)
The number of time periods to look backwards, based on the specified mode
.
To accurately determine the start of the calculated time period when using
offset
, use the time
value of the response. Likewise, to calculate the end
of the time period, add the seconds
value to the time
value.
Response Members
seconds
integer
Number of seconds in the analyzed period.
time
UNIX Epoch time
Start time of the analyzed period or, if mode="total"
, the time of activation.
bytes_sent
integer
Number of bytes sent by the Notecard to Notehub.
bytes_received
integer
Number of bytes received by the Notecard from Notehub.
notes_sent
integer
Approximate number of notes sent by the Notecard to Notehub.
notes_received
integer
Approximate number of notes received by the Notecard from Notehub.
sessions_standard
integer
Number of standard Notehub sessions.
sessions_secure
integer
Number of secure Notehub sessions.
{ "seconds": 1291377, "time": 1598479763, "bytes_sent": 163577, "bytes_received": 454565, "notes_sent": 114, "notes_received": 26, "sessions_standard": 143, "sessions_secure": 31 }
card.usage.test
days
integer (optional)
Number of days to use for the test.
hours
integer (optional)
If you want to analyze a period shorter than one day, the number of hours to use for the test.
megabytes
integer (Default: 1024
)
The Notecard lifetime data quota (in megabytes) to use for the test.
Response Members
max
integer
The days of projected data available based on test.
days
integer
The number of days used for the test.
bytes_per_day
integer
Average bytes per day used during the test period.
seconds
integer
Number of seconds in the analyzed period.
time
UNIX Epoch time
Time of device activation.
bytes_sent
integer
Number of bytes sent by the Notecard to Notehub.
bytes_received
integer
Number of bytes received by the Notecard from Notehub.
notes_sent
integer
Number of notes sent by the Notecard to Notehub.
notes_received
integer
Number of notes received by the Notecard from Notehub.
sessions_standard
integer
Number of standard Notehub sessions.
sessions_secure
integer
Number of secure Notehub sessions.
{ "max": 12730, "days": 7, "bytes_per_day": 41136, "seconds": 1291377, "time": 1598479763, "bytes_sent": 163577, "bytes_received": 454565, "notes_sent": 114, "notes_received": 26, "sessions_standard": 143, "sessions_secure": 31 }
card.version
Returns firmware version information for the Notecard.
api
(Added in v1.5.5)
integer (Optional)
Specify a major version of the Notecard firmware that a host expects to use.
Response Members
body
JSON object
An object containing Notecard firmware details for programmatic access.
version
string
The full version number of the Notecard firmware.
device
string
The DeviceUID of the Notecard.
name
string
The official name of the device.
board
integer
The Notecard board version number.
sku
string
The Notecard SKU.
api
integer
The current Notecard API major version in use.
{ "version": "notecard-5.1.1.16026", "device": "dev:000000000000000", "name": "Blues Wireless Notecard", "sku": "NOTE-WBNA-500", "board": "1.11", "api": 5, "body": { "org": "Blues Wireless", "product": "Notecard", "target": "r5", "version": "notecard-5.1.1", "ver_major": 5, "ver_minor": 1, "ver_patch": 1, "ver_build": 16026, "built": "Jan 27 2023 15:58:47" } }
card.voltage
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.
hours
integer (Default: all available data)
The number of hours to analyze, up to 720 (30 days).
mode
string (Default: default
)
Used to set voltage thresholds based on how the Notecard will be powered, and
which can be used to
configure voltage-variable Notecard behavior.
Each value is shorthand that assigns a battery voltage reading
to a given device state like high
, normal
, low
, and dead
.
One of:
"lipo"
for LiPo batteries. Equivalent to
"usb:4.6;high:4.0;normal:3.5;low:3.2;dead:0"
.
"l91"
for L91 batteries. Equivalent to
"high:5.0;normal:4.5;low:0"
.
"alkaline"
for Alkaline batteries. Equivalent to
"usb:4.6;high:4.2;normal:3.6;low:0"
.
"tad"
for Tadiran HLC batteries. Equivalent to
"usb:4.6;normal:3.2;low:0"
.
"lic"
for Lithium-ion capacitors. Equivalent to
"usb:4.6;high:3.8;normal:3.1;low:0"
.
"default"
for the default behavior. Equivalent to
"normal:2.5;dead:0"
.
"?"
to query the Notecard for its currently-set thresholds.
offset
integer (Default: 0
)
Number of hours to move into the past before starting analysis.
vmax
integer (Default: 4.5
)
Ignore voltage readings above this level when performing calculations.
vmin
integer (Default: 2.5
)
Ignore voltage readings below this level when performing calculations.
name
string
Specifies an environment variable to override application default timing values.
usb
(Added in v3.5.1)
boolean (Default: false
)
When enabled, the Notecard will monitor for changes to USB power state,
which you can act upon with alert
and sync
arguments.
alert
(Added in v3.5.1)
boolean (Default: false
)
When enabled and the usb
argument is set to true
, the Notecard will add
an entry to the health.qo
Notefile when USB power is connected or disconnected.
sync
(Added in v3.5.1)
boolean (Default: false
)
When enabled and the usb
argument is set to true
, the Notecard will perform
a sync when USB power is connected or disconnected.
Response Members
mode
string
Current power mode, or usb
if the Notecard is connected to USB power.
usb
boolean
true
if the Notecard is connected to USB power.
value
decimal
The current voltage.
hours
integer
The number of hours used for trend analysis.
vmin
decimal
The lowest voltage value captured during the measurement period.
vmax
decimal
The highest voltage value captured during the measurement period.
vavg
decimal
The average voltage value during the measured period.
daily
decimal
Change of moving average in the last 24 hours, if relevant to the time period analyzed.
weekly
decimal
Change of moving average in the last 7 days, if relevant to the time period analyzed.
monthly
decimal
Change of moving average in the last 30 days, if relevant to the time period analyzed.
{ "usb": true, "hours": 120, "mode": "usb", "value": 5.112190219747135, "vmin": 4, "vmax": 4, "vavg": 4 }
card.wifi
Sets up a Wi-Fi Notecard to connect to a Wi-Fi access point. This request is not available for Cellular Notecards.
Wi-Fi updates cannot occur if you have changed a Wi-Fi Notecard's connection
mode from periodic
to continuous
. If you have a Wi-Fi Notecard in
continuous
mode, you must change it using
a hub.set request before using
card.wifi
.
ssid
string (optional)
The SSID of the Wi-Fi access point. Alternatively, use -
to clear an already
set SSID.
password
string (optional)
The network password of the Wi-Fi access point. Alternatively, use -
to clear
an already set password.
name
string (optional)
By default, the Notecard creates a SoftAP (software enabled access point) under
the name "Notecard". You can use the name
argument to change the name of the
SoftAP to a custom name.
If you include a -
at the end of the name
(for example "name": "acme-"
),
the Notecard will append the last four digits of the network's MAC address (for
example acme—025c
). This allows you to distinguish between multiple Notecards
in SoftAP mode.
org
string (optional)
If specified, replaces the Blues logo on the SoftAP page with the provided name.
start
boolean (optional)
Specify true
to activate SoftAP mode on the Notecard programatically.
Response Members
secure
boolean
true
means that the Wi-Fi access point is using Management Frame Protection.
version
string
The Silicon Labs WF200 Wi-Fi Transceiver binary version.
ssid
string
The SSID of the Wi-Fi access point.
security
string
The security protocol the Wi-Fi access point uses.
{ "secure": true, "version": "3.12.3", "ssid": "<ssid name>", "security": "wpa2-psk" }
card.wireless
View the last known network state, or customize the behavior of the modem. Note: Be careful when using this mode with hardware not on hand as a mistake may cause loss of network and Notehub access.
mode
string
Network scan mode. Must be one of:
"-"
to reset to the default mode.
"auto"
to perform automatic band scan mode (this is the default mode).
"m"
to restrict the modem to Cat-M1.
"nb"
to restrict the modem to Cat-NB1.
"gprs"
to restrict the modem to EGPRS.
apn
string
Access Point Name (APN) when using an external SIM. Use "-"
to reset to the
Notecard default APN.
method
(Added in LTS v4.1.1)
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.
Response Members
status
string
The current status of the wireless connection and modem.
count
integer
Number of bars of signal quality.
net
JSON object
An object with detailed modem, radio access technology, and signal information (details will differ depending on whether it's a Cellular or Wi-Fi Notecard).
{ "status": "{modem-off}", "count": 1, "net": { "iccid": "00000000000000000000", "imsi": "000000000000000", "imei": "000000000000000", "modem": "EG91NAXGAR07A03M1G_BETA0415_01.001.01.001", "band": "LTE BAND 2", "rat": "lte", "rssir": -69, "rssi": -70, "rsrp": -105, "sinr": 86, "rsrq": -17, "bars": 1, "mcc": 310, "mnc": 410, "lac": 28681, "cid": 211150856, "updated": 1599225076 } }
card.wireless.penalty
Added in v1.5.6
View the current state of a Notecard Penalty Box, manually remove the Notecard from a penalty box, or override penalty box defaults.
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.
stop
boolean
Set to true
to remove the Notecard from certain types of penalty boxes.
set
boolean
Set to true
to override the default settings of the
Network Registration Failure Penalty Box.
rate
float (Default 1.25
)
The rate at which the penalty box time multiplier is increased over successive
retries. Used with the set
argument to override the Network Registration
Failure Penalty Box defaults.
add
integer (Default 15
)
The number of minutes to add to successive retries. Used with the set
argument
to override the Network Registration Failure Penalty Box defaults.
max
integer (Default 4320
)
The maximum number of minutes that a device can be in a Network Registration
Failure Penalty Box. Used with the set
argument to override the Network
Registration Failure Penalty Box defaults.
min
integer (Default 15
)
The number of minutes of the first retry interval of a Network Registration
Failure Penalty Box. Used with the set
argument to override the Network
Registration Failure Penalty Box defaults.
Response Members
minutes
integer
The time since the first network registration failure.
count
integer
The number of consecutive network registration failures.
seconds
(Added in LTS v4.1.1)
integer
If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends.
{ "minutes": 36, "count": 2 }