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

智慧手錶

使用 Hanging-Get 模式變更電池狀態通知。

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

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

參數：

  • lease：選用的電源租用權杖，可在伺服器處理呼叫時讓系統保持喚醒狀態。如果呼叫立即獲得回應 (首次呼叫一律如此)，伺服器會將其傳回為 wake_lease，除非伺服器傳回自己的喚醒租約。如果通話處於保留狀態，伺服器會中斷通話。

傳回值：

  • status：電池目前的完整遙測快照。
  • wake_lease：用戶端在處理 status 時應持有的選用租約權杖：用戶端的 lease 在立即回覆時交回，或在變更觸發 wake_on 條件或 max_interval 樣本喚醒系統時，為設定 wake_on_max_interval 的用戶端提供喚醒租約。否則會省略。

錯誤：

  • 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 資源

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

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

列舉

錯誤彈性

類型：uint32

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

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

名稱值說明
1

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

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

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

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

這個連線已有待處理的 Watch 呼叫。

HealthStatus 彈性

類型：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

選用。電池化學成分說明 (例如「Li-ion」、「LiFePO4」、「NiMH」)。如果硬體不明或未經程式設計，則會省略。
model string:128

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

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

驅動程式必須填入這個表格，用戶端才能知道哪些欄位支援主動變更通知。如果驅動程式庫省略這個欄位，用戶端應假設不支援主動中斷監控。

  • supported_options.interest：變更時可主動觸發 hanging-get 監控通知的遙測欄位。省略的欄位是被動測量，不會產生硬體中斷；系統會在主動狀態變更期間或透過 Battery.GetStatus 傳回最新值。
  • supported_options.wake_on：可透過硬體中斷線等方式，主動將系統從暫停狀態喚醒的遙測欄位。
  • supported_options.max_interval：如果伺服器支援定期取樣，則會顯示這個值，代表伺服器接受的最短間隔。
  • supported_options.wake_on_max_interval：如果伺服器可以將系統從暫停狀態喚醒，以擷取 max_interval 樣本，則為 True。

狀態

定義於 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

內部電池溫度 (攝氏)。如果裝置不支援或無法使用溫度感應功能，則會省略。
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 中。預設為不含任何欄位：暫停期間發生的變更會延遲到下次系統喚醒時，且不會喚醒裝置。
max_interval zx/Duration

Watch 回應之間的最長時間。設定後，如果距離上次回應已超過這段時間，伺服器會以新取樣的 Status 完成待處理的 Watch，即使 interest 中的欄位未變更也一樣。時間是根據啟動時間軸計算，因此暫停的時間也會計入。預設為 absent：Watch 只會在變更時完成。如果伺服器不支援定期取樣，則會從 ConfigureWatch 傳回的有效選項和 Spec.supported_options 中省略這個欄位。伺服器可能會限制該值，並在有效選項中回報將採用的間隔。除非設定 wake_on_max_interval，否則樣本不會將系統從暫停狀態喚醒：系統暫停時到期的樣本會在系統恢復後擷取。
wake_on_max_interval bool

系統暫停時，到期的 max_interval 樣本是否會喚醒系統。預設為 false；與 wake_on 相同，喚醒系統是客戶選擇承擔的成本。如果缺少 max_interval，則會略過。如果伺服器無法喚醒系統，則會從 ConfigureWatch 傳回的有效選項和 Spec.supported_options 中省略這個欄位。

UNIONS

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 版本