---
title: Working with the Notecard AUX Pins
description: Learn the various modes for using the Notecard AUX pins in your projects.
source_url: https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins/
canonical_url: https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins/
markdown_url: https://dev.blues.io/notecard/notecard-walkthrough/working-with-the-notecard-aux-pins.md
---

# Working with the Notecard AUX Pins

The Notecard edge connector provides a series of pins that developers can utilize for detailed tracing of Notecard activity, interfacing with GPS operations, accessing GPIO pins on the Notecard, connecting external LEDs to a product in order to monitor Notecard activity, and more.

The Notecard brings out seven AUX-labeled pins. They are:

- `AUXEN`
- `AUXRX`
- `AUXTX`
- `AUX1`
- `AUX2`
- `AUX3`
- `AUX4`

The behavior of these pins changes depending on the AUX mode configured on the Notecard.

- The usage of `AUX1` - `AUX4` is determined by the [`card.aux` request](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux), and the different modes you can use for that request are described in [Using AUX1, AUX2, AUX3, and AUX4](#using-aux1-aux2-aux3-and-aux4).

- The usage of `AUXEN`, `AUXRX`, and `AUXTX` is determined by the [`card.aux.serial` request](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux-serial), and the different modes you can use for that request are described in [Using AUXEN, AUXRX, and AUXTX](#using-auxen-auxrx-and-auxtx).

> **Note:**
>
> The Notecard AUX pins are used during [Notecard Outboard Firmware Updates](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md), and some Notecard AUX modes may interfere with Outboard Firmware Updates. For more information see the Outboard Firmware Updates' [required wiring](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#required-wiring), and if you have questions feel free to [reach out in our forum](https://discuss.blues.com/).

## Using AUX1, AUX2, AUX3, and AUX4

The following sections describe various ways to use the [`card.aux` request](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux) to control the behavior of the Notecard’s `AUX1` - `AUX4` pins.

- [Determining the Current AUX Mode](#determining-the-current-aux-mode)
- [Using AUX Track Mode](#using-aux-track-mode)
- [Using AUX Motion Mode](#using-aux-motion-mode)
- [Using AUX GPIO Mode](#using-aux-gpio-mode)
- [Using Monitor Mode](#using-monitor-mode)
- [Using Neo-Monitor Mode](#using-neo-monitor-mode)
- [Using RGB-Monitor Mode](#using-rgb-monitor-mode)
- [Combining Track Mode with Monitor Modes](#combining-track-mode-with-monitor-modes)
- [Using DFU Mode](#using-dfu-mode)
- [Turning AUX Mode Off](#turning-aux-mode-off)

### Determining the Current AUX Mode

You can query the Notecard AUX mode at any time with a `card.aux` request and no arguments.

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}

card.Transaction(req)
```

By default, the Notecard AUX mode is `off`.

```json
{ "mode": "off" }
```

### Using AUX Track Mode

AUX track mode allows you to enhance Notes in the [`_track.qo` Notefile](https://dev.blues.io/api-reference/system-notefiles.md#track-qo) with temperature, pressure, and humidity readings from a connected BME280 sensor.

When in track mode, specific pins should be configured as follows:

- `AUX1` should be connected to the `SDA` or `SDI` pin on the sensor.
- `AUX4` should be connected to the `SCL` or `SCK` pin on the sensor.
- `GND` should be connected to the `GND` pin on the sensor.
- `BAT` should be connected to the `EN`, `ENABLE`, or `3VO` pin on the sensor.

If you have other I2C devices on the same bus as the Notecard, ensure the BME280's I2C address (`0x76` primary or `0x77` secondary) does not conflict with another device.

Once everything is connected, you can enable track mode by performing a `card.aux` request with a `"mode"` of `"track"`.

**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"

card.Transaction(req)
```

When track mode is enabled, the Notecard will automatically append the temperature, pressure, and humidity from the connected BME280 to every new Note it adds to the `_track.qo` Notefile.

For more information on how to enable and use the `_track.qo` Notefile, see our [guide on asset tracking](https://dev.blues.io/guides-and-tutorials/notecard-guides/asset-tracking-with-gps.md).

### Using AUX Motion Mode

AUX Motion mode allows you to configure the Notecard as a standalone motion tracking device, without requiring a host processor. Motion mode is enabled with the value `motion` in the `mode` argument of a `card.aux` request:

**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"

card.Transaction(req)
```

When in `motion` mode, the `AUX1`-`AUX4` pins are configured as follows:

- `AUX1` is an active-`LOW` input control that can be wired to a button. When the button is pressed, the Notecard adds a "button pushed" event to the tracking database and initiates an immediate cloud sync.
- `AUX2` is an active-`HIGH` input control meant to signal when a notable event has occurred. When the input control sends a pulse to the `AUX2` pin, a counter is incremented and added to the database on the next tracking event or heartbeat.
- `AUX3` is an active-`HIGH` input control meant to signal when a notable event has occurred *while the Notecard is in motion*. When the input control sends a pulse to the `AUX3` pin, a counter is incremented and added to the database on the next tracking event or heartbeat.
- `AUX4` is an output signal used to indicate that the Notecard has detected motion. Whenever the device has been in motion for several seconds, `AUX4` is set to digital `HIGH`. After the device is no longer in motion, the signal is returned to `LOW`.

In Motion mode, the `AUX1`-`AUX4` pins have a specific configuration, but it is up to the hardware designer to determine the specific inputs and outputs connected to these pins in a product.

### Using AUX GPIO Mode

In AUX GPIO mode, the `AUX1`-`AUX4` pins are used as general purpose I/O pins. AUX GPIO mode is enabled with the value `gpio` in the `mode` argument of a `card.aux` request:

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"

card.Transaction(req)
```

To modify the mode for each pin, a `card.aux` request accepts a `usage` argument in the form of an array of strings in pin order. The possible values for each pin are:

- `""` to leave the pin mode unchanged.
- `off` to disable the pin.
- `high` to set the pin as a `HIGH` output.
- `low` to set the pin as a `LOW` output.
- `input` to set the pin as an input. It is up to the device's designer to make sure that the signal is either HIGH or LOW at any time, and is never left floating.
- `input-pulldown` to set the pin as a pull-down input. *(Added in v3.3.1)*
- `input-pullup` to set the pin as a pull-up input. *(Added in v3.3.1)*
- `count` to set the pin as an input (interrupt) that increments a counter for each rising edge pulse on the pin. It is up to the device's designer to make sure that the signal is either HIGH or LOW at any time, and is never left floating.
- `count-pulldown` Same as `count` mode, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating.
- `count-pullup` Same as `count` mode, but a pull-up resistor internal to the Notecard will automatically keep the pin from floating and the falling edge of each pulse is counted.

For instance, the following request turns off `AUX1`, sets `AUX2` `LOW`, `AUX3` `HIGH`, and `AUX4` as an input:

**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 *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("off"));   // AUX1
JAddItemToArray(pins, JCreateString("low"));   // AUX2
JAddItemToArray(pins, JCreateString("high"));  // AUX3
JAddItemToArray(pins, JCreateString("input")); // AUX4

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
    "off", # AUX1
    "low", # AUX2
    "high", # AUX3
    "input" # AUX4
  ]

card.Transaction(req)
```

When setting usage, a `card.aux` request will return the `state` field with the applied usage settings.

```json
{
 "mode": "gpio",
 "state": [
  {},
  {
   "low": true
  },
  {
   "high": true
  },
  {
   "low": true
  }
 ]
}
```

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

**JSON**

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

**C/C++**

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

J *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("")); // AUX1
JAddItemToArray(pins, JCreateString("")); // AUX2
JAddItemToArray(pins, JCreateString("")); // AUX3
JAddItemToArray(pins, JCreateString("")); // AUX4

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
    "", # AUX1
    "", # AUX2
    "", # AUX3
    "" # AUX4
  ]

card.Transaction(req)
```

```json
{
 "mode": "gpio",
 "state": [
  {},
  {},
  {},
  {}
 ]
}
```

#### Sending Notes Based on AUX Pin State Changes

As of v3.3.1, the Notecard can autonomously (i.e. without a host MCU) report AUX GPIO input changes to Notehub by using the `"sync":true` parameter in a `card.aux` request.

An example of this type of request could be setting `AUX1` `low` and `AUX2-4` as `input-pulldown`:

**JSON**

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

**C/C++**

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

J *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("low")); // AUX1
JAddItemToArray(pins, JCreateString("input-pulldown")); // AUX2
JAddItemToArray(pins, JCreateString("input-pulldown")); // AUX3
JAddItemToArray(pins, JCreateString("input-pulldown")); // AUX4

JAddBoolToObject(req, "sync", true);
JAddStringToObject(req, "file", "gpio.qo");

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
    "low", # AUX1
    "input-pulldown", # AUX2
    "input-pulldown", # AUX3
    "input-pulldown" # AUX4
  ]
req["sync"] = True
req["file"] = "gpio.qo"

card.Transaction(req)
```

With this request, the Notecard will automatically report any state changes on AUX2, AUX3, and AUX4. By default, the state changes are reported in a Notefile called `_button.qo`, but the Notefile name can be specified with the `file` parameter.

The Notecard applies about one second of debounce to any GPIO transition and on state changes adds a Note to the Notefile specified by `file` and immediately syncs with Notehub. However, by using `"connected":true` this sync can be deferred to sync based on the period defined in the original `hub.set` request.

When synced with Notehub, the Note body will appear something like this:

```json
{
 "power": true,
 "state": [
  {
   "low": true
  },
  {
   "low": true
  },
  {
   "high": true
  },
  {
   "low": true
  }
 ]
}
```

The `power` parameter indicates whether or not the Notecard has USB (main) power, which could be useful if monitoring a Notecard for power failure. The `state` shows the current state of each AUX GPIO, regardless of whether it is configured as an input or an output.

#### Configuring an AUX Pin as a Counter

For pins used as counters, the Notecard will count rising edge pulses lasting more than about 12ns. Being interrupt based, this works well in low-power environments.

If `sync` is set to `true`, the Notecard will trigger a sync each time it counts a pulse.

When using `count` in the `usage` for any pin, the following can also be configured to group pulses in a counter:

- `seconds` - The number of seconds to include in a sample. Passing `0` will total into a single sample.
- `max` - The maximum number of samples to take. Counts above this value are added to the final sample. Passing `0` or omitting this value will provide a single incrementing count of rising edges on the pin.
- `start` - Set to `true` to reset counters and start incrementing.
- `ms` - A debounce interval in milliseconds. Any pulse transitions shorter than this duration are ignored, which is useful when counting signals from mechanical switches that may bounce.

**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 *pins = JAddArrayToObject(req, "usage");
JAddItemToArray(pins, JCreateString("off")); // AUX1
JAddItemToArray(pins, JCreateString("low")); // AUX2
JAddItemToArray(pins, JCreateString("high")); // AUX3
JAddItemToArray(pins, JCreateString("count")); // AUX4

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", # AUX1
    "low", # AUX2
    "high", # AUX3
    "count" # AUX4
  ]
req["seconds"] = 2
req["max"] = 5
req["start"] = True

card.Transaction(req)
```

Once GPIO mode is configured, subsequent requests to `card.aux` will return the current pin state and counter values for each pin.

```json
{
 "mode": "gpio",
 "state": [
  {},
  {
   "low": true
  },
  {
   "high": true
  },
  {
   "count": [
    4
   ]
  }
 ]
}
```

#### Using Environment Variables to Set and Monitor AUX GPIOs

As of v3.4.1, you can change AUX GPIO output values using [environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md), provided the Notecard has previously been configured with `{"req":"card.aux","mode":"gpio","usage":[...]}`.

The environment variable `_aux_gpio_set` is used to set AUX GPIOs `HIGH` or `LOW`, or pulse them `HIGH` or `LOW` for a specified period (in milliseconds).

#### Setting GPIO Outputs High or Low with Environment Variables

To set GPIOs permanently `HIGH` or `LOW` (not pulse), the value of the environment variable should be a comma-separated list of values. Any GPIOs that should not change their configuration (e.g. inputs or counters) should be left blank.

For example, `_aux_gpio_set` with a value of `,low,,high` causes `AUX2` to go `LOW` and `AUX4` to go `HIGH`.

The Notecard saves this setting to non-volatile memory, so that if it restarts it restores the pin states as defined.

#### Pulsing GPIO Outputs High or Low with Environment Variables

To pulse one or more GPIOs `HIGH` or `LOW`, add a duration in milliseconds plus a UNIX epoch time and validity period (both in seconds).

For example, `_aux_gpio_set` with a value of `,,,high,1300,1656110120,60` means pulse `AUX4` `HIGH` for 1300ms, valid for 60 seconds from 1656110120 until 1656110180.

> **Note:**
>
> It's a best practice to add a UNIX epoch time and a validity period with the `_aux_gpio_set` environment variable.
>
> If the Notecard is not currently connected to Notehub, the environment variable will not be synced to the Notecard until it next connects to Notehub. It's likely that a command to pulse the output of the Notecard is an action you'd like to be performed now, or not at all (e.g. if the pulse is used to unlock a door to allow entry).
>
> Environment variables are persistent on the Notecard. If the Notecard should reboot, the environment variable will be re-read, causing a pulse on the GPIO output at a future point in time.
>
> At the end of the pulse the pin returns to its previous state, which means if you send a `LOW`/`HIGH` pulse to a pin that is already `LOW`/`HIGH` there will be no observed effect on the Notecard.
>
> AUX GPIO pulses are NOT stored in non-volatile memory in the Notecard, because they are ephemeral events. If the Notecard should happen to reboot during the duration of the pulse, the GPIO outputs would revert to their long term state.

#### Monitoring AUX GPIO State with Environment Variables

There are two environment variables used for monitoring AUX GPIO state:

`_aux_gpio_report_enable` is set to enable reporting via environment variable. If it is set to the value `sync`, then the Notecard will immediately sync to Notehub when a GPIO input changes (max rate of once per second). If it is set to any other value (i.e. just non-empty) the Notecard will update the environment variable described below, but will not force a sync (which will occur according to the `hub.set` configuration).

`_aux_gpio_report` is set by the Notecard to a comma-separated string that reflects the current state of the AUX GPIO inputs. The format is very similar to the JSON `state` field in the response to a [card.aux](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux) request.

The format is a comma-separated list of pin states. A pin configured as a counter is reported with its current count in parentheses (e.g. `low(8)`).

For example, with the value of `low(8),low,off,high`:

- AUX1 is configured to count, has counted `8` pulses, and is currently `LOW`.
- AUX2 is currently `LOW` (it may be an input or an output).
- AUX3 is currently configured to be `OFF` (high impedance).
- AUX4 is currently `HIGH` (it may be an input or an output).

### Using Monitor Mode

If you plan to place your Notecard-based product into an enclosure, `monitor` mode can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity.

> See `monitor` mode in action as part of the [Using LEDs and NeoPixels to Monitor Notecard Status](https://dev.blues.io/example-apps/samples/using-leds-and-neopixels-to-monitor-notecard-status.md) sample app.

To use `monitor` mode for adding functionality to an enclosure, send a `card.aux` request:

**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"

card.Transaction(req)
```

In `monitor` mode, the `AUX1` pin is configured as a test button, while `AUX2`-`AUX4` are configured as outputs for LED control. The LEDs should correspond to the color guidelines below and can be connected directly to each pin with resistors chosen to ensure a maximum current draw of 20mA per LED.

- `AUX1` is configured active-`LOW` with a pullup and meant to be wired to a normally open momentary switch. When this button, named "COMM TEST" is pressed, a test note is added to the `_button.qo` Notefile and a manual sync is initiated.
- `AUX2` is a **yellow LED** referred to as "STATUS." This is a general purpose LED that flashes an acknowledgement when the `AUX1` "COMM TEST" button is pressed.
- `AUX3` is a **green LED** referred to as "COMM BUSY." This LED blinks in a pattern based on communications status.
- `AUX4` is a **red LED** referred to as "COMM ERROR." This LED turns on continuously for two minutes after there is a failure to connect to a network. To conserve battery life, after the first two minutes the LED turns on for four seconds each minute.

If your host application needs to override the function of these LEDs to display its own error code or status, it can do so using the `mode` and `count` arguments in a `card.monitor` request. `mode` is the name of the AUX pin LED you wish to override. Possible values are `yellow`, `red`, and `green`. `count` is the number of pulses the LED should display in a repeating pattern.

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

card.Transaction(req)
```

To return an LED to its default behavior, set the `count` to `0`:

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.monitor"}
req["mode"] = "green"
req["count"] = 0

card.Transaction(req)
```

Finally, the `usb` argument can be set to `true` to configure LED behavior so that it is only active when on USB power. This can be useful if you want to conserve power while your product is temporarily running on battery power.

**JSON**

```json
{
  "req": "card.monitor",
  "usb": true
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.monitor"}
req["usb"] = True

card.Transaction(req)
```

### Using Neo-Monitor Mode

The AUX `neo-monitor` mode allows you to replace the traditional 3 monocolor LEDs used in [Monitor mode](#using-monitor-mode) with NeoPixel LEDs, which will carry out the same basic functions using only a single AUX GPIO pin.

> See `neo-monitor` mode in action as part of the [Using LEDs and NeoPixels to Monitor Notecard Status](https://dev.blues.io/example-apps/samples/using-leds-and-neopixels-to-monitor-notecard-status.md) sample app.

Just like with `monitor` mode, the `AUX1` pin is configured as a test button, and `AUX2` is configured as the output for NeoPixel LED control.

- `AUX1` is configured active-`LOW` with a pullup and meant to be wired to a normally open momentary switch. When this button is pressed, a Note is added to the `_button.qo` Notefile and a manual sync is initiated.
- `AUX2` is where the NeoPixel LED's `DI` (Data In) pin connects to Notecard. It is held in a high-impedance state except when Notecard is actively driving the NeoPixel data signal.
- `AUX3` is a power-enable output for the NeoPixel. It is `HIGH` whenever any NeoPixel in the strip should be lit and `LOW` when all NeoPixels are "black", so battery-powered designs can switch the NeoPixel rail off when it is not needed (see the warning below).
- `AUX4` is reserved as a primary-battery indicator input. If your design uses a non-rechargeable primary battery, you can pull `AUX4` `LOW` while the device is running on the primary battery and `HIGH` (or leave it floating) otherwise; Notecard uses this signal to manage power. If you do not have a primary battery, leave `AUX4` disconnected.

`neo-monitor` is also one of the AUX modes that is compatible with [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md); see the [Required Wiring guide](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#required-wiring) for details.

As a NeoPixel can be programmed to display any color of the rainbow, this general purpose LED flashes the following colors:

- **white** will appear when the `AUX1` button is pressed.
- **gray** (may appear white) will flash acknowledgments when there is activity on Notecard (such as writing/reading to/from flash memory) or an active serial transaction.
- **yellow** will flash when Notecard is establishing a network connection.
- **green** will flash based on active network communications (after a network connection has been established).
- **orange** will flash when the GPS module is searching for satellites.
- **blue** will light when the GPS module is active.
- **magenta** will flash when Notecard is triangulating its location with WiFi access point data.
- **red** will turn on for two minutes if there is a failure to connect to the network.

To enable `neo-monitor` mode for a Notecard, send the following `card.aux` request:

**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"

card.Transaction(req)
```

If you would like to use multiple NeoPixels in a strip, pass the `card.aux` request a `count` of either `1`, `2`, or `5`. When using multiple NeoPixels, the Notecard automatically redistributes the "STATUS", "COMM BUSY", and "COMM ERROR" lights among the available NeoPixels.

To control NeoPixel brightness, use the `sensitivity` argument with a value between `1` (minimum brightness) and `100` (maximum brightness).

In addition, if you would like to reserve a single NeoPixel in the strip for direct management via the [card.led API](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-led), use the 1-based `offset` argument to specify which NeoPixel.

> **Note:**
>
> The `count` and `offset` arguments are not supported on Notecard for LoRa.

For example, the request below tells the Notecard to use five NeoPixels, and to reserve the second NeoPixel in the strip for use with the `card.led` API.

**JSON**

```json
{
  "req": "card.aux",
  "mode": "neo-monitor",
  "count": 5,
  "offset": 2
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "neo-monitor"
req["count"] = 5
req["offset"] = 2

card.Transaction(req)
```

> **Warning:**
>
> For NeoPixel-based designs that are battery-powered, it is critical that the NeoPixel be powered off when the connected NeoPixels are all "black". The Notecard helps by providing a signal on `AUX3`, which is `HIGH` when the NeoPixel should be powered on, and `LOW` when the NeoPixel should be powered off.
>
> However, do NOT attempt to power the NeoPixel from `AUX3` directly, because it is not capable of delivering the 60mA required and you will risk damaging the Notecard. Use `AUX3` to gate an external load switch or P-channel MOSFET that controls the NeoPixel rail.

### Using RGB-Monitor Mode

The AUX `rgb-monitor` mode allows you to monitor Notecard functions using a single RGB LED.

> See `rgb-monitor` mode in action as part of the [Using LEDs and NeoPixels to Monitor Notecard Status](https://dev.blues.io/example-apps/samples/using-leds-and-neopixels-to-monitor-notecard-status.md) sample app.

Just like with `monitor` and `neo-monitor` modes, the `AUX1` pin is configured as a test button and `AUX2-4` pins are configured as outputs for the RGB LED.

- `AUX1` is configured active-`LOW` with a pullup and meant to be wired to a normally open momentary switch. When this button is pressed, a note is added to the `_button.qo` Notefile and a manual sync is initiated.
- `AUX2` is wired to the red LED.
- `AUX3` is wired to the blue LED.
- `AUX4` is wired to the green LED.

As a single RGB LED can display many different colors, you may see any of the following colors flash:

- **white** will appear when the `AUX1` button is pressed, when there is activity on Notecard (such as writing/reading to/from flash memory), or during an active serial transaction.
- **yellow** will flash when Notecard is establishing a network connection.
- **green** will flash based on active network communications (after a network connection has been established).
- **cyan** will flash when there is GPS activity.
- **magenta** will flash when Notecard is searching for a GPS signal.
- **red** will turn on for two minutes if there is a failure to connect to the network.

To enable `rgb-monitor` mode on a Notecard, send the following `card.aux` request:

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "rgb-monitor"

card.Transaction(req)
```

### Combining Track Mode with Monitor Modes

If your application needs both the BME280 sensor support of [track mode](#using-aux-track-mode) and the technician-facing button/LEDs of one of the monitor modes, you can combine them in a single AUX configuration. Notecard supports three combined modes (noting the BME280 must be wired to Notecard's primary I2C bus rather than to the AUX pins):

- `track-monitor` combines [track](#using-aux-track-mode) with [monitor](#using-monitor-mode). The AUX pins follow the `monitor` pin map (button on `AUX1`, yellow / green / red LEDs on `AUX2`-`AUX4`).
- `track-neo-monitor` combines [track](#using-aux-track-mode) with [neo-monitor](#using-neo-monitor-mode). The AUX pins follow the `neo-monitor` pin map (button on `AUX1`, NeoPixel data on `AUX2`, NeoPixel power-enable on `AUX3`, `NPRIMARY` sense on `AUX4`).
- `track-rgb-monitor` combines [track](#using-aux-track-mode) with [rgb-monitor](#using-rgb-monitor-mode). The AUX pins follow the `rgb-monitor` pin map (button on `AUX1`, RGB LED on `AUX2`-`AUX4`).

To enable any of these modes, send a `card.aux` request with the corresponding `mode` value. For example, to combine track and monitor modes:

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "track-monitor"

card.Transaction(req)
```

`track-neo-monitor` accepts the same `count`, `offset`, and `sensitivity` arguments described in [Using Neo-Monitor Mode](#using-neo-monitor-mode). `track-neo-monitor` is also one of the AUX modes that is compatible with [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md); see the [Required Wiring guide](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#required-wiring) for details.

### Using DFU Mode

When using [Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md) you can use the `card.aux` request's DFU mode to enable Notecard's `AUX1` pin as a "DFU in progress" signal.

When enabled, the `AUX1` pin is active `LOW` whenever a DFU is in progress, otherwise it remains `HIGH`. The `card.aux` request's DFU mode can be used to provide a signal to a multiplexor (mux), an interrupt for firmware, or to power an LED that gives a visual indicator of when DFU is (or is not) in progress.

You can enable the Notecard's `card.aux` DFU mode using the request below:

**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"

card.Transaction(req)
```

> **Note:**
>
> Modern Notecards expose dedicated `ALT_DFU_*` pins on the edge connector that the loader uses to drive the host MCU's `BOOT`, `RESET`, and UART lines during ODFU, leaving the `AUX2`-`AUX4` pins free for other AUX-mode functionality. See [Required Wiring](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#required-wiring) for the full pin map.

### Turning AUX Mode Off

Disable AUX mode by setting the `mode` argument to `off` in a `card.aux` request:

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux"}
req["mode"] = "off"

card.Transaction(req)
```

## Using AUXEN, AUXRX, and AUXTX

The following sections describe various ways to use the [`card.aux.serial` request](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-aux-serial) to control the behavior of the Notecard's `AUXEN`, `AUXRX`, and `AUXTX` pins.

By default information is transmitted over AUX serial at a baud rate of `115200`, unless using GPS mode, in which case the default baud rate is `9600`. You can update the baud rate used with the `card.aux.serial` request's `rate` argument.

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "card.aux.serial"}
req["rate"] = 115200

card.Transaction(req)
```

> **Note:**
>
> **Using the AUX Pins for Tracing**
>
> In addition to the modes below, the Notecard AUX pins can be used for tracing on a separate bus from primary Notecard communications. While this does not require an explicit AUX mode setting, it does require a physical connection to `AUXRX`, `AUXTX`, and `AUXEN`, and the `AUXEN` must be pulled high to enable this mode.

### Using AUX Serial GPS Mode

If your product design requires concurrent usage of the cellular radio and GPS module, or if the existing GPS module on Notecard is not adequate for your needs, you may connect an external GPS to Notecard via the `AUXTX` and `AUXRX` pins. Using an external GPS/GNSS module allows you to run both the `hub.set` and `card.location.mode` requests in continuous mode, which is not possible with Notecard's internal GPS/GNSS module.

To start using an external GPS/GNSS module, create a `card.aux.serial` request with a `mode` of `"gps"`.

**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"

card.Transaction(req)
```

Next, connect the Notecard's `AUXRX` and `AUXTX` pins to your GPS module's `TX` and `RX` pins, respectively. If the Notecard successfully detects an external GPS/GNSS module, it will disable its internal GPS module and use the external one instead.

Note that the Notecard only powers the AUX serial port while it has decided that GPS should be running, which means [`card.location.mode`](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-location-mode) must be set to `continuous` or `periodic`. Learn more in [Using an External GPS with the Notecard](https://dev.blues.io/blog/using-an-external-gps-with-the-notecard.md).

> **Note:**
>
> **Match the baud rate of your GPS/GNSS module**
>
> In GPS mode the Notecard reads NMEA sentences over AUX serial at 9600 baud by default. If your module uses a different baud rate, the Notecard can't parse the incoming NMEA stream and `card.location` will remain at a `{gps-starting}/GPS waiting to start` status. In that case, set the `rate` argument on `card.aux.serial` to match your module:
>
> ```json
> {
>   "req": "card.aux.serial",
>   "mode": "gps",
>   "rate": 38400
> }
> ```

> **Note:**
>
> **Don't power your GPS/GNSS module directly from `AUX_EN`**
>
> When using an external GPS/GNSS module, `AUX_EN` is changed to an `OUTPUT` and that `OUTPUT` goes `HIGH` when the GPS is to be switched `ON`, and `LOW` when it should be switched `OFF`. It's important to NOT power the external GPS module directly using `AUX_EN`.

> **Tip:**
>
> **Already using a Starnote?** Starnote's GPS/GNSS module counts as an external GPS, and Notecard uses it automatically — so you get concurrent cellular and GPS without wiring anything to the AUX pins. In fact, setting an AUX serial `mode` of `"gps"` stops Notecard from using Starnote's GPS/GNSS module. Learn more at [Use Starnote as an External GPS](https://dev.blues.io/starnote/satellite-best-practices.md#use-starnote-as-an-external-gps).

[Low Bandwidth Design](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md "Low Bandwidth Design") [Updating Notecard Firmware](https://dev.blues.io/notecard/notecard-walkthrough/updating-notecard-firmware.md "Updating Notecard Firmware")