Android system health

Android 13 includes android.hardware.health AIDL HAL, a conversion from health@2.1 HAL. This new HAL has the following advantages:

  • Remove unused charger-related APIs
  • Remove unused StorageAttribute and related fields
  • Support dock charging.

Android 11 includes android.hardware.health HAL 2.1, a minor version upgrade from health@2.0 HAL. This new HAL has the following advantages:

  • Cleaner separation between framework and vendor code.
  • Greater degrees of freedom for vendor customization in health information reports.
  • More device health information than just battery.

Documentation for implementing Health 2.1 HAL is on this page as reference.

Requirements

This section contains requirements for Android 11, 12 and 13 or higher.

Devices running Android 11 and Android 12

Devices launching with Android 11 and 12 must provide the 2.1 HAL or the AIDL HAL. Devices not launching with Android 11 or 12 but planning to update the vendor image to Target Framework Compatibility Matrix Version 5 (released in Android 11) or 6 (released in Android 12) must remove existing 2.0 HAL implementations and provide the 2.1 HAL or the AIDL HAL. Devices not launching with Android 11 and not planning to update the vendor image are also recommended to provide the 2.1 or AIDL HAL.

AOSP includes multiple helper libraries designed to help you implement the 2.1 HAL and transition from the old HIDL HALs.

Devices running Android 13 and higher

Devices launching with Android 13 must provide the AIDL HAL (and must not provide HIDL HAL). Devices not launching with Android 13 but planning to update the vendor image to Target Framework Compatibility Matrix Version 7 (released in Android 13) must remove existing HIDL HAL implementations and provide the AIDL HAL. Devices not launching with Android 13 and not planning to update the vendor image are also recommended to provide the AIDL HAL.

AOSP includes multiple helper libraries designed to help you implement the AIDL HAL and the transition from the old HIDL HALs.

Terminology

Following are terms you should know before reading the rest of the Android system health documentation:

health@2.1
Abbreviation of android.hardware.health@2.1. Version 1 of the health HIDL was released in Android 11.
health AIDL HAL
Abbreviation of android.hardware.health. Version 1 of the health AIDL HAL was released in Android 13.
charger
Executable running in off-mode charging that displays the phone-charging animation.
recovery
Executable running in recovery mode that must retrieve battery information.
storaged
Daemon that retrieves storage information and provides it to the framework.

Health in Android 11 and 12

In Android 11 and 12, the health component works as detailed in the following diagram:

[system]
    | getService()
    V
[health@2.1-service]
        | getService(stub=true)
        V
[      health@2.0-impl-2.1-<device>.so      ]
        |                                  | (device-dependent linkage)
        V                                  V
+---------Helper libs for impl--------+   [libhealthd.device]
| [libhealthloop (uevent, wakealarm)] |
| [libhealth2impl (IHealth impl)    ] |
| [libbatterymonitor (battery)      ] |
+-------------------------------------+

For other modes:

[       charger          ]
    | getService()      |  (legacy code path)
    V                   +-------------------------------------------------+
[health@2.1-service]                                                      |
        | getService(stub=true)                                           |
        V                                                                 |
[      health@2.0-impl-2.1-<device>.so      ]                             |
        |                                  | (device-dependent linkage)   |
        V                                  V                              |
+---------Helper libs for impl--------+   [libhealthd.device]             |
| [libhealthloop (uevent, wakealarm)] |                                   |
| [libhealth2impl (IHealth impl)    ] | <---------------------------------+
| [libbatterymonitor (battery)      ] |
+-------------------------------------+

[recovery]
        | getService() w/o hwservicemanager
        V
[      health@2.0-impl-2.1-<device>.so      ]
        |                                  | (device-dependent linkage)
        V                                  V
+---------Helper libs for impl--------+   [libhealthd.device]
| [libhealthloop (uevent, wakealarm)] |
| [libhealth2impl (IHealth impl)    ] |
| [libbatterymonitor (battery)      ] |
+-------------------------------------+

See the following simplified diagram for different modes:

Health HIDL HAL 2.1 infrastructure

Figure 1. Health HIDL HAL 2.1 infrastructure.

Health in Android 13

In Android 13, the health AIDL HAL is introduced. Figure 2 details how the health component works:

Health AIDL HAL infrastructure

Figure 2. Health AIDL HAL infrastructure.

HIDL HAL interface 2.1

The health@2.1 HAL supports off-mode charging and provides more information about the battery.

The main interface, IHealth, provides the following additional functions

  • getHealthConfig: to retrieve the configuration of this HAL
  • getHealthInfo_2_1: a minor version upgrade to getHealthInfo
  • shouldKeepScreenOn: to determine whether the screen should be kept on in charger mode

In addition, the implementation of @2.1::IHealth is required to support @2.1::IHealthInfoCallback for its inherited registerCallback and unregisterCallback functions. The new callback interface returns health health information to the client using its healthInfoChanged_2_1 function instead of the inherited healthInfoChanged function.

A new struct, @2.1::HealthInfo, is returned using callbacks and getHealthInfo_2_1. This struct contains additional device health information available through health@2.0 HAL, including:

  • Battery capacity level
  • Battery charge time to full now (in seconds)
  • Battery full charge design capacity (in μAh)

Figure 3 shows a UML diagram of the classes useful to the health HAL implementation:

Health 2.1 HAL UML diagram

Figure 3. Health HAL 2.1 UML diagram.

For information on implementing the Health service 2.1, see Implementing Health 2.1.

AIDL HAL interface version 1

This section contains information on AIDL HAL interface version 1.

API changes

The AIDL version 1 HAL supports similar APIs to the HIDL 2.1 HAL. Compared to the HIDL 2.1 interface, the following are changed in the API:

  • Charger-related APIs introduced in HIDL HAL 2.1 are not ported to the AIDL HAL. Because the functionality of off-mode charging lives only on the /vendor partition, APIs on the Vendor Interface are not necessary. To implement off-mode charging properly, see charger.
  • Type StorageAttribute and related fields are removed because they are unused.
  • chargerDockOnline is added to HealthInfo to support dock charging.

Implementation

Figure 4 shows a UML diagram of the classes useful to the health AIDL HAL implementation:

Health AIDL HAL UML diagram

Figure 4. Health AIDL HAL UML diagram.

For information on implementing the health AIDL service, see Implementing Health AIDL HAL.

Recovery

Android 13 supports binder in recovery. Installing the Health AIDL service to recovery allows it to run in recovery mode.

For information on installing the health AIDL service to recovery, see the following:

Charger

The functionality of off-mode charging is moved from /system to /vendor. For devices launching with Android 13, if they support off-mode charging, the HAL service binary must support charger mode. To do so, refer to implementing charger.

Charger system properties

The properties ro.charger.* are no longer readable by the charger binary in /vendor. If your device has any of the ro.charger.* system properties set, refer to system properties for charger.