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.
-
The usage of
AUX1
-AUX4
is determined by thecard.aux
request, and the different modes you can use for that request are described in Using AUX1, AUX2, AUX3, and AUX4. -
The usage of
AUXEN
,AUXRX
, andAUXTX
is determined by thecard.aux.serial
request, and the different modes you can use for that request are described in Using AUXEN, AUXRX, and AUXTX.
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
- Using AUX Track Mode
- Using AUX Motion Mode
- Using AUX GPIO Mode
- Using Monitor Mode
- Using Neo-Monitor Mode
- Using DFU Mode
- 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.
{
"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 theSDA
orSDI
pin on the sensor.AUX4
should be connected to theSCL
orSCK
pin on the sensor.GND
should be connected to theGND
pin on the sensor.BAT
should be connected to theEN
,ENABLE
, or3VO
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 theAUX2
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 theAUX3
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 digitalHIGH
. After the device is no longer in motion, the signal is returned toLOW
.
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 aHIGH
output.low
to set the pin as aLOW
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 ascount
mode, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating.count-pullup
Same ascount
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. Passing0
will total into a single sample.max
- The maximum number of samples to take. Counts above this value are added to the final sample. Passing0
or omitting this value will provide a single incrementing count of rising edges on the pin.start
- Set totrue
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.
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 theAUX1
"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'sDI
(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:
- yellow ("STATUS") to acknowledge when the
AUX1
button is pressed. - white ("SERIAL") when there is an active serial transaction.
- a series of green ("COMM BUSY") LED blinks as the newly created
_button.qo
Notefile is successfully sent to Notehub. - blue ("GPS") when the GPS module is active.
- If there is a failure to connect to a network, the LED flashes red ("COMM ERROR") continuously for two minutes, followed by a four second flash once per minute thereafter.
To enable neo-monitor mode for a Notecard, send the following card.aux
request:
{
"req": "card.aux",
"mode": "neo-monitor"
}
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)
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)
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
There are scenarios where the onboard GPS antenna of the Notecarrier is not adequate to identify GPS satellites (e.g. if the Notecarrier does not have a clear view of the southern sky). To accommodate these situations, an external GPS module such as the Adafruit Ultimate GPS or Quectel L86 can be used (though since NMEA sentences are standardized, many GPS modules will work).
To start using an external GPS/GNSS module call the 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.
Using an external GPS/GNSS module is the only way to run both the hub.set
and
card.location.mode
requests in continuous mode.