Low Power Design

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.

note

As a low-power device (e.g. the Notecard Cellular consumes only ~8µA@5V when idle), the Notecard was built to be continuously powered. This is important to know because certain features of the Notecard require the current time, which is established upon the Notecard successfully connecting to Notehub upon startup.

Consult the Low-Power Hardware Design Application Note for more details on how to design a low-power system that uses the Notecard for wireless communications.

Modem Power Management

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 a network.

note

The Notecard will never go into low power (~8µA@5V) mode if VUSB is present (M.2 pin 13), or if AUX_EN (pin 56) is pulled HIGH (3v3).

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
}

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "outbound", 60);
JAddNumberToObject(req, "inbound", 120);

NoteRequest(req);

req = {"req": "hub.set"}
req["mode"] = "periodic"
req["outbound"] = 60
req["inbound"] = 120

card.Transaction(req)

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
}

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "periodic");
JAddNumberToObject(req, "outbound", 480);
JAddNumberToObject(req, "inbound", 1440);

NoteRequest(req);

req = {"req": "hub.set"}
req["mode"] = "periodic"
req["outbound"] = 480
req["inbound"] = 1440

card.Transaction(req)

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

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "off");

NoteRequest(req);

req = {"req": "hub.set"}
req["mode"] = "off"

card.Transaction(req)

Voltage-Variable Sync Behavior

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.

warning

Setting voltage-variable values is not supported on Notecard for LoRa or Notecard XP.

Both arguments expect semicolon-delimited string values with intervals that correspond to a battery state. The pre-defined Notecard battery states are:

• usb
• high
• normal
• low
• dead

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.

Using 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"
}

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "periodic");
JAddStringToObject(req, "voutbound", "usb:30;high:60;normal:90;low:120;dead:0");
JAddStringToObject(req, "vinbound", "usb:60;high:120;normal:240;low:480;dead:0");

NoteRequest(req);

req = {"req": "hub.set"}
req["mode"] = "periodic"
req["voutbound"] = "usb:30;high:60;normal:90;low:120;dead:0"
req["vinbound"] = "usb:60;high:120;normal:240;low:480;dead:0"

card.Transaction(req)

Likewise, you can use a shorter syntax to express "if USB-powered, sync every 30 minutes, otherwise sync every 60 minutes" with "usb:30;60".

You can confirm these settings with the response from 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": "com.your-company.your-name:your_product",
 "device": "dev:0000000000000"
}

USB/Line Power Variable Sync Behavior

When in development, you may want to maintain a continuous connection to Notehub when your device is USB/line-powered, but return to periodic, minimum, or off sync modes when USB/line power is disconnected. This capability is available as of the LTS 4.1.1 Notecard firmware release.

Fallback to Periodic Mode

The uperiodic argument in a hub.set request configures the Notecard to use periodic mode when USB/line power is disconnected.

In the following example, when the Notecard has USB/line power it operates in continuous mode, with inbound Notefiles synced immediately and outbound Notefiles synced every minute. If USB/line power is disconnected, the Notecard changes to periodic mode and syncs Notefiles every hour.

{
  "req": "hub.set",
  "mode": "continuous",
  "sync": true,
  "voutbound": "usb:1;60",
  "uperiodic": true
}

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "continuous");
JAddBoolToObject(req, "sync", true);
JAddStringToObject(req, "voutbound", "usb:1;60");
JAddBoolToObject(req, "uperiodic", true);

NoteRequest(req);

req = {"req": "hub.set"}
req["mode"] = "continuous"
req["sync"] = True
req["voutbound"] = "usb:1;60"
req["uperiodic"] = True

card.Transaction(req)

Fallback to Minimum or Off Modes

Likewise, you can fallback to minimum mode or off mode when USB/line power is disconnected with the umin or uoff arguments, respectively.

{
  "req": "hub.set",
  "mode": "continuous",
  "sync": true,
  "voutbound": "usb:1;60",
  "umin": true
}

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "continuous");
JAddBoolToObject(req, "sync", true);
JAddStringToObject(req, "voutbound", "usb:1;60");
JAddBoolToObject(req, "umin", true);

NoteRequest(req);

req = {"req": "hub.set"}
req["mode"] = "continuous"
req["sync"] = True
req["voutbound"] = "usb:1;60"
req["umin"] = True

card.Transaction(req)

Host Power Management

If needed in your design, the Notecard can also manage the power state of its connected host MCU using the card.attn request.

warning

Additional 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
}

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

NoteRequest(req);

req = {"req": "card.attn"}
req["mode"] = "sleep"
req["seconds"] = 3600

card.Transaction(req)

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
}

Optional: In order to disable the host RESET that is normally performed on the host MCU when the Notecard starts up, use the "stop":true argument in a card.dfu request.

{
  "req": "card.dfu",
  "stop": true
}

J *req = NoteNewRequest("card.dfu");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);

req = {"req": "card.dfu"}
req["stop"] = True

card.Transaction(req)

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=="
}

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

NoteRequest(req);

req = {"req": "card.attn"}
req["mode"] = "sleep"
req["seconds"] = 3600
req["payload"] = "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="

card.Transaction(req)

When the host reawakens, the payload is retrieved by setting start to true in a card.attn request.

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

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

NoteRequest(req);

req = {"req": "card.attn"}
req["start"] = True

card.Transaction(req)

The response object also includes the UNIX Epoch time at which the payload was stored.

{
 "payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ==",
 "files": [
  "timeout"
 ],
 "time": 1599064794,
 "set": true
}

Voltage Monitoring

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 with "mode":"?".

{
  "req": "card.voltage",
  "mode": "?"
}

J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "?");

NoteRequest(req);

req = {"req": "card.voltage"}
req["mode"] = "?"

rsp = card.Transaction(req)

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.

As of Notecard firmware v3.2.1, four additional boolean values may appear in the response if the Notecard is connected to USB power ("usb": true), the cellular modem is active ("cell": true), the Wi-Fi radio is active ("wifi": true), and/or the GPS module is active ("gps": true).

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.

{
 "usb": true,
 "hours": 120,
 "mode": "usb",
 "value": 5.112190219747135,
 "vmin": 4,
 "vmax": 4,
 "vavg": 4
}

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
}

J *req = NoteNewRequest("card.voltage");
JAddNumberToObject(req, "hours", 8);

NoteRequest(req);

req = {"req": "card.voltage"}
req["hours"] = 8

rsp = card.Transaction(req)

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
}

J *req = NoteNewRequest("card.voltage");
JAddNumberToObject(req, "hours", 24);
JAddNumberToObject(req, "offset", 48);

NoteRequest(req);

req = {"req": "card.voltage"}
req["hours"] = 24
req["offset"] = 48

rsp = card.Transaction(req)

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": 4,
  "vmin": 2.2
}

J *req = NoteNewRequest("card.voltage");
JAddNumberToObject(req, "hours", 300);
JAddNumberToObject(req, "vmax", 4);
JAddNumberToObject(req, "vmin", 2.2);

NoteRequest(req);

req = {"req": "card.voltage"}
req["hours"] = 300
req["vmax"] = 4
req["vmin"] = 2.2

rsp = card.Transaction(req)

Temperature Monitoring

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

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

NoteRequest(req);

req = {"req": "card.temp"}

rsp = card.Transaction(req)

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
}

note

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.

JSON

COPY

{
  "err": "temperature is not available if accelerometer was disabled with card.motion.mode"
}

Motion Monitoring

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.

note

Motion monitoring is not supported on the Notecard LoRa.

{
  "req": "card.motion"
}

J *req = NoteNewRequest("card.motion");

NoteRequest(req);

req = {"req": "card.motion"}

rsp = card.Transaction(req)

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-up
• face-down
• portrait-up
• portrait-down
• landscape-right
• landscape-left

{
  "status": "face-down",
  "motion": 1599073299,
  "count": 1
}

Retrieving Motion Results Over a Time Period

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
}

J *req = NoteNewRequest("card.motion");
JAddNumberToObject(req, "minutes", 5);

NoteRequest(req);

req = {"req": "card.motion"}
req["minutes"] = 5

rsp = card.Transaction(req)

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 second, and ten in the last. No movement was detected for all of the other buckets.

Configuring Motion Monitoring

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
}

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

NoteRequest(req);

req = {"req": "card.motion.mode"}
req["stop"] = True

card.Transaction(req)

Use the start argument to turn motion monitoring back on:

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

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

NoteRequest(req);

req = {"req": "card.motion.mode"}
req["start"] = True

card.Transaction(req)

note

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
}

J *req = NoteNewRequest("card.motion.mode");
JAddNumberToObject(req, "seconds", 30);

NoteRequest(req);

req = {"req": "card.motion.mode"}
req["seconds"] = 30

card.Transaction(req)

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
}

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

NoteRequest(req);

req = {"req": "card.motion"}
req["minutes"] = 2

rsp = card.Transaction(req)

{
  "seconds": 30,
  "status": "face-up",
  "movements": "1010",
  "motion": 1599074347
}

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

• -1: 1.6Hz, +/-2G range, 1 milli-G sensitivity (default)
• 1: 25Hz, +/- 16G range, 7.8 milli-G sensitivity
• 2: 25Hz, +/- 8G range, 3.9 milli-G sensitivity
• 3: 25Hz, +/- 4G range, 1.95 milli-G sensitivity
• 4: 25Hz, +/- 2G range, 1 milli-G sensitivity
• 5: 25Hz, +/- 2G range, 0.25 milli-G sensitivity

{
  "req": "card.motion.mode",
  "sensitivity": 3
}

J *req = NoteNewRequest("card.motion.mode");
JAddNumberToObject(req, "sensitivity", 3);

NoteRequest(req);

req = {"req": "card.motion.mode"}
req["sensitivity"] = 2

card.Transaction(req)

Automatic Motion Capture

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
}

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

NoteRequest(req);

req = {"req": "card.motion.track"}
req["start"] = True

card.Transaction(req)

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",
  "start": true,
  "minutes": 5,
  "count": 10,
  "threshold": 2,
  "file": "movements.qo"
}

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

NoteRequest(req);

req = {"req": "card.motion.track"}
req["start"] = True
req["minutes"] = 5
req["count"] = 10
req["threshold"] = 2
req["file"] = "movements.qo"

card.Transaction(req)

With the now argument set to true, the Notecard will immediately create a _motion.qo event if the orientation of the Notecard changes (overriding the minutes setting).

{
  "req": "card.motion.track",
  "start": true,
  "minutes": 5,
  "count": 10,
  "threshold": 2,
  "file": "movements.qo",
  "now": true
}

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

NoteRequest(req);

req = {"req": "card.motion.track"}
req["start"] = True
req["minutes"] = 5
req["count"] = 10
req["threshold"] = 2
req["file"] = "movements.qo"
req["now"] = True

card.Transaction(req)

To stop automatic motion capture, use the stop argument.

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

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

NoteRequest(req);

req = {"req": "card.motion.track"}
req["stop"] = True

card.Transaction(req)

Configuring Sync on Notecard Motion

Finally, use the card.motion.sync to configure automatic syncs to Notehub based on Notecard movement. Use the start argument to turn this feature on:

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

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

NoteRequest(req);

req = {"req": "card.motion.sync"}
req["start"] = True

card.Transaction(req)

And stop to turn it off:

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

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

NoteRequest(req);

req = {"req": "card.motion.sync"}
req["stop"] = True

card.Transaction(req)

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
}

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

NoteRequest(req);

req = {"req": "card.motion.sync"}
req["start"] = True
req["minutes"] = 20
req["count"] = 20
req["threshold"] = 5

card.Transaction(req)

Customizing Voltage-Variable Behaviors

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, use the card.voltage API's mode argument to specify voltage values that correspond to the following battery states:

• usb
• high
• normal
• low
• dead

For instance, if powering a project with a LiPo battery, you'd use the following for the mode argument:

{
  "req": "card.voltage",
  "mode": "lipo"
}

J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "lipo");

NoteRequest(req);

req = {"req": "card.voltage"}
req["mode"] = "lipo"

rsp = card.Transaction(req)

Consult the card.voltage API docs for a complete listing of the mode options.

If you need to customize the battery state voltage levels, you can use the mode field as well.

{
  "req": "card.voltage",
  "mode": "usb:4.6;high:4.2;normal:3.6;low:0"
}

J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "usb:4.6;high:4.2;normal:3.6;low:0");

NoteRequest(req);

req = {"req": "card.voltage"}
req["mode"] = "usb:4.6;high:4.2;normal:3.6;low:0"

rsp = card.Transaction(req)

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": "lipo",
  "name": "sensor-timings"
}

J *req = NoteNewRequest("card.voltage");
JAddStringToObject(req, "mode", "lipo");
JAddStringToObject(req, "name", "sensor-timings");

NoteRequest(req);

req = {"req": "card.voltage"}
req["mode"] = "lipo"
req["mode"] = "sensor-timings"

rsp = card.Transaction(req)

Sampling at Voltage-variable Intervals

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:

• usb
• high
• normal
• low
• dead

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

J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddStringToObject(req, "vseconds", "usb:3600;high:14400;normal:43200;low:86400;dead:0");

NoteRequest(req);

req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["vseconds"] = "usb:3600;high:14400;normal:43200;low:86400;dead:0"

rsp = card.Transaction(req)

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
}

J *req = NoteNewRequest("card.location.mode");
JAddStringToObject(req, "mode", "periodic");
JAddStringToObject(req, "vseconds", "-");
JAddNumberToObject(req, "seconds", 60);

NoteRequest(req);

req = {"req": "card.location.mode"}
req["mode"] = "periodic"
req["vseconds"] = "-"
req["seconds"] = 60

rsp = card.Transaction(req)

This will return an object confirming that the Notecard is in periodic mode and sample GPS at a set rate:

{
 "mode": "periodic",
 "seconds": 60
}

Achieving the Lowest Possible Power State

The Notecard's hardware components and factory firmware settings provide a default experience with minimal power usage. There are additional Notecard API requests and hardware settings that can be altered to achieve the right balance of power savings and functionality for your specific requirements.

For example, the following Notecard API commands will place the Notecard in its lowest possible power state (e.g. ~8µA@5V on a Notecard Cellular):

// perform a "factory reset" on the Notecard and restart
{"req":"card.restore","delete":true}

// disables all syncing between Notecard and Notehub
{"req":"hub.set","mode":"off"}

// disable the Notecard accelerometer and stop motion tracking
{"req":"card.motion.mode","stop":true}

// disables ATTN processing and sets the pin OFF
{"req":"card.attn","off":true}

Likewise, the Notecarrier in use can impact overall power consumption. For instance, the Notecarrier A provides the best out-of-the-box power performance of ~8-9µA@5V with a Notecard Cellular.

The Notecarrier F, however, requires changing a DIP switch to achieve the lowest possible power state. For example, on a Notecarrier F v1.3, setting the FEATHER_EN DIP switch to N_ATTN (which disables the Feather) will lead to the lowest possible power usage (approximately ~9-11µA@5V with a Notecard Cellular).

note

There is a lot of capacitance aboard the Notecarrier F, so you may see the current start high and drift downward toward ~9-11µA@5V.