fuchsia.hardware.power.battery

新增：HEAD

通訊協定

電池

定義於 fuchsia.hardware.power.battery/battery.fidl

電池硬體的診斷和遙測介面。

這是唯讀通訊協定，支援多個並行用戶端。

ConfigureWatch

設定這個用戶端連線的感興趣的欄位和喚醒觸發條件。

驅動程式會根據硬體功能篩選所要求的遮罩，並在 effective_options 中傳回有效設定。

  • 部分支援的選項：如果部分要求的欄位受支援，其他則否 (例如要求不支援主動中斷通知的被動欄位，如 voltage_uv 或 current_ua)，驅動程式庫會啟用支援的欄位，並在 effective_options 中傳回主動子集。呼叫成功 (Ok)。
  • 完全不受支援的選項：如果指定了非空白遮罩，但系統不支援任何要求的欄位，驅動程式庫會傳回 NOT_SUPPORTED。

如果從未呼叫 ConfigureWatch，Watch 預設會在任何支援的欄位變更時傳回。驅動程式會匯總所有用戶端的限制，以判斷硬體回報率。

ConfigureWatch 可隨時呼叫，包括 Watch 待處理時。新的遮蓋會立即生效，並套用至待處理的通話。變更偵測功能會繼續與上次透過這個連線傳送的狀態進行比較，因此在重新設定前變更的欄位，仍可解決待處理的 Watch。

參數：

  • options：要求的觀看選項。interest 和 wake_on 皆為選用欄位。

退貨：

  • effective_options：驅動程式庫支援及啟用的要求選項子集。

錯誤：

  • NOT_SUPPORTED：系統要求非空白選項，但驅動程式庫不支援任何要求的興趣/喚醒欄位。

發生錯誤時，連線的設定不會變更；失敗的呼叫絕不會部分套用。

要求

名稱類型
options WatchOptions

回應

名稱類型
payload Battery_ConfigureWatch_Result

GetSpec

擷取電池的靜態規格。

退貨：

  • spec：電池的靜態硬體特性和驅動程式庫功能。

錯誤：

  • NOT_SUPPORTED：硬體未提供靜態規格。
  • IO：無法與電量計硬體通訊 (例如 I2C 傳輸失敗)。
  • INTERNAL：內部驅動程式庫錯誤。

要求

<EMPTY>

回應

名稱類型
payload Battery_GetSpec_Result

GetStatus

擷取電池狀態的即時快照。

退貨：

  • status：完成電池指標的目前遙測快照。

錯誤：

  • IO：無法與電量計硬體通訊 (例如 I2C 傳輸失敗)。
  • INTERNAL：內部驅動程式庫錯誤。

要求

<EMPTY>

回應

名稱類型
payload Battery_GetStatus_Result

智慧手錶

使用暫止式擷取模式變更電池狀態通知。

第一次呼叫會立即傳回目前的完整硬體狀態。後續呼叫會封鎖，直到狀態變更符合 ConfigureWatch 中的遮罩為止。每次傳回的資料都包含所有目前電池欄位的完整遙測快照，而非稀疏的差異。

每個連線最多只能有一次未完成的 Watch 呼叫；並行呼叫會失敗，並傳回 ALREADY_WATCHING。

參數：

  • lease：選用的電源租用權杖，用於協調用戶端和伺服器之間的交接，防止系統在處理重要電池事件前暫停。如果省略，系統就不會協調租約。如果驅動程式庫未在 Spec.supported_options 中宣傳任何 wake_on 欄位，系統會忽略 lease，並一律省略 wake_lease。

退貨：

  • status：電池的完整遙測快照。
  • wake_lease：如果變更觸發 wake_on 條件，系統會提供選填的保留權杖。如果變更未觸發喚醒條件，或暫停協調作業處於非啟用狀態，則會省略這項資訊。

錯誤：

  • ALREADY_WATCHING：這個連線已有待處理的 Watch 通話。
  • IO：無法與電量計硬體通訊 (例如 I2C 傳輸失敗)。
  • INTERNAL：內部驅動程式庫錯誤。

要求

名稱類型
lease fuchsia.power.system/LeaseToken

回應

名稱類型
payload Battery_Watch_Result

STRUCTS

Battery_ConfigureWatch_Response

定義於 fuchsia.hardware.power.battery/battery.fidl

欄位類型說明預設
effective_options WatchOptions 無預設值

Battery_GetSpec_Response

定義於 fuchsia.hardware.power.battery/battery.fidl

欄位類型說明預設
spec Spec 無預設值

Battery_GetStatus_Response

定義於 fuchsia.hardware.power.battery/battery.fidl

欄位類型說明預設
status Status 無預設值

Battery_Watch_Response resource

定義於 fuchsia.hardware.power.battery/battery.fidl

欄位類型說明預設
status Status 無預設值
wake_lease fuchsia.power.system/LeaseToken 無預設值

ENUMS

ChargeStatus flexible

類型：uint32

定義於 fuchsia.hardware.power.battery/battery.fidl

說明電池組的實際充電狀態。

名稱值說明
1

電池既未主動充電，也未放電 (淨電流接近零)，且尚未充飽電 (例如系統透過外部電源運作，但充電已暫停/閒置、受到熱節流限制，或處於電池保護模式)。
2

電池正在接收外部電源 (淨電流 > 0)。
3

電池正在為系統供電 (淨電流 < 0)。
4

電池已充飽，因此停止充電。

錯誤 flexible

類型：uint32

定義於 fuchsia.hardware.power.battery/battery.fidl

電池通訊協定傳回的錯誤。

名稱值說明
1

驅動程式庫發生未預期的錯誤。
2

這項硬體不支援要求的作業、欄位或模式。
3

提供給方法的一或多個引數無效，或要求的值超出硬體可程式設計的範圍。
4

無法與電池硬體通訊 (例如匯流排傳輸錯誤)。
5

這項連線已有待處理的 Watch 通話。

健康狀態 彈性

類型：uint32

定義於 fuchsia.hardware.power.battery/battery.fidl

電池健康度和安全狀態，包括 JEITA 溫度區域和故障情況。

每個值都會說明電池組是否可能充電，以及是否仍可為系統供電。除非值另有說明，否則電池仍可供電。

名稱值說明
1

正常作業溫度和電池健康狀態。允許充電和放電。
2

電池溫度低於安全充電門檻 (禁止充電)。 電池仍可供電，但可用容量和峰值電流通常會減少。
3

電池溫度過低 (充電電流或電壓可能受到限制)。 電池仍可供電。
4

電池溫度過高 (充電電流或電壓可能受到限制)。電池仍可供電。
5

電池溫度超過安全門檻 (禁止充電)。 電池通常仍可供電，但如果溫度持續升高，硬體保護機制可能會開啟放電路徑。
6

電池組電壓低於運作門檻或電池沒電。 電池無法為系統供電。
7

電池電壓超過硬體安全限制 (禁止充電)。 電池仍可供電，放電是預期的復原路徑。
8

未指定的硬體或油量計安全故障。 電池組是否可充電或供電，目前尚不確定。

TABLES

規格

定義於 fuchsia.hardware.power.battery/battery.fidl

靜態硬體特性和驅動程式庫功能。

序數欄位類型說明
design_capacity_uah uint32

選用。設計容量 (以微安培小時為單位)。如果硬體不支援，則會省略。
design_voltage_uv uint32

選用。以微伏特為單位的設計電壓。如果硬體不支援，則會省略。
chemistry string:128

選用。電池化學成分說明資訊 (例如「鋰離子」、「LiFePO4」、「NiMH」)。 如果硬體中未編程或不明，則可省略。
model string:128

選用。資訊型電池型號字串或製造商零件編號。 如果不明或未在硬體中程式化，則可省略。
supported_options WatchOptions

此為必要項目。這個驅動程式庫/硬體支援的興趣和喚醒選項。

驅動程式必須填入這個表格，讓用戶端瞭解哪些欄位支援主動變更通知。如果驅動程式庫省略此欄位，用戶端應假設系統不支援主動中斷觀看。

  • supported_options.interest：可主動觸發變更時暫止的 get 監控通知的遙測欄位。省略的欄位是不會產生硬體中斷的被動測量值；這些欄位的最新值會在有效狀態變更期間或透過 Battery.GetStatus 傳回。
  • supported_options.wake_on：可透過硬體中斷線等方式，主動喚醒系統的遙測欄位。

狀態

定義於 fuchsia.hardware.power.battery/battery.fidl

電池電量計的主要遙測快照。

所有欄位均為選填欄位。每個傳回的 Status 都代表完整的快照，而非稀疏的差異；驅動程式庫省略的欄位表示硬體燃料計量表不支援該指標，或目前無法使用/不確定。

注意：部分欄位 (例如即時 voltage_uv 和 current_ua) 可能是被動測量值，不會在變更時產生硬體中斷。如要瞭解可主動觸發變更通知的選項，請參閱 Spec.supported_options。

序數欄位類型說明
present bool

電池組是否實際存在並已連線。 如果為 false，表示電池已拆下/遺失。如果狀態不明，則會省略。
voltage_uv uint32

以微伏特為單位呈現端子電壓。 如果硬體不支援或無法使用，則會省略。
current_ua int32

目前電流 (以微安培為單位)：正號 (+) 代表充電，負號 (-) 代表放電。 如果硬體不支援或無法使用，則會省略。
level_percent float32

電量百分比，範圍為 [0.0, 100.0]。如果硬體無法判斷或不支援，則會省略這項資訊。
temp_celsius float32

電池內部溫度 (攝氏)。如果裝置不支援或無法使用溫度感應功能，系統會省略這項資訊。
charge_status ChargeStatus

高階充電狀態。 如果硬體無法判斷或不支援，則會省略這項資訊。
remaining_capacity_uah uint32

預估剩餘可用容量，以微安小時為單位。 如果硬體無法判斷或不支援，則會省略這項資訊。
full_charge_capacity_uah uint32

以微安時為單位的預估充飽電容量，反映電池組老化程度。 如果硬體無法判斷或不支援，則會省略這項資訊。
health HealthStatus

健康狀況或安全行程狀態。 如果硬體不支援健康狀態診斷，則會省略這項資訊。
cycle_count uint32

充放電週期總數。 如果硬體不支援經期追蹤功能，則會省略此步驟。
time_remaining zx/Duration

預估完全放電 (放電) 或完全充電 (充電) 的剩餘時間。 如果狀態不明、不受支援或電池閒置，則會省略這項資訊。

WatchOptions

定義於 fuchsia.hardware.power.battery/battery.fidl

電池狀態監控的設定選項。

這兩個欄位都是選填遮罩。在 interest 和 wake_on 中，系統都會忽略 Status 資料表中的實際欄位值，只會根據欄位是否存在 (已設定與未設定) 決定遮罩。

如果沒有遮罩，表示「使用這個欄位的預設值」；如果遮罩存在但為空白，表示「沒有任何欄位」。這兩種預設值不同，是因為安全選擇不同：interest 預設為驅動程式庫支援觀看的所有內容，因此即使用戶端從未設定任何項目，仍可繼續運作；而 wake_on 預設為無，因為喚醒系統是客戶必須選擇加入的費用。

序數欄位類型說明
interest Status

用戶端要接收變更通知的欄位。 根據預設，這會是驅動程式庫回報的每個支援觀看的欄位 (Spec.supported_options)。傳遞明確的空白資料表，只接收 wake_on 中指定欄位的通知。
wake_on Status

應主動喚醒系統的欄位。 wake_on 中的任何欄位都會隱含地納入 interest。預設為無欄位：暫停期間發生的變更會延後到下次系統喚醒時處理，且不會喚醒裝置。

工會

Battery_ConfigureWatch_Result strict

定義於 fuchsia.hardware.power.battery/battery.fidl

序數Variant類型說明
response Battery_ConfigureWatch_Response
err Error
framework_err internal

Battery_GetSpec_Result strict

定義於 fuchsia.hardware.power.battery/battery.fidl

序數Variant類型說明
response Battery_GetSpec_Response
err Error
framework_err internal

Battery_GetStatus_Result strict

定義於 fuchsia.hardware.power.battery/battery.fidl

序數Variant類型說明
response Battery_GetStatus_Response
err Error
framework_err internal

Battery_Watch_Result strict resource

定義於 fuchsia.hardware.power.battery/battery.fidl

序數Variant類型說明
response Battery_Watch_Response
err Error
framework_err internal

服務

服務

定義於 fuchsia.hardware.power.battery/battery.fidl

名稱類型傳輸
電池 fuchsia.hardware.power.battery/Battery 版本