Power Management API

The Power Management API provides tools to manage a device's power consumption.

Managing power

Managing power is something that is way beyond power itself: avoiding large computations, limiting reflow, etc. All of this is part of power management. However, the Power Management API really focuses on the direct power consumption (screen, cpu, etc.) The main interface to manage power is accessible through navigator.mozPower which is an instance of the PowerManager interface.

Basic power operations

The PowerManager interface allows to manage basic power operations.

Global power operations

It's possible to simply shut down the device with the powerOff() method or even reboot it with the reboot() method.

navigator.mozPower.powerOff();

Screen power operations

The screen can be turned off and on with the read/write property screenEnabled. But it's also possible to act by accessing and changing the screen brightness. It can be changed with the read/write property screenBrightness, which defines how bright the screen's backlight is, on a scale from 0 (very dim) to 1 (full brightness).

// It doesn't make sense to change the brightness if the screen is off
if (navigator.mozPower.screenEnabled) {
  navigator.mozPower.screenBrightness = 0.5;
}

CPU power operations

Even if it's not possible to directly shut down the cpu, it's possible to tell if it can be shut down or not if the screen is turned off. This can be set with the cpuSleepAllowed. It determines if the device's CPU will sleep after the screen is disabled (true) or not (false); in this last case it will prevent the device from entering a suspended state.

Advanced power operations

Power management is better handled when the application in charge of the power can be notified about the needs of third party applications. For example, it is probably better if the screen does not turn off automatically after a few seconds while the user is watching a video.

Request wake locks

Any application can request a wake lock. A wake lock is a way to ask one of the device's resources to not power itself off. A wake lock can be requested through the navigator.requestWakeLock() method.

Wake locks are requested for specific resources that might be made unavailable for various reasons. For example, on a mobile device the power manager might decide to turn off the screen after a period of idle time to save power. The application that handles the ressource checks the lock state of a topic before turning off the associated resource. For example, a page could hold a lock on the screen topic to prevent the screensaver from appearing or the screen from turning off.

By default, Firefox OS allow screen, cpu, and wifi resources. But any application that handle a resource can define a resource name and set policy on its lock. For example, the resource manager might decide to ignore screen wake locks held by applications which are not visible.

var lock = navigator.requestWakeLock('screen');

The requestWakeLock method returns an object containing a topic property, which represents the name of the resource with the lock, and an unlock() method that can be used to manully release the lock. Note that if the application is closed (really closed, not just idle) all the locks it requests will be released automatically.

Handling wake lock

Certified applications able to manage locks can be notified about change on the lock state. Actually, any application that wants to manage power should listen for lock state change on screen and cpu. This is done by using the PowerManager.addWakeLockListener() method (and it's possible to stop listening for lock requests by using the PowerManager.removeWakeLockListener() method).

The addWakeLockListener method expects a callback function which must accept two parameters: a first string representing the resource to handle (in our case here, screen or cpu) and a second string representing the state of the lock.

A lock can be in three different states:

unlocked

Nobody holds the wake lock for the given resource.

locked-foreground

At least one application holds the wake lock and is visible.

locked-background

At least one application holds the wake lock, but all of them are hidden.

// This is used to keep track of the last change on the lock state
var screenTimeout;
// A reference to the Power Manager
var power = window.navigator.mozPower;
// Here are the actions to handle based on the lock state
var powerAction = {
  // If there is no lock at all, we will suspend the device:
  // * Turn the screen off
  // * Allow the cpu to shut down
  unlocked: function suspendDevice() {
    power.cpuSleepAllowed = true;
    power.screenEnabled   = false;
  },
  // If there is a lock but the applications requesting it
  // are all in the background, we just turn the screen off
  'locked-background': function shutOffOnlyScreen() {
    power.cpuSleepAllowed = false;
    power.screenEnabled   = false;
  },
  // At last, if there is an active application that requests a lock,
  // actually there is nothing to do. That's the whole point.
}
function screenLockListener(topic, state) {
  // If the lock is not about the screen, there is nothing to do.
  if ('screen' !== topic) return;
  // Each time the lock changes state, we stop any pending power management operations
  window.clearTimeout(screenTimeout);
  // If there is an action defined for the given state
  if (powerAction[state]) {
    // We delay that action by 3s
    screenTimeout = window.setTimeout(powerAction[state], 3000);
  }
}
// We make sure our power management application is listening for any change on locks.
power.addWakeLockListener(screenLockListener);

Specification

Not part of any specification

See also

• navigator.mozPower
• PowerManager
• navigator.requestWakeLock()