fuchsia.hardware.power.battery

Added: 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 资源

在 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：可在发生更改时主动触发挂起获取监视通知的遥测字段。省略的字段是被动测量值，不会生成硬件中断；它们的最新的值会在活跃状态更改期间或通过 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

内部电池温度（摄氏度）。 如果不支持或无法使用温度感测功能，则省略。
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 中。默认不设置任何字段：在暂停期间发生的更改会推迟到下次系统唤醒时，并且不会唤醒设备。

UNIONS

Battery_ConfigureWatch_Result strict

在 fuchsia.hardware.power.battery/battery.fidl 中定义

序数变体类型说明
response Battery_ConfigureWatch_Response
err Error
framework_err internal

Battery_GetSpec_Result strict

在 fuchsia.hardware.power.battery/battery.fidl 中定义

序数变体类型说明
response Battery_GetSpec_Response
err Error
framework_err internal

Battery_GetStatus_Result strict

在 fuchsia.hardware.power.battery/battery.fidl 中定义

序数变体类型说明
response Battery_GetStatus_Response
err Error
framework_err internal

Battery_Watch_Result strict resource

在 fuchsia.hardware.power.battery/battery.fidl 中定义

序数变体类型说明
response Battery_Watch_Response
err Error
framework_err internal

服务

服务

在 fuchsia.hardware.power.battery/battery.fidl 中定义

名称类型传输
电池 fuchsia.hardware.power.battery/Battery 渠道