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

{
  "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"
}
note

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"
}
warning

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
}
note

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.

note

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

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

note

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

{
 "req": "card.aux",
 "mode": "gpio"
}

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:

{
  "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
  ]
}

If one or more pins are undefined (""), that pin defaults to high-impedance and is reported as {} in the response.

{
 "req": "card.aux",
 "mode": "gpio",
 "usage": [
  "",
  "",
  "",
  ""
 ]
}
{
  "mode":  "gpio",
  "state": [
    {}, // AUX1
    {}, // AUX2
    {}, // AUX3
    {}  // 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 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.
{
  "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
   ]
  }
 ]
}

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.

note

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:

  • AUX1 is configured to count and is currently LOW.
  • AUX2 is currently LOW (it may be an input or an output).
  • AUX3 is currently configured to be OFF (high impedance).
  • AUX4 is currently LOW (it may be an input or an output).

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

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

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 1 - 5 NeoPixel LEDs 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:

{
 "req": "card.aux",
 "mode": "neo-monitor"
}

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.

note

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: