Android system health

Android 9 includes android.hardware.health HAL 2.0, a major version upgrade from health@1.0 HAL. This new HAL has the following advantages:

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

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:

  • Easier to implement
  • Better conformance with existing 2.0 HAL APIs
  • Better Treble separation in off-mode charging code
  • Better support for the framework to indicate the battery health of the device

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.

Requirements

Devices running Android 9 and Android 10

Devices launching with Android 9 must provide the 2.x HAL (and must not provide the 1.0 HAL) or the AIDL HAL. Devices not launching with Android 9 but planning to update the vendor image to Target Framework Compatibility Matrix Version 3 (released in Android 9) must remove existing 1.0 HAL implementations and provide the 2.x HAL or the AIDL HAL.

AOSP includes multiple helper libraries designed to help you implement the 2.0 HAL and the transition from the old 1.0 HAL.

Devices running Android 11 and Android 12

Devices launching with Android 11 must provide the 2.1 HAL (and must not provide the 1.0 or 2.0 HAL) or the AIDL HAL. Devices not launching with Android 11 but planning to update the vendor image to Target Framework Compatibility Matrix Version 5 (released in Android 11) 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 HAL.

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

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.

Devices must not provide the HIDL 1.0 HAL.

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

Terminology

  • health@1.0: abbreviation of android.hardware.health@1.0. Refers to health HIDL HAL version 1.0 released in Android 8.0.
  • health@2.0: abbreviation of android.hardware.health@2.0. Refers to health HIDL HAL version 2.0 released in Android 9.
  • health@2.1: abbreviation of android.hardware.health@2.1. Refers to health HIDL HAL version 2.1 released in Android 11.
  • health AIDL HAL: abbreviation of android.hardware.health.
    • Version 1 is 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.
  • healthd: legacy daemon running in Android that retrieves health-related information and provides it to framework.
  • storaged: daemon running in Android that retrieves storage information and provides it to framework.

Health in Android 8.x

In Android 8.x, the health component works as detailed in the following diagram:

Health in Android 8.x

Figure 1. Health in Android 8.x.

In this diagram:

  • One (1) binder call and one (1) hwbinder call are used by the framework to communicate with hardware.
  • healthd statically links to libhealthd_android, libbatterymonitor, and libbatteryservice.
  • health@1.0-impl statically links to libhealthd.BOARD.

Each board can customize a different libhealthd.BOARD; it is determined at build time what charger, health@1.0-impl, and recovery link to.

For other modes:

Off-mode charing and recovery mode in Android 8.x

Figure 2. Health in Android 8.x, off-mode charging and recovery mode.

  • charger statically links to libhealthd.BOARD, libhealthd_charger and libbatterymonitor.
  • recovery statically links to libhealthd.BOARD and libbatterymonitor.

Health in Android 9

In Android 9, the health component works as detailed in the following diagram: Health in Android 9

Figure 3. Health in Android 9.

The framework attempts to retrieve health@2.0 service from hwservicemanager. If it fails, it calls into health@1.0 (in Android 8.x). The legacy code path is kept so the Android 9 system image is compatible with the Android 8.x vendor image. The framework does not retrieve information from both HALs because only one service version (1.0 or 2.0) can exist on the device.

For other modes:

Off-mode charing and recovery in Android 9

Figure 4. Health in Android 9, off-mode charging and recovery mode.

Health in Android 11

In Android 11, 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)      ] |
+-------------------------------------+

If the health 2.1 implementation doesn't exist, the system falls back to the legacy code path as described in previous sections

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 HAL 2.1 infrastructure

Figure 5. Health HAL 2.1 infrastructure.

Health in Android 13

In Android 13, the health AIDL HAL is introduced. The health component works as detailed in the following diagram:

Health AIDL HAL infrastructure

Figure 6. Health AIDL HAL infrastructure.

HIDL HAL interface 2.0

The health@2.0 HAL provides the same functionality to the framework as the old healthd daemon. It also provides APIs that are similar to what healthd previously provided as a binder service (i.e. IBatteryPropertiesRegistrar).

The main interface, IHealth , provides the following functions:

  • registerCallback, to replace IBatteryPropertiesRegistrar.registerListener
  • unregisterCallback, to replace IBatteryPropertiesRegistrar.unregisterListener
  • update, to replace IBatteryPropertiesRegistrar.scheduleUpdate
  • IBatteryPropertiesRegistrar.getProperties are replaced by the following:
    • getChargeCounter
    • getCurrentNow
    • getCurrentAverage
    • getCapacity
    • getEnergyCounter
    • getChargeStatus
    • getHealthInfo

In addition, IHealth provides the following new APIs for storaged to retrieve vendor-specific storage related information:

  • getStorageInfo
  • getDiskStats

A new struct, @2.0::HealthInfo, is returned via callbacks and getHealthInfo. This struct contains all device health information available through health@2.0 HAL, including:

  • Charging information (AC/USB/wireless, current, voltage, etc.)
  • Battery information (presence, battery level, current, voltage, charge, technology, etc.)
  • Storage information (storage device information, disk statistics)

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

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 via 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)

See the following UML diagram for the classes useful to the health HAL implementation:

Health 2.1 HAL UML diagram

Figure 7. 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

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 below.
  • Type StorageAttribute and related fields are removed because they are unused.
  • chargerDockOnline is added to HealthInfo to support dock charging.

Implementation

See the following UML diagram for the classes useful to the health HAL implementation:

Health AIDL HAL UML diagram

Figure 8. 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.