The Notecard is designed to be battery operated, with low current consumption, making it an ideal choice for low power applications. Because of its low power design, in many applications, a host processor and its peripherals will be larger contributors to power drain.
To help designers and developers build low power applications, the Notecard implements two tools:
- A power management technique that allows firmware developers to regulate modem activity on the Notecard as a function of available energy.
- A design technique that allows the Notecard to shut the host processor down completely, for dramatic power savings.
In battery-operated systems, and in particular those using energy harvesting
approaches like solar power, the energy available to a processor and its
peripherals rises and falls, sometimes between extreme levels. The Notecard
is extremely low power in its idle state, and when staging data with
note.add requests, but uses a nontrivial amount of energy when the modem is
on and transmitting to and receiving data from the cellular network.
When designing a system that utilizes the Notecard, its a good idea to vary
Notehub connection intervals based on the energy available to the system
as monitored through a host's use of a fuel gauge or Power management integrated
circuit (PMIC). Using the information available to the host, you can use
hub.set to configure the Notecard's connection mode, as well as
voltage-variable settings for inbound and outbound data synchronization.
For example, when ample energy is available in the system, you may prefer to sync outbound Notes each hour and process inbound data every two hours.
{
"req": "hub.set",
"mode": "periodic",
"outbound": 60,
"inbound": 120
}
In a hub.set request, the outbound is the maximum latency between changes
made at the Notecard (Notes or environment variables), and when the Notecard
attempts to sync changes to Notehub. inbound is the maximum latency between
syncs with the Notehub to check for changes to Notefiles and environment
variables that need to propagate to the Notecard.
If, as the product is running, the host detects that available energy is low,
a subsequent hub.set request can be issued to adjust the inbound and outbound
sync intervals accordingly. For instance, the following request instructs the
Notecard to sync outbound Notes every eight hours, and process inbound data once
per day.
{
"req": "hub.set",
"mode": "periodic",
"outbound": 480,
"inbound": 1440
}
In extreme cases, available power may be so low that you need to instruct the
Notecard to keep the modem off completely, and until instructed otherwise. To
do this, use the off mode.
{
"req": "hub.set",
"mode": "off"
}
Each of the examples above require the host to track power levels and manually
intervene to instruct the Notecard to modify its sync behaviors. Alternatively,
the Notecard can automatically adjust its sync behavior with voltage-variable
arguments in a hub.set request. Instead of using outbound and inbound to
specify sync intervals, you can use voutbound and vinbound.
Both arguments expect semicolon-delimited string values with intervals that correspond to a battery state. The pre-defined Notecard battery states are:
maxhighnormallowdead
When the Notecard's power source is in a given state, it will adjust the period
based on the values defined in the voutbound and vinbound strings. Note: a
0 value for any state disables that timer as a trigger for sync activity.
For instance, if you wanted to sync outbound every 30 minutes and inbound every hour when the battery is at full strength, and throttle back as available power decreases, send a request like this:
{
"req": "hub.set",
"mode": "periodic",
"voutbound": "usb:30;high:60;normal:90;low:120;dead:0",
"vinbound": "usb:60;high:120;normal:240;low:480;dead:0"
}
You can confirm these settings with a hub.get request:
{
"voutbound": "usb:30;high:60;normal:90;low:120;dead:0",
"vinbound": "usb:60;high:120;normal:240;low:480;dead:0",
"mode": "periodic",
"host": "a.notefile.net",
"product": "org.coca-cola.soda.vending-machine.v2",
"device": "dev:0000000000000"
}
If needed in your design, the Notecard can also manage the power state of its
host using the card.attn request.
warningAdditional Connection Required
As with the other uses of card.attn, this feature requires an
additional physical connection between the Notecard and host beyond the default
I2C or Serial connection for communication. In order to leverage the host power
management feature described here, the Notecard ATTN pin must be wired to an
EN or regulator pin on the host.
To utilize this feature, upon each boot, the host sends card.attn request
to determine if the host is in an initial boot, or is being awakened from sleep.
First, the host configures this mode by passing sleep into the mode argument
of a card.attn request, as well as a number of seconds to sleep.
{
"req": "card.attn",
"mode": "sleep",
"seconds": 3600
}
When this request is received, the Notecard pulls the ATTN pin LOW, and
the host can respond by placing itself into a sleep or low power mode.
After the seconds interval has elapsed, the ATTN pin is pulled HIGH.
Upon restart, the host should send a no argument
card.attn request. The response will include the value timeout to indicate
a timeout as the reason for the pulling the pin HIGH.
{
"files": [
"timeout"
],
"set": true
}
If nonvolatile memory is at a premium or nonexistent on the host, the Notecard
can hold data in memory on behalf of the host in the form of a Base64-encoded
string. This string should be provided with a payload argument during the
sleep mode call to card.attn.
{
"req": "card.attn",
"mode": "sleep",
"seconds": 3600,
"payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
}
When the host reawakens, the payload is retrieved by setting
start to true in a card.attn request. The response object also
includes the UNIX Epoch time at which the payload was stored.
{
"req": "card.attn",
"start": true
}
{
"payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ==",
"files": [
"timeout"
],
"time": 1599064794,
"set": true
}
In some hardware designs, the Notecard's V+ will be connected directly to
a battery. This approach is ideal for ensuring that potential current spikes
during wireless transmission are served directly from the product's power
source. What's more, the low standby power draw of the Notecard minimizes
the potential downsides of this approach.
To measure the voltage on the Notecard's V+ pin, and obtain historical voltage
information, use the card.voltage request.
{"req": "card.voltage"}This request will return an object with the current power mode (or usb if
the Notecard is being powered by a USB connection), the current
voltage value, and the number of hours
available for the Notecard to use for trend analysis. It will also return the
minimum (vmin), maximum (vmax), and average (vavg) voltages during
that time frame. Finally, the object includes values indicating the
moving average in voltage over the past 24 hours (daily), 7 days (weekly),
and 30 days (monthly), if those values are relevant to the time period
analyzed.
{
"mode": "usb",
"value": 5.279199405944246,
"hours": 772,
"vmin": 4.48,
"vmax": 5.28,
"vavg": 4.910674846625767,
"daily": 0.13,
"weekly": 0.12,
"monthly": 0.11
}
A card.voltage request can be customized to analyze a developer-defined number
of hours with the hours argument. This argument can be any whole number up
to 720 (30 days) and it defaults to use all of the data available to the
Notecard.
{
"req": "card.voltage",
"hours": 8
}
You can also use the offset argument to instruct the Notecard to go back
a set number of hours into the past before starting analysis.
{
"req": "card.voltage",
"hours": 24,
"offset": 48
}
Finally, you can use the vmax and vmin arguments to tell the Notecard to
ignore voltage measurements above or below a certain level, respectively.
{
"req": "card.voltage",
"hours": 300,
"vmax": 5,
"vmin": 2.2
}
Sometimes a product will be deployed in environments where extreme temperatures
may affect battery performance. In these situations, you may need to know the
temperature within the electronics enclosure. The Notecard has a calibrated
absolute temperature sensor that can be used to measure the temperature
around the Notecard with a card.temp request.
{ "req": "card.temp" }This request returns an object with the temperature in degrees centigrade,
and a calibration value. The calibration value, taken together with the
temp value means that the Notecard measured a value of 29.3125, which was
adjusted to 26.3125 before being returned.
{
"value": 26.3125,
"calibration": -3
}
Notecard temperature readings are performed by the device's onboard
accelerometer. If the accelerometer is disabled with a
card.motion.mode request,
card.temp will return an error.
{ "err": "temperature is not available if accelerometer was disabled with card.motion.mode" }
The Notecard includes a three-axis accelerometer that can be used to detect
the orientation of the module or when the Notecard is in motion with a
card.motion request. When passed with no arguments, the Notecard responds
with a count of the number of motion events since the last time the request
was made, a motion field with the UNIX Epoch time of the last motion
event, and an alert field if a free-fall was detected since the last call.
The response will also include the current device orientation in the status
field. The orientation will be one of the following values:
face-upface-downportrait-upportrait-downlandscape-rightlandscape-left
> { "req": "card.motion" }{
"status": "face-down",
"motion": 1599073299,
"count": 1
}
By default, card.motion returns a single orientation status and a count of
motion events. You can also use the minutes argument to specify an amount of
time to sample for buckets of movement.
{
"req": "card.motion",
"minutes": 5
}
When card.motion is used in this manner, the Notecard will return a
movements field of movement buckets (up to 250 samples). Each character is
a base 36 value (0-9, A-Z and * to indicate a value greater than 35) that
shows the most-recent to least-recent number of movements for each bucket
during the amount of time sampled. A seconds field, which signifies the
size of each bucket, is also returned.
{
"count": 17,
"seconds": 5,
"status": "face-up",
"movements": "520000000000000000000A",
"motion": 1599074347
}
In the example above, the Notecard detected five movements in the first (or, most-recent) bucket, two in the seconds, and ten in the last. No movement was detected for all of the other buckets.
If you need finer-grained control over motion tracking on the Notecard, use the
card.motion.mode request. With this request, you can stop motion monitoring
with the stop argument. Once sent, subsequent calls to card.motion return
an empty JSON object ({}).
{
"req": "card.motion.mode",
"stop": true
}
Use the start argument to turn motion monitoring back on:
{
"req": "card.motion.mode",
"start": true
}
The Notecard uses its onboard accelerometer to perform temperature readings in
response to card.temp requests.
If you need this feature in your app, make sure that card.motion.mode
is active or card.temp requests will return an error.
You can also use the seconds argument to specify a period for each bucket
when using the minutes argument with card.motion. For instance, the
following request sets the bucket size to 30 seconds:
{
"req": "card.motion.mode",
"seconds": 30
}
If you then perform another request to card.motion and set the minutes
argument to 2, the response will return a movements string with four
characters, one for each 30 second bucket of motion.
> { "req": "card.motion", "minutes": 2}{
"seconds": 30,
"status": "face-up",
"movements": "1010",
"motion": 1599074347
}
Finally, if you need to adjust the sensitivity of the accelerometer, use the
sensitivity field. This field takes a number between 1 (the default) and 5
that corresponds with a sensitivity setting on the built-in accelerometer. The
higher the number, the more sensitive the Notecard's accelerometer will be.
1for 7.808G2for 3.904G3for 1.952G4for 0.976G5for 0.244G
{
"req": "card.motion.mode",
"sensitivity": 3
}
To automatically store motion events as Notes in a Notefile, use the
card.motion.track request and the start argument. If successful, calls
to this request return an empty JSON object ({}).
{
"req": "card.motion.track",
"start": true
}
By default, the Notecard stores motion events in a Notefile called _motion.qo.
You can specify your own Notefile with the file argument. You can also use
the minutes to specify the maximum frequency at which Notes will be recorded,
count for the number of most recent buckets to examine, and threshold to
specify the number of buckets that must indicate motion in order for a tracking
Note to be added.
{
"req": "card.motion.track",
"file": "movements.qo",
"minutes": 5,
"count" 10,
"threshold": 2
}
To stop automatic motion capture, use the stop argument.
{
"req": "card.motion.track",
"stop": true
}
Finally, use the card.motion.sync to configure automatic syncs to Notehub
based on movement. Use the start argument to turn this feature on:
{
"req": "card.motion.sync",
"start": true
}
And stop to turn it off:
{
"req": "card.motion.sync",
"stop": true
}
For finer-grained control, use the minutes argument to specify the maximum
frequency at which a sync will be initiated, count for the number of most
recent buckets to examine, and threshold to specify the number of buckets that
must indicate motion in order for sync to be triggered.
{
"req": "card.motion.sync",
"start": true,
"minutes": 20,
"count": 20,
"threshold": 5
}
A number of requests in the Notecard API, like hub.set and card.location
can be configured to use voltage-variable behaviors to perform battery-
intensive actions like a sync or tracking location with GPS. If your product
battery (a LiPo, for instance) allows you to use voltage as a proxy for
the available energy left in the battery, you can use voltage mode string
in a card.voltage request to specify voltage values that correspond to the
following battery states:
maxhighnormallowdead
For instance, if powering a project with a LiPo battery, you'd use the
following for the mode argument:
{
"req": "card.voltage",
"mode": "usb:4.6;high:4.0;normal:3.5;low:3.1;dead:0"
}
If your application needs to use a similar approach for timing intervals
against a connected sensor or peripheral, you can use the name argument
to specify an environment variable. This variable can then be set in Notehub
to override application default timing values.
{
"req": "card.voltage",
"mode": "usb:4.6;high:4.0;normal:3.5;low:3.1;dead:0",
"name": "sensor-timings"
}
Finally, you can customize the value field returned in a card.voltage
request with the vvalue argument, which follows the same pattern as the mode
field.
{
"req": "card.voltage",
"vvalue": "usb:1;high:2;normal:4;low:8;dead:0"
}
To aid you in setting voltage thresholds in your projects, the mode
argument also supports a few keywords. Each is a shorthand to
set the recommended voltage thresholds that correspond to a given power
solution.
"lipo"for LiPo batteries. Equivalent to"usb:4.6;high:4.0;normal:3.5;low:3.1;dead:0"."l91"for L91 batteries. Equivalent to"high:5.1;normal:4.8;low:4.2;dead:3.9"."alkaline"for Alkaline batteries. Equivalent to"usb:4.6;high:4.2;normal:3.6;low:3.3;dead:3.0"."default"for the default behavior. Equivalent to"normal:2.5;dead:0".
{ "req": "card.voltage", "mode": "lipo" }
The mode argument also provides a capability for querying
voltage thresholds currently set on the Notecard when a question mark
"?" is provided as the argument value.
{ "req": "card.voltage", "mode": "?" }
The request above will return an object similar to the following if the Notecard is operating in LiPo mode.
{ "mode": "usb:4.6;high:4.0;normal:3.5;low:3.1;dead:0", "value":4.9861173510647878 }
If the Notecard is sampling in periodic mode and you want to minimize the impact
of GPS on the battery powering your project, use the vseconds argument to
instruct the device to take the charge of your battery into
consideration when obtaining GPS readings.
The vseconds argument should be a semicolon-delimited string that defines a
period for each state of your battery. The pre-defined Notecard battery states
are:
usbhighnormallowdead
When the Notecard's battery is in a given state, it will adjust the period based
on the values defined in the vseconds string.
For instance, if you wanted to sample GPS once per hour when the battery
is full, but scale back the sample rate as the power decreases, you'd provide
a vseconds string like this:
{
"req": "card.location.mode",
"mode": "periodic",
"vseconds": "usb:3600;high:14400;normal:43200;low:86400;dead:0"
}
This will return an object confirming that the Notecard is in periodic mode and that GPS should be sampled at a voltage-variable rate:
{
"mode": "periodic",
"vseconds": "usb:3600;high:14400;normal:43200;low:86400;dead:0"
}
To set the sample rate from a voltage variable rate back to a set rate,
set vseconds to - and provide a new value for the seconds argument:
{
"req": "card.location.mode",
"mode": "periodic",
"vseconds": "-",
"seconds": 60
}
This will return an object confirming that the Notecard is in periodic mode and sample GPS at a set rate:
{
"mode": "periodic",
"seconds": 60
}
