homechevron_rightDocschevron_rightNotecardchevron_rightNotecard Walkthroughchevron_rightWorking with the Notecard AUX Pins

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 change depending on the AUX mode configured on the Notecard.

note

The Notecard AUX pins are used during Notecard Outboard Firmware Updates, and some Notecard AUX modes may interfere with Outboard Firmware Updates. For more information see the Outboard Firmware Updates' required wiring, and if you have questions feel free to reach out in our forum .

Using AUX1, AUX2, AUX3, and AUX4

The following sections describes various ways to use the card.aux request to control the behavior of the Notecard’s AUX1 - AUX4 pins.

Determining the Current AUX Mode

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

{
  "req": "card.aux"
}
J *req = NoteNewRequest("card.aux");

NoteRequest(req);
req = {"req": "card.aux"}

card.Transaction(req)

By default, the default Notecard AUX mode is off.

{ "mode": "off" }

Using AUX Track Mode

AUX track mode allows you to enhance Notes in the _track.qo Notefile 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.

The BME280 must also be wired to use its secondary I2C address if it conflicts with the Notecard's default I2C address of 0x17.

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

{
  "req": "card.aux",
  "mode": "track"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "track");

NoteRequest(req);
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.

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:

{
  "req": "card.aux",
  "mode": "motion"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "motion");

NoteRequest(req);
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 ocurred while the Notecard is in motion. When the input control sends a pulse to the AUX3 pin, a counter is incremented and added to the database on the next tracking event or heartbeat.
  • AUX4 is an output signal used to indicate that the Notecard has detected motion. Whenever the device has been in motion for several seconds, AUX4 is set to digital HIGH. After the device is no longer in motion, the signal is returned to LOW.

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

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:

{
  "req": "card.aux",
  "mode": "gpio"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "gpio");

NoteRequest(req);
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:

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": ["off", "low", "high", "input"]
}
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);
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.

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

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": ["", "", "", ""]
}
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);
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
    "", # AUX1
    "", # AUX2
    "", # AUX3
    "" # AUX4
  ]

card.Transaction(req)
{
 "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:

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": ["low", "input-pulldown", "input-pulldown", "input-pulldown"],
  "sync": true,
  "file": "gpio.qo"
}
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);
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:

{
 "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 (Added in v3.4.1).

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

  • seconds - The number of seconds to include in a sample. Passing 0 will total into a single sample.
  • max - The maximum number of samples to take. Counts above this value are added to the final sample. Passing 0 or omitting this value will provide a single incrementing count of rising edges on the pin.
  • start - Set to true to reset counters and start incrementing.
{
  "req": "card.aux",
  "mode": "gpio",
  "usage": ["off", "low", "high", "count"],
  "seconds": 2,
  "max": 5,
  "start": true
}
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);
req = {"req": "card.aux"}
req["mode"] = "gpio"
req["usage"] = [
    "off", # AUX1
    "low", # AUX2
    "high", # AUX3
    "input" # 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.

{
 "mode": "gpio",
 "state": [
  {},
  {
   "high": true
  },
  {
   "low": 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, 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 it's previous state, which means if you send a LOW/HIGH pulse to a pin that is already LOW/HIGH there will be no observed effect on the Notecard.

AUX GPIO pulses are NOT stored in non-volatile memory in the Notecard, because they are ephemeral events. If the Notecard should happen to reboot during the duration of the pulse, the GPIO outputs would revert to their long term state.

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

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

  • AUX1 is configured to count and is currently LOW.
  • AUX2 is currently LOW (it may be an input or an output).
  • AUX3 is currently configured to be OFF (high impedance).
  • AUX4 is currently 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 sample app.

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

{
  "req": "card.aux",
  "mode": "monitor"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "monitor");

NoteRequest(req);
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 as general purpose LED that flashes an acknowledgement when the AUX1 "COMM TEST" button is pressed.
  • AUX3 is a green LED referred to as "COMM BUSY." This LED blinks in a pattern based on communications status.
  • AUX4 is a red LED referred to as "COMM ERROR." This LED turns on continuously for two minutes after there is a failure to connect to a network. To conserve battery life, after the first two minutes the LED turns on for four seconds each minute.

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

{
  "req": "card.monitor",
  "mode": "green",
  "count": 5
}
J *req = NoteNewRequest("card.monitor");
JAddStringToObject(req, "mode", "green");
JAddNumberToObject(req, "count", 5);

NoteRequest(req);
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:

{
  "req": "card.monitor",
  "mode": "green",
  "count": 0
}
J *req = NoteNewRequest("card.monitor");
JAddStringToObject(req, "mode", "green");
JAddNumberToObject(req, "count", 0);

NoteRequest(req);
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.

{
  "req": "card.monitor",
  "usb": true
}
J *req = NoteNewRequest("card.monitor");
JAddBoolToObject(req, "usb", true);

NoteRequest(req);
req = {"req": "card.monitor"}
req["usb"] = True

card.Transaction(req)

Using Neo-Monitor Mode

As of v3.5.1 of the Notecard firmware, the AUX Neo-Monitor mode allows you to replace the traditional 3 monocolor LEDs used in Monitor mode with 1, 2, or 5 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 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 the Notecard.

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

{
  "req": "card.aux",
  "mode": "neo-monitor"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "neo-monitor");

NoteRequest(req);
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.

In addition, if you would like to reserve a single NeoPixel in the strip for direct management via the card.led API, use the 1-based offset argument to specify which NeoPixel.

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.

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

NoteRequest(req);
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.

Using DFU Mode

When using Notecard Outboard Firmware Update you can use the card.aux request's DFU mode to enable the Notecard's AUX1 pin.

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:

{
  "req": "card.aux",
  "mode": "dfu"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "dfu");

NoteRequest(req);
req = {"req": "card.aux"}
req["mode"] = "dfu"

card.Transaction(req)

Turning AUX Mode Off

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

{
  "req": "card.aux",
  "mode": "off"
}
J *req = NoteNewRequest("card.aux");
JAddStringToObject(req, "mode", "off");

NoteRequest(req);
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 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.

{
  "req": "card.aux.serial",
  "rate": 115200
}
J *req = NoteNewRequest("card.aux");
JAddNumberToObject(req, "rate", 115200);

NoteRequest(req);
req = {"req": "card.aux"}
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 is the only way to run both the hub.set and card.location.mode requests in continuous mode.

note

Learn more about using an external GPS/GNSS module with Notecard in this blog post.

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

{
  "req": "card.aux.serial",
  "mode": "gps"
}
J *req = NoteNewRequest("card.aux.serial");
JAddStringToObject(req, "mode", "gps");

NoteRequest(req);
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

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.