fuchsia.hardware.power.battery

添加了：HEAD

PROTOCOLS

电池

在 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 无默认值

枚举

ChargeStatus 灵活

类型：uint32

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

描述电池组的实际充电状态。

名称值说明
1

电池既未主动充电也未放电（净电流接近于零），且尚未充满电（例如，系统正在使用外部电源运行，但充电已暂停/处于空闲状态、存在热节流或处于电池保护模式）。
2

电池正在主动从外部来源接收电量（净电流 > 0）。
3

电池正在主动为系统供电（净电流 < 0）。
4

电池已达到满电终止状态，不再充电。

错误 灵活

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

可选。信息性电池化学成分说明（例如“锂离子”“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

内部电池温度（以摄氏度为单位）。 如果不支持或无法使用温度感测，则省略。
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 中。默认值为无字段：在挂起期间发生的更改会延迟到下次系统唤醒时进行，并且不会唤醒设备。

UNIONS

Battery_ConfigureWatch_Result 严格

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

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

Battery_GetSpec_Result 严格

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

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

Battery_GetStatus_Result 严格

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

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

Battery_Watch_Result 严格 资源

在 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 渠道