Exploring Android PowerManager API

Let’s take a look at Android’s PowerManager API. This API has been around since API Level 1 and is used for acquiring power states of a device, such as thermal status, screen/interactivity status, and Wake Lock (a convenient method for keeping your screen/CPU awake).

In this article we will explore what you can do with this API up until API Level 30 (Android 11).

Where’s the Source Code?

yggr-medium-source-code/power-manager at master · hanmajid/yggr-medium-source-code

tl;dr

PowerManager API allows you to get and manage various power state of your device. Here’s all of them:

1. Thermal status: The device’s thermal status (None, Light, Moderate, Severe, Critical, Emergency, Shutdown). Depending on the severity of the device’s thermal status, the OS will throttle UX and/or limit functionalities. At the very worst, the device needs to be shutdown.
2. Thermal headroom: An estimate of how much thermal headroom the device has before hitting sever throttling.
3. Whether Power Save Mode is on: When a device enables Power Save Mode, application should reduce their functionality to conserve battery. You can listen to this change via BroadcastReceiver.
4. Location mode in Power Save Mode: How the location features should behave when the Power Save Mode is turned on. There are 4 modes available: No Change, GPS Disabled When Screen Off, All Disabled When Screen Off, Foreground Only, and Throttle Requests When Screen Off.
5. Whether the device is in Idle Mode: Idle mode happens when a device has been unused and unmoving for a sufficiently long period of time and decides to go into a lower power-use state. You can listen to this change via BroadcastReceiver.
6. Whether the app is Ignoring Battery Optimization: An application can register itself to device’s power allowlist, allowing it to not be subjected to battery optimization. (Although Google Play policies are very strict about this setting nowadays)
7. Whether the device is in Interactive State: A device is in interactive state when it is awake and ready to interact with user. You can listen to the screen on and off action via BroadcastReceiver.
8. Rebooting device: Only system apps are allowed to have reboot functionality.
9. Whether the devices supports Sustained Performance Mode: Sustained Performance Mode is intended to provide a consistent level of performance for prolonged amount of time.
10. Manage Wake Lock: Wake Lock allows you to keep the CPU running to do some work before going to sleep. There are several levels of Wake Lock: Partial, Full, Screen Dim, and Screen Bright. There’s also a level called Proximity Screen Off that turns off screen if the proximity sensor detects an object nearby.

If you run the source code of this article, you can try all of these functionalities in your device like this:

If you run the source code in this article, you can try various features of the PowerManager API.

Step by Step Explanation

Now, I will explain how you can use my favorite feature from the PowerManager API, which is Proximity Wake Lock. This feature will turns off your screen when the proximity sensor detects a nearby object. You usually see this feature in a call app. When you put your phone up to your ear, the screen will turns off while you are talking.

Here’s how you do it:

1. Open Android Studio. Create new project with “Empty Activity” option. Set the minSdkVersion to 21.

2. Add android.permission.WAKE_LOCK to your AndroidManifest.xml like this: (You can also add android.permissionREQUEST_IGNORE_BATTERY_OPTIMIZATIONS for other feature in this source code)

3. Add lifecycle-runtime-ktx to your app/build.gradle file like the snippet below. We need this to be able to use coroutines in the Activity.

4. Get the Power Manager service in your MainActivity.kt like this:

5. We will implement the Proximity Wake Lock in a button’s onClickListener. What you need to do is first check whether your device supports the Wake Lock by calling isWakeLockSupported. And then you can create the Wake Lock by calling newWakeLock. Finally you must acquire the Wake Lock, do some work, and finally release the Wake Lock.

6. That’s it! Now your device will turns off its screen when the proximity sensor detects something.

As always, thanks for reading!