The Notecard provides a number of advanced configuration features that you can use to query the state and status of the Notecard, customize its behavior, set its Notehub service location, and configure the available AUX pins for use in your application.
The Notecard API provides requests you can use to query the Notecard for version and status information, restart the Notecard, or factory reset it completely.
To obtain version information from the Notecard, send card.version
request.
This request is sent without arguments, and returns the Notecard brand and
model for the name
, Notecard version
, the sku
,
device
UID, device type
, and a body
with version and build
details for programmatic access.
{
"req": "card.version"
}
{
"body": {
"org": "Blues Wireless",
"product": "Notecard",
"version": "notecard-1.5.5",
"ver_major": 1,
"ver_minor": 5,
"ver_patch": 5,
"ver_build": 13078,
"built": "May 28 2021 12:45:10"
},
"version": "notecard-1.5.5.13078",
"device": "dev:000000000000000",
"name": "Blues Wireless Notecard",
"board": "1.11",
"sku": "NOTE-WBNA500",
"api": 1
}
(Added in v1.5.5)
If you need to specify the major version of the Notecard API your host expects,
you can do so by adding an api
argument to a card.version
request. All
subsequent requests to the Notecard will use the API contract of that major
version. This capability allows you to freely update your Notecard firmware
to get fixes and improvements without needing to update your host application.
{
"req": "card.version",
"api": "1"
}
To obtain information about the current operating status of the Notecard,
use the card.status
request. This request is sent without arguments, and
returns a status
string, a usb
field if the Notecard is currently powered
by USB, the percentage of storage
used on the Notecard, The UNIX Epoch
time
the Notecard obtained the time after starting up, and a connected
field if the Notecard is connected to Notehub.
{
"req": "card.status"
}
{
"status": "{normal}",
"usb": true,
"storage": 8,
"time": 1599067096,
"connected": true
}
The card.contact
request can be 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. When setting this information, any or
all of the following values can be provided:
name
org
role
email
{
"req": "card.contact",
"name": "Tom Turkey",
"org": "Blues Wireless",
"role": "Head of Security",
"email": "tom@blues.com"
}
When sent with no arguments, card.contact
returns all of the previously
set contact values:
{
"req": "card.contact"
}
{
"name": "Tom Turkey",
"org": "Blues Wireless",
"role": "Head of Security",
"email": "tom@blues.com"
}
To power-cycle the Notecard, send a card.restart
request with no arguments.
This request returns an empty JSON object ({}
) before restarting.
{
"req": "card.restart"
}
To perform a factory reset on the Notecard, send a card.restore
request. This
request can be made with no arguments, which restores the Notecard to
its factory state but preserves its configuration settings. To delete these
settings as well, set the delete
argument to true
. This request returns an
empty JSON object ({}
) before restoring the device and restarting. Note:
Setting delete
to true
will also remove the ProductUID on the Notecard,
and the Notecard will not be able to re-connect to Notehub until a new Product
UID is set.
{
"req": "card.restore",
"delete": true
}
If your Notecard needs to be configured to connect to a new Notehub host, use
the hub.set
request and provide the url of the new host in the host
argument. This request returns an empty JSON object ({}
).
{
"req": "hub.set",
"host": "i.newhost.net"
}
To reset your host back to the default Notehub host, use a single dash (-
)
in the host argument.
{
"req": "hub.set",
"host": "-"
}
The card.wireless
request can be used to view details about the
last known cellular network, or customize the behavior of the Notecard's
modem, if needed. A card.wireless
request with no arguments returns
network state information, including the current connection status
, count
of bars of signal quality, and net
object that contains detailed modem,
access technology and signal strength information.
{ "req": "card.wireless" }
{ "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 } }
To customize the behavior of the modem on the Notecard, use the mode
argument
in a card.wireless
request, which accepts the following values:
auto
to select automatic band scan mode.m
to restrict the modem to Cat-M1.nb
to restrict the modem to Cat-NB1.gprs
to restrict the modem to EGPRS.-
to reset the modem configuration to the Notecard default.
When the mode
argument is used, card.wireless
returns the same fields
as a no argument request.
{ "req": "card.wireless", "mode": "nb" }
Modes m
, nb
, and gprs
are only applicable on the "narrowband" Notecard
SKUs (NOTE-NB*)
If you prefer to use the Notecard with an external 3rd party SIM, you can
use the apn
argument to instruct the Notecard to connect to a different
Access Point Name (APN) when establishing a network connection.
{ "req": "card.wireless", "apn": "myapn.nb" }
Setting the mode
or apn
arguments may cause the Notecard to lose its
cellular connection and be unable to reconnect until it has been reconfigured.
Be careful when using this setting to select a mode that you know will work for
the Notecard's physical location.
If the default I2C address of the Notecard (0x17
) conflicts with another
device in your product, you can change the Notecard address with a card.io
request. This request takes an i2c
argument with a decimal value of the
new I2C address and returns an empty JSON object ({}
).
{
"req": "card.io",
"i2c": 24 // 0x18
}
To reset the Notecard to the default I2C address, use -1
as the i2c
argument
value:
{
"req": "card.io",
"i2c": -1
}
Be sure to issue this request over a UART or USB connection. Changing the I2C address while connected to the Notecard I2C may cause unexpected results!
The Notecard edge connector provides a series of pins that developers can utilize for detailed tracing of Notecard activity, interfacing with GPS operations, accessing GPIO pins on the Notecard, and connecting external LEDs to a product in order to monitor Notecard activity.
The Notecard brings out seven AUX-labeled pins. They are:
AUX-RX
AUX-TX
AUX-EN
AUX-1
throughAUX-4
The behavior of these pins change depending on the AUX mode configured on the Notecard.
Using the AUX Pins for Tracing
In addition to the modes below, the Notecard AUX pins can be used for
tracing on a separate bus from primary Notecard communications. While this
does not require an explicit AUX mode setting, it does require a physical
connection to AUX-RX
, AUX-TX
, and AUX-EN
, and the AUX-EN
must be
pulled high to enable this mode.
You can query the Notecard AUX mode at any time with a card.aux
request
and no arguments. By default, the default Notecard AUX mode is off
.
{ "req":"card.aux" }
{ "mode":"off" }
AUX Track mode allows you to enhance the built-in sensor readings from the
Notecard with temperature, pressure, and humidity readings through a
BME280 sensor wired to the AUX
pins. When in Track mode, specific pins are
configured as follows:
AUX1
should be connected to theSDA
orSDI
pin on the sensor.AUX4
should be connected to theSCL
orSCK
pin on the sensor.GND
should be connected to theGND
pin on the sensor.BAT
should be connected to theEN
,ENABLE
, or3VO
pin on the sensor.
The BME280 must also be wired to use its secondary I2C address if it
conflicts with the Notecard's default I2C address of 0x17
.
Track mode can then be enabled with the value track
in the mode
argument
of a card.aux
request:
{
"req": "card.aux",
"mode": "track"
}
When Track mode is enabled, the temperature, pressure, and humidity from the
BME280 is automatically added to the _track.qo
Notefile.
There are scenarios where the onboard GPS antenna of the Notecarrier is not adequate to identify GPS satellites (e.g. if the Notecarrier does not have a clear view of the southern sky). To accommodate these situations, an external GPS module such as the Adafruit Ultimate GPS or Quectel L86 can be used (though since NMEA sentences are standardized, many GPS modules will work).
If using an external GPS module, the gps
parameter of card.aux
must be set
to true
:
{
"req": "card.aux",
"mode": "track",
"gps": true
}
In this mode, AUX3
becomes an output used to turn on/off the GPS.
AUX-RX/AUX-TX should be connected to the GPS TX and RX respectively.
If the gps:true
parameter is set, the internal GPS module will be disabled and
the Notecard will look for an external GNSS/GPS hat. If there is no external
GNSS/GPS hat, the Notecard will not be able to receive a GPS location.
AUX Motion mode allows you to configure the Notecard as a standalone motion
tracking device, without requiring a host processor. Motion mode is enabled with
the value motion
in the mode
argument of a card.aux
request:
{
"req": "card.aux",
"mode": "motion"
}
When in Motion mode, the AUX1
-AUX4
pins are configured as follows:
AUX1
is an active-LOW
input control that can be wired to a button. When the button is pressed, the Notecard adds a "button pushed" event to the tracking database and initiates an immediate cloud sync.AUX2
is an active-HIGH
input control meant to signal when a notable event has occurred. When the input control sends a pulse to theAUX2
pin, a counter is incremented and added to the database on the next tracking event or heartbeat.AUX3
is an active-HIGH
input control meant to signal when a notable event has ocurred while the Notecard is in motion. When the input control sends a pulse to theAUX3
pin, a counter is incremented and added to the database on the next tracking event or heartbeat.AUX4
is an output signal used to indicate that the Notecard has detected motion. Whenever the device has been in motion for several seconds,AUX4
is set to digitalHIGH
. After the device is no longer in motion, the signal is returned toLOW
.
In Motion mode, the AUX1
-AUX4
pins have a specific configuration, but it
is up to the hardware designer to determine the specific inputs and outputs
connected to these pins in a product.
In AUX GPIO mode, the AUX1
-AUX4
pins are used as general purpose I/O pins.
AUX GPIO mode is enabled with the value gpio
in the mode
argument of
a card.aux
request:
{
"req": "card.aux",
"mode": "gpio"
}
By default, all four pins are off and the Notecard reports the state of each as
LOW
in a state
array:
{
"mode": "gpio",
"state": [
{"low": true}, // AUX1
{"low": true}, // AUX2
{"low": true}, // AUX3
{"low": true} // AUX4
]
}
To modify the mode for each pin, a card.aux
request accepts a usage
argument in the form of an array of strings in pin order. The possible values
for each pin are:
""
to leave the pin mode unchanged.off
to disable the pin.high
to set the pin as aHIGH
output.low
to set the pin as aLOW
output.input
to set the pin as an input. 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.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 ascount
mode, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating.count-pullup
Same ascount
mode, but a pull-up resistor internal to the Notecard will automatically keep the pin from floating and the falling edge of each pulse is counted.
For instance, the following request turns off AUX1
, sets AUX2
LOW
,
AUX3
HIGH
and AUX4
as an input:
{
"req": "card.aux",
"mode": "gpio",
"usage": [
"off", // AUX1
"low", // AUX2
"high", // AUX3
"input" // AUX4
]
}
When setting usage, a card.aux
request will return the state
field with
the applied usage settings.
{
"mode": "gpio",
"state": [
{}, // AUX1
{"low": true}, // AUX2
{"high": true}, // AUX3
{"low": true} // AUX4
]
}
As of v3.3.1, the Notecard can autonomously (i.e. without a host MCU) report AUX
GPIO input changes to Notehub by using the "sync":true
parameter in a
card.aux
request.
An example of this type of request could be:
{
"req": "card.aux",
"mode": "gpio",
"usage": [
"low", // AUX1
"input-pulldown", // AUX2
"input-pulldown", // AUX3
"input-pulldown" // AUX4
],
"sync": true,
"file": "gpio.qo"
}
With this request, the Notecard will automatically report any state changes
on AUX2, AUX3, and AUX4. By default, the state changes are reported in a
Notefile called _button.qo
, but the Notefile name can be specified with the
file
parameter.
The Notecard applies about one second of debounce to any GPIO transition and on
state changes adds a Note to the Notefile specified by file
and immediately
syncs with Notehub. However, by using "connected":true
this sync can be
deferred to sync based on the period defined in the original hub.set
request.
When synced with Notehub, the Note body will appear something like this:
{
"power": true,
"state": [
{"low": true}, // AUX1
{"low": true}, // AUX2
{"high": true}, // AUX3
{"low": true} // AUX4
]
}
The power
parameter indicates whether or not the Notecard has USB (main)
power, which could be useful if monitoring a Notecard for power failure.
The state
shows the current state of each AUX GPIO, regardless of whether it
is configured as an input or an output.
For pins used as counter
s, the Notecard will count rising edge pulses lasting
more than about 12ns. Being interrupt based, this works well in low-power
environments.
sync
is ignored for pins in counter
mode through v3.3.1. In the future
it will function much like it does for pins in input
mode today.
When using count
in the usage
for any pin, the following can also
be configured to group pulses in a counter:
seconds
- The number of seconds to include in a sample. Passing0
will total into a single sample.max
- The maximum number of samples to take. Counts above this value are added to the final sample. Passing0
or omitting this value will provide a single incrementing count of rising edges on the pin.start
- Set totrue
to reset counters and start incrementing.
{
"req": "card.aux",
"mode": "gpio",
"usage": [
"off", // AUX1
"low", // AUX2
"high", // AUX3
"count" // AUX4
],
"seconds": 2,
"max": 5,
"start": true
}
Once GPIO mode is configured, subsequent requests to card.aux
will return
the current pin state and counter values for each pin.
{
"mode": "gpio",
"state": [
{},
{
"high": true
},
{
"low": true
},
{
"count": [
4
]
}
]
}
Disable AUX mode by setting the mode
argument to off
in a card.aux
request:
{
"req": "card.aux",
"mode": "off"
}
If you plan to place your Notecard-based product into 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.
To use monitor mode for adding functionality to an enclosure, send a
card.aux
request:
{
"req": "card.aux",
"mode": "monitor"
}
In monitor mode, the AUX1
pin is configured as a test button,
while AUX2
-AUX4
are configured as outputs for LED control. The LEDs should
correspond to the color guidelines below and can be connected directly to
each pin with resistors chosen to ensure a maximum current draw of 20mA per LED.
AUX1
is configured active-LOW
with a pullup and meant to be wired to a normally open momentary switch. When this button, named "COMM TEST" is pressed, a test note is added to the_test.qo
Notefile and a manual sync is initiated.AUX2
is a yellow LED referred to as "STATUS." This is as general purpose LED that flashes an acknowledgement when theAUX1
"COMM TEST" button is pressed.AUX3
is a green LED referred to as "COMM BUSY." This LED blinks in a pattern based on communications status.AUX4
is a red LED referred to as "COMM ERROR." This LED turns on continuously for two minutes after there is a failure to connect to a network. To conserve battery life, after the first two minutes the LED turns on for four seconds each minute.
If your host application needs to override the function of these LEDs to
display its own error code or status, it can do so using the mode
and
count
arguments in a card.monitor
request. mode
is the name of the AUX
pin LED you wish to override. Possible values are yellow
, red
, and green
.
count
is the number of pulses the LED should display in a repeating pattern.
{
"req": "card.monitor",
"mode": "green",
"count": 5
}
To return an LED to its default behavior, set the count
to 0
:
{
"req": "card.monitor",
"mode": "green",
"count": 0
}
Finally, the usb
argument can be set to true
to configure LED behavior
so that it is only active when on USB power. This can be useful if you
want to conserve power while your product is temporarily running on battery
power.
{
"req": "card.monitor",
"usb": true
}
The Notecard will not enable certain functions until it has made a successful cellular connection upon startup to obtain the current time. Once the Notecard has the time, these functions are available for use, regardless of the state of the cellular connection going forward.
If the Notecard is power cycled, it will have to re-establish a successful cellular connection to obtain the current time.
These are the functions that require the current time:
- GPS location tracking
- Motion/asset tracking
- Notecard and host MCU DFU
- A
note.add
request - Cell tower and Wi-Fi triangulation
- A
card.time
request - Notecard data usage tracking for usage analysis requests
- Voltage monitoring for voltage analysis requests
- Inbound/outbound sync scheduling calculations
- Certain AUX counter features