--- title: Advanced Notecard Configuration description: 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. source_url: https://dev.blues.io/notecard/notecard-walkthrough/advanced-notecard-configuration/ canonical_url: https://dev.blues.io/notecard/notecard-walkthrough/advanced-notecard-configuration/ markdown_url: https://dev.blues.io/notecard/notecard-walkthrough/advanced-notecard-configuration.md --- # 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. ## Issue 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 a `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, the `board` version, `cell`/`gps`/`wifi` booleans indicating which connectivity and location features the Notecard supports, and a `body` with version and build details for programmatic access. **JSON** ```json { "req": "card.version" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.version"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.version"} card.Transaction(req) ``` ```json { "version": "notecard-5.3.1", "device": "dev:000000000000000", "name": "Blues Wireless Notecard", "sku": "NOTE-NBGL", "board": "1.11", "cell": true, "gps": true, "api": 5, "body": { "org": "Blues Wireless", "product": "Notecard", "target": "r5", "version": "notecard-5.3.1", "ver_major": 5, "ver_minor": 3, "ver_patch": 1, "ver_build": 371, "built": "Sep 5 2023 12:21:30" } } ``` ### 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. **JSON** ```json { "req": "card.status" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.status"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.status"} card.Transaction(req) ``` ```json { "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 synced to Notehub. When setting this information, any or all of the following values can be provided: - `name` - `org` - `role` - `email` **JSON** ```json { "req": "card.contact", "name": "Tom Turkey", "org": "Blues Inc.", "role": "Head of Security", "email": "tom@blues.com" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.contact"); JAddStringToObject(req, "name", "Tom Turkey"); JAddStringToObject(req, "org", "Blues Inc."); JAddStringToObject(req, "role", "Head of Security"); JAddStringToObject(req, "email", "tom@blues.com"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.contact"} req["name"] = "Tom Turkey" req["org"] = "Blues Inc." req["role"] = "Head of Security" req["email"] = "tom@blues.com" rsp = card.Transaction(req) ``` When sent with no arguments, `card.contact` returns all of the previously set contact values: **JSON** ```json { "req": "card.contact" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.contact"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.contact"} card.Transaction(req) ``` ```json { "name": "Tom Turkey", "org": "Blues Inc.", "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. **JSON** ```json { "req": "card.restart" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.restart"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.restart"} card.Transaction(req) ``` > **Warning:** > > Calls to `card.restart` are not supported for use in production applications as they can cause increased cellular data and [event credit](https://dev.blues.io/notehub/notehub-walkthrough.md#understanding-event-credits) usage. ### 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, Notefile templates, and environment variables. To delete configuration settings, set the `delete` argument to `true`. > **Warning:** > > 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. 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. The `card.restore` request returns an empty JSON object (`{}`) before restoring the device and restarting. > **Note:** > > There are a few configurations that a `card.restore` request will *not* reset: > > 1. WiFi settings set with the [card.wifi](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-wifi) API. > 2. The [alternate I2C address](https://dev.blues.io/notecard/notecard-walkthrough/advanced-notecard-configuration.md#change-the-notecard-i2c-address) used by Notecard, if previously set by the [card.io](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-io) API. > 3. The NTN (Starnote) settings automatically configured when Notecard is paired with a Starnote device. > > These values can be reset individually following the guidance provided in the [card.wifi](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-wifi), [card.io](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-io), and [ntn.reset](https://dev.blues.io/api-reference/notecard-api/ntn-requests/latest.md#ntn-reset) docs. **JSON** ```json { "req": "card.restore", "delete": true, "connected": true } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.restore"); JAddBoolToObject(req, "delete", true); JAddBoolToObject(req, "connected", true); NoteRequest(req); ``` **Python** ```python req = {"req": "card.restore"} req["delete"] = True req["connected"] = True card.Transaction(req) ``` #### card.restore Factory Reset Reference The table below summarizes the persistent settings cleared or restored to defaults when `card.restore` is issued with `"delete":true`. > **Note:** > > Transient API calls and API arguments (e.g. one-time actions, query parameters) are **omitted from this table**, as are the exceptions noted above (e.g. WiFi credentials, custom I2C address, and NTN settings). | API | Argument | State After Factory Reset | | ------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **card.attn** | `files` | *cleared* | | | `mode` | *disarmed (all monitors cleared)* | | | `on` / `off` | *ATTN processing enabled* | | | `seconds` | *unset* | | **card.aux** | `count` | *unset* | | | `file` | *unset* | | | `limit` | `false` | | | `max` | *unset* | | | `mode` | `"off"` | | | `ms` | *unset* | | | `offset` | *unset* | | | `rate` | `115200` | | | `seconds` | *unset* | | | `sensitivity` | *unset* | | | `sync` | `false` | | | `usage` | *all pins disabled* | | **card.aux.serial** | `duration` | *unset* | | | `limit` | `false` | | | `max` | *unset* | | | `minutes` | *unset* | | | `mode` | `"req"` | | | `ms` | *unset* | | | `rate` | `115200` | | **card.carrier** | `mode` | `"off"` | | **card.contact** | `email` | *cleared* | | | `name` | *cleared* | | | `org` | *cleared* | | | `role` | *cleared* | | **card.dfu** | `mode` | `"aux"` | | | `name` | *unset (Outboard DFU disabled)* | | | `on` / `off` | *Outboard DFU disabled* | | | `start` / `stop` | *host RESET enabled* | | **card.io** | `mode` | *reset to default ([see card.io/mode for details](https://dev.blues.io/api-reference/notecard-api/card-requests/latest.md#card-io))* | | **card.location.mode** | `lat` / `lon` / `max` | *cleared (i.e. geofence disabled)* | | | `minutes` | *unset* | | | `mode` | `"off"` | | | `seconds` | *unset* | | | `threshold` | `0` | | | `vseconds` | *cleared* | | **card.location.track** | `file` | *unset* | | | `heartbeat` | `false` | | | `hours` | *unset* | | | `start` / `stop` | *tracking stopped* | | | `sync` | `false` | | **card.monitor** | `usb` | `false` | | **card.motion.mode** | `motion` | `0` | | | `seconds` | *unset* | | | `sensitivity` | `-1` | | | `start` / `stop` | *motion tracking stopped* | | **card.motion.sync** | `count` | *cleared* | | | `minutes` | *cleared* | | | `start` / `stop` | *motion-triggered sync stopped* | | | `threshold` | *cleared* | | **card.motion.track** | `count` | *cleared* | | | `file` | *unset* | | | `minutes` | *cleared* | | | `start` / `stop` | *motion capture stopped* | | | `threshold` | *cleared* | | **card.power** | `minutes` | `720` | | **card.sleep** | `mode` | `"-accel"` | | | `on` / `off` | *sleep disabled* | | | `seconds` | *unset* | | **card.trace** | `mode` | `"off"` | | **card.transport** | `allow` | `false` | | | `method` | *device default* | | | `seconds` | `3600` | | | `umin` | `false` | | **card.triangulate** | `minutes` | `0` | | | `mode` | *cleared* | | | `on` | `false` | | | `usb` | `false` | | **card.voltage** | `alert` | `false` | | | `calibration` | `0.35` | | | `hours` | `720` | | | `mode` | `"default"` | | | `on` / `off` | *historic trends off* | | | `sync` | `false` | | | `usb` | `false` | | **card.wifi** | `name` | `Notecard` | | | `org` | *cleared* | | **card.wireless** | `apn` | *Notecard default* | | | `hours` | *unset* | | | `method` | `"primary"` | | | `mode` | `"auto"` | | **card.wireless.penalty** | `add` | `15` | | | `max` | `4320` | | | `min` | `15` | | | `rate` | `1.25` | | **dfu.status** | `on` / `off` | *DFU downloads enabled* | | | `vvalue` | *cleared* | | | `version` | *cleared* | | **env.default** | `name` / `text` | *all defaults cleared* | | **env.template** | `body` | *template cleared* | | **hub.set** | `align` | `false` | | | `duration` | *unset* | | | `host` | *default Notehub host* | | | `inbound` | `0` | | | `outbound` | `0` | | | `mode` | `"periodic"` | | | `product` | *cleared* | | | `sn` | *cleared* | | | `sync` | `false` | | | `umin` | `false` | | | `uoff` | `false` | | | `uperiodic` | `false` | | | `version` | *cleared* | | | `vinbound` | *cleared* | | | `voutbound` | *cleared* | | **ntn.gps** | `on` / `off` | *Starnote uses its own GPS/GNSS* | ## Change 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 (`{}`). **JSON** ```json { "req": "hub.set", "host": "a.mynotehub.net" } ``` **C/C++** ```cpp J *req = NoteNewRequest("hub.set"); JAddStringToObject(req, "host", "a.mynotehub.net"); NoteRequest(req); ``` **Python** ```python req = {"req": "hub.set"} req["host"] = "a.mynotehub.net" card.Transaction(req) ``` To [reset](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#resetting-request-argument-values) your host back to the default Notehub host, use a single dash (`-`) in the host argument. **JSON** ```json { "req": "hub.set", "host": "-" } ``` **C/C++** ```cpp J *req = NoteNewRequest("hub.set"); JAddStringToObject(req, "host", "-"); NoteRequest(req); ``` **Python** ```python req = {"req": "hub.set"} req["host"] = "-" card.Transaction(req) ``` ## View and Customize Modem Behavior The `card.wireless` request can be used to view details about the last known 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. **JSON** ```json { "req": "card.wireless" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.wireless"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.wireless"} card.Transaction(req) ``` ```json { "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": -3, "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 (only available on Narrowband/NB Notecards). - `nb` to restrict the modem to Cat-NB1 (only available on Narrowband/NB Notecards). - `gprs` to restrict the modem to EGPRS (only available on Narrowband/NB Notecards). - `-` to [reset](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#resetting-request-argument-values) the modem configuration to the Notecard default. When the `mode` argument is used, `card.wireless` returns the same fields as a no argument request. **JSON** ```json { "req": "card.wireless", "mode": "nb" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.wireless"); JAddStringToObject(req, "mode", "nb"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.wireless"} req["mode"] = "nb" rsp = card.Transaction(req) ``` > **Note:** > > Modes `m`, `nb`, and `gprs` are only applicable on the "narrowband" Notecard SKUs (e.g. SKUs that start with `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. **JSON** ```json { "req": "card.wireless", "apn": "myapn.nb" } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.wireless"); JAddStringToObject(req, "apn", "myapn.nb"); NoteRequest(req); ``` **Python** ```python req = {"req": "card.wireless"} req["apn"] = "myapn.nb" rsp = card.Transaction(req) ``` > **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. > **Note:** > > For a complete walkthrough of provisioning and failing over to a third-party SIM, see the [Using External SIM Cards](https://dev.blues.io/guides-and-tutorials/notecard-guides/using-external-sim-cards.md) guide. ## Change 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 (`{}`). For example, this request passes a decimal value of `24`, which corresponds to the I2C address of `0x18`: **JSON** ```json { "req": "card.io", "i2c": 24 } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.io"); JAddNumberToObject(req, "i2c", 24); NoteRequest(req); ``` **Python** ```python req = {"req": "card.io"} req["i2c"] = 24 card.Transaction(req) ``` > **Note:** > > The configured address is stored in non-volatile memory, so it persists across restarts and power cycles until you change or reset it. To [reset](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#resetting-request-argument-values) the Notecard to the default I2C address, use `-1` as the `i2c` argument value: **JSON** ```json { "req": "card.io", "i2c": -1 } ``` **C/C++** ```cpp J *req = NoteNewRequest("card.io"); JAddNumberToObject(req, "i2c", -1); NoteRequest(req); ``` **Python** ```python req = {"req": "card.io"} req["i2c"] = -1 card.Transaction(req) ``` > **Warning:** > > 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. ## Functions that Require Setting Time The Notecard will not enable certain functions until it has made a successful network 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 network connection going forward. > **Note:** > > If the Notecard is power cycled, it will have to re-establish a successful network connection to obtain the current time. These are the functions that require the current time: - [GPS location tracking](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#working-with-gps-on-the-notecard) - [Motion/asset tracking](https://dev.blues.io/guides-and-tutorials/notecard-guides/asset-tracking-with-gps.md) - Notecard and host MCU DFU - A `note.add` request - [Cell tower and WiFi triangulation](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#using-cell-tower-and-wifi-triangulation) - A `card.time` request - Notecard [data usage tracking](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#measuring-data-usage) for usage analysis requests - [Voltage monitoring](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#voltage-monitoring) for voltage analysis requests - Inbound/outbound sync scheduling calculations - Certain AUX counter features ## Validate Notecard Responses As of [Notecard firmware v5.3.1](https://dev.blues.io/notecard/notecard-firmware-releases.md), you may validate responses from the Notecard using a [Cyclic Redundancy Check](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) (CRC). In extremely rare cases, dropped or altered bytes on I2C or UART interfaces could result in JSON parse errors on the Notecard. > **Note:** > > The latest versions of [`note-arduino`](https://dev.blues.io/tools-and-sdks/firmware-libraries/arduino-library.md), [`note-c`](https://github.com/blues/note-c), and [`note-go`](https://github.com/blues/note-go) all apply the CRC checks described below, and additionally perform automatic retries on I/O errors. If you're using one of these libraries make sure you update to the latest version, and Notecard response validation will happen automatically with no extra work required. ### CRC Usage The `crc` argument can be supplied to **any Notecard API**. The format of the argument is `"crc":"SSSS:CCCCCCCC"`: - **SSSS** = An arbitrary sequence number chosen by the host (this matches responses to requests). - **CCCCCCCC** = CRC-32 as ASCII Hex (IEEE 802.3 polynomial 0x04C11DB7 Init:0xFFFFFFFF). The CRC-32 should be calculated on the JSON request **without the CRC argument**, but with the closing brace. For example with this request: ```json {"req":"hub.get"} ``` The `crc32` value is `0xE37F7D23`. See the [Online CRC Calculator](https://crccalc.com/) and select "CRC-32" for more details. ### CRC Example Consider the following Notecard request: ```json {"req":"note.add","body":{"foo":"bar"}} ``` Without using `crc`, in an extremely rare circumstance with dropped or altered bytes on the I2C or UART interfaces, the request could become the following, with no error reported: ```json {"req":"note.add","body":{"fxx":"bx"}} ``` However, with `crc` enabled: ```json {"req":"note.add","body":{"foo":"bar"},"crc":"1234:9F27DC43"} ``` ```json {"total":2,"crc":"1234:3EE67BF0"} ``` The error would have been caught: ```json {"req":"note.add","body":{"fxx":"bx"},"crc":"1234:9F27DC43"} ``` ```json {"err":"CRC error in request {io}"} ``` ## APIs and Arguments for Robustness Testing The Notecard API includes an additional request and the ability to use "universal arguments" (meaning usable with any Notecard API) that can help to test the robustness of Notecard requests. > **Note:** > > These are generally only useful if **not** using one of the Blues-supported [Notecard firmware libraries](https://dev.blues.io/tools-and-sdks/firmware-libraries.md). ### `echo` API The `echo` API takes everything in the request, except for the `req` field, and returns it in the response. Each argument in the request must correspond to an existing argument available in any other Notecard API (and also must match the data type). This is included for robustness testing of I2C and serial hardware communications, generally to make sure that pull-ups and lines are behaving properly at high velocity. For example: ```json { "req": "echo", "deleted": true, "start": true, "signals": 752408723, "max": -1006377422, "status": "open" } ``` Will return: ```json { "deleted": true, "start": true, "signals": 752408723, "max": -1006377422, "status": "open" } ``` ### `id` Argument If an `id` argument (integer) is passed with a request, the same `id` will be returned in the response. This is included for serial protocol robustness testing, as a way to ensure that a given response correlates to a given request. For example: ```json { "req": "hub.get", "id": 123456 } ``` Will return: ```json { "id": 123456, "secure": true, "mode": "continuous", "host": "a.notefile.net", "product": "com.blues.testing:testing", "device": "dev:860322068012345", "sync": true } ``` ### `pad` Argument If an integer value >= `20` is supplied to the `pad` argument, it is guaranteed that the first \[n] bytes of the reply will look like `{"len":n ...` (potentially filled out to \[n] bytes with spaces if the total request length is < `pad`). This is useful in a serial driver or OS environment where ONLY blocking I/Os are supported, as you can read the response in a reliable manner using blocking I/O. The following are steps you could take to utilize the `pad` argument in C: 1. Send an API request with `"pad":20`. 2. Perform a blocking read of `20` bytes into `buf`, waiting for the reply. 3. Perform the following length calculation: `unsigned remainingLen = atoi(&buf[7]) - 20`. 4. Perform a blocking read of `remainingLen` bytes into `&buf[20]`. This will read the entire JSON reply into `buf`. The following is an example request in plain JSON: ```json { "pad": 20, "req": "card.time" } ``` Will return: ```json { "len": 169, "minutes": -240, "lat": 42.512662499999978, "lon": -70.910546875000009, "area": "Salem MA", "country": "US", "zone": "EDT,America/New_York", "time": 1625711237 } ``` In the above example, `len` is `169` because of the `\r\n` that is not visible. [Updating Notecard Firmware](https://dev.blues.io/notecard/notecard-walkthrough/updating-notecard-firmware.md "Updating Notecard Firmware")