Routine Battery Saver

Android 10 introduces a battery saver schedule option called based on routine. This option allows an app chosen by the OEM to provide signals to the system for more intelligent battery saver scheduling. This option requires configuration, and is optional to implement.

Device configuration

Provider specification

To notify the Settings UI that the device is configured correctly, use your config overlay to override the value config_batterySaverScheduleProvider with the package name of your app.

For example, if you want the app package com.google.android.apps.turbo to control the based on routine setting, then you would set this config value:

<string name="config_batterySaverScheduleProvider" translatable="false">
com.google.android.apps.turbo</string>

Now the phone should show the based on routine option. To verify, build your image, flash it to a phone, and navigate to Settings > Battery > Battery Saver > Battery Saver Schedule. The based on routine option should appear.

Default off threshold

The new config_dynamicPowerSavingsDefaultDisableThreshold field specifies a battery level at which the system turns off battery saver, if it was turned on by the based on routine scheduler. The system default is 80%, but you can change it.

App configuration

Permissions

The APIs needed for the app to turn on battery saver from the app are protected by the permission android.permission.POWER_SAVER. This is a signature/privileged permission, so grant the app you want to be able to trigger battery saver this permission in your privapp-whitelist.

An example of granting the privapp permission to an app:

<privapp-permissions package="com.google.android.apps.turbo">
   <permission name="android.permission.POWER_SAVER"/>
</privapp-permissions>

If you don't pre-grant this permission to the version of the app on the system image, the app can't acquire the permission or properly call the APIs. The system doesn't provide any feedback beyond the usual permission errors, so verify that you can call the APIs and observe their effects.

Installation

For based on routine to work properly, you must pre-install the app on the system image with the required permission. Give only one app the POWER_SAVER permission and allow it to control the based on routine APIs. Behavior of the feature when more than one app tries to use the permission and APIs is unsupported and unspecified.

Triggering battery saver

APIs

Assuming setup is successful so far, the OEM app specified in the config should be able to successfully call the associated method in PowerManager to trigger battery saver:

public boolean setDynamicPowerSaveHint(boolean powerSaveHint, int disableThreshold)

If the based on routine battery saver schedule option is enabled and the app calls this method with a true value for powerSaveHint, then battery saver turns on. Specify disableThreshold so that if the app can't communicate with the system, the system still knows at which battery percentage it's safe to turn off battery saver.

This API is subject to user overrides and battery saver snoozing in the same way as the percentage-based automatic battery saver. See the API documentation for more information.

To verify the APIs are called successfully, query settings global to verify that the backing setting changed value according to the API calls.

For example, if the user selected routine battery saver mode and the app is calling setDynamicPowerSaveHint(true, 10), the global settings should have these values:

automatic_power_save_mode: 1
dynamic_power_savings_disable_threshold: 10
dynamic_power_savings_enabled: 1

If you then call setDynamicPowerSaveHint(false, 25), the values should be:

automatic_power_save_mode: 1
dynamic_power_savings_disable_threshold: 25
dynamic_power_savings_enabled: 0

You can check these values using this adb command:

adb shell settings get global <setting-name>

Verification

There's no automated way to verify this feature because there's no way to know what behavior an OEM will use to decide when to trigger routine battery saver mode. OEMs are thus responsible for testing their integration to make sure that the behavior meets expectations. In particular, verify that the device can fulfill the following tasks:

  • The user selects based on percentage in the battery saver schedule UI and selects 15%. Battery saver should come on automatically ONLY when hitting 15% battery.
  • The user selects based on routine in the battery saver schedule UI. When the app calls the API with true, battery saver turns on. Additionally, battery saver automatically turns off if the device is charged to the indicated threshold level and unplugged.
  • The user selects none in the battery saver schedule UI. Battery saver should NEVER come on automatically.
  • If the app turns on battery saver and the user manually overrides battery saver to be off again (using Quick Settings, Settings, etc.), it should STAY OFF until the user either turns it back on again manually or plugs the device in.