Android Health

Android 9 には、health@1.0 HAL からのメジャー バージョン アップグレードである android.hardware.health HAL 2.0 が含まれています。この新しい HAL には次の利点があります。

  • フレームワークとベンダーコードが明確に分離される。
  • 不要な healthd デーモンのサポートが終了している。
  • ヘルス情報レポートのベンダー カスタマイズにおける自由度が高い。
  • バッテリー以外についてもデバイスのヘルス情報を確認できる。

Android 11 には、health@2.0 HAL からのマイナー バージョン アップグレードである android.hardware.health HAL 2.1 が含まれています。この新しい HAL には次の利点があります。

  • 実装が簡単
  • 既存の 2.0 HAL API への準拠を強化
  • オフモード充電のコードで Treble の分離を改善
  • デバイスのバッテリーの健全性を示すフレームワークのサポートを改善

Android 13 には、health@2.1 HAL から変更された android.hardware.health AIDL HAL が含まれています。この新しい HAL には次の利点があります。

  • 使用していない充電器関連の API を削除する
  • 未使用の StorageAttribute と関連フィールドを削除する
  • ホルダーでの充電をサポートする

要件

Android 9 と Android 10 を搭載したデバイス

Android 9 でリリースするデバイスでは、2.x HAL または AIDL HAL を提供する必要があります(1.0 HAL は提供できません)。Android 9 でリリースせずに、ベンダー イメージをターゲット フレームワーク互換性マトリックス バージョン 3(Android 9 でリリース済み)に更新する予定のデバイスでは、既存の 1.0 HAL 実装を削除して 2.x HAL または AIDL HAL を提供する必要があります。

AOSP には、2.0 HAL の実装と古い 1.0 HAL からの移行に役立つ複数のヘルパー ライブラリが含まれています。

Android 11 と Android 12 を搭載したデバイス

Android 11 でリリースするデバイスでは、2.1 HAL または AIDL HAL を提供する必要があります(1.0 または 2.0 HAL は提供できません)。Android 11 でリリースせずに、ベンダー イメージをターゲット フレームワーク互換性マトリックス バージョン 5(Android 11 でリリース済み)に更新する予定のデバイスでは、既存の 2.0 HAL 実装を削除して 2.1 HAL または AIDL HAL を提供する必要があります。Android 11 でリリースしておらず、ベンダー イメージを更新する予定がないデバイスであっても、2.1 HAL の提供が推奨されています。

AOSP には、2.1 HAL の実装と古い 1.0 HAL からの移行に役立つ複数のヘルパー ライブラリが含まれています。

Android 13 以降を搭載したデバイス

Android 13 でリリースするデバイスでは、AIDL HAL を提供する必要があります(HIDL HAL は提供できません)。Android 13 でリリースせずに、ベンダー イメージをターゲット フレームワーク互換性マトリックス バージョン 7(Android 13 でリリース済み)に更新する予定のデバイスでは、既存の HIDL HAL 実装を削除して AIDL HAL を提供する必要があります。Android 13 でリリースせず、ベンダー イメージを更新する予定がないデバイスであっても、AIDL HAL を提供することが推奨されます。

デバイスは HIDL 1.0 HAL を提供できません。

AOSP には、AIDL HAL の実装と古い HIDL HAL からの移行に役立つ複数のヘルパー ライブラリが含まれています。

用語

  • health@1.0: android.hardware.health@1.0 の略語。Android 8.0 でリリースされた health HIDL HAL バージョン 1.0 を指します。
  • health@2.0: android.hardware.health@2.0 の略語。Android 9 でリリースされた health HIDL HAL バージョン 2.0 を指します。
  • health@2.1: android.hardware.health@2.1 の略語。Android 11 でリリースされた health HIDL HAL バージョン 2.1 を指します。
  • Health AIDL HAL: android.hardware.health の略語。
    • バージョン 1 は Android 13 でリリースされています。
  • charger: スマートフォン充電中のアニメーションを表示するオフモード充電で実行可能です。
  • recovery: バッテリー情報を取得する必要があるリカバリモードで実行可能です。
  • healthd: Android で動作する以前のデーモンで、ヘルス関連の情報を取得してフレームワークに提供します。
  • storaged: Android で動作するデーモンで、ストレージ情報を取得してフレームワークに提供します。

Android 8.x の Health

Android 8.x では、次の図で示すようにヘルス コンポーネントが動作します。

Android 8.x の Health

図 1. Android 8.x の Health

図の説明:

  • フレームワークによるハードウェアとの通信に、1 つのバインダー呼び出しと 1 つの hwbinder 呼び出しが使用されています。
  • healthdlibhealthd_androidlibbatterymonitorlibbatteryservice に静的にリンクしています。
  • health@1.0-impl が libhealthd.BOARD に静的にリンクしています。

ボードごとに異なる libhealthd.BOARD をカスタマイズできます。charger、health@1.0-impl、recovery のリンク先はビルド時に決まります。

その他のモードの場合:

Android 8.x でのオフモード充電とリカバリモード

図 2. Android 8.x Health、オフモード充電、リカバリモード

  • charger は libhealthd.BOARDlibhealthd_chargerlibbatterymonitor に静的にリンクしています。
  • recovery は libhealthd.BOARDlibbatterymonitor に静的にリンクしています。

Android 9 の Health

Android 9 では、次の図で示すようにヘルス コンポーネントが動作します。 Android 9 の Health

図 3. Android 9 の Health

フレームワークは hwservicemanager から health@2.0 サービスを取得しようとします。 失敗した場合は、health@1.0 を呼び出します(Android 8.x)。Android 9 のシステム イメージが Android 8.x のベンダー イメージと互換性を保てるように、以前のコードパスが保持されます。デバイスに存在できるのは 1 つのサービス バージョン(1.0 または 2.0)のみであるため、フレームワークが両方の HAL から情報を取得することはありません。

その他のモードの場合:

Android 9 のオフモード充電とリカバリ

図 4. Android 9 の Health、オフモード充電、リカバリモード

Android 11 の Health

Android 11 では、次の図で示すようにヘルス コンポーネントが動作します。

[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)      ] |
+-------------------------------------+

health 2.1 の実装が存在しない場合は、前のセクションで説明した以前のコードパスにフォールバックします。

その他のモードの場合:

[       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)      ] |
+-------------------------------------+

種々のモードについて、以下の簡略図をご覧ください。

Health HAL 2.1 のインフラストラクチャ

図 5. Health HAL 2.1 のインフラストラクチャ

Android 13 の Health

Android 13 では、Health AIDL HAL が導入されています。ヘルス コンポーネントは次の図に示すように動作します。

Health AIDL HAL のインフラストラクチャ

図 6. Health AIDL HAL のインフラストラクチャ

HIDL HAL インターフェース 2.0

health@2.0 HAL は、古い healthd デーモンと同じ機能をフレームワークに提供します。healthd がバインダー サービスとして以前提供していたサービス(IBatteryPropertiesRegistrar)と類似の API も提供されます。

メイン インターフェース(IHealth)には次の関数が用意されています。

  • IBatteryPropertiesRegistrar.registerListener に代わる registerCallback
  • IBatteryPropertiesRegistrar.unregisterListener に代わる unregisterCallback
  • IBatteryPropertiesRegistrar.scheduleUpdate に代わる update
  • IBatteryPropertiesRegistrar.getProperties に代わる関数は次のとおりです
    • getChargeCounter
    • getCurrentNow
    • getCurrentAverage
    • getCapacity
    • getEnergyCounter
    • getChargeStatus
    • getHealthInfo

さらに IHealth では、storaged がベンダー固有のストレージ関連情報を取得できるように、次の新しい API も提供されます。

  • getStorageInfo
  • getDiskStats

コールバックと getHealthInfo によって、新しい構造体 @2.0::HealthInfo が返されます。 この構造体には、health@2.0 HAL から入手できる、次のようなデバイスヘルス情報がすべて含まれます。

  • 充電情報(AC / USB / ワイヤレス、電流、電圧など)
  • バッテリー情報(バッテリーの有無、バッテリー残量、電流、電圧、充電、テクノロジーなど)
  • ストレージ情報(ストレージ デバイス情報、ディスク統計情報)

Health サービス 2.0 の実装については、Health 2.0 の実装をご覧ください。

HIDL HAL インターフェース 2.1

health@2.1 HAL はオフモード充電に対応し、バッテリーに関する詳細情報を提供します。

メイン インターフェース(IHealth)には次の関数が用意されています。

  • getHealthConfig: この HAL の構成を取得します
  • getHealthInfo_2_1: getHealthInfo のマイナー バージョン アップグレード
  • shouldKeepScreenOn: 画面を充電モードにしておくかどうかを決定します

さらに、@2.1::IHealth の実装には、継承された registerCallback 関数と unregisterCallback 関数に対して @2.1::IHealthInfoCallback をサポートする必要があります。新しいコールバック インターフェースは、継承された healthInfoChanged 関数ではなく、healthInfoChanged_2_1 関数を使用してヘルス情報をクライアントに返します。

コールバックと getHealthInfo_2_1 によって、新しい構造体 @2.1::HealthInfo が返されます。この構造体には、health@2.0 HAL から入手できる、次のような追加のデバイスヘルス情報が含まれます。

  • バッテリー容量
  • フル充電までの時間(秒)
  • フル充電の設計容量(~μAh)

Health HAL の実装に役立つクラスについては、次の UML 図をご覧ください。

Health HAL 2.1 の UML 図

図 7. Health HAL 2.1 の UML 図

Health サービス 2.1 の実装については、Health 2.1 の実装をご覧ください。

AIDL HAL インターフェース バージョン 1

API の変更

AIDL バージョン 1 HAL は、HIDL 2.1 HAL と同様の API をサポートしています。HIDL 2.1 インターフェースと比較して、API に次の変更が行われています。

  • HIDL HAL 2.1 で導入された充電器関連の API は、AIDL HAL に移植されていません。オフモード充電の機能は /vendor パーティションでのみ有効であるため、ベンダー インターフェースの API は必要ありません。オフモード充電を適切に実装するには、下記の充電器をご覧ください。
  • StorageAttribute タイプと関連フィールドは、使用されていないため削除されました。
  • ホルダーでの充電をサポートするために、chargerDockOnlineHealthInfo に追加されました。

実装

Health HAL の実装に役立つクラスについては、次の UML 図をご覧ください。

Health AIDL HAL の UML 図

図 8. Health AIDL HAL の UML 図

Health AIDL サービスの実装については、Health AIDL HAL の実装をご覧ください。

リカバリ

Android 13 では、リカバリのバインダがサポートされています。Health AIDL サービスをリカバリにインストールすると、リカバリモードで実行できます。

Health AIDL サービスをリカバリにインストールする方法については、次のページをご覧ください。

充電器

オフモード充電の機能は、/system から /vendor に移動されました。Android 13 を搭載したデバイスがオフモード充電をサポートする場合、HAL サービス バイナリは充電器モードをサポートする必要があります。詳しくは、充電器の実装をご覧ください。

充電器のシステム プロパティ

/vendorcharger バイナリでは、プロパティ ro.charger.* を読み取れなくなりました。デバイスに ro.charger.* システム プロパティのいずれかが設定されている場合は、充電器のシステム プロパティをご覧ください。