Thermal in Android

Android Q introduced new thermal APIs to allow better handling of thermal issues. This article goes over why these APIs were needed, the information and controls they provide, and how you can test your app under different thermal stress levels.

The need for thermal APIs

An Android device undergoes thermal stress when the amount of heat it’s generating is greater than what it’s able to dissipate (get rid of). This causes the device’s surface to overheat. It may also throttle the CPU/GPU and can cause display jank, audio jitter and other side effects which heavily depend on the device and its hardware. As a result, new thermal APIs were introduced in Android Q to allow app developers to better react to and handle thermal issues.

Understanding thermal severity levels

Instead of providing actual device temperature values which wouldn’t be very indicative of whether the device is undergoing thermal issues, the Android thermal APIs introduced the concept of thermal severity levels, which are based on status codes, and are defined in the PowerManager class. Below are examples of how one might react to each of them to maintain a good user experience.

Thermal status codes

As the thermal severity level increases, an app should disable -optional- power-consuming features, such as reducing the resolution/bit rate on a video streaming app, disabling intensive image enhancement features on a camera app, and disabling GPS on a maps app. This will help lower power usage and potentially restore the device back to its normal temperature.

Receiving thermal notifications

To receive thermal status updates, the Android thermal APIs provide the following callback and polling methods through the PowerManager class.

• getCurrentThermalStatus() returns the current thermal status of the device.
• addThermalStatusListener() adds a listener that’s notified of thermal status changes.
• removeThermalStatusListener() removes a previously added listener.

An app can choose to register a thermal status listener once it’s resumed, and unregister it when it’s paused. This would allow it to receive updates as long as it’s foregrounded.

Note that these thermal APIs were introduced with a redesigned thermal HAL, Thermal HAL 2.0. It provides thermal signals to the Android framework’s thermal Service, IThermalService, which then passes them to its clients, which include Android apps.

The flow of thermal signals

The fact that the thermal APIs depend on Thermal HAL 2.0 means that not all devices running Android 10 or later will support them. At the time of their release, the thermal APIs were supported on Pixel devices.

Testing thermal levels

To see how your app reacts to thermal status changes, you can test its behavior using the command line with the following.

Set the device’s thermal status

STATUS represents the thermal severity status, it’s an integer between 0 (THERMAL_STATUS_NONE) and 6 (THERMAL_STATUS_SHUTDOWN).

When you’re done testing, you can reset the thermal status back to its normal value using the following command.

Reset the device’s thermal status

Sample code

The following sample app showcases how to register for updates of the device’s thermal severity level, and keep the user aware of them using a foreground service.

husaynhakeem/android-playground

Conclusion

In summary:

• The thermal APIs introduced in Android Q expose the severity of the device’s thermal stress.
• Use getCurrentThermalStatus() to poll for the device’s thermal status.
• Register a thermal status listener to continually receive updates on the device’s thermal status using addThermalStatusListener().
• Simulate different thermal severity levels using the command line to test how your app reacts to them.

Want to learn more about Android thermal APIs? Check out these resources:

• Thermal mitigation
• Keeping cool in Android Q with the Thermal API

For more on Android, follow me to get notified when I write new posts or let’s connect on Github and Twitter!