With the Android framework, device manufacturers and app developers can use
thermal data to ensure a consistent user experience (UX) if a device begins to
overheat. For example, when a system undergoes thermal stress,
jobscheduler jobs get throttled and, if necessary, a framework
thermal shutdown is initiated. Apps that receive thermal-stress notifications
through a registered callback in the
can gracefully adjust their UX.
Android 9 and lower use a polling interface defined in Thermal HAL 1.0 to get temperature readings. This HAL allowed the Android framework and other trusted clients, such as a device manufacturer's HAL, to read the current temperature and product-policy specific throttling and shutdown thresholds for each sensor through the same API.
Android 10 introduced a thermal system in the Android framework and a new version of the HAL, Thermal HAL 2.0, that abstracts the interface to the thermal subsystem hardware devices. The hardware interface includes temperature sensors and thermistors for the skin, battery, GPU, CPU, and USB port. The device skin temperature is the most important system to track to keep the device surface temperature within specified thermal limits.
Additionally, Thermal HAL 2.0 provides multiple clients with thermal sensor
readings and associated severity levels to indicate thermal stress. The
following figure shows two warning messages from the Android System
UI. These messages are displayed when the
interface for the
SKIN sensors, respectively, reach the
THERMAL_STATUS_EMERGENCY severity level.
Figure 1. Overheat warnings.
The current temperatures are retrieved for the different
types of thermal sensors through
IThermal HAL. Each function call
returns a status value of either
returned, the process continues. If
FAILURE is returned, an error
message, which must be human-readable, is sent to
In addition to being a polling interface that returns the current temperatures,
you can use the callback
IThermalChangedCallback (HIDL, Android 10 through 13) or
IThermalChangedCallback (AIDL, Android 14 and higher)
with the callback interface from thermal HAL clients, such as the framework’s
thermal service. For example,
UnregisterIThermalChangedCallback to register or unregister severity-changed
events. If the thermal severity of a given sensor has changed,
notifyThrottling sends a thermal throttling event callback to thermal-event
In addition to thermal sensor information, a list of mitigated cooling devices
is exposed in
getCurrentCoolingDevices. This list's order is persistent, even
if a cooling device has gone offline. Device manufacturers can use the list to
For more information, see the Reference implementation.
While you can add your own extensions, you shouldn't disable the thermal mitigation function.
In Android 10 and higher, the thermal service in the framework provides constant
monitoring using the various mitigation signals from Thermal HAL 2.0, and gives
throttling severity feedback to its clients. These clients include internal
components and Android apps. The service uses two binder callback interfaces,
IThermalStatusListener, exposed as callbacks. The
former is for internal platform and device manufacturer use, and the latter is
for Android apps.
Through the callback interfaces, a device’s current thermal status is
retrievable as an integer value ranging from
0x00000000 (no throttling) to
0x00000006 (device shutdown). Only a trusted system service, such as an
Android API or device manufacturer API, can access the detailed thermal sensor
and thermal event information. The following figure provides a model of the
thermal mitigation process flow in Android 10 and higher:
Figure 2. Thermal mitigation process flow in Android 10 and higher.
Device manufacturer guidelines
To report device temperature sensor and throttling status for Android 10 through
13, device manufacturers must implement the HIDL aspect of the Thermal
HAL 2.0 (
To report device temperature sensor and throttling status for Android
14, device manufacturers must implement the AIDL aspect
of the Thermal HAL 2.0 (
Anything that throttles device performance, including battery power constraints, must be reported through the thermal HAL. To ensure this happens, put all sensors that might indicate a need for mitigation (based on status changes) into the thermal HAL, and report the severity of any mitigation actions taken. The temperature value returned from a sensor reading doesn’t have to be the actual temperature, as long as it accurately reflects the corresponding severity threshold. For example, you can pass different numerical values instead of your actual temperature threshold values, or you can build guardbanding into threshold specifications to provide hysteresis. However, the severity corresponding to that value must match what’s needed at that threshold. For example, you might decide to return 72°C as your critical temperature threshold, when the actual temperature is 65°C, and it corresponds to the critical severity you specified. The severity level must be accurate for best thermal framework functionality.
To read more about the threshold levels in the framework and how they correspond to mitigation actions, see Use thermal status codes.
Use thermal APIs
Apps can add and remove listeners, and access thermal status information
IThermal interface provides all the functionality needed, including
returning the thermal status values. The
IThermal binder interface
is wrapped as the
OnThermalStatusChangedListener interface, which apps can use
when registering or removing thermal status listeners.
The Android thermal APIs have both callback and polling methods for apps to be
notified of the thermal severity levels through status codes, which are defined
PowerManager class. The methods are:
getCurrentThermalStatus()returns the current thermal status of the device as an integer, unless the device is undergoing throttling.
addThermalStatusListener()adds a listener.
removeThermalStatusListener()removes a previously added listener.
Use thermal status codes
The thermal status codes translate to specific throttling levels, which you can
use for gathering data and for designing an optimal UX. For example, apps might
receive a status of
THERMAL_STATUS_NONE), which might later
THERMAL_STATUS_LIGHT). Marking the
as t0, then measuring the time lapsed from status
THERMAL_STATUS_LIGHT as t1 enables device manufacturers to design and
test mitigation strategies for specific use cases. The following table outlines
suggested ways to use the thermal status codes:
|Thermal status code||Description and suggested use|
||No throttling. Use this status to implement protective actions, such as detecting the start of the time period (t0 to t1) from
||Light throttling, UX isn't impacted. Use gentle device mitigation for this stage. For example, skip boosting or using inefficient frequencies, but only on big cores.|
||Moderate throttling, UX isn't greatly impacted. Thermal mitigation impacts foreground activities, so apps should reduce power immediately.|
||Severe throttling; UX is largely impacted. In this stage, device thermal mitigation should limit the system capacity. This state might cause side effects, such as display jank and audio jitter.|
||Platform has done everything to reduce power. The device thermal mitigation software has placed all components to run at their lowest capacity.|
||Key components in the platform are shutting down due to thermal conditions and device functionality is limited. This status code represents the last warning before device shutdown. In this state, some functions, such as the modem and cellular data, are turned off completely.|
||Shut down immediately. Due to the severity of this stage, apps might not be able to receive this notification.|
Device manufacturers must pass the VTS test for thermal HAL, and can use
emul_temp from the
interface to simulate temperature changes.