Controlling Ultra Low Power Mode

Ultra low power mode (ULPM) is an operating mode on an Octave edge device in which the device shuts down its main processor to save power. The processor can then be woken from an external source or from a timer.

Turning on ULPM can be done using an Edge Action or by sending an event via the :command stream. This topic describes how to configure ULPM.

🚧

Important

Before triggering a device shutdown, ensure that you have first set up a trigger to wake up the device, such as a timer or a GPIO or ADC as indicated later in this page.

Controlling Ultra Low Power Mode via an Edge Action

Setting the ULPM timeout via an Edge Action would typically be done via an Edge Action that has been configured with an Observation to some other Resource. The ULPM can therefore be considered an Actuator.

The steps below describe how to configure the timeout using an Edge Action that triggers ULPM when the light sensor value on a mangOH Red falls below a certain threshold.

  1. Navigate to Build > Device > Observations.
  2. Create an Observation for the /redSensor/light/value resource and set its Send events to option to Edge Action.
  3. Navigate to Build > Device > Actions.
  4. Create a new Edge Action and set the Source Observation to the Observation created in Step 2.
  5. Add the following code to set the return value for the /util/ulpm/shutdown Resource to true:
function(event) {
   ...

   return {
      "dh://util/ulpm/shutdown" : [true],
   }
}
  1. Click Save

🚧

Important

When configuring an Edge Action to enable ULPM, watch out for "loops" that constantly turn ULPM on and off again. Depending on the underlying event that triggers the Edge Action, it's possible that after your Edge Action enables ULPM, another Edge Action disables ULPM, but then your Edge Action is the re-triggered causing the device to re-enter ULPM again.

Controlling Ultra Low Power Mode via the :command Stream

The steps below describe how to configure the timeout via the :command stream:

  1. Navigate to Build > Device > Streams > :command and click Add Event.
  2. Locate the elems element in the JSON, replace it with the following, and click Create:
"elems": {
    "util": {
      "ulpm": {
        "shutdown": [true]
      }
    }
  }

  ...

The code above directly sets the /util/ulpm/shutdown Resource to true causing the device to enter ULPM.

📘

Note

For information about programmatically using the :command Stream see: Temporarily Changing a Value via an Event.

Configuring how the Device Wakes from ULPM

Ultra low power mode is configured via the util/ulpm/config Resource. The following subsections describe how to config the device to awaken from ultra low power mode through different mechanisms.

The setting of the util/ulpm/config Resource is usually static, and it's therefore usually defined via the Octave Resource Dashboard and saved in the device's Blueprint.

Wake from a Timer

Expected JSON format:

{"timer":value}

Where:

  • timer : an integer specifying the expiration time (in seconds) to boot. This is the time relative from when the modem/app processor shutdown.

Wake from a GPIO

Expected JSON format:

{"gpio": [{"id":value,"state":string},{"id":value,"state":string}]}

Where:

  • id : an integer that can be set to 36 or 38 to specify the respective GPIO to boot.
  • state: the state that should cause the boot. The string value for state can be set to LOW, HIGH, RISING, FALLING, BOTH.

🚧

Wake from a GPIO unavailable from Firmware 3.5.0

From Firmware version 3.5.0 setting a GPIO as a wakeup source will not be supported anymore.

Wake from an ADC

Expected JSON format:

{"adc": [{"id": value,"poll":value, "low":value,"high":value}]}

Where

  • id : an integer that can be set to 2 or 3 to configure the respective ADC pin.
  • poll : an integer specifying how frequently to poll the ADC while sleeping, in milliseconds.
  • low : a double specifying the ADC reading above which the system should wake.
  • high : a double specifying the ADC reading below which the system should wake.

🚧

Wake from an ADC unavailable from Firmware 3.5.0

From Firmware version 3.5.0 setting an ADC as a wakeup source will not be supported anymore.