Rate this page Â
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
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.
{
"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.
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.
{
"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
When sent with no arguments, card.contact
returns all of the previously
set contact values:
{
"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.
Calls to card.restart
are not supported for use in production applications as
they can cause increased cellular data and consumption credit usage.
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, Notefile templates, and
environment variables.
To delete configuration settings, set the delete
argument to true
.
To remove any Notefile templates and environment variables used by this device,
set the connected
argument to true
. Conversely, if connected
is false (or
omitted), then the Notecard's environment variables and data will be restored
from Notehub the next time the Notecard connects to the previously used Notehub
project.
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.
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 ({}
).
To reset your host back to the default Notehub host, use a single dash (-
)
in the host argument.
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.
{ "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.
Modes m
, nb
, and gprs
are only applicable on the "narrowband" Notecard
SKUs (e.g. NOTE-NBNA and NOTE-NBGL).
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.
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 ({}
).
For example, this request passes a decimal value of 24
, which corresponds to
the I2C address of 0x18
:
To reset the Notecard to the default I2C address, use -1
as the i2c
argument
value:
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
through AUX-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
.
{ "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 the SDA
or SDI
pin on the sensor.AUX4
should be connected to the SCL
or SCK
pin on the sensor.GND
should be connected to the GND
pin on the sensor.BAT
should be connected to the EN
, ENABLE
, or 3VO
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:
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
:
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:
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 the AUX2
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 the AUX3
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 digital HIGH
. After the device is no longer in motion, the signal
is returned to LOW
.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:
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 a HIGH
output.low
to set the pin as a LOW
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 as count
mode, but a pull-down resistor internal to
the Notecard will automatically keep the pin from floating.count-pullup
Same as count
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:
When setting usage, a card.aux
request will return the state
field with
the applied usage settings.
{
"mode": "gpio",
"state": [
{},
{
"low": true
},
{
"high": true
},
{
"low": true
}
]
}
If one or more pins are undefined (""
), that pin defaults to high-impedance
and is reported as {}
in the response.
{
"mode": "gpio",
"state": [
{},
{},
{},
{}
]
}
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 setting AUX1
low
and AUX2-4
as
input-pulldown
:
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
},
{
"low": true
},
{
"high": true
},
{
"low": true
}
]
}
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 counters, the Notecard will count rising edge pulses lasting more than about 12ns. Being interrupt based, this works well in low-power environments.
If sync
is set to true
, the Notecard will trigger a sync each time it counts
a pulse (Added in v3.4.1).
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. Passing 0
will
total into a single sample.max
- The maximum number of samples to take. Counts above this value
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
- Set to true
to reset counters and start incrementing.
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
]
}
]
}
As of v3.4.1, you can change AUX GPIO output values using
environment variables,
provided the Notecard has previously been configured with
{"req":"card.aux","mode":"gpio","usage":[...]}
.
The environment variable _aux_gpio_set
is used to set AUX GPIOs HIGH
or
LOW
, or pulse them HIGH
or LOW
for a specified period (in milliseconds).
To set GPIOs permanently HIGH
or LOW
(not pulse), the value of the
environment variable should be a comma-separated list of values. Any GPIOs that
should not change their configuration (e.g. inputs or counters) should be left
blank.
For example, _aux_gpio_set
with a value of ,low,,high
causes AUX2
to go
LOW
and AUX4
to go HIGH
.
The Notecard saves this setting to non-volatile memory, so that if it restarts it restores the pin states as defined.
To pulse one or more GPIOs HIGH
or LOW
, add a duration in milliseconds plus
a UNIX epoch time and validity period (both in seconds).
For example, _aux_gpio_set
with a value of ,,,high,1300,1656110120,60
means
pulse AUX4
HIGH
for 1300ms, valid for 60 seconds from 1656110120 until
1656110180.
It's a best practice to add a UNIX epoch time and a validity period with the
_aux_gpio_set
environment variable.
If the Notecard is not currently connected to Notehub, the environment variable will not be synced to the Notecard until it next connects to Notehub. It's likely that a command to pulse the output of the Notecard is an action you'd like to be performed now, or not at all (e.g. if the pulse is used to unlock a door to allow entry).
Environment variables are persistent on the Notecard (stored in _env.dbs
). If
the Notecard should reboot, the environment variable will be re-read, causing a
pulse on the GPIO output at a future point in time.
At the end of the pulse the pin returns to it's previous state, which means if
you send a LOW
/HIGH
pulse to a pin that is already LOW
/HIGH
there will
be no observed effect on the Notecard.
AUX GPIO pulses are NOT stored in non-volatile memory in the Notecard, because they are ephemeral events. If the Notecard should happen to reboot during the duration of the pulse, the GPIO outputs would revert to their long term state.
There are two environment variables used for monitoring AUX GPIO state:
_aux_gpio_report_enable
is set to enable reporting via environment variable.
If it is set to the value sync
, then the Notecard will immediately sync to
Notehub when a GPIO input changes (max rate of once per second). If it is set to
any other value (i.e. just non-empty) the Notecard will update the environment
variable described below, but will not force a sync (which will occur according
to the hub.set
configuration).
_aux_gpio_report
is set by the Notecard to a comma-separated string that
reflects the current state of the AUX GPIO inputs. The format is very similar to
the JSON state
field in the response to a
card.aux request.
For example, with the value of low(8),low,off,high
:
LOW
.LOW
(it may be an input or an output).OFF
(high impedance).HIGH
(it may be an input or an output).Disable AUX mode by setting the mode
argument to off
in a card.aux
request:
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:
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 the AUX1
"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.
To return an LED to its default behavior, set the count
to 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.
As of v3.5.1 of the Notecard firmware, the AUX Neo-Monitor mode allows you to replace the traditional 3 monocolor LEDs used in Monitor mode with a NeoPixel LED, which will carry out the same basic functions using only a single AUX GPIO pin.
Just like with monitor mode, the AUX1
pin is configured as a test button,
and AUX2
is configured as the output for NeoPixel LED control.
AUX1
is configured active-LOW
with a pullup and meant to be wired to a
normally open momentary switch. When this button is pressed,
a note is added to the _button.qo
Notefile and a manual sync is initiated.AUX2
is where the NeoPixel LED's DI
(Data In) pin connects to the Notecard. As a NeoPixel can be programmed to display any color of the rainbow,
this general purpose LED flashes yellow ("STATUS") to acknowledge when the
AUX1
button is pressed, then proceeds to flash a series of green ("COMM
BUSY") LED blinks as the newly created _button.qo
Notefile is successfully
sent to Notehub. If there is a failure to connect to a network, the LED flashes
red ("COMM ERROR") continuously for two minutes, followed by a four second
flash once per minute thereafter.
To enable neo-monitor mode for a Notecard, send the following card.aux
request:
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:
note.add
requestcard.time
request