Advanced Notecard Configuration
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.
Performing Notecard Maintenance Requests
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.
Getting the Notecard Version
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.0",
"ver_major": 1,
"ver_minor": 5,
"ver_patch": 0,
"ver_build": 11236,
"built": "Sep 2 2020 08:45:10"
},
"version": "notecard-1.5.0.11236",
"device": "dev:000000000000000",
"name": "Blues Wireless Notecard",
"type": 11,
"sku": "NOTE-WBNA500"
}
Getting Notecard Status
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
}
Setting Card Contact information
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"
}
Restarting the Notecard
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"
}
Factory Resetting the Notecard
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
}
Changing the Notehub Service Host
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": "-"
}
Viewing & Customizing Modem behavior
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. In this mode, the modem will try Cat-M1, Cat-NB1, and EGPRS, in order, until it obtains a signal.m
to restrict the modem to Cat-M1.nb
to restrict the modem to Cat-NB1.gprs
to restrict the modem to EGPRS.- A custom connection string with your network details, including APN, bands, and seek order.
-
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"
}
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"
}
Changing the Notecard I2C Address
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
}
Working with the Notecard AUX Pins
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.
Determining the Current AUX 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" }
Using AUX Track Mode
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, the AUX1
-AUX4
pins are configured as follows:
AUX1
should be connected to theSDA
orSDI
pin on the sensor.AUX2
should be connected to theEN
,ENABLE
or3VO
pin on the sensor.AUX3
should remain disconnected.AUX4
should be connected to theSCL
orSCK
pin on the sensor.
The BME280 must also be wired to use its secondary I2C address.
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.
Using AUX Motion Mode
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.
Using AUX GPIO Mode
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.count
to set the pin as an input that increments a counter for each rising edge pulse on the pin.
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
]
}
Configuring an AUX Pin as a Counter
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]}
]
}
Turing AUX Mode Off
Disable AUX mode by setting the mode
argument to off
in a card.aux
request:
{
"req": "card.aux",
"mode": "off"
}
Using Monitor Mode
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.monitor
request:
{
"req": "card.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 cellular. 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
}