---
title: card Requests - API Reference
description: Reference for Notecard requests used to configure device behavior, GPS and accelerometer data, and to query device state, network, and peripherals.
source_url: https://dev.blues.io/api-reference/notecard-api/card-requests/
canonical_url: https://dev.blues.io/api-reference/notecard-api/card-requests/
markdown_url: https://dev.blues.io/api-reference/notecard-api/card-requests.md
---

# card Requests

The Notecard provides a number of requests that can be used to configure the behavior of the Notecard, its pins, its use of GPS and accelerometer data, and to query the state of the Device, its network connection and peripherals. All of these requests begin with the `card` prefix.

## card.attn

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Configure hardware notifications from a Notecard to a host MCU.

***NOTE:** Requires a connection between the Notecard ATTN pin and a GPIO pin on the host MCU.*

Arguments

### `files`

*array of string (optional)*

A list of [Notefiles](https://dev.blues.io/api-reference/glossary.md#notefile) to watch for file-based interrupts.

### `mode`

*string (optional)*

A comma-separated list of one or more of the following keywords. Some keywords are only supported on certain types of Notecards.

`""` (Cell, Cell+WiFi, Skylo, WiFi)

Queries the current ATTN pin state.

`"arm"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Clear "files" events and cause the ATTN pin to go LOW. After an event occurs or "seconds" has elapsed, the ATTN pin will then go HIGH (a.k.a. "fires"). If "seconds" is 0, no timeout will be scheduled. If ATTN is armed, calling `arm` again will disarm (briefly pulling ATTN HIGH), then arm (non-idempotent).

`"auxgpio"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using `-auxgpio`.

`"connected"` (Cell, Cell+WiFi, Skylo, WiFi)

When armed, will cause ATTN to fire whenever the module connects to cellular. Disable with `-connected`.

`"disarm"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Causes ATTN pin to go HIGH if it had been LOW.

Passing both `"disarm"` and `"-all"` clears all ATTN monitors currently set.

`"env"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

When armed, causes ATTN to fire if an environment variable changes on the Notecard. Disable by using `-env`.

`"files"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

When armed, will cause ATTN to fire if any of the "files" are modified. Disable by using `-files`.

`"location"` (Cell, Cell+WiFi, Skylo, WiFi)

When armed, will cause ATTN to fire whenever the Notecard GPS module makes a position fix. Disable by using `-location`.

`"motion"` (Cell, Cell+WiFi, Skylo, WiFi)

When armed, will cause ATTN to fire whenever the accelerometer detects module motion. Disable with `-motion`.

`"motionchange"` (Cell, Cell+WiFi, Skylo, WiFi)

When armed, will cause ATTN to fire whenever the `card.motion.mode` changes from "moving" to "stopped" (or vice versa). Learn how to configure this feature [in this guide](https://dev.blues.io/guides-and-tutorials/notecard-guides/asset-tracking-with-gps.md#wake-host-or-send-note-on-motion-status-change).

`"rearm"` (Cell, Cell+WiFi, Skylo, WiFi)

Will arm ATTN if not already armed. Otherwise, resets the values of `mode`, `files`, and `seconds` specified in the initial `arm` or `rearm` request (idempotent).

`"signal"` (Cell, Cell+WiFi, Skylo, WiFi)

When armed, will cause ATTN to fire whenever the Notecard receives a [signal](https://dev.blues.io/api-reference/glossary.md#signal).

`"sleep"` (Cell, Cell+WiFi, Skylo, WiFi)

Instruct the Notecard to pull the ATTN pin low for a period of time, and optionally keep a payload in memory. Can be used by the host to sleep the host MCU.

`"usb"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

When armed, will enable USB power events firing the ATTN pin. Disable with `-usb`.

`"watchdog"` (Cell, Cell+WiFi, Skylo, WiFi)

Not an "arm" mode, rather will cause the ATTN pin to go from HIGH to LOW, then HIGH if the notecard fails to receive any JSON requests for "seconds." In this mode, "seconds" must be >= 60.

`"wireless"` (Cell, Cell+WiFi, Skylo, WiFi)

Instruct the Notecard to fire the ATTN pin whenever the `card.wireless` [status](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-wireless) changes.

### `off`

*boolean (optional)*

When `true`, completely disables ATTN processing and sets the pin OFF. This setting is retained across device restarts.

### `on`

*boolean (optional)*

When `true`, enables ATTN processing. This setting is retained across device restarts.

### `payload`

*string (format: binary) (optional)*

When using `sleep` mode, a payload of data from the host that the Notecard should hold in memory until retrieved by the host.

### `seconds`

*integer (optional)*

To set an ATTN timeout when arming, or when using `sleep`.

***NOTE:** When the Notecard is in `continuous` mode, the `seconds` timeout is serviced by a routine that wakes every 15 seconds. You can predict when the device will wake, by rounding up to the nearest 15 second interval.*

### `start`

*boolean (optional)*

When using `sleep` mode and the host has reawakened, request the Notecard to return the stored `payload`.

### `verify`

*boolean (optional)*

When `true`, returns the current attention mode configuration, if any.

**Connected**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "arm,connected"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm,connected");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "arm,connected"
rsp = card.Transaction(req)
```

Configure the Notecard to perform an interrupt on a successful connection to Notehub.

**Files**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "arm,files",
  "files": [
    "data.qi",
    "my-settings.db"
  ]
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm,files");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("data.qi"));
JAddItemToArray(files, JCreateString("my-settings.db"));

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "arm,files"
req["files"] = ["data.qi", "my-settings.db"]
rsp = card.Transaction(req)
```

Configure the Notecard to perform an interrupt on the `data.qi` and `my-settings.db` Notefiles.

**Location**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "arm,location"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm,location");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "arm,location"
rsp = card.Transaction(req)
```

Configure the Notecard to perform an interrupt when the Notecard makes a position fix.

**Motion**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "arm,motion"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm,motion");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "arm,motion"
rsp = card.Transaction(req)
```

Configure the Notecard to perform an interrupt when the Notecard detects motion.

**Signal**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "arm,signal"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "arm,signal");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "arm,signal"
rsp = card.Transaction(req)
```

Configure the Notecard to perform an interrupt when the Notecard receives a signal.

**Watchdog**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "watchdog",
  "seconds": 60
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "watchdog");
JAddNumberToObject(req, "seconds", 60);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "watchdog"
req["seconds"] = 60
rsp = card.Transaction(req)
```

Configure the Notecard to function as a watchdog timer with a 60 second timeout.

**Sleep With Payload**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "sleep",
  "seconds": 3600,
  "payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "sleep");
JAddNumberToObject(req, "seconds", 3600);
JAddStringToObject(req, "payload", "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ==");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "sleep"
req["seconds"] = 3600
req["payload"] = "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
rsp = card.Transaction(req)
```

Configure the Notecard to instruct the host MCU to sleep for a period of time.

**Retrieve Payload**

**JSON**

```json
{
  "req": "card.attn",
  "start": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddBoolToObject(req, "start", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["start"] = True
rsp = card.Transaction(req)
```

Retrieve a payload from the Notecard after sleep.

**Disarm all Modes**

**JSON**

```json
{
  "req": "card.attn",
  "mode": "disarm,-all"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.attn");
JAddStringToObject(req, "mode", "disarm,-all");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.attn"}
req["mode"] = "disarm,-all"
rsp = card.Transaction(req)
```

Disarm all interrupts.

**Response Members**

### `files`

*array of string*

A list of files changed since `file` attention mode was set. In addition, this field will include keywords to signify the occurrence of other attention mode triggers:

`"auxgpio"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Indicates that the ATTN pin fired due to an AUX GPIO input change.

`"connected"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to the Notecard connecting to the network.

`"env"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Indicates that the ATTN pin fired due to an environment variable change on the Notecard.

`"files"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Indicates that the ATTN pin fired due to a change in one or more monitored Notefiles.

`"journey"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to the start or end of a journey (a period of sustained motion).

`"location"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to the GPS module making a position fix.

`"modified"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Indicates that the ATTN pin fired because one or more monitored Notefiles were modified. This keyword accompanies the names of the files that changed.

`"motion"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to the accelerometer detecting motion.

`"motionchange"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to a transition between "moving" and "stopped" detected by `card.motion.mode`.

`"signal"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to the Notecard receiving an inbound [signal](https://dev.blues.io/api-reference/glossary.md#signal).

`"timeout"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Indicates that the ATTN pin fired due to the timeout period specified in `seconds` elapsing.

`"usb"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Indicates that the ATTN pin fired due to a USB power state change.

`"watchdog"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to the watchdog timer expiring.

`"wireless"` (Cell, Cell+WiFi, Skylo, WiFi)

Indicates that the ATTN pin fired due to a change in the `card.wireless` status.

### `off`

*boolean*

This field is present and set to `true` if ATTN processing has been disabled with the `off` argument.

### `payload`

*base64 string*

When using `sleep` mode with a `payload`, the payload provided by the host to the Notecard.

### `set`

*boolean*

Reflects the state of the attention pin. The `set` field is `true` when the attention pin is `HIGH`, otherwise the `set` field will not be present when the attention pin is `LOW`.

### `time`

*UNIX Epoch time*

When using `sleep` mode with a `payload`, the time (UNIX Epoch time) that the payload was stored by the Notecard.

Example Response

```json
{
  "files": [
    "data.qi",
    "modified"
  ],
  "set": true
}
```

## card.aux

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Configure various uses of the general-purpose I/O (GPIO) pins `AUX1`-`AUX4` on the Notecard edge connector for tracking applications and simple GPIO sensing and counting tasks.

> **Note:**
>
> Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces.

Arguments

### `connected`

*boolean (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

If `true`, defers the sync of the state change Notefile to the next sync as configured by the `hub.set` request.

### `count`

*integer (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

When used with `"mode":"neo-monitor"` or `"mode":"track-neo-monitor"`, this controls the number of NeoPixels to use in a strip. Possible values are `1`, `2`, or `5`.

### `file`

*string (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

The name of the Notefile used to report state changes when used in conjunction with `"sync": true`. Default Notefile name is `_button.qo`.

### `gps`

*boolean (optional)*

(Deprecated)

If `true`, along with `"mode":"track"` the Notecard supports the use of an external GPS module. This argument is deprecated. Use the `card.aux.serial` request with a `mode` of `"gps"` instead.

### `limit`

*boolean (optional)*

If `true`, along with `"mode":"track"` and `gps:true` the Notecard will disable concurrent modem use during GPS tracking.

### `max`

*integer (optional)*

When in `gpio` mode, if an `AUX` pin is configured as a `count` type, the maximum number of `seconds`-long sample buckets to collect. Once `max` buckets have been filled, additional counts roll into the final bucket. Passing `0` or omitting this value will provide a single incrementing count of rising edges on the pin.

### `mode`

*string (optional)*

The AUX mode. If specified, must be one of the following keywords. Some keywords are only supported on certain types of Notecards.

`"dfu"` (Cell, Cell+WiFi, Skylo, WiFi)

Enable the Notecard's `AUX1` pin as a "DFU in progress" signal for use with [Outboard Firmware Updates](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md). When enabled, `AUX1` is active `LOW` while a DFU is running and `HIGH` otherwise. See [Using DFU Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-dfu-mode) for more information.

`"gpio"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Configure the Notecard for GPIO mode with `AUX1` OFF, `AUX2` as an output `LOW`, `AUX3` as an output `HIGH`, and `AUX4` as an input.

`"led"` (Cell, Cell+WiFi, Skylo, WiFi)

When wiring LEDs to the Notecard's AUX pins (as is done when using monitor mode), use this mode along with the card.led API to manually enable/disable individual red, green, and/or yellow LEDs.

`"monitor"` (Cell, Cell+WiFi, Skylo, WiFi)

If you plan to place your Notecard in 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.

`"motion"` (Cell, Cell+WiFi, Skylo, WiFi)

Supplement autonomous tracking with digital inputs and a status output.

`"neo"` (Cell, Cell+WiFi, Skylo, WiFi)

When wiring a NeoPixel or NeoPixel strip to the Notecard's AUX2 pin (as is done when using neo-monitor mode), use this mode along with the card.led API to manually enable/disable a single NeoPixel.

`"neo-monitor"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Similar to monitor mode, neo-monitor mode supports NeoPixel LEDs that 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.

`"off"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Disable AUX mode.

`"rgb"` (Cell, Cell+WiFi, Skylo, WiFi)

When wiring an RGB LED to the Notecard's AUX2-4 pins, you may use this mode along with the card.led API to manually enable/disable colors in a single RGB LED.

`"rgb-monitor"` (Cell, Cell+WiFi, Skylo, WiFi)

Similar to monitor mode, `rgb-monitor` mode supports a single RGB LED that 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.

`"track"` (Cell, Cell+WiFi, Skylo, WiFi)

Enhance Notes in the `_track.qo` Notefile with temperature, pressure, and humidity readings from a connected BME280 sensor.

`"track-monitor"` (Cell, Cell+WiFi, Skylo, WiFi)

Combines the functionality of the `track` and `monitor` AUX modes.

`"track-neo-monitor"` (Cell, Cell+WiFi, Skylo, WiFi)

Combines `track` and `monitor` modes while also supporting NeoPixel LEDs that allow for monitoring Notecard activity.

`"track-rgb-monitor"` (Cell, Cell+WiFi, Skylo, WiFi)

Combines `track` and `monitor` modes while also supporting a single RGB LED that allows for monitoring Notecard activity.

`"-"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Resets the AUX mode to its default value (`off`).

### `ms`

*integer (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

When in `gpio` mode, this argument configures a debouncing interval. With a debouncing interval in place, the Notecard excludes all transitions with a shorter duration than the provided debounce time, in milliseconds. This interval only applies to GPIOs configured with a `usage` of `count`, `count-pulldown`, or `count-pullup`.

### `offset`

*integer (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

When used with `"mode":"neo-monitor"` or `"mode":"track-neo-monitor"`, this is the 1-based index in a strip of NeoPixels that determines which single NeoPixel the host can command.

### `rate`

*integer (optional, default `115200`)*

The AUX UART baud rate for debug communication over the AUXRX and AUXTX pins.

### `seconds`

*integer (optional)*

When in `gpio` mode, if an `AUX` pin is configured as a `count` type, the count of rising edges can be broken into samples of this duration. Passing `0` or omitting this field will total into a single sample.

### `sensitivity`

*integer (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

When used with `"mode":"neo-monitor"` or `"mode":"track-neo-monitor"`, this controls the brightness of NeoPixel lights, where `100` is the maximum brightness and `1` is the minimum.

### `start`

*boolean (optional)*

When in `gpio` mode, if an `AUX` pin is configured as a `count` type, set to `true` to reset counters and start incrementing.

### `sync`

*boolean (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

If `true`, for pins set as `input` by `usage`, the Notecard will autonomously report any state changes as new notes in `file`. For pins used as `count`, the Notecard will use an interrupt to count pulses and will report the total in a new note in `file` unless it has been noted in the previous second.

### `usage`

*array of string (optional)*

An ordered list of pin modes for each AUX pin when in GPIO mode.

`""` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to leave the pin unchanged.

`"off"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to disable the pin.

`"high"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to set the pin as a `HIGH` output.

`"low"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to set the pin as a `LOW` output.

`"input"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to set the pin as an input.

`"input-pulldown"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to set the pin as a pull-down input.

`"input-pullup"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

to set the pin as a pull-up input.

`"count"` (Cell, Cell+WiFi, Skylo, WiFi)

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"` (Cell, Cell+WiFi, Skylo, WiFi)

Same as `count` usage, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating.

`"count-pullup"` (Cell, Cell+WiFi, Skylo, WiFi)

Same as `count` usage, but a pull-up resistor internal to the Notecard will automatically keep the pin from floating and falling edges of pulses are counted.

**DFU Mode**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "dfu"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "dfu");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "dfu"
rsp = card.Transaction(req)
```

Enable the Notecard's `AUX1` pin as a "DFU in progress" signal for use with [Outboard Firmware Updates](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md). When enabled, `AUX1` is active `LOW` while a DFU is running and `HIGH` otherwise.

**GPIO Mode**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "off",
    "low",
    "high",
    "input"
  ]
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *usage = JAddArrayToObject(req, "usage");
JAddItemToArray(usage, JCreateString("off"));
JAddItemToArray(usage, JCreateString("low"));
JAddItemToArray(usage, JCreateString("high"));
JAddItemToArray(usage, JCreateString("input"));

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = ["off", "low", "high", "input"]
rsp = card.Transaction(req)
```

Configure the Notecard for GPIO mode with `AUX1` OFF, `AUX2` as an output `LOW`, `AUX3` as an output `HIGH`, and `AUX4` as an input.

**GPIO Mode With Count**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "off",
    "low",
    "high",
    "count"
  ],
  "seconds": 2,
  "max": 5,
  "start": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *usage = JAddArrayToObject(req, "usage");
JAddItemToArray(usage, JCreateString("off"));
JAddItemToArray(usage, JCreateString("low"));
JAddItemToArray(usage, JCreateString("high"));
JAddItemToArray(usage, JCreateString("count"));
JAddNumberToObject(req, "seconds", 2);
JAddNumberToObject(req, "max", 5);
JAddBoolToObject(req, "start", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = ["off", "low", "high", "count"]
req["seconds"] = 2
req["max"] = 5
req["start"] = True
rsp = card.Transaction(req)
```

Configure the Notecard for GPIO mode with `AUX1` OFF, `AUX2` as an output `LOW`, `AUX3` as an output `HIGH`, and `AUX4` as a count.

**GPIO Mode With Notefile**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "off",
    "low",
    "high",
    "input"
  ],
  "sync": true,
  "file": "statechange.qo"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");
J *usage = JAddArrayToObject(req, "usage");
JAddItemToArray(usage, JCreateString("off"));
JAddItemToArray(usage, JCreateString("low"));
JAddItemToArray(usage, JCreateString("high"));
JAddItemToArray(usage, JCreateString("input"));
JAddBoolToObject(req, "sync", true);
JAddStringToObject(req, "file", "statechange.qo");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = ["off", "low", "high", "input"]
req["sync"] = True
req["file"] = "statechange.qo"
rsp = card.Transaction(req)
```

Configure GPIO mode with automatic state change reporting to a Notefile.

**Monitor Mode**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "monitor"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "monitor");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "monitor"
rsp = card.Transaction(req)
```

Configure inputs and outputs typically placed on the faceplate of a device for technicians to test and monitor Notecard activity.

**Neo-Monitor Mode**

**JSON**

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

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "neo-monitor");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "neo-monitor"
rsp = card.Transaction(req)
```

Enable neo-monitor mode which supports NeoPixel LEDs for monitoring Notecard activity.

**Motion Mode**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "motion"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "motion");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "motion"
rsp = card.Transaction(req)
```

Supplement autonomous tracking with digital inputs and a status output.

**Setting AUX UART Baud**

**JSON**

```json
{
  "req": "card.aux",
  "rate": 9600
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddNumberToObject(req, "rate", 9600);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["rate"] = 9600
rsp = card.Transaction(req)
```

Configure the AUX UART baud rate for debug communication.

**Track Mode**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "track"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "track");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "track"
rsp = card.Transaction(req)
```

Enhance Notes with temperature, pressure, and humidity readings from a connected BME280 sensor.

**Response Members**

### `mode`

*string*

The current AUX `mode`, or `off` if not set.

### `power`

*boolean*

If `true`, indicates the Notecard has USB (main) power. This parameter only appears in the body of the Note in Notehub if using `"sync":true`.

### `seconds`

*integer*

When in AUX `gpio` mode, and if `count` is enabled on an AUX pin, the number of seconds per sample.

### `state`

*array of object*

When in AUX `gpio` mode, the array element for each pin reflects its current configuration. The label below each example object identifies the corresponding `usage` value the pin was configured with.

`""` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

`{}` when the pin is off.

`"high"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

`{"high": true}` when the pin is high.

`"low"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

`{"low": true}` when the pin is low.

`"input"` (Cell, Cell+WiFi, LoRa, Skylo, WiFi)

`{"input": true}` when the pin is input.

`"count"` (Cell, Cell+WiFi, Skylo, WiFi)

`{"count": [4]}` where each item in the array is the count per sample.

### `time`

*integer (format: unix-time)*

When in AUX `gpio` mode, and if `count` is enabled on an AUX pin, the time that counting started.

Example Response

```json
{
  "mode": "gpio",
  "state": [
    {},
    {
      "low": true
    },
    {
      "high": true
    },
    {
      "count": [
        3
      ]
    }
  ],
  "time": 1592587637,
  "seconds": 2
}
```

## card.aux.serial

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Configure various uses of the AUXTX and AUXRX pins on the Notecard's edge connector.

> **Note:**
>
> Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's serial data interfaces. See [this guide](https://dev.blues.io/guides-and-tutorials/notecard-guides/debugging-with-the-ftdi-debug-cable.md) for an example of connecting to the Notecard AUX pins using an FTDI cable.

Arguments

### `duration`

*integer (optional)*

If using `"mode": "notify,accel"`, specify a sampling duration (in milliseconds) for the Notecard accelerometer.

### `limit`

*boolean (optional)*

If `true`, along with `"mode":"gps"` the Notecard will disable concurrent modem use during GPS tracking.

### `max`

*integer (optional)*

The maximum amount of data, in bytes, that can be sent in a single transmission before the Notecard pauses to allow the host to process incoming data. This value should be set to the size of the host's serial receive buffer minus `1`, which represents the number of bytes the host can absorb before the sender must delay due to the absence of flow control. For example, `note-arduino` uses a buffer size of `(SERIAL_RX_BUFFER_SIZE - 1)`.

### `minutes`

*integer (optional)*

When using `"mode": "notify,dfu"`, specify an interval for notifying the host.

### `mode`

*string (optional)*

The AUX mode. Must be one of the following:

`"req"`: (Default) for request/response monitoring on the AUX pins.

`"gps"`: Use an external GPS/GNSS module on the AUX pins. Using an external GPS/GNSS module allows you to acquire GPS/GNSS location while Notecard is connected to Notehub in `continuous` mode. Learn more at [Using AUX Serial GPS Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-aux-serial-gps-mode).

`"notify"`: Used along with one or more of the `notify` options to send streaming data or notification data over the AUX pins. When used alone, preserves existing notification settings.

`"notify,accel"`: Used to stream readings from the onboard accelerometer over AUX.

`"notify,signals"`: Used to notify the host of any [Inbound Signals](https://dev.blues.io/guides-and-tutorials/notecard-guides/minimizing-latency.md#using-inbound-signals) from Notehub.

`"notify,env"`: Used to notify the host of Environment Variable changes over AUX.

`"notify,dfu"`: Used to notify the host that the Notecard has downloaded updated host firmware.

### `ms`

*integer (optional)*

The delay in milliseconds before sending a buffer of `max` size.

### `rate`

*integer (optional)*

The baud rate or speed at which information is transmitted over AUX serial. The default is `115200` unless using GPS, in which case the default is `9600`.

**Enable GPS Mode**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "gps"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "gps");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "gps"
rsp = card.Transaction(req)
```

Configure AUX serial for external GPS communication. Using an external GPS/GNSS module allows you to acquire GPS/GNSS location while Notecard is connected to Notehub in `continuous` mode. Learn more at [Using AUX Serial GPS Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-aux-serial-gps-mode).

**Enable DFU Notifications**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "notify,dfu",
  "minutes": 5
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,dfu");
JAddNumberToObject(req, "minutes", 5);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "notify,dfu"
req["minutes"] = 5
rsp = card.Transaction(req)
```

Configure AUX serial for DFU notifications with timeout.

**Enable Environment Notifications**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "notify,env"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,env");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "notify,env"
rsp = card.Transaction(req)
```

Configure AUX serial for environment variable change notifications.

**Request Mode**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "req"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "req");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "req"
rsp = card.Transaction(req)
```

Set AUX serial to request mode for command/response communication.

**Accelerometer Mode**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "notify,accel",
  "duration": 500
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,accel");
JAddNumberToObject(req, "duration", 500);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "notify,accel"
req["duration"] = 500
rsp = card.Transaction(req)
```

Send raw readings from the onboard accelerometer over AUX every 500 ms.

**Signal Mode**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "notify,signals"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,signals");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "notify,signals"
rsp = card.Transaction(req)
```

Turn on Inbound Signals from Notehub for low-latency communication.

**Multiple Mode**

**JSON**

```json
{
  "req": "card.aux.serial",
  "mode": "notify,accel,env",
  "duration": 500
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "notify,accel,env");
JAddNumberToObject(req, "duration", 500);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["mode"] = "notify,accel,env"
req["duration"] = 500
rsp = card.Transaction(req)
```

Subscribe to multiple notifications at once.

**Response Members**

### `max`

*integer*

The currently configured `max` transmission size, in bytes. Returned only when a non-zero value has been configured.

### `mode`

*string*

The current AUX `mode`.

### `ms`

*integer*

The currently configured `ms` delay between transmissions, in milliseconds. Returned only when a non-zero value has been configured.

### `rate`

*integer*

The baud rate or speed at which information is transmitted over AUX serial.

Example Response

```json
{
  "mode": "req",
  "rate": 115200
}
```

## card.binary

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

View the status of the binary storage area of the Notecard and optionally clear any data and related `card.binary` variables. See the guide on [Sending and Receiving Large Binary Objects](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md) for best practices when using `card.binary`.

Arguments

### `delete`

*boolean (optional)*

Clear the COBS area on the Notecard and reset all related arguments previously set by a card.binary request.

**View Binary Status**

**JSON**

```json
{
  "req": "card.binary"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.binary");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.binary"}
rsp = card.Transaction(req)
```

Check the status of binary storage area.

**Reset Binary Data**

**JSON**

```json
{
  "req": "card.binary",
  "delete": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.binary");
JAddBoolToObject(req, "delete", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.binary"}
req["delete"] = True
rsp = card.Transaction(req)
```

Clear the COBS area and reset binary variables.

**Response Members**

### `cobs`

*integer*

The size of COBS-encoded data stored in the reserved area (without the trailing ).

### `connected`

*boolean*

Returns true if the Notecard is connected to the network.

### `err`

*string*

If present, a string describing the error that occurred during transmission.

### `length`

*integer*

The amount of unencoded data currently stored (in bytes).

### `max`

*integer*

The space available (in bytes) for storing unencoded data on the Notecard.

### `status`

*string*

The MD5 checksum calculated for the entire unencoded buffer.

Example Response

```json
{
  "connected": true,
  "max": 130554,
  "status": "ce6fdef565eeecf14ab38d83643b922d",
  "length": 4,
  "cobs": 5
}
```

## card.binary.get

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Returns binary data stored in the binary storage area of the Notecard. The response to this API command first returns the JSON-formatted response object, then the binary data.

See the guide on [Sending and Receiving Large Binary Objects](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md) for best practices when using `card.binary`.

Arguments

### `cobs`

*integer (optional)*

The size of the COBS-encoded data you are expecting to be returned (in bytes).

### `length`

*integer (optional)*

Used along with `offset`, the number of bytes to retrieve from the binary storage area of the Notecard.

### `offset`

*integer (optional)*

Used along with `length`, the number of bytes to offset the binary payload from 0 when retrieving binary data from the binary storage area of the Notecard. Primarily used when retrieving multiple fragments of a binary payload from the Notecard.

**Example**

**JSON**

```json
{
  "req": "card.binary.get"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.binary.get");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.binary.get"}
rsp = card.Transaction(req)
```

Retrieve all binary data from storage area.

**Response Members**

### `err`

*string*

If present, a string describing the error that occurred during transmission

### `status`

*string*

The MD5 checksum of the data returned, after it has been decoded

Example Response

```json
{
  "status": "ce6fdef565eeecf14ab38d83643b922d"
}
```

## card.binary.put

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Adds binary data to the binary storage area of the Notecard. The Notecard expects to receive binary data immediately following the usage of this API command.

See the guide on [Sending and Receiving Large Binary Objects](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md) for best practices when using `card.binary`.

Arguments

### `cobs`

*integer (optional)*

The size of the COBS-encoded data (in bytes).

### `offset`

*integer (optional)*

The number of bytes to offset the binary payload from 0 when appending the binary data to the binary storage area of the Notecard. Primarily used when sending multiple fragments of one binary payload to the Notecard.

### `status`

*string (optional)*

The MD5 checksum of the data, before it has been encoded.

**Example**

**JSON**

```json
{
  "req": "card.binary.put",
  "cobs": 5,
  "status": "ce6fdef565eeecf14ab38d83643b922d"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.binary.put");
JAddNumberToObject(req, "cobs", 5);
JAddStringToObject(req, "status", "ce6fdef565eeecf14ab38d83643b922d");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.binary.put"}
req["cobs"] = 5
req["status"] = "ce6fdef565eeecf14ab38d83643b922d"
rsp = card.Transaction(req)
```

Send binary data with MD5 checksum.

**Response Members**

### `err`

*string*

If present, a string describing the error that occurred during transmission

## card.carrier

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Uses the `AUX_CHARGING` pin on the Notecard edge connector to notify the Notecard that the pin is connected to a Notecarrier that supports charging, using open-drain.

Once set, `{"charging":true}` will appear in a response if the Notecarrier is currently indicating that charging is in progress.

Arguments

### `mode`

*string (optional)*

The `AUX_CHARGING` mode.

`"charging"`: Tell the Notecard that `AUX_CHARGING` is connected to a Notecarrier that supports charging on `AUX_CHARGING`.

`"-"`: Turn off `AUX_CHARGING` detection.

`"off"`: Turn off `AUX_CHARGING` detection.

**Example**

**JSON**

```json
{
  "req": "card.carrier",
  "mode": "charging"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.carrier");
JAddStringToObject(req, "mode", "charging");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.carrier"}
req["mode"] = "charging"
rsp = card.Transaction(req)
```

Set the `AUX_CHARGING` mode to charging.

**Response Members**

### `charging`

*boolean*

Will display `true` when in `AUX_CHARGING` `"charging"` mode.

### `mode`

*string*

The current `AUX_CHARGING` `mode`, or `off` if not set.

Example Response

```json
{
  "mode": "charging",
  "charging": true
}
```

## card.contact

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Used to set or retrieve information about the Notecard maintainer. Once set, this information is synced to Notehub.

Arguments

### `email`

*string (format: email) (optional)*

Set the email address of the Notecard maintainer.

### `name`

*string (optional)*

Set the name of the Notecard maintainer.

### `org`

*string (optional)*

Set the organization name of the Notecard maintainer.

### `role`

*string (optional)*

Set the role of the Notecard maintainer.

**Set Contact Information**

**JSON**

```json
{
  "req": "card.contact",
  "name": "Tom Turkey",
  "org": "Blues",
  "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");
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"
req["role"] = "Head of Security"
req["email"] = "tom@blues.com"
rsp = card.Transaction(req)
```

Set contact information for the Notecard maintainer.

**Retrieve Contact Information**

**JSON**

```json
{
  "req": "card.contact"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.contact");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.contact"}
rsp = card.Transaction(req)
```

Retrieve the currently stored contact information by issuing the request with no arguments.

**Response Members**

### `email`

*string (format: email)*

Email address of the Notecard maintainer.

### `name`

*string*

Name of the Notecard maintainer.

### `org`

*string*

Organization name of the Notecard maintainer.

### `role`

*string*

Role of the Notecard maintainer.

Example Response

```json
{
  "name": "Tom Turkey",
  "org": "Blues",
  "role": "Head of Security",
  "email": "tom@blues.com"
}
```

## card.dfu

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Used to configure a Notecard for [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md).

Arguments

### `mode`

*string (optional)*

The `mode` argument allows you to control whether a Notecard's `AUX` pins (default) or `ALT_DFU` pins are used for [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md). This argument is only supported on Notecards that have `ALT_DFU` pins, which includes all versions of Notecard Cell+WiFi, non-legacy versions of Notecard Cellular, and Notecard WiFi v2.

`"altdfu"`: Enable the Notecard's `ALT_DFU` pins (instead of the `AUX` pins) for use with Notecard Outboard Firmware Update.

`"aux"`: Return the Notecard's `ALT_DFU` pins to their default state of `AUX`.

### `name`

*string (optional)*

One of the supported classes of host MCU. Supported MCU classes are `"esp32"`, `"stm32"`, `"stm32-bi"`, `"mcuboot"` (added in v5.3.1), and `"-"`, which resets the configuration. The "bi" in `"stm32-bi"` stands for "boot inverted", and the `"stm32-bi"` option should be used on STM32 family boards where the hardware boot pin is assumed to be active low, instead of active high. Supported MCUs can be found on the [Notecarrier F datasheet](https://dev.blues.io/datasheets/notecarrier-datasheet/notecarrier-f-v1-3.md).

`"esp32"`: ESP32 microcontroller family.

`"stm32"`: STM32 microcontroller family.

`"stm32-bi"`: STM32 microcontroller family with boot inverted (boot pin active low).

`"mcuboot"`: MCUboot compatible microcontroller (added in v5.3.1).

`"-"`: Resets the configuration.

### `off`

*boolean (optional)*

Set to `true` to disable Notecard Outboard Firmware Update from occurring.

### `on`

*boolean (optional)*

Set to `true` to enable Notecard Outboard Firmware Update.

### `seconds`

*integer (optional)*

When used with `"off":true`, disable Notecard Outboard Firmware Update operations for the specified number of `seconds`.

### `start`

*boolean (optional)*

Set to `true` to enable the host RESET if previously disabled with `"stop":true`.

### `stop`

*boolean (optional)*

Set to `true` to disable the host RESET that is normally performed on the host MCU when the Notecard starts up (in order to ensure a clean startup), and also when the Notecard wakes up the host MCU after the expiration of a `card.attn` "sleep" operation. If `true`, the host MCU will not be reset in these two conditions.

**Configure STM32 DFU**

**JSON**

```json
{
  "req": "card.dfu",
  "name": "stm32",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "stm32");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.dfu"}
req["name"] = "stm32"
req["on"] = True
rsp = card.Transaction(req)
```

Enable DFU for STM32 microcontroller.

**Configure ESP32 DFU**

**JSON**

```json
{
  "cmd": "card.dfu",
  "name": "esp32",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "esp32");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.dfu"}
req["name"] = "esp32"
req["on"] = True
card.Transaction(req)
```

Enable DFU for ESP32 microcontroller.

**Enable Alternative DFU Pins**

**JSON**

```json
{
  "req": "card.dfu",
  "mode": "altdfu"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "mode", "altdfu");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.dfu"}
req["mode"] = "altdfu"
rsp = card.Transaction(req)
```

Use ALT\_DFU pins instead of AUX pins on Cell+WiFi.

**Disable DFU Temporarily**

**JSON**

```json
{
  "req": "card.dfu",
  "off": true,
  "seconds": 3600
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.dfu");
JAddBoolToObject(req, "off", true);
JAddNumberToObject(req, "seconds", 3600);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.dfu"}
req["off"] = True
req["seconds"] = 3600
rsp = card.Transaction(req)
```

Disable DFU for 3600 seconds.

**Response Members**

### `name`

*string*

The class of MCU that the Notecard is currently configured to support for Outboard DFU.

Example Response

```json
{
  "name": "stm32"
}
```

## card.illumination

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

This request returns an illumination reading (in lux) from an OPT3001 ambient light sensor connected to Notecard's I2C bus. If no OPT3001 sensor is detected, this request returns an “illumination sensor is not available” error.

Arguments

None

**Example**

**JSON**

```json
{
  "req": "card.illumination"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.illumination");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.illumination"}
rsp = card.Transaction(req)
```

Read current Lux value from the attached OPT3001 sensor.

**Response Members**

### `value`

*number*

An illumination reading (in lux) from the attached OPT3001 sensor.

Example Response

```json
{
  "value": 8806.4
}
```

## card.io

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Can be used to override the Notecard's I2C address from its default of `0x17` and change behaviors of the onboard LED and USB port.

Arguments

### `i2c`

*integer (optional)*

The alternate address to use for I2C communication.

### `mode`

*string (optional)*

Used to control the Notecard's IO behavior, including USB port, LED, I2C master, NTN fallback.

`"-1"`: Send `-1` to [reset](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#resetting-request-argument-values) to the default I2C address.

`"-usb"`: Set to `"-usb"` to disable the Notecard's USB port. Re-enable the USB port with `"usb"` or `"+usb"`.

`"usb"`: Re-enable the Notecard's USB port after it has been disabled with `"-usb"`.

`"+usb"`: Re-enable the Notecard's USB port after it has been disabled with `"-usb"`.

`"+busy"`: If set to `"+busy"`, the Notecard's LED will be on when the Notecard is awake, and off when the Notecard goes to sleep.

`"-busy"`: Resets `"+busy"` to its default, making the onboard LED blink only during Notecard flash memory operations.

`"i2c-master-disable"`: Disables Notecard acting as an I2C master. Re-enable by using `"i2c-master-enable"`.

`"i2c-master-enable"`: Re-enables the Notecard to act as an I2C master after it has been disabled with `"i2c-master-disable"`.

`"+fallback"`: Setting `"+fallback"` forces NTN fallback mode: WiFi and cellular are automatically failed over, and all traffic goes through NTN. This applies whether a Starnote is attached or NTN mode is simulated, and it overrides the configured `card.transport` method. This state persists across reboots and therefore is discouraged for use in production deployments because it can incur unexpectedly high satellite data costs.

`"-fallback"`: Resets `"+fallback"` to its default state, ensuring fallback mode is only enabled if cellular/WiFi are not available.

**Change I2C Address**

**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
rsp = card.Transaction(req)
```

Change the Notecard's I2C address from its default of `0x17` to `0x18`.

**Keep LED On While Notecard Awake.**

**JSON**

```json
{
  "req": "card.io",
  "mode": "+busy"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.io");
JAddStringToObject(req, "mode", "+busy");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.io"}
req["mode"] = "+busy"
rsp = card.Transaction(req)
```

Keep the onboard LED on while the Notecard is awake.

**Disable I2C Master.**

**JSON**

```json
{
  "req": "card.io",
  "mode": "i2c-master-disable"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.io");
JAddStringToObject(req, "mode", "i2c-master-disable");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.io"}
req["mode"] = "i2c-master-disable"
rsp = card.Transaction(req)
```

Disable the Notecard from acting as an I2C master. Re-enable by using `"i2c-master-enable"`.

**Force Fallback Mode For Starnote.**

**JSON**

```json
{
  "req": "card.io",
  "mode": "+fallback"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.io");
JAddStringToObject(req, "mode", "+fallback");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.io"}
req["mode"] = "+fallback"
rsp = card.Transaction(req)
```

Force the Notecard to enter fallback mode (cellular/WiFi automatically failed over to NTN).

**Response Members**

None: an empty object `{}` means success.

## card.led

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Used along with the [card.aux API](https://dev.blues.io/api-reference/notecard-api/card-requests/latest.md#card-aux) to turn connected LEDs on/off, to enable a specific color on an RGB LED, or to manage a single connected NeoPixel.

Monochromatic LEDs must be wired according to the instructions provided in the guide on [Using Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-monitor-mode). Please note that the use of monochromatic LEDs is not supported by Notecard for LoRa.

RGB LEDs must be wired according to the instructions provided in the guide on [Using RGB-Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-rgb-monitor-mode). Please note that the use of RGB LEDs is not supported by Notecard for LoRa.

NeoPixels must be wired according to the instructions provided in the guide on [Using Neo-Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-neo-monitor-mode).

> **Note:**
>
> The Notecard must first be configured for the appropriate LED type using `card.aux`.
>
> For monochromatic LEDs, use `{"req": "card.aux", "mode": "led"}`.
>
> For RGB LEDs, use `{"req": "card.aux", "mode": "rgb"}`.
>
> For NeoPixels, use `{"req": "card.aux", "mode": "neo"}`.

Arguments

### `mode`

*string (optional)*

Used to specify the color of the LED to turn on or off.

**Note:** Notecard LoRa does not support monochromatic **LED** or **RGB** modes, only **NeoPixels**.

`"red"`: Supports **LED**, **RGB**, & **NeoPixel**

`"green"`: Supports **LED**, **RGB**, & **NeoPixel**

`"yellow"`: Supports **LED**, **RGB**, & **NeoPixel**

`"blue"`: Supports **RGB** & **NeoPixel**

`"cyan"`: Supports **RGB** & **NeoPixel**

`"magenta"`: Supports **RGB** & **NeoPixel**

`"orange"`: Supports **NeoPixel**

`"white"`: Supports **RGB** & **NeoPixel**

`"gray"`: Supports **NeoPixel**

### `off`

*boolean (optional)*

Set to `true` to turn the specified LED or NeoPixel off.

### `on`

*boolean (optional)*

Set to `true` to turn the specified LED or NeoPixel on.

**Turn Red LED On**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "led"
}

{
  "req": "card.led",
  "mode": "red",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "led");

NoteRequest(req);

req = NoteNewRequest("card.led");
JAddStringToObject(req, "mode", "red");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "led"
rsp = card.Transaction(req)

req = {"req": "card.led"}
req["mode"] = "red"
req["on"] = True
rsp = card.Transaction(req)
```

As shown above, the Notecard must also be in `led` mode and the LED(s) wired according to the instructions provided in the guide on [Using Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-monitor-mode).

**Turn Blue NeoPixel On**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "neo"
}

{
  "req": "card.led",
  "mode": "blue",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "neo");

NoteRequest(req);

req = NoteNewRequest("card.led");
JAddStringToObject(req, "mode", "blue");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "neo"
rsp = card.Transaction(req)

req = {"req": "card.led"}
req["mode"] = "blue"
req["on"] = True
rsp = card.Transaction(req)
```

As shown above, the Notecard must also be in `neo`, `neo-monitor`, or `track-neo-monitor` mode and the NeoPixel(s) wired according to the instructions provided in the guide on [Using Neo-Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-neo-monitor-mode).

**Turn Green RGB LED On**

**JSON**

```json
{
  "req": "card.aux",
  "mode": "rgb"
}

{
  "req": "card.led",
  "mode": "green",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "rgb");

NoteRequest(req);

req = NoteNewRequest("card.led");
JAddStringToObject(req, "mode", "green");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "rgb"
rsp = card.Transaction(req)

req = {"req": "card.led"}
req["mode"] = "green"
req["on"] = True
rsp = card.Transaction(req)
```

As shown above, the Notecard must also be in `rgb`, `rgb-monitor`, or `track-rgb-monitor` mode and the RGB LED wired according to the instructions provided in the guide on [Using RGB-Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-rgb-monitor-mode).

**Response Members**

None: an empty object `{}` means success.

## card.location

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Retrieves the last known location of the Notecard and the time at which it was acquired. Use [card.location.mode](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-location-mode) to configure location settings.

This request will return the cell tower location or triangulated location of the most recent session if a GPS/GNSS location is not available.

On Notecard LoRa this request can only return a location set through the [card.location.mode](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-location-mode) request's `"fixed"` mode.

Arguments

None

**Example**

**JSON**

```json
{
  "req": "card.location"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location"}
rsp = card.Transaction(req)
```

Retrieve the last known location of the Notecard.

**Response Members**

### `count`

*integer*

The number of consecutive recorded GPS/GNSS failures.

### `dop`

*number*

The "Dilution of Precision" value from the latest GPS/GNSS reading. The lower the value, the higher the confidence level of the reading. Values can be interpreted in [this Wikipedia table](https://en.wikipedia.org/wiki/Dilution_of_precision_\(navigation\)#Interpretation).

### `lat`

*number*

The latitude in degrees of the last known location.

### `lon`

*number*

The longitude in degrees of the last known location.

### `max`

*integer*

If a geofence is enabled by `card.location.mode`, meters from the geofence center.

### `mode`

*string*

The GPS/GNSS connection mode. Will be `continuous`, `periodic`, or `off`.

`"continuous"`: The Notecard's onboard GPS/GNSS module is enabled for continuous sampling.

`"periodic"`: The Notecard samples location at a specified interval, if the device has moved.

`"off"`: Location mode is off.

### `status`

*string*

The current status of the Notecard GPS/GNSS connection.

### `time`

*UNIX Epoch time*

The time of the location capture.

Example Response

```json
{
  "status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active} {gps-signal} {gps-sats} {gps}",
  "mode": "periodic",
  "lat": 42.5776,
  "lon": -70.87134,
  "time": 1598554399,
  "max": 25
}
```

## card.location.mode

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Sets location-related configuration settings. Retrieves the current location mode when passed with no argument.

Arguments

### `delete`

*boolean (optional)*

Set to `true` to delete the last known location stored in the Notecard.

### `lat`

*number (optional, default `last known latitude`)*

When in periodic or continuous mode, providing this value enables [geofencing](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#geofencing-with-the-notecard). The value you provide for this argument should be the latitude of the center of the geofence, in degrees. When in fixed mode, the value you provide for this argument should be the latitude location of the device itself, in degrees.

### `lon`

*number (optional, default `last known longitude`)*

When in periodic or continuous mode, providing this value enables [geofencing](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#geofencing-with-the-notecard). The value you provide for this argument should be the longitude of the center of the geofence, in degrees. When in fixed mode, the value you provide for this argument should be the longitude location of the device itself, in degrees.

### `max`

*integer (optional)*

Meters from a geofence center. Used to enable geofence location tracking.

### `minutes`

*integer (optional, default `5`)*

When geofence is enabled, the number of minutes the device should be outside the geofence before the Notecard location is tracked.

### `mode`

*string (optional)*

Sets the location mode.

`""`: Retrieves the current mode.

`"off"`: Turns location mode off. Approximate location may still be [ascertained from Notehub](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#ascertaining-an-approximate-device-location).

`"periodic"`: Samples location at a specified interval, if the device has moved.

`"continuous"`: Enables the Notecard's onboard GPS/GNSS module for continuous sampling, at a maximum frequency of one fix every 5 seconds. When in continuous mode the Notecard samples a new GPS/GNSS reading for every new Note.

`"fixed"`: Reports the location as a fixed location using the specified `lat` and `lon` coordinates. This is the only supported mode on Notecard LoRa.

`"-"`: Resets the mode to the default value (`off`).

### `seconds`

*integer (optional)*

When in `periodic` mode, location will be sampled at this interval, if the Notecard detects motion. If seconds is < 300, during periods of sustained movement the Notecard will leave its onboard GPS/GNSS on continuously to avoid powering the module on and off repeatedly.

### `threshold`

*integer (optional, default `0`)*

When in `periodic` mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.

### `vseconds`

*string (optional)*

In `periodic` mode, overrides `seconds` with a voltage-variable value.

**Continuous Mode**

**JSON**

```json
{
  "req": "card.location.mode",
  "mode": "continuous"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "continuous");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.mode"}
req["mode"] = "continuous"
rsp = card.Transaction(req)
```

Enable continuous GPS/GNSS sampling.

**Periodic Mode**

**JSON**

```json
{
  "req": "card.location.mode",
  "mode": "periodic",
  "seconds": 3600
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "seconds", 3600);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["seconds"] = 3600
rsp = card.Transaction(req)
```

Enable periodic location sampling at 1-hour intervals.

**Geofence Mode**

**JSON**

```json
{
  "req": "card.location.mode",
  "mode": "periodic",
  "lat": 42.5776,
  "lon": -70.87134,
  "max": 100,
  "minutes": 2
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "lat", 42.5776);
JAddNumberToObject(req, "lon", -70.87134);
JAddNumberToObject(req, "max", 100);
JAddNumberToObject(req, "minutes", 2);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["lat"] = 42.5776
req["lon"] = -70.87134
req["max"] = 100
req["minutes"] = 2
rsp = card.Transaction(req)
```

Enable geofencing with specific location and radius.

**Fixed Mode**

**JSON**

```json
{
  "req": "card.location.mode",
  "mode": "fixed",
  "lat": 42.5776,
  "lon": -70.87134
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "fixed");
JAddNumberToObject(req, "lat", 42.5776);
JAddNumberToObject(req, "lon", -70.87134);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.mode"}
req["mode"] = "fixed"
req["lat"] = 42.5776
req["lon"] = -70.87134
rsp = card.Transaction(req)
```

Set a fixed location for the device.

**Response Members**

### `journey`

*boolean*

`true` if a journey is currently in progress (i.e., the Notecard has detected motion and is actively tracking a journey). The Notecard tracks journeys when `mode` is set to `continuous` or to `periodic` with `seconds` less than 300. See [`_track.qo`](https://dev.blues.io/api-reference/system-notefiles.md#track-qo) for details on the `journey` and `jcount` fields included in tracking Notes.

### `lat`

*number*

If geofence is enabled, the geofence center latitude in degrees.

### `lon`

*number*

If geofence is enabled, the geofence center longitude in degrees.

### `max`

*integer*

If geofence is enabled, the meters from geofence center.

### `minutes`

*integer*

If geofence is enabled, the currently configured geofence debounce period.

### `mode`

*string*

The current location mode.

`"continuous"`: Enables the Notecard's onboard GPS/GNSS module for continuous sampling, at a maximum frequency of one fix every 5 seconds. When in continuous mode the Notecard samples a new GPS/GNSS reading for every new Note.

`"periodic"`: Samples location at a specified interval, if the device has moved.

`"off"`: Turns location mode off. Approximate location may still be ascertained from Notehub.

`"fixed"`: Reports the location as a fixed location using the specified `lat` and `lon` coordinates. This is the only supported mode on Notecard LoRa.

### `seconds`

*integer*

If specified, the periodic sample interval.

### `threshold`

*integer*

When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.

### `vseconds`

*string*

If specified, the voltage-variable period.

Example Response

```json
{
  "mode": "continuous",
  "max": 100,
  "lat": 42.5776,
  "lon": -70.87134,
  "minutes": 2,
  "threshold": 4
}
```

## card.location.track

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Store location data in a Notefile at the `periodic` interval, or using a specified `heartbeat`.

This request is only available when the `card.location.mode` request has been set to `periodic`—e.g. `{"req":"card.location.mode","mode":"periodic","seconds":300}`. If you want to track and transmit data simultaneously consider using an [external GPS/GNSS module with the Notecard](https://dev.blues.io/blog/using-an-external-gps-with-the-notecard.md).

If you connect a BME280 sensor on the I2C bus, Notecard will include a temperature, humidity, and pressure reading with each captured Note. If you connect an ENS210 sensor on the I2C bus, Notecard will include a temperature and pressure reading with each captured Note. Learn more in [\_track.qo](https://dev.blues.io/api-reference/system-notefiles.md#track-qo).

Arguments

### `file`

*string (optional, default `_track.qo`)*

The Notefile in which to store tracked location data. See the `_track.qo` Notefile's [documentation](https://dev.blues.io/api-reference/system-notefiles.md#track-qo) for details on the format of the data captured.

### `heartbeat`

*boolean (optional)*

When `start` is `true`, set to `true` to capture a tracking Note on a fixed interval even when no motion has been detected. The interval is configured with the `hours` field below.

### `hours`

*integer (optional)*

When `heartbeat` is `true`, the interval at which to capture a heartbeat tracking Note. A positive value sets the interval in hours (e.g. `2` captures a Note every two hours). To configure an interval shorter than one hour, pass a negative integer whose absolute value is the number of minutes (e.g. `-30` captures a Note every 30 minutes).

### `payload`

*string (optional)*

A base64-encoded binary payload to be included in the next `_track.qo` Note. See the guide on [Sampling at Predefined Intervals](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#sampling-at-predefined-intervals) for more details.

### `start`

*boolean (optional)*

Set to `true` to start Notefile tracking.

### `stop`

*boolean (optional)*

Set to `true` to stop Notefile tracking.

### `sync`

*boolean (optional)*

Set to `true` to perform an immediate sync to the Notehub each time a new Note is added.

**Start**

**JSON**

```json
{
  "req": "card.location.track",
  "start": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.track");
JAddBoolToObject(req, "start", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.track"}
req["start"] = True
rsp = card.Transaction(req)
```

Start location tracking.

**Stop**

**JSON**

```json
{
  "req": "card.location.track",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.track");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.track"}
req["stop"] = True
rsp = card.Transaction(req)
```

Stop location tracking.

**Heartbeat**

**JSON**

```json
{
  "req": "card.location.track",
  "start": true,
  "sync": true,
  "heartbeat": true,
  "hours": 2
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.location.track");
JAddBoolToObject(req, "start", true);
JAddBoolToObject(req, "sync", true);
JAddBoolToObject(req, "heartbeat", true);
JAddNumberToObject(req, "hours", 2);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.location.track"}
req["start"] = True
req["sync"] = True
req["heartbeat"] = True
req["hours"] = 2
rsp = card.Transaction(req)
```

Start tracking with heartbeat mode and immediate sync.

**Response Members**

### `file`

*string*

The tracking Notefile, if provided.

### `heartbeat`

*boolean*

`true` if heartbeat is enabled.

### `hours`

*integer*

The configured heartbeat interval in hours. Only returned when the heartbeat interval is a whole number of hours; otherwise, the interval is returned in `minutes` instead. `hours` and `minutes` are never returned together.

### `journey`

*boolean*

`true` if a journey is currently in progress (i.e., the Notecard has detected motion and is actively tracking a journey). The Notecard tracks journeys when `card.location.mode` is set to `continuous` or to `periodic` with `seconds` less than 300. See [`_track.qo`](https://dev.blues.io/api-reference/system-notefiles.md#track-qo) for details on the `journey` and `jcount` fields included in tracking Notes.

### `minutes`

*integer*

The configured heartbeat interval in minutes. Only returned when the heartbeat interval is not a whole number of hours; when the interval is a whole number of hours, it is returned in `hours` instead. `hours` and `minutes` are never returned together.

### `seconds`

*integer*

If tracking is enabled and no heartbeat interval is configured, the periodic tracking interval set via `card.location.mode`.

### `start`

*boolean*

`true` if tracking is enabled.

### `stop`

*boolean*

`true` if tracking is disabled.

Example Response

```json
{
  "start": true,
  "heartbeat": true,
  "file": "locations.qo",
  "hours": 2
}
```

## card.monitor

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

When a Notecard is in [monitor mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-monitor-mode), this API is used to configure the general-purpose `AUX1`-`AUX4` pins to test and monitor Notecard activity.

> **Note:**
>
> Utilizing these pins requires a physical connection to each pin, separate from a connection to the Notecard's M.2 connector.

Arguments

### `count`

*integer (optional)*

The number of pulses to send to the overridden AUX pin LED. Set this value to `0` to return the LED to its default behavior.

### `mode`

*string (optional)*

Can be set to one of `green`, `red` or `yellow` to temporarily override the behavior of an AUX pin LED.

See [Using Monitor Mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-monitor-mode) for additional details.

`"green"`: Temporarily override the behavior of the green AUX pin LED.

`"red"`: Temporarily override the behavior of the red AUX pin LED.

`"yellow"`: Temporarily override the behavior of the yellow AUX pin LED.

### `usb`

*boolean (optional, default `false`)*

Set to `true` to configure LED behavior so that it is only active when the Notecard is connected to USB power.

**Example**

**JSON**

```json
{
  "req": "card.monitor",
  "mode": "green",
  "count": 5
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.monitor");
JAddStringToObject(req, "mode", "green");
JAddNumberToObject(req, "count", 5);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.monitor"}
req["mode"] = "green"
req["count"] = 5
rsp = card.Transaction(req)
```

Configure the green LED to pulse 5 times.

**Response Members**

None: an empty object `{}` means success.

## card.motion

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Returns information about the Notecard accelerometer's motion and orientation. Motion tracking must be enabled first with `card.motion.mode`. Otherwise, this request will return `{}`.

Arguments

### `minutes`

*integer (optional)*

Amount of time to sample for buckets of accelerometer-measured movement. For instance, `5` will sample motion events for the previous five minutes and return a `movements` string with motion counts in each bucket.

**Example**

**JSON**

```json
{
  "req": "card.motion",
  "minutes": 2
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion");
JAddNumberToObject(req, "minutes", 2);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion"}
req["minutes"] = 2
rsp = card.Transaction(req)
```

Request motion information with 2-minute sampling buckets.

**Response Members**

### `alert`

*boolean*

`true` if the Notecard's accelerometer detected a free-fall since the last request to `card.motion`.

### `count`

*integer*

The number of accelerometer motion events since the `card.motion` request was last made.

### `mode`

*string*

Returns the current motion status of the Notecard (e.g. `"stopped"` or `"moving"`). Learn how to configure this feature [in this guide](https://dev.blues.io/guides-and-tutorials/notecard-guides/asset-tracking-with-gps.md#wake-host-or-send-note-on-motion-status-change).

### `motion`

*integer*

Time of the last accelerometer motion event.

### `movements`

*string*

If the `minutes` argument is provided, a string of base-36 characters, where each character represents the number of accelerometer movements in each bucket during the sample duration. Each character will be a digit 0-9, A-Z to indicate a count of 10-35, or `*` to indicate a count greater than 35.

### `seconds`

*integer*

If the `minutes` argument is provided, the duration of each bucket of sample accelerometer movements.

### `status`

*string*

Comma-separated list of accelerometer orientation events that ocurred since the last request to `card.motion`. One or more of the following: `"face-up"`, `"face-down"`, `"portrait-up"`, `"portrait-down"`, `"landscape-right"`, `"landscape-left"`, `"angled"`.

Example Response

```json
{
  "count": 17,
  "status": "face-up",
  "alert": true,
  "motion": 1599741952,
  "seconds": 5,
  "movements": "520000000000000000000A"
}
```

## card.motion.mode

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Configures accelerometer motion monitoring parameters used when providing results to `card.motion`.

Arguments

### `motion`

*integer (optional)*

If `motion` is > 0, a [card.motion](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-motion) request will return a `"mode"` of `"moving"` or `"stopped"`. The `motion` value is the threshold for how many motion events in a single bucket will trigger a motion status change.

Learn how to configure this feature [in this guide](https://dev.blues.io/guides-and-tutorials/notecard-guides/asset-tracking-with-gps.md#wake-host-or-send-note-on-motion-status-change).

### `seconds`

*integer (optional)*

Period for each bucket of movements to be accumulated when `minutes` is used with `card.motion`.

### `sensitivity`

*integer (optional, default `-1`)*

Used to set the accelerometer sample rate. The default sample rate of 1.6Hz could miss short-duration accelerations (e.g. bumps and jolts), and free fall detection may not work reliably with short falls. The penalty for increasing the sample rate to 25Hz is increased current consumption by \~1.5uA relative to the default `-1` setting.

`-1`: 1.6Hz, +/-2G range, 1 milli-G sensitivity

`0`: Not specified. Do not modify the current sample rate.

`1`: 25Hz, +/- 16G range, 7.8 milli-G sensitivity

`2`: 25Hz, +/- 8G range, 3.9 milli-G sensitivity

`3`: 25Hz, +/- 4G range, 1.95 milli-G sensitivity

`4`: 25Hz, +/- 2G range, 1 milli-G sensitivity

`5`: 25Hz, +/- 2G range, 0.25 milli-G sensitivity

### `start`

*boolean (optional)*

`true` to enable the Notecard accelerometer and start motion tracking.

### `stop`

*boolean (optional)*

`true` to disable the Notecard accelerometer and stop motion tracking.

**Start Motion Tracking**

**JSON**

```json
{
  "req": "card.motion.mode",
  "start": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.mode");
JAddBoolToObject(req, "start", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.mode"}
req["start"] = True
rsp = card.Transaction(req)
```

Enable motion tracking with default settings.

**Configure Motion Tracking with Parameters**

**JSON**

```json
{
  "req": "card.motion.mode",
  "start": true,
  "seconds": 10,
  "sensitivity": 2
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.mode");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "seconds", 10);
JAddNumberToObject(req, "sensitivity", 2);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.mode"}
req["start"] = True
req["seconds"] = 10
req["sensitivity"] = 2
rsp = card.Transaction(req)
```

Enable motion tracking with custom sensitivity and bucket duration.

**Stop Motion Tracking**

**JSON**

```json
{
  "req": "card.motion.mode",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.mode");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.mode"}
req["stop"] = True
rsp = card.Transaction(req)
```

Disable motion tracking.

**Configure Motion Status Change**

**JSON**

```json
{
  "req": "card.motion.mode",
  "motion": 5,
  "seconds": 60
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.mode");
JAddNumberToObject(req, "motion", 5);
JAddNumberToObject(req, "seconds", 60);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.mode"}
req["motion"] = 5
req["seconds"] = 60
rsp = card.Transaction(req)
```

Set motion threshold for status change detection.

**Response Members**

### `motion`

*integer*

The motion threshold (number of motion events in a single bucket) above which the Notecard state is considered `moving` and below which the state is considered `stopped`.

### `seconds`

*integer*

The period (in seconds) of each bucket of movements being accumulated when `minutes` is used with `card.motion`.

### `start`

*boolean*

`true` if the Notecard accelerometer is enabled and motion tracking is active.

### `stop`

*boolean*

`true` if the Notecard accelerometer is disabled and motion tracking is stopped.

Example Response

```json
{
  "start": true,
  "seconds": 5
}
```

Response showing motion tracking is enabled with the active bucket period.

```json
{
  "stop": true
}
```

Response showing motion tracking has been disabled.

## card.motion.sync

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Configures automatic sync triggered by Notecard movement.

Arguments

### `count`

*integer (optional)*

The number of most recent motion buckets to examine.

### `minutes`

*integer (optional)*

The maximum frequency at which sync will be triggered. Even if a `threshold` is set and exceeded, there will only be a single sync for this amount of time.

### `start`

*boolean (optional)*

`true` to start motion-triggered syncing.

### `stop`

*boolean (optional)*

`true` to stop motion-triggered syncing.

### `threshold`

*integer (optional)*

The number of buckets that must indicate motion in order to trigger a sync. If set to `0`, the Notecard will only perform a sync when its orientation changes.

**Start Motion-Triggered Sync**

**JSON**

```json
{
  "req": "card.motion.sync",
  "start": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "start", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.sync"}
req["start"] = True
rsp = card.Transaction(req)
```

Enable motion-triggered syncing with default settings.

**Configure Motion Sync Parameters**

**JSON**

```json
{
  "req": "card.motion.sync",
  "start": true,
  "minutes": 20,
  "count": 20,
  "threshold": 5
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "minutes", 20);
JAddNumberToObject(req, "count", 20);
JAddNumberToObject(req, "threshold", 5);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.sync"}
req["start"] = True
req["minutes"] = 20
req["count"] = 20
req["threshold"] = 5
rsp = card.Transaction(req)
```

Set motion sync with specific timing and threshold parameters.

**Stop Motion-Triggered Sync**

**JSON**

```json
{
  "req": "card.motion.sync",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.sync"}
req["stop"] = True
rsp = card.Transaction(req)
```

Disable motion-triggered syncing.

**Orientation Change Only**

**JSON**

```json
{
  "req": "card.motion.sync",
  "start": true,
  "threshold": 0,
  "minutes": 10
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.sync");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "threshold", 0);
JAddNumberToObject(req, "minutes", 10);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.sync"}
req["start"] = True
req["threshold"] = 0
req["minutes"] = 10
rsp = card.Transaction(req)
```

Configure sync to trigger only on orientation changes.

**Response Members**

None: an empty object `{}` means success.

## card.motion.track

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Configures automatic capture of Notecard accelerometer motion in a Notefile.

Arguments

### `count`

*integer (optional)*

The number of most recent motion buckets to examine.

### `file`

*string (optional, default `_motion.qo`)*

The Notefile to use for motion capture Notes. See the [`_motion.qo` Notefile's documentation](https://dev.blues.io/api-reference/system-notefiles.md#motion-qo) for details on the format of the data captured.

### `minutes`

*integer (optional)*

The maximum period to capture Notes in the Notefile.

### `now`

*boolean (optional)*

Set to `true` to trigger the immediate creation of a `_motion.qo` event if the orientation of the Notecard changes (overriding the `minutes` setting).

### `start`

*boolean (optional)*

`true` to start motion capture.

### `stop`

*boolean (optional)*

`true` to stop motion capture.

### `threshold`

*integer (optional)*

The number of buckets that must indicate motion in order to capture.

**Start Motion Tracking**

**JSON**

```json
{
  "req": "card.motion.track",
  "start": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "start", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.track"}
req["start"] = True
rsp = card.Transaction(req)
```

Enable motion tracking with default settings.

**Configure Motion Tracking with Custom File**

**JSON**

```json
{
  "req": "card.motion.track",
  "start": true,
  "minutes": 20,
  "count": 20,
  "threshold": 5,
  "file": "movements.qo"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "start", true);
JAddNumberToObject(req, "minutes", 20);
JAddNumberToObject(req, "count", 20);
JAddNumberToObject(req, "threshold", 5);
JAddStringToObject(req, "file", "movements.qo");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.track"}
req["start"] = True
req["minutes"] = 20
req["count"] = 20
req["threshold"] = 5
req["file"] = "movements.qo"
rsp = card.Transaction(req)
```

Set motion tracking with custom parameters and Notefile.

**Stop Motion Tracking**

**JSON**

```json
{
  "req": "card.motion.track",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.track"}
req["stop"] = True
rsp = card.Transaction(req)
```

Disable motion tracking.

**Enable Immediate Orientation Changes**

**JSON**

```json
{
  "req": "card.motion.track",
  "start": true,
  "now": true,
  "minutes": 15
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.motion.track");
JAddBoolToObject(req, "start", true);
JAddBoolToObject(req, "now", true);
JAddNumberToObject(req, "minutes", 15);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.motion.track"}
req["start"] = True
req["now"] = True
req["minutes"] = 15
rsp = card.Transaction(req)
```

Configure motion tracking with immediate orientation change capture.

**Response Members**

None: an empty object `{}` means success.

## card.power

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

The `card.power` API is used to configure a connected Mojo device or to manually request power consumption readings in firmware.

Arguments

### `hours`

*integer (optional)*

How often, in hours, Notecard should log power consumption in a `_log.qo` Note. Provided as a convenience alternative to `minutes`. If both `hours` and `minutes` are provided, the resulting cadence is the sum of the two.

### `minutes`

*integer (optional, default `720`)*

How often, in minutes, Notecard should log power consumption in a `_log.qo` Note. The default value is `720` (12 hours). May be combined with `hours`, in which case the two values are added together.

### `reset`

*boolean (optional)*

Set to `true` to reset the power consumption counters back to 0.

**Get Latest Power Consumption Reading**

**JSON**

```json
{
  "req": "card.power"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.power");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.power"}
rsp = card.Transaction(req)
```

Request current power consumption data.

**Set Cadence of Readings**

**JSON**

```json
{
  "req": "card.power",
  "minutes": 60
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.power");
JAddNumberToObject(req, "minutes", 60);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.power"}
req["minutes"] = 60
rsp = card.Transaction(req)
```

Configure how often power consumption is logged.

**Reset Counters**

**JSON**

```json
{
  "cmd": "card.power",
  "reset": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.power");
JAddBoolToObject(req, "reset", true);

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.power"}
req["reset"] = True
card.Transaction(req)
```

Reset power consumption counters back to 0.

**Response Members**

### `milliamp_hours`

*number*

The cumulative number of milliamp hours (mAh) consumed. You can reset this number with this request's `reset` argument.

### `temperature`

*number*

The temperature in degrees centigrade, as measured by the coulomb counter on the connected Mojo.

### `voltage`

*number*

The voltage, in volts, measured by Mojo on the load side of its current-sense resistor.

Example Response

```json
{
  "temperature": 26.028314208984398,
  "voltage": 4.200970458984375,
  "milliamp_hours": 3.9566722000000007
}
```

## card.random

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Obtain a single random 32 bit unsigned integer modulo or `count` number of bytes of random data from the Notecard hardware random number generator.

Arguments

### `count`

*integer (optional)*

If the `mode` argument is excluded from the request, the Notecard uses this as an upper-limit parameter and returns a random unsigned 32 bit integer between zero and the value provided.

If `"mode":"payload"` is used, this argument sets the number of random bytes of data to return in a base64-encoded buffer from the Notecard.

### `mode`

*string (optional)*

Accepts a single value `"payload"` and, if specified, uses the `count` value to determine the number of bytes of random data to generate and return to the host.

**Get a Random Number**

**JSON**

```json
{
  "req": "card.random",
  "count": 100
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.random");
JAddNumberToObject(req, "count", 100);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.random"}
req["count"] = 100
rsp = card.Transaction(req)
```

Request a random integer between 0 and count-1.

**Get a Buffer of Random Numbers**

**JSON**

```json
{
  "req": "card.random",
  "mode": "payload",
  "count": 100
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.random");
JAddStringToObject(req, "mode", "payload");
JAddNumberToObject(req, "count", 100);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.random"}
req["mode"] = "payload"
req["count"] = 100
rsp = card.Transaction(req)
```

Request random bytes returned as base64-encoded payload.

**Response Members**

### `count`

*integer*

A random number generated by the Notecard's onboard hardware random number generator.

### `payload`

*base64 string*

If using `"mode":"payload"`, a base64-encoded string with random values, the length of which is specified by the `count` argument.

Example Response

```json
{
  "count": 86
}
```

Example response with a random integer.

```json
{
  "payload": "SGVsbG8gV29ybGQ="
}
```

Example response with base64-encoded random data.

## card.restart

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Performs a firmware restart of the Notecard.

> **Warning:**
>
> Calls to `card.restart` are not supported for use in production applications as they can cause increased cellular data and event credit usage.

Arguments

None

**Example**

**JSON**

```json
{
  "cmd": "card.restart"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.restart");

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.restart"}
card.Transaction(req)
```

Perform a firmware restart of the Notecard.

**Response Members**

None: an empty object `{}` means success.

## card.restore

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Performs a factory reset on the Notecard and restarts.

*Sending this request without either of the optional arguments below will only reset the Notecard's file system, thus forcing a re-sync of all Notefiles from Notehub.*

On Notecard LoRa there is no option to retain configuration settings, and providing `"delete": true` is required. The Notecard LoRa retains LoRaWAN configuration after factory resets.

Arguments

### `connected`

*boolean (optional)*

Set to `true` to reset the Notecard on Notehub. This will delete and deprovision the Notecard from Notehub the next time the Notecard connects. This also removes any Notefile templates used by this device.

Conversely, if `connected` is `false` (or omitted), the Notecard's settings and data will be restored from Notehub the next time the Notecard connects to the previously used Notehub project.

### `delete`

*boolean (optional)*

Set to `true` to reset most Notecard configuration settings. Note that this does not reset stored WiFi credentials or the [alternate I2C address](https://dev.blues.io/notecard/notecard-walkthrough/advanced-notecard-configuration.md#change-the-notecard-i2c-address) (if previously set) so the Notecard can still contact the network after a reset.

*The Notecard will be unable to sync with Notehub until the `ProductUID` is set again.*

**Complete Factory Reset**

**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
rsp = card.Transaction(req)
```

Reset Notecard configuration and deprovision from Notehub.

**File System Reset Only**

**JSON**

```json
{
  "req": "card.restore"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.restore");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.restore"}
rsp = card.Transaction(req)
```

Reset only the file system, forcing re-sync from Notehub.

**Response Members**

None: an empty object `{}` means success.

## card.sleep

Supported on

(WiFi)

Allows the ESP32-based Notecard WiFi v2 to fall back to a low current draw when idle (this behavior differs from the STM32-based Notecards that have a `STOP` mode where UART and I2C may still operate). Note that this power state is not available if the Notecard is plugged in via USB.

Read more in the guide on using [Deep Sleep Mode on Notecard WiFi v2](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#deep-sleep-mode-on-notecard-wifi-v2).

> **Note:**
>
> This API is only valid for **[Notecard WiFi v2](https://dev.blues.io/datasheets/notecard-datasheet/note-esp.md)**. Additionally, `card.sleep` will not activate while USB-connected.

Arguments

### `mode`

*string (optional)*

Set to `"accel"` to wake from deep sleep on any movement detected by the onboard accelerometer. Set to `"-accel"` to reset to the default setting.

`"accel"`: Wake from deep sleep on any movement detected by the onboard accelerometer.

`"-accel"`: Reset to the default setting.

### `off`

*boolean (optional)*

Set to `true` to disable the sleep mode on Notecard.

### `on`

*boolean (optional)*

Set to `true` to enable Notecard to sleep once it is idle for >= 30 seconds.

### `seconds`

*integer (optional)*

The number of seconds the Notecard will wait before entering sleep mode (minimum value is 30).

**Enable Sleep Mode**

**JSON**

```json
{
  "req": "card.sleep",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.sleep");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.sleep"}
req["on"] = True
rsp = card.Transaction(req)
```

Enable sleep mode with default settings.

**Configure Sleep with Accelerometer Wake**

**JSON**

```json
{
  "req": "card.sleep",
  "on": true,
  "mode": "accel"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.sleep");
JAddBoolToObject(req, "on", true);
JAddStringToObject(req, "mode", "accel");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.sleep"}
req["on"] = True
req["mode"] = "accel"
rsp = card.Transaction(req)
```

Enable sleep mode with accelerometer wake functionality.

**Custom Sleep Timer**

**JSON**

```json
{
  "req": "card.sleep",
  "seconds": 60
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.sleep");
JAddNumberToObject(req, "seconds", 60);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.sleep"}
req["seconds"] = 60
rsp = card.Transaction(req)
```

Set custom wait time before entering sleep mode.

**Disable Sleep Mode**

**JSON**

```json
{
  "cmd": "card.sleep",
  "off": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.sleep");
JAddBoolToObject(req, "off", true);

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.sleep"}
req["off"] = True
card.Transaction(req)
```

Disable sleep mode functionality.

**Response Members**

### `mode`

*string*

Returns `"accel"` if the Notecard is configured to wake from deep sleep on any movement detected by the onboard accelerometer.

### `off`

*boolean*

`true` if sleep mode is disabled.

### `on`

*boolean*

`true` if sleep mode is enabled.

### `seconds`

*integer*

The number of seconds the Notecard will wait before entering sleep mode (only included if default settings are overridden).

Example Response

```json
{
  "seconds": 10,
  "mode": "accel",
  "on": true
}
```

## card.status

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Returns general information about the Notecard's operating status.

Arguments

None

**Example**

**JSON**

```json
{
  "req": "card.status"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.status");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.status"}
rsp = card.Transaction(req)
```

Request general information about the Notecard's operating status.

**Response Members**

### `cell`

*boolean*

`true` if the modem is currently powered on.

### `connected`

*boolean*

`true` if connected to Notehub.

### `gps`

*boolean*

`true` if Notecard's GPS module is currently powered on.

### `inbound`

*integer*

The effective inbound synchronization period being used by the device. See [Configuring Synchronization Modes](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#configuring-synchronization-modes) for details on how Notecard synchronization modes work.

### `outbound`

*integer*

The effective outbound synchronization period being used by the device. See [Configuring Synchronization Modes](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#configuring-synchronization-modes) for details on how Notecard synchronization modes work.

### `status`

*string*

General status information.

### `storage`

*integer*

Indicates the percentage of total Notecard storage in use. Note that users can utilize approximately 80% of this total capacity.

### `sync`

*boolean*

`true` if the Notecard has ever connected to Notehub.

### `time`

*UNIX Epoch time*

The UNIX Epoch Time of approximately when the Notecard was first powered up.

### `usb`

*boolean*

`true` if the Notecard is being powered by USB.

### `wifi`

*boolean*

`true` if the Notecard's WiFi radio is currently powered on.

Example Response

```json
{
  "status": "{normal}",
  "usb": true,
  "storage": 8,
  "time": 1599684765,
  "connected": true,
  "cell": true,
  "gps": true,
  "sync": true,
  "inbound": 60,
  "outbound": 360
}
```

## card.temp

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Get the current temperature from the Notecard's onboard calibrated temperature sensor.

When using a Notecard Cellular or Notecard Cell+WiFi, if you connect a BME280 sensor on the I2C bus the Notecard will add `temperature`, `pressure`, and `humidity` fields to the response. If you connect an ENS210 sensor on the I2C bus the Notecard will add `temperature` and `pressure` fields to the response.

Arguments

### `minutes`

*integer (optional)*

If specified, creates a templated `_temp.qo` file that gathers Notecard temperature value at the specified minutes interval. *When using [card.aux track mode](https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md#using-aux-track-mode), the sensor temperature, pressure, and humidity is also included with each Note.*

### `status`

*string (optional)*

Overrides `minutes` with a voltage-variable value. For example: `"usb:15;high:30;normal:60;720"`. See [Voltage-Variable Sync Behavior](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md#voltage-variable-sync-behavior) for more information on configuring these values.

### `stop`

*boolean (optional)*

If set to `true`, the Notecard will stop logging the temperature value at the interval specified with the `minutes` parameter (see above).

### `sync`

*boolean (optional)*

If set to `true`, the Notecard will immediately sync any pending `_temp.qo` Notes created with the `minutes` parameter (see above).

**Get Card Temperature**

**JSON**

```json
{
  "req": "card.temp"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.temp");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.temp"}
rsp = card.Transaction(req)
```

Get current temperature from Notecard's onboard sensor.

**Configure Temperature Tracking**

**JSON**

```json
{
  "req": "card.temp",
  "minutes": 30
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.temp");
JAddNumberToObject(req, "minutes", 30);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.temp"}
req["minutes"] = 30
rsp = card.Transaction(req)
```

Set up automatic temperature logging at 30-minute intervals.

**Stop Temperature Tracking**

**JSON**

```json
{
  "cmd": "card.temp",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.temp");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.temp"}
req["stop"] = True
card.Transaction(req)
```

Stop automatic temperature logging.

**Sync Temperature Notes**

**JSON**

```json
{
  "cmd": "card.temp",
  "sync": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.temp");
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.temp"}
req["sync"] = True
card.Transaction(req)
```

Immediately sync pending temperature notes.

**Response Members**

### `calibration`

*number*

The calibration differential, in degrees centigrade, applied to the Notecard's onboard temperature sensor. This per-device offset is added to the raw sensor reading to produce `value`.

### `humidity`

*number*

If the Notecard finds a BME280 sensor on the I2C bus, this field will be set to the humidity percentage value from the connected sensor.

### `pressure`

*number*

If the Notecard finds a BME280 or ENS210 sensor on the I2C bus, this field will be set to the atmospheric pressure value from the connected sensor in Pascals.

### `temperature`

*number*

If the Notecard finds a BME280 or ENS210 sensor on the I2C bus, this field will be set to the temperature value from the connected sensor in degrees centigrade.

### `usb`

*boolean*

`true` if the Notecard is connected to USB power.

### `value`

*number*

The current temperature from the Notecard's onboard sensor in degrees centigrade, including the calibration offset.

### `voltage`

*number*

The current voltage.

Example Response

```json
{
  "value": 27.625,
  "calibration": -3.0
}
```

Example response with onboard sensor temperature and calibration.

```json
{
  "value": 25.5,
  "calibration": -2.5,
  "temperature": 24.8,
  "humidity": 45.2,
  "pressure": 101325,
  "usb": true,
  "voltage": 4.95
}
```

Example response with BME280 sensor data and power information.

## card.time

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Retrieves current date and time information in UTC. Upon power-up, the Notecard must complete a sync to Notehub in order to obtain time and location data. Before the time is obtained, this request will return `{"zone":"UTC,Unknown"}`. The Notecard's stored timezone is only updated when a new Notehub session begins.

> **Note:**
>
> Different models of Notecard exhibit varying levels of clock drift depending on their hardware design and operating temperature. If you would like to calibrate your Notecard for your own known operating conditions, see the [Notecard Real-Time Clock application note](https://dev.blues.io/datasheets/application-notes/notecard-real-time-clock.md#calibrating-the-rtc), which demonstrates how to use the Notecard CLI to perform such calibration.

Arguments

None

**Example**

**JSON**

```json
{
  "req": "card.time"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.time");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.time"}
rsp = card.Transaction(req)
```

Retrieve current date and time information in UTC with location data if available.

**Response Members**

### `area`

*string*

The geographic area of the Notecard, if the cell tower is recognized.

### `country`

*string*

The country where the Notecard is located, if the cell tower is recognized.

### `lat`

*number*

Latitude of the Notecard, if the cell tower is recognized.

### `lon`

*number*

Longitude of the Notecard, if the cell tower is recognized.

### `minutes`

*integer*

Number of minutes East of GMT, if the cell tower is recognized.

### `time`

*UNIX Epoch time*

The current time in UTC. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.

### `zone`

*string*

The time zone of the Notecard, if the cell tower is recognized.

Example Response

```json
{
  "time": 1599769214,
  "area": "Beverly, MA",
  "zone": "CDT,America/New York",
  "minutes": -300,
  "lat": 42.5776,
  "lon": -70.87134,
  "country": "US"
}
```

Example response with full time and location information.

```json
{
  "zone": "UTC,Unknown"
}
```

Example response when time is available but location data hasn't been obtained yet.

## card.trace

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Enable and disable [trace mode](https://dev.blues.io/support/using-notecard-trace-mode.md) on a Notecard for debugging.

Arguments

### `mode`

*string (optional)*

`"on"`: Enable trace mode on the Notecard for debugging.

`"off"`: Disable trace mode on the Notecard.

**Enable Trace Mode**

**JSON**

```json
{
  "req": "card.trace",
  "mode": "on"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.trace");
JAddStringToObject(req, "mode", "on");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.trace"}
req["mode"] = "on"
rsp = card.Transaction(req)
```

Enable trace mode for debugging the Notecard.

**Disable Trace Mode**

**JSON**

```json
{
  "cmd": "card.trace",
  "mode": "off"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.trace");
JAddStringToObject(req, "mode", "off");

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.trace"}
req["mode"] = "off"
card.Transaction(req)
```

Disable trace mode on the Notecard.

**Response Members**

None: an empty object `{}` means success.

## card.transport

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Specifies the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard.

Arguments

### `allow`

*boolean (optional, default `false`)*

Set to `true` to allow adding Notes to templated Notefiles that have no `port` while connected over a non-terrestrial network.

See [Define NTN vs non-NTN Templates](https://dev.blues.io/starnote/satellite-best-practices.md#define-ntn-vs-non-ntn-templates).

### `method`

*string (optional)*

The connectivity method to enable on the Notecard.

`"-"` (Cell, Cell+WiFi, Skylo, WiFi)

Resets the transport mode to the device default.

`"cell"` (Cell, Cell+WiFi, Skylo)

Enables **cellular only** on the device.

`"cell-ntn"` (Cell, Cell+WiFi, Skylo)

Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established.

`"dual-wifi-cell"` (Cell+WiFi, Skylo, Deprecated)

Deprecated form of `"wifi-cell"`

`"ntn"` (Cell, Cell+WiFi, Skylo, WiFi)

Enables **NTN (Non-Terrestrial Network)** mode on the device for use with Starnote.

`"wifi"` (Cell+WiFi, Skylo, WiFi)

Enables **WiFi only** on the device.

`"wifi-cell"` (Cell+WiFi, Skylo)

Prioritizes WiFi connectivity while falling back to cellular if a WiFi connection cannot be established. This is the default behavior on Notecard Cell+WiFi.

`"wifi-cell-ntn"` (Cell+WiFi, Skylo)

Prioritizes WiFi connectivity while falling back to cellular, and lastly to NTN.

`"wifi-ntn"` (Cell+WiFi, Skylo, WiFi)

Prioritizes WiFi connectivity while falling back to NTN if a WiFi connection cannot be established.

### `seconds`

*integer (optional, default `3600`)*

The amount of time (in seconds) a Notecard will spend on any fallback transport before retrying the first transport specified in the `method`. The default is `3600` or 60 minutes.

### `set`

*boolean (optional, default `false`)*

Set to `true` to apply the `allow` argument without also changing the transport `method`.

### `umin`

*boolean (optional, default `false`)*

Set to `true` to force a longer network transport timeout when using Wideband Notecards.

**Set WiFi-Cell Priority**

**JSON**

```json
{
  "req": "card.transport",
  "method": "wifi-cell"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "wifi-cell");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.transport"}
req["method"] = "wifi-cell"
rsp = card.Transaction(req)
```

Configure Notecard Cell+WiFi to prioritize WiFi while falling back to cellular.

**Enable WiFi Only Mode**

**JSON**

```json
{
  "req": "card.transport",
  "method": "wifi"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "wifi");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.transport"}
req["method"] = "wifi"
rsp = card.Transaction(req)
```

Configure device to use WiFi connectivity only.

**Enable Cellular Only Mode**

**JSON**

```json
{
  "req": "card.transport",
  "method": "cell"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "cell");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.transport"}
req["method"] = "cell"
rsp = card.Transaction(req)
```

Configure device to use cellular connectivity only.

**Reset to Default Transport**

**JSON**

```json
{
  "cmd": "card.transport",
  "method": "-"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "-");

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "card.transport"}
req["method"] = "-"
card.Transaction(req)
```

Reset the transport mode to device default settings.

**Configure NTN Mode**

**JSON**

```json
{
  "req": "card.transport",
  "method": "ntn"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "ntn");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.transport"}
req["method"] = "ntn"
rsp = card.Transaction(req)
```

Enable NTN (Non-Terrestrial Network) mode for Starnote connectivity.

**WiFi-Cell-NTN Priority**

**JSON**

```json
{
  "req": "card.transport",
  "method": "wifi-cell-ntn",
  "seconds": 1800
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.transport");
JAddStringToObject(req, "method", "wifi-cell-ntn");
JAddNumberToObject(req, "seconds", 1800);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.transport"}
req["method"] = "wifi-cell-ntn"
req["seconds"] = 1800
rsp = card.Transaction(req)
```

Configure triple fallback: WiFi → cellular → NTN with custom timeout.

**Response Members**

### `allow`

*boolean*

When `true`, the Notecard is configured to allow adding Notes to non-compact Notefiles while connected over a non-terrestrial network. See [Define NTN vs non-NTN Templates](https://dev.blues.io/starnote/satellite-best-practices.md#define-ntn-vs-non-ntn-templates).

### `method`

*string*

The connectivity method currently enabled on the device.

`"-"` (Cell, Cell+WiFi, WiFi)

The transport mode is set to the device default.

`"cell"` (Cell, Cell+WiFi)

Cellular only is enabled on the device.

`"cell-ntn"` (Cell, Cell+WiFi)

Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established.

`"dual-wifi-cell"` (Cell+WiFi, Deprecated)

Deprecated form of `"wifi-cell"`.

`"ntn"` (Cell, Cell+WiFi, WiFi)

NTN (Non-Terrestrial Network) mode is enabled on the device for use with Starnote.

`"wifi"` (Cell+WiFi, WiFi)

WiFi only is enabled on the device.

`"wifi-cell"` (Cell+WiFi)

Prioritizes WiFi connectivity while falling back to cellular if a WiFi connection cannot be established. This is the default behavior on Notecard Cell+WiFi.

`"wifi-cell-ntn"` (Cell+WiFi)

Prioritizes WiFi connectivity while falling back to cellular, and lastly to NTN.

`"wifi-ntn"` (Cell+WiFi, WiFi)

Prioritizes WiFi connectivity while falling back to NTN if a WiFi connection cannot be established.

### `seconds`

*integer*

The amount of time (in seconds) the Notecard will spend on any fallback transport before retrying the first transport specified in the `method`. The default is `3600` (60 minutes).

### `umin`

*boolean*

When `true`, the Notecard is configured to force a longer network transport timeout when using Wideband Notecards.

Example Response

```json
{
  "method": "wifi-cell"
}
```

Response showing WiFi-cellular priority transport mode is active.

```json
{
  "method": "cell"
}
```

Response showing cellular-only transport mode is active.

```json
{
  "method": "ntn"
}
```

Response showing NTN (Non-Terrestrial Network) transport mode is active.

## card.triangulate

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Enables or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or WiFi access points with each new Notehub session.

> **Note:**
>
> See [Using Cell Tower & WiFi Triangulation](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#using-cell-tower-and-wifi-triangulation) for more information.

Arguments

### `minutes`

*integer (optional, default `0`)*

Minimum delay, in minutes, between triangulation attempts. Use `0` for no time-based suppression.

### `mode`

*string (optional)*

The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order. See [Using Cell Tower & WiFi Triangulation](https://dev.blues.io/notecard/notecard-walkthrough/time-and-location-requests.md#using-cell-tower-and-wifi-triangulation) for more information.

`"cell"`: Enables cell tower scanning to determine the position of the Device.

`"wifi"`: Enables the use of nearby WiFi access points to determine the position of the Device. To leverage this feature, the host will need to provide access point information to the Notecard via the `text` argument in subsequent requests.

`"-"`: Clear the currently-set triangulation mode.

### `on`

*boolean (optional, default `false`)*

`true` to instruct the Notecard to triangulate even if the module has not moved. Only takes effect when `set` is `true`.

### `set`

*boolean (optional, default `false`)*

`true` to instruct the module to use the state of the `on` and `usb` arguments.

### `text`

*string (optional)*

When using WiFi triangulation, a newline-terminated list of WiFi access points obtained by the external module. Format should follow the ESP32's [AT+CWLAP command output](https://docs.espressif.com/projects/esp-at/en/latest/AT_Command_Set/Wi-Fi_AT_Commands.html#cmd-lap).

### `time`

*UNIX Epoch time (optional)*

When passed with `text`, records the time that the WiFi access point scan was performed. *If not provided, Notecard time is used.*

### `usb`

*boolean (optional, default `false`)*

`true` to use perform triangulation only when the Notecard is connected to USB power. Only takes effect when `set` is `true`.

**Single Mode**

**JSON**

```json
{
  "req": "card.triangulate",
  "mode": "cell",
  "on": true,
  "set": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "cell");
JAddBoolToObject(req, "on", true);
JAddBoolToObject(req, "set", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.triangulate"}
req["mode"] = "cell"
req["on"] = True
req["set"] = True
rsp = card.Transaction(req)
```

Enable triangulation using cell towers only.

**Dual Mode**

**JSON**

```json
{
  "req": "card.triangulate",
  "mode": "wifi,cell",
  "on": true,
  "usb": true,
  "set": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "wifi,cell");
JAddBoolToObject(req, "on", true);
JAddBoolToObject(req, "usb", true);
JAddBoolToObject(req, "set", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.triangulate"}
req["mode"] = "wifi,cell"
req["on"] = True
req["usb"] = True
req["set"] = True
rsp = card.Transaction(req)
```

Enable triangulation using both WiFi and cell towers when connected to USB power.

**Send WiFi AP Data**

**JSON**

```json
{
  "req": "card.triangulate",
  "text": "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "text", "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)
+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)
+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)
+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)
+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)
+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)
+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)
+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)
+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)

");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.triangulate"}
req["text"] = "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
rsp = card.Transaction(req)
```

Send a newline-terminated list of WiFi access points to the Notecard for triangulation.

**Disable Triangulation**

**JSON**

```json
{
  "req": "card.triangulate",
  "mode": "-"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.triangulate");
JAddStringToObject(req, "mode", "-");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.triangulate"}
req["mode"] = "-"
rsp = card.Transaction(req)
```

Disable triangulation mode.

**Response Members**

### `length`

*integer*

The length of the `text` buffer provided in the current or a previous request.

### `mode`

*string*

A comma-separated list indicating the active triangulation modes.

### `motion`

*integer*

Time of last detected Notecard movement.

### `on`

*boolean*

`true` if triangulation scans will be performed even if the device has not moved.

### `time`

*UNIX Epoch time*

Time of last triangulation scan.

### `usb`

*boolean*

`true` if triangulation scans will be performed only when the device is USB-powered.

Example Response

```json
{
  "usb": true,
  "mode": "wifi,cell",
  "length": 443,
  "on": true,
  "time": 1606755042,
  "motion": 1606757487
}
```

Response showing full triangulation configuration and status information.

```json
{
  "mode": "cell",
  "on": false
}
```

Response showing basic triangulation mode configuration.

## card.usage.get

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Returns the Notecard's network usage statistics for cellular and WiFi transmissions.

> **Note:**
>
> Usage data is updated by the Notecard at the end of each session. When operating in `continuous` mode, usage data is updated only after the interval specified by the [hub.set/duration argument](https://dev.blues.io/api-reference/notecard-api/hub-requests.md#hub-set) elapses.
>
> Please note that the `card.usage.get` API only applies to cellular and WiFi data, not LoRa or satellite (NTN).

Arguments

### `mode`

*string (optional, default `total`)*

The time period to use for statistics. Must be one of:

`"total"`: All stats since the Notecard was activated.

`"1hour"`: Statistics for the last hour period.

`"1day"`: Statistics for the last day period.

`"30day"`: Statistics for the last 30 days period.

### `offset`

*integer (optional)*

The number of time periods to look backwards, based on the specified `mode`.

To accurately determine the start of the calculated time period when using `offset`, use the `time` value of the response. Likewise, to calculate the end of the time period, add the `seconds` value to the `time` value.

**Get Total Usage**

**JSON**

```json
{
  "req": "card.usage.get"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.get");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.get"}
rsp = card.Transaction(req)
```

Retrieve all cellular and WiFi usage statistics since Notecard activation.

**Get Daily Usage with Offset**

**JSON**

```json
{
  "req": "card.usage.get",
  "mode": "1day",
  "offset": 5
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.get");
JAddStringToObject(req, "mode", "1day");
JAddNumberToObject(req, "offset", 5);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.get"}
req["mode"] = "1day"
req["offset"] = 5
rsp = card.Transaction(req)
```

Get usage statistics for a specific day, 5 days ago.

**Get Hourly Usage**

**JSON**

```json
{
  "req": "card.usage.get",
  "mode": "1hour"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.get");
JAddStringToObject(req, "mode", "1hour");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.get"}
req["mode"] = "1hour"
rsp = card.Transaction(req)
```

Get usage statistics for the current hour period.

**Get 30-Day Usage**

**JSON**

```json
{
  "req": "card.usage.get",
  "mode": "30day"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.get");
JAddStringToObject(req, "mode", "30day");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.get"}
req["mode"] = "30day"
rsp = card.Transaction(req)
```

Get usage statistics for the last 30 days.

**Response Members**

### `bytes_received`

*integer*

Number of bytes received by the Notecard from Notehub.

### `bytes_sent`

*integer*

Number of bytes sent by the Notecard to Notehub.

### `notes_received`

*integer*

Approximate number of notes received by the Notecard from Notehub.

### `notes_sent`

*integer*

Approximate number of notes sent by the Notecard to Notehub.

### `seconds`

*integer*

Number of seconds in the analyzed period.

### `sessions_secure`

*integer*

Number of secure Notehub sessions.

### `sessions_standard`

*integer*

Number of standard Notehub sessions.

### `time`

*UNIX Epoch time*

Start time of the analyzed period or, if `mode="total"`, the time of activation.

Example Response

```json
{
  "seconds": 1291377,
  "time": 1598479763,
  "bytes_sent": 163577,
  "bytes_received": 454565,
  "notes_sent": 114,
  "notes_received": 26,
  "sessions_standard": 143,
  "sessions_secure": 31
}
```

Example response showing comprehensive cellular and WiFi network usage data.

```json
{
  "seconds": 3600,
  "time": 1700000000,
  "bytes_sent": 1024,
  "bytes_received": 2048
}
```

Example response with basic cellular and WiFi usage metrics.

## card.usage.test

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Calculates a projection of how long the available cellular data quota will last based on the observed usage patterns.

> **Note:**
>
> The `card.usage.test` API only applies to cellular and WiFi data, not LoRa or satellite (NTN).

Arguments

### `days`

*integer (optional)*

Number of days to use for the test.

### `hours`

*integer (optional)*

If you want to analyze a period shorter than one day, the number of hours to use for the test.

### `megabytes`

*integer (optional, default `1024`)*

The Notecard lifetime cellular data quota (in megabytes) to use for the test.

**Test 7-Day Usage Projection**

**JSON**

```json
{
  "req": "card.usage.test",
  "days": 7,
  "megabytes": 500
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.test");
JAddNumberToObject(req, "days", 7);
JAddNumberToObject(req, "megabytes", 500);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.test"}
req["days"] = 7
req["megabytes"] = 500
rsp = card.Transaction(req)
```

Calculate data quota projection based on the last 7 days with 500MB quota.

**Test 12-Hour Usage Projection**

**JSON**

```json
{
  "req": "card.usage.test",
  "hours": 12
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.test");
JAddNumberToObject(req, "hours", 12);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.test"}
req["hours"] = 12
rsp = card.Transaction(req)
```

Calculate data quota projection based on the last 12 hours.

**Default Quota Test**

**JSON**

```json
{
  "req": "card.usage.test",
  "days": 30
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.usage.test");
JAddNumberToObject(req, "days", 30);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.usage.test"}
req["days"] = 30
rsp = card.Transaction(req)
```

Test with default 1024MB quota using 30 days of data.

**Response Members**

### `bytes_per_day`

*integer*

Average bytes per day used during the test period.

### `bytes_received`

*integer*

Number of bytes received by the Notecard from Notehub.

### `bytes_sent`

*integer*

Number of bytes sent by the Notecard to Notehub.

### `days`

*integer*

The number of days used for the test.

### `max`

*integer*

The days of projected data available based on test.

### `notes_received`

*integer*

Number of notes received by the Notecard from Notehub.

### `notes_sent`

*integer*

Number of notes sent by the Notecard to Notehub.

### `seconds`

*integer*

Number of seconds in the analyzed period.

### `sessions_secure`

*integer*

Number of secure Notehub sessions.

### `sessions_standard`

*integer*

Number of standard Notehub sessions.

### `time`

*UNIX Epoch time*

Time of device activation.

Example Response

```json
{
  "max": 12730,
  "days": 7,
  "bytes_per_day": 41136,
  "seconds": 1291377,
  "time": 1598479763,
  "bytes_sent": 163577,
  "bytes_received": 454565,
  "notes_sent": 114,
  "notes_received": 26,
  "sessions_standard": 143,
  "sessions_secure": 31
}
```

Example response showing comprehensive usage projection data.

```json
{
  "max": 1825,
  "days": 30,
  "bytes_per_day": 56832,
  "seconds": 2592000,
  "time": 1700000000
}
```

Example response with essential projection metrics.

## card.version

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Returns firmware version information for the Notecard.

Arguments

None

**Example**

**JSON**

```json
{
  "req": "card.version"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.version");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.version"}
rsp = card.Transaction(req)
```

Retrieve firmware version and device information.

**Response Members**

### `board`

*string*

The Notecard board version number.

### `body`

*object*

An object containing Notecard firmware details for programmatic access.

### `cell`

*boolean*

If `true`, indicates the Notecard supports cellular connectivity.

### `device`

*string*

The DeviceUID of the Notecard.

### `gps`

*boolean*

If `true`, indicates the Notecard has an onboard GPS module.

### `name`

*string*

The official name of the device.

### `sku`

*string*

The Notecard SKU.

### `version`

*string*

The full version number of the Notecard firmware.

### `wifi`

*boolean*

If `true`, indicates the Notecard supports WiFi connectivity.

Example Response

```json
{
  "version": "notecard-5.3.1",
  "device": "dev:000000000000000",
  "name": "Blues Wireless Notecard",
  "sku": "NOTE-NBGL",
  "board": "1.11",
  "cell": true,
  "gps": true,
  "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"
  }
}
```

## card.voltage

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Provides the current VMODEM\_P voltage level on the Notecard, and provides information about historical voltage trends. When used with the mode argument, configures voltage thresholds based on how the device is powered.

Arguments

### `alert`

*boolean (optional, default `false`)*

When enabled and the `usb` argument is set to `true`, the Notecard will add an entry to the `_health.qo` Notefile when USB power is connected or disconnected.

### `calibration`

*number (optional, default `0.35`)*

The offset, in volts, to account for the forward voltage drop of the diode used between the battery and Notecard in either Blues- or customer-designed Notecarriers.

### `hours`

*integer (optional, default `720`)*

The number of hours to analyze, up to 720 (30 days).

### `mode`

*string (optional, default `default`)*

Used to set voltage thresholds based on how the Notecard will be powered, and which can be used to [configure voltage-variable Notecard behavior](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md). Each value is shorthand that assigns a battery voltage reading to a given device state like `high`, `normal`, `low`, and `dead`.

In addition to the named presets below, a custom semicolon-separated shorthand string may be provided using any combination of the `usb`, `high`, `normal`, `low`, and `dead` states (e.g. `"usb:4.6;high:4.2;normal:3.6;low:0"`).

**NOTE:** Setting voltage thresholds is not supported on the Notecard XP.

`"default"`: Default behavior. Equivalent to `normal:2.5;dead:0`.

`"lipo"`: LiPo batteries. Equivalent to `usb:4.6;high:4.0;normal:3.5;low:3.2;dead:0`.

`"l91"`: L91 batteries. Equivalent to `high:5.0;normal:4.5;low:0`.

`"alkaline"`: Alkaline batteries. Equivalent to `usb:4.6;high:4.2;normal:3.6;low:0`.

`"tad"`: Tadiran HLC batteries. Equivalent to `usb:4.6;normal:3.2;low:0`.

`"lic"`: Lithium-ion capacitors. Equivalent to `usb:4.6;high:3.8;normal:3.1;low:0`.

`"?"`: Query the Notecard for its currently-set thresholds.

### `name`

*string (optional)*

Specifies an environment variable to override application default timing values.

### `now`

*boolean (optional, default `false`)*

By default, the returned `value` is an average of the voltage readings taken over the previous 15 minutes, which smooths out momentary fluctuations. Set to `true` to return the instantaneous voltage reading instead.

### `off`

*boolean (optional)*

Disable historic voltage trend calculations.

### `offset`

*integer (optional, default `0`)*

Number of hours to move into the past before starting analysis.

### `on`

*boolean (optional)*

Enable historic voltage trend calculations.

### `set`

*boolean (optional, default `false`)*

Used along with `calibration`, set to `true` to specify a new calibration value.

### `sync`

*boolean (optional, default `false`)*

When enabled and the `usb` argument is set to `true`, the Notecard will perform a sync when USB power is connected or disconnected.

### `usb`

*boolean (optional, default `false`)*

When enabled, the Notecard will monitor for changes to USB power state.

### `vmax`

*number (optional, default `5.4`)*

Ignore voltage readings above this level when performing calculations. Defaults to the maximum voltage the Notecard's components are rated for.

### `vmin`

*number (optional, default `2.3`)*

Ignore voltage readings below this level when performing calculations. Defaults to the minimum voltage the Notecard's components are rated for.

**Get Voltage Trends**

**JSON**

```json
{
  "req": "card.voltage",
  "hours": 300,
  "vmax": 4,
  "vmin": 2.2
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.voltage");
JAddNumberToObject(req, "hours", 300);
JAddNumberToObject(req, "vmax", 4);
JAddNumberToObject(req, "vmin", 2.2);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.voltage"}
req["hours"] = 300
req["vmax"] = 4
req["vmin"] = 2.2
rsp = card.Transaction(req)
```

Retrieve voltage information with trend analysis for 300 hours.

**Set LiPo Voltage Thresholds**

**JSON**

```json
{
  "req": "card.voltage",
  "mode": "lipo"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "lipo");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.voltage"}
req["mode"] = "lipo"
rsp = card.Transaction(req)
```

Configure voltage thresholds for LiPo battery operation.

**Query Current Thresholds**

**JSON**

```json
{
  "req": "card.voltage",
  "mode": "?"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "?");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.voltage"}
req["mode"] = "?"
rsp = card.Transaction(req)
```

Query the Notecard for its currently-set voltage thresholds.

**Set Custom Voltage Thresholds**

**JSON**

```json
{
  "req": "card.voltage",
  "mode": "usb:4.6;high:4.2;normal:3.6;low:0"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "usb:4.6;high:4.2;normal:3.6;low:0");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.voltage"}
req["mode"] = "usb:4.6;high:4.2;normal:3.6;low:0"
rsp = card.Transaction(req)
```

Configure voltage thresholds using a custom semicolon-separated shorthand string.

**Enable USB Power Monitoring**

**JSON**

```json
{
  "req": "card.voltage",
  "usb": true,
  "alert": true,
  "sync": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.voltage");
JAddBoolToObject(req, "usb", true);
JAddBoolToObject(req, "alert", true);
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.voltage"}
req["usb"] = True
req["alert"] = True
req["sync"] = True
rsp = card.Transaction(req)
```

Enable USB power state monitoring with alerts and sync.

**Enable Historic Voltage Trends**

**JSON**

```json
{
  "req": "card.voltage",
  "on": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.voltage");
JAddBoolToObject(req, "on", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.voltage"}
req["on"] = True
rsp = card.Transaction(req)
```

Enable historic voltage trends tracking.

**Response Members**

### `alert`

*boolean*

`true` if the Notecard is configured to add an entry to the `_health.qo` Notefile on USB connect/disconnect (enabled by sending `card.voltage` with `"usb": true, "alert": true`).

### `calibration`

*number*

If a user calibration value has been saved (via `"set": true`), this is that value; otherwise it is the hardware-supplied default.

### `daily`

*number*

Change in the 24-hour moving average over the analyzed window. Only present when historic voltage trend calculations have been enabled with `"on": true` and the analyzed window includes at least 24 hours of history.

### `hours`

*integer*

The number of hours of voltage history actually used in the analysis. Only present when historic voltage trend calculations have been enabled with `"on": true`.

### `minutes`

*integer*

The number of minutes since the Notecard was last on USB power. Not present when the Notecard is currently connected to USB power.

### `mode`

*string*

The current voltage-variable threshold value returned from Notecard.

For example, if the voltage threshold is `"usb:4.6;normal:3.5;dead:0"` and the power source returns a voltage of `3.9`, the mode value would be `"normal"`.

### `monthly`

*number*

Change in the 30-day moving average over the analyzed window. Only present when historic voltage trend calculations have been enabled with `"on": true` and the analyzed window includes at least 30 days of history.

### `on`

*boolean*

`true` if the request that produced this response set `"on": true`.

### `sync`

*boolean*

`true` if the Notecard is configured to perform a sync on USB connect/disconnect (enabled by sending `card.voltage` with `"usb": true, "sync": true`).

### `usb`

*boolean*

`true` if the Notecard is connected to USB power.

### `value`

*number*

The current voltage, in volts.

### `vavg`

*number*

The average voltage during the analyzed window. Only present when historic voltage trend calculations have been enabled with `"on": true`.

### `vmax`

*number*

The highest voltage during the analyzed window. Only present when historic voltage trend calculations have been enabled with `"on": true`.

### `vmin`

*number*

The lowest voltage during the analyzed window. Only present when historic voltage trend calculations have been enabled with `"on": true`.

### `weekly`

*number*

Change in the 7-day moving average over the analyzed window. Only present when historic voltage trend calculations have been enabled with `"on": true` and the analyzed window includes at least 7 days of history.

Example Response

```json
{
  "usb": true,
  "mode": "usb",
  "value": 5.112190219747135
}
```

Minimal response from a bare `card.voltage` request on a USB-powered Notecard. No historical fields are present because trend analysis has not been enabled with `"on": true`.

```json
{
  "usb": true,
  "hours": 120,
  "mode": "usb",
  "value": 5.112190219747135,
  "vmin": 4,
  "vmax": 4,
  "vavg": 4
}
```

Response when Notecard is powered via USB and historic voltage trend calculations have been enabled with `"on": true`.

```json
{
  "mode": "normal",
  "value": 3.85,
  "hours": 720,
  "vmin": 3.2,
  "vmax": 4.1,
  "vavg": 3.75,
  "daily": -0.05,
  "weekly": -0.3,
  "monthly": -0.8,
  "minutes": 43200
}
```

Response when Notecard is on battery and historic voltage trend calculations have been enabled with `"on": true`.

```json
{
  "usb": true,
  "mode": "usb:4.6;high:4.0;normal:3.5;low:3.2;dead:0",
  "value": 5.112190219747135
}
```

Response to a `card.voltage` request that includes `"mode": "?"`. The `mode` field carries the configured threshold definition string, not a bucket label.

## card.wifi

Supported on

(Cell+WiFi, Skylo, WiFi)

Sets up a Notecard's connection to a WiFi access point.

> **Note:**
>
> Updates to Notecard WiFi credentials cannot occur while Notecard is in `continuous` mode, as a new session is required to change the credentials. If you have a Notecard WiFi in `continuous` mode, you must change to another mode such as `periodic` or `off`, using [a hub.set request](https://dev.blues.io/api-reference/notecard-api/hub-requests.md#hub-set) before calling `card.wifi`.
>
> WiFi credentials set via `card.wifi` (including multiple-network lists set with the `text` argument) are saved to non-volatile flash storage on the Notecard and persist across power cycles and reboots.

Arguments

### `name`

*string (optional)*

By default, the Notecard creates a SoftAP (software enabled access point) under the name "Notecard". You can use the `name` argument to change the name of the SoftAP to a custom name.

If you include a `-` at the end of the `name` (for example `"name": "acme-"`), the Notecard will append the last four digits of the network's MAC address (for example `acme-025c`). This allows you to distinguish between multiple Notecards in SoftAP mode.

### `org`

*string (optional)*

If specified, replaces the Blues logo on the SoftAP page with the provided name.

### `password`

*string (optional)*

The network password of the WiFi access point. Alternatively, use `-` to clear an already set password or to connect to an open access point.

### `ssid`

*string (optional)*

The SSID of the WiFi access point. Alternatively, use `-` to clear an already set SSID.

### `start`

*boolean (optional)*

Specify `true` to activate SoftAP mode on the Notecard programmatically.

### `text`

*string (optional)*

A string containing an array of access points the Notecard should attempt to use. The access points should be provided in the following format:

`["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"]`.

You may need to escape any quotes used in this argument before passing it to the Notecard. For example, the following is a valid request to pass to a Notecard through the [In-Browser Terminal](https://dev.blues.io/terminal/).

`{"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"]"}`

**Create a Connection**

**JSON**

```json
{
  "req": "card.wifi",
  "ssid": "<ssid name>",
  "password": "<password>"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "ssid", "<ssid name>");
JAddStringToObject(req, "password", "<password>");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wifi"}
req["ssid"] = "<ssid name>"
req["password"] = "<password>"
rsp = card.Transaction(req)
```

Set WiFi SSID and password to connect to an access point.

**Clear a Connection**

**JSON**

```json
{
  "req": "card.wifi",
  "ssid": "-",
  "password": "-"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "ssid", "-");
JAddStringToObject(req, "password", "-");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wifi"}
req["ssid"] = "-"
req["password"] = "-"
rsp = card.Transaction(req)
```

Clear existing WiFi credentials to disconnect.

**Customize the SoftAP**

**JSON**

```json
{
  "req": "card.wifi",
  "name": "ACME Inc",
  "org": "ACME Inc"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "name", "ACME Inc");
JAddStringToObject(req, "org", "ACME Inc");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wifi"}
req["name"] = "ACME Inc"
req["org"] = "ACME Inc"
rsp = card.Transaction(req)
```

Configure SoftAP with custom name and organization branding.

**Customize the SoftAP w/MAC Address**

**JSON**

```json
{
  "req": "card.wifi",
  "name": "acme-",
  "org": "ACME Inc"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "name", "acme-");
JAddStringToObject(req, "org", "ACME Inc");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wifi"}
req["name"] = "acme-"
req["org"] = "ACME Inc"
rsp = card.Transaction(req)
```

Configure SoftAP name with MAC address suffix for unique identification.

**Configure Multiple Access Points**

**JSON**

```json
{
  "req": "card.wifi",
  "text": "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wifi");
JAddStringToObject(req, "text", "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wifi"}
req["text"] = "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"
rsp = card.Transaction(req)
```

Set up multiple WiFi access points for fallback connectivity.

**Response Members**

### `secure`

*boolean*

`true` means that the WiFi access point is using Management Frame Protection.

### `security`

*string*

The security protocol the WiFi access point uses.

### `ssid`

*string*

The SSID of the WiFi access point.

### `version`

*string*

The Silicon Labs WF200 WiFi Transceiver binary version.

Example Response

```json
{
  "secure": true,
  "version": "3.12.3",
  "ssid": "<ssid name>",
  "security": "wpa2-psk"
}
```

Example response showing comprehensive WiFi connection information.

```json
{
  "ssid": "HomeNetwork",
  "security": "wpa3"
}
```

Example response with basic WiFi access point information.

```json
{
  "version": "3.12.3"
}
```

Example response showing WiFi transceiver version.

## card.wireless

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

View the last known network state, or customize the behavior of the modem. *Note: Be careful when using this mode with hardware not on hand as a mistake may cause loss of network and Notehub access.*

Arguments

### `apn`

*string (optional)*

Access Point Name (APN) when using an external SIM. Use `"-"` to reset to the Notecard default APN.

### `hours`

*integer (optional)*

When using the `method` argument with `"dual-primary-secondary"` or `"dual-secondary-primary"`, this is the number of hours after which the Notecard will attempt to switch back to the preferred SIM.

### `method`

*string (optional)*

Used when configuring a [Notecard to failover to a different SIM](https://dev.blues.io/guides-and-tutorials/notecard-guides/using-external-sim-cards.md#failing-over-to-a-different-sim).

`"-"`: Resets the Notecard to the default method.

`"dual-primary-secondary"`: Will attempt to register with the internal SIM first, then failover to the external SIM.

`"dual-secondary-primary"`: Will attempt to register with the external SIM first, then failover to the internal SIM.

`"primary"`: Will exclusively use the internal SIM.

`"secondary"`: Will exclusively use the external SIM.

### `mode`

*string (optional)*

Network scan mode. Must be one of:

`"-"`: Reset to the default mode.

`"auto"`: Perform automatic band scan mode (this is the default mode).

`"m"`: Restrict the modem to Cat-M1 (applies exclusively to Narrowband Notecard Cellular devices).

`"nb"`: Restrict the modem to Cat-NB1 (applies exclusively to Narrowband Notecard Cellular devices).

`"gprs"`: Restrict the modem to EGPRS (applies exclusively to Narrowband Notecard Cellular devices).

**Current Network State**

**JSON**

```json
{
  "req": "card.wireless"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wireless");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wireless"}
rsp = card.Transaction(req)
```

Request current network state without any modifications.

**Change Scan Mode**

**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)
```

Restrict the modem to Cat-NB1 for narrowband connectivity.

**Reset Scan Mode**

**JSON**

```json
{
  "req": "card.wireless",
  "mode": "-"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "mode", "-");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wireless"}
req["mode"] = "-"
rsp = card.Transaction(req)
```

Reset network scan mode to default behavior.

**Set External SIM APN**

**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)
```

Configure APN for external SIM card usage.

**Failover to External SIM**

**JSON**

```json
{
  "req": "card.wireless",
  "apn": "myapn.nb",
  "method": "dual-primary-secondary"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wireless");
JAddStringToObject(req, "apn", "myapn.nb");
JAddStringToObject(req, "method", "dual-primary-secondary");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wireless"}
req["apn"] = "myapn.nb"
req["method"] = "dual-primary-secondary"
rsp = card.Transaction(req)
```

Configure dual SIM failover with external SIM priority.

**Response Members**

### `count`

*integer*

Number of bars of signal quality.

### `net`

*object*

An object with detailed modem, radio access technology, and signal information (details will differ depending on the type of Notecard).

### `status`

*string*

The current status of the wireless connection and modem.

Example Response

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

Example response showing comprehensive wireless connection and signal information.

```json
{
  "status": "connected",
  "count": 3
}
```

Example response with basic signal strength and status.

```json
{
  "status": "searching",
  "count": 2,
  "net": {
    "band": "LTE BAND 12",
    "rat": "lte",
    "rssi": -85,
    "bars": 2,
    "mcc": 310,
    "mnc": 260
  }
}
```

Example response showing detailed network information.

## card.wireless.penalty

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

View the current state of a [Notecard Penalty Box](https://dev.blues.io/support/understanding-notecard-penalty-boxes.md), manually remove the Notecard from a penalty box, or override penalty box defaults.

> **Warning:**
>
> The misuse of this feature may result in the cellular carrier preventing the Notecard from future connections because it's effectively "spamming" the network. The cellular carrier may blacklist devices that it thinks are attempting to connect too frequently.

Arguments

### `add`

*integer (optional, default `15`)*

The number of minutes to add to successive retries. Used with the `set` argument to override the Network Registration Failure Penalty Box defaults.

### `max`

*integer (optional, default `4320`)*

The maximum number of minutes that a device can be in a Network Registration Failure Penalty Box. Used with the `set` argument to override the Network Registration Failure Penalty Box defaults.

### `min`

*integer (optional, default `15`)*

The number of minutes of the first retry interval of a Network Registration Failure Penalty Box. Used with the `set` argument to override the Network Registration Failure Penalty Box defaults.

### `rate`

*number (optional, default `1.25`)*

The rate at which the penalty box time multiplier is increased over successive retries. Used with the `set` argument to override the Network Registration Failure Penalty Box defaults.

### `reset`

*boolean (optional)*

Set to `true` to remove the Notecard from certain types of penalty boxes.

### `set`

*boolean (optional)*

Set to `true` to override the default settings of the [Network Registration Failure Penalty Box](https://dev.blues.io/support/understanding-notecard-penalty-boxes.md#network-registration-failure).

**Check Penalty Box State**

**JSON**

```json
{
  "req": "card.wireless.penalty"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wireless.penalty");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wireless.penalty"}
rsp = card.Transaction(req)
```

Request current penalty box status and information.

**Remove from Penalty Box**

**JSON**

```json
{
  "req": "card.wireless.penalty",
  "reset": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wireless.penalty");
JAddBoolToObject(req, "reset", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wireless.penalty"}
req["reset"] = True
rsp = card.Transaction(req)
```

Reset and remove the Notecard from penalty box conditions.

**Override Default Penalty Box Settings**

**JSON**

```json
{
  "req": "card.wireless.penalty",
  "set": true,
  "rate": 2.0,
  "add": 10,
  "max": 720,
  "min": 5
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("card.wireless.penalty");
JAddBoolToObject(req, "set", true);
JAddNumberToObject(req, "rate", 2.0);
JAddNumberToObject(req, "add", 10);
JAddNumberToObject(req, "max", 720);
JAddNumberToObject(req, "min", 5);

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.wireless.penalty"}
req["set"] = True
req["rate"] = 2.0
req["add"] = 10
req["max"] = 720
req["min"] = 5
rsp = card.Transaction(req)
```

Configure custom penalty box parameters with modified defaults.

**Response Members**

### `count`

*integer*

The number of consecutive network registration failures.

### `minutes`

*integer*

The time since the first network registration failure.

### `seconds`

*integer*

If the Notecard is in a [Penalty Box](https://dev.blues.io/support/understanding-notecard-penalty-boxes.md), the number of seconds until the penalty condition ends.

### `status`

*string*

If the Notecard is in a [Penalty Box](https://dev.blues.io/support/understanding-notecard-penalty-boxes.md), this field provides the associated [Error and Status Codes](https://dev.blues.io/support/notecard-error-and-status-codes.md).

Example Response

```json
{
  "seconds": 3324,
  "minutes": 69,
  "status": "network: can't connect (55.4 min remaining) {registration-failure}{network}{extended-network-failure}",
  "count": 6
}
```

Example response showing Notecard in penalty box with active network registration failure.

```json
{
  "minutes": 0,
  "count": 0
}
```

Example response when Notecard is not in a penalty box.

```json
{
  "count": 3,
  "minutes": 15
}
```

Example response with basic penalty metrics without active penalty.

[Notecard API Introduction](https://dev.blues.io/api-reference/notecard-api.md "Notecard API Introduction") [dfu Requests](https://dev.blues.io/api-reference/notecard-api/dfu-requests.md "dfu Requests")