Android 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

Requirements

Devices launching with Android 9 must provide the 2.0 HAL (and must not provide the 1.0 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.0 HAL.

Devices launching with Android 11 must provide the 2.1 HAL (and must not provide the 1.0 or 2.0 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. 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.

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.
  • 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)      ] |
+-------------------------------------+

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)

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)

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