Linux power supply class
Linux power supply class
========================
UPS:不间断电源, uninterrupted power supply，当正常交流供电中断时，将蓄电池输出的直流变换成交流持续供电的电源设备。
AC:交流电(alternating current)
DC:直流电（Direct Current，简称DC），是指方向和时间不作周期性变化的电流，但电流大小可能不固定，而产生波形。
摘要
~~~~
Power supply class用于向用户层提供电池、UPS、AC、DC等电源的属性。
其中定义了一系列核心属性，几乎囊括所有电源设备。这些属性通过sysfs和uevent接口
与用户层进行交互。
每个属性都有确切的定义，这取决于其使用的度量单位。这一系列属性是为了能够广泛适
用于任意电源，单个监测硬件(电源监测硬件)可能无法提供所有预定义的属性，不存在的
属性可以忽略，不提供。
Power supply class是可扩展的，允许驱动只定义其存在的属性。核心属性集的选定也
是Linux演进的一个方面(即，如果发现有些属性适用于大多电源类型或它们的驱动，则可
以添加到核心属性集中)。
Power supply class整合了LED框架，这样就可以使用LED来指示电池充电/充满状态或
AC/USB插入状态(具体操作细节和使用由驱动来控制)。
Attributes/properties
~~~~~~~~~~~~~~~~~~~~~
Power supply class预定义了一系列的属性以避免驱动之间的重复定义，建议驱动使用预
定义的属性和单位。
用户空间拿到这些属性数据并已知它们的单位，经过加工之后以一致的方式呈现给用户。
Units
~~~~~
引用 include/linux/power_supply.h 里的话：
All voltages, currents, charges, energies, time and temperatures in µV,
µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
stated. It's driver's job to convert its raw values to units in which
this class operates.
电压、电流、电荷、能量、时间和温度单位分别为 µV, µA, µAh, µWh, seconds和
0.1摄氏度。由驱动来完成原始值到这些单位的转换。
Attributes/properties detailed
"charge"(µAh) 和 "energy" (µWh) 都可以用来表示电池的电量"capacity"，区别是：
~ CHARGE_* 以 µAh 为单位来表示电量。
~ ENERGY_* 以 µWh 为单位来表示电量。
~ CAPACITY 以百分比来表示电量，从 0 到 100。
后缀：
_AVG - 平均值。
_NOW - 当前值(瞬时值，与平均值相对)。
STATUS - 表示当前的电源状态(charging, full, discharging 等)。
CHARGE_TYPE - 电池可以以不同速率充电，此属性定义涓流充电和快速充电。对于未充电
可显示'n/a'(或'unknown')。
HEALTH - 表示电池的健康状况。取值为POWER_SUPPLY_HEALTH_*。
VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - 电源的电大/最小电压值。其意义是电池在
正常情况下"full"/"empty"时刻的电压值。电池的电压和电量并没有直接关系，但一些电
池使用电压来估算电量。电池驱动可以使用这两个属性向用户空间提供一块电池的最大最
小电压阀值。
VOLTAGE_MAX, VOLTAGE_MIN - 同_DESIGN，在只能估算阀值时使用这两个属性。
CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - 设计的电池满/空电量，以 µAh 为单位。
ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - 同上，以 µWh 为单位。
CHARGE_FULL, CHARGE_EMPTY - 上次记录的电池满/空电荷值。此属性表示实际阀值，而不是设计值。
CHARGE_COUNTER - 当前电荷数量(µAh)，可能为负数。没有确定的空或满状态的值，只在以时间度量时有用。
ENERGY_FULL, ENERGY_EMPTY - 上次记录的电池满/空电荷值。此属性表示实际阀值，而不是设计值。。
CAPACITY - 电量百分比。
CAPACITY_LEVEL - 电量等级，对应于POWER_SUPPLY_CAPACITY_LEVEL_*属性。
TEMP - 电源温度
TEMP_AMBIENT - 周边环境温度
TIME_TO_EMPTY - 电池剩余时间(秒)
TIME_TO_FULL - 电池充电距离充满的时间(秒)
Battery <-> external power supply interaction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
电池与外部电源的交互
通常电源会同时扮演生产(supplies)和消费(supplicants)的角色，电池就是这样。
所以电池对于当前是否有外部电源非常敏感。
所以，power supply class要为电池实现通知机制。
外部电源(如AC)用"supplied_to"成员列出它的请求者(电池)的名称，而外部电源调用
power_supply_changed()会通过external_power_changed回调函数来通知到它的请求者。
QA
~~
Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
A: If you cannot find attribute suitable for your driver needs, feel free
to add it and send patch along with your driver.
The attributes available currently are the ones currently provided by the
drivers written.
Good candidates to add in future: model/part#, cycle_time, manufacturer,
etc.
Q: I have some very specific attribute (e.g. battery color), should I add
this attribute to standard ones?
我有一些非常特殊的属性(比如：电池颜色)，我可以将其加入标准属性列表中么？
A: Most likely, no. Such attribute can be placed in the driver itself, if
it is useful. Of course, if the attribute in question applicable to
large set of batteries, provided by many drivers, and/or comes from
some general battery specification/standard, it may be a candidate to
be added to the core attribute set.
八成是不行的。类似这种属性可以将其放入驱动中而不是power supply class中。
当然，如果这个属性可能适用于大部分电池，且许多驱动都提供，且来自于某些电池
规范或标准，它将会被加入核心属性集中。
Q: Suppose, my battery monitoring chip/firmware does not provides capacity
in percents, but provides charge_{now,full,empty}. Should I calculate
percentage capacity manually, inside the driver, and register CAPACITY
attribute? The same question about time_to_empty/time_to_full.
假设，我的电池监测芯片或固件不提供电量百分比，但是提供了其他的电量属性。可
以在驱动中计算出电量百分比，然后注册CAPACITY属性么？
A: Most likely, no. This class is designed to export properties which are
directly measurable by the specific hardware available.
八成不行。power supply class被设计为导出硬件可直接测量的属性。
Inferring not available properties using some heuristics or mathematical
model is not subject of work for a battery driver. Such functionality
should be factored out, and in fact, apm_power, the driver to serve
legacy APM API on top of power supply class, uses a simple heuristic of
approximating remaining battery capacity based on its charge, current,
voltage and so on. But full-fledged battery model is likely not subject
for kernel at all, as it would require floating point calculation to deal
with things like differential equations and Kalman filters. This is
better be handled by batteryd/libbattery, yet to be written.
使用一些探索方法或数学模型来推断不存在的属性，这不是电池驱动的工作。这项工
作应该被分解为其他功能，事实上，apm_power驱动使用一些简单的探索方法，根据电
荷、电流、电压等估算电量。但是成熟的电池模型并不是内核的工作，因为它需要浮
点计算来处理一些如微分方程、卡尔曼滤波等问题。这些工作更适合被专用的库来完
成。
========================
UPS:不间断电源, uninterrupted power supply，当正常交流供电中断时，将蓄电池输出的直流变换成交流持续供电的电源设备。
AC:交流电(alternating current)
DC:直流电（Direct Current，简称DC），是指方向和时间不作周期性变化的电流，但电流大小可能不固定，而产生波形。
摘要
~~~~
Power supply class用于向用户层提供电池、UPS、AC、DC等电源的属性。
其中定义了一系列核心属性，几乎囊括所有电源设备。这些属性通过sysfs和uevent接口
与用户层进行交互。
每个属性都有确切的定义，这取决于其使用的度量单位。这一系列属性是为了能够广泛适
用于任意电源，单个监测硬件(电源监测硬件)可能无法提供所有预定义的属性，不存在的
属性可以忽略，不提供。
Power supply class是可扩展的，允许驱动只定义其存在的属性。核心属性集的选定也
是Linux演进的一个方面(即，如果发现有些属性适用于大多电源类型或它们的驱动，则可
以添加到核心属性集中)。
Power supply class整合了LED框架，这样就可以使用LED来指示电池充电/充满状态或
AC/USB插入状态(具体操作细节和使用由驱动来控制)。
Attributes/properties
~~~~~~~~~~~~~~~~~~~~~
Power supply class预定义了一系列的属性以避免驱动之间的重复定义，建议驱动使用预
定义的属性和单位。
用户空间拿到这些属性数据并已知它们的单位，经过加工之后以一致的方式呈现给用户。
Units
~~~~~
引用 include/linux/power_supply.h 里的话：
All voltages, currents, charges, energies, time and temperatures in µV,
µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
stated. It's driver's job to convert its raw values to units in which
this class operates.
电压、电流、电荷、能量、时间和温度单位分别为 µV, µA, µAh, µWh, seconds和
0.1摄氏度。由驱动来完成原始值到这些单位的转换。
Attributes/properties detailed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Charge/Energy/Capacity 别弄混了"charge"(µAh) 和 "energy" (µWh) 都可以用来表示电池的电量"capacity"，区别是：
~ CHARGE_* 以 µAh 为单位来表示电量。
~ ENERGY_* 以 µWh 为单位来表示电量。
~ CAPACITY 以百分比来表示电量，从 0 到 100。
后缀：
_AVG - 平均值。
_NOW - 当前值(瞬时值，与平均值相对)。
STATUS - 表示当前的电源状态(charging, full, discharging 等)。
CHARGE_TYPE - 电池可以以不同速率充电，此属性定义涓流充电和快速充电。对于未充电
可显示'n/a'(或'unknown')。
HEALTH - 表示电池的健康状况。取值为POWER_SUPPLY_HEALTH_*。
VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - 电源的电大/最小电压值。其意义是电池在
正常情况下"full"/"empty"时刻的电压值。电池的电压和电量并没有直接关系，但一些电
池使用电压来估算电量。电池驱动可以使用这两个属性向用户空间提供一块电池的最大最
小电压阀值。
VOLTAGE_MAX, VOLTAGE_MIN - 同_DESIGN，在只能估算阀值时使用这两个属性。
CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - 设计的电池满/空电量，以 µAh 为单位。
ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - 同上，以 µWh 为单位。
CHARGE_FULL, CHARGE_EMPTY - 上次记录的电池满/空电荷值。此属性表示实际阀值，而不是设计值。
CHARGE_COUNTER - 当前电荷数量(µAh)，可能为负数。没有确定的空或满状态的值，只在以时间度量时有用。
ENERGY_FULL, ENERGY_EMPTY - 上次记录的电池满/空电荷值。此属性表示实际阀值，而不是设计值。。
CAPACITY - 电量百分比。
CAPACITY_LEVEL - 电量等级，对应于POWER_SUPPLY_CAPACITY_LEVEL_*属性。
TEMP - 电源温度
TEMP_AMBIENT - 周边环境温度
TIME_TO_EMPTY - 电池剩余时间(秒)
TIME_TO_FULL - 电池充电距离充满的时间(秒)
Battery <-> external power supply interaction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
电池与外部电源的交互
通常电源会同时扮演生产(supplies)和消费(supplicants)的角色，电池就是这样。
所以电池对于当前是否有外部电源非常敏感。
所以，power supply class要为电池实现通知机制。
外部电源(如AC)用"supplied_to"成员列出它的请求者(电池)的名称，而外部电源调用
power_supply_changed()会通过external_power_changed回调函数来通知到它的请求者。
QA
~~
Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
A: If you cannot find attribute suitable for your driver needs, feel free
to add it and send patch along with your driver.
The attributes available currently are the ones currently provided by the
drivers written.
Good candidates to add in future: model/part#, cycle_time, manufacturer,
etc.
Q: I have some very specific attribute (e.g. battery color), should I add
this attribute to standard ones?
我有一些非常特殊的属性(比如：电池颜色)，我可以将其加入标准属性列表中么？
A: Most likely, no. Such attribute can be placed in the driver itself, if
it is useful. Of course, if the attribute in question applicable to
large set of batteries, provided by many drivers, and/or comes from
some general battery specification/standard, it may be a candidate to
be added to the core attribute set.
八成是不行的。类似这种属性可以将其放入驱动中而不是power supply class中。
当然，如果这个属性可能适用于大部分电池，且许多驱动都提供，且来自于某些电池
规范或标准，它将会被加入核心属性集中。
Q: Suppose, my battery monitoring chip/firmware does not provides capacity
in percents, but provides charge_{now,full,empty}. Should I calculate
percentage capacity manually, inside the driver, and register CAPACITY
attribute? The same question about time_to_empty/time_to_full.
假设，我的电池监测芯片或固件不提供电量百分比，但是提供了其他的电量属性。可
以在驱动中计算出电量百分比，然后注册CAPACITY属性么？
A: Most likely, no. This class is designed to export properties which are
directly measurable by the specific hardware available.
八成不行。power supply class被设计为导出硬件可直接测量的属性。
Inferring not available properties using some heuristics or mathematical
model is not subject of work for a battery driver. Such functionality
should be factored out, and in fact, apm_power, the driver to serve
legacy APM API on top of power supply class, uses a simple heuristic of
approximating remaining battery capacity based on its charge, current,
voltage and so on. But full-fledged battery model is likely not subject
for kernel at all, as it would require floating point calculation to deal
with things like differential equations and Kalman filters. This is
better be handled by batteryd/libbattery, yet to be written.
使用一些探索方法或数学模型来推断不存在的属性，这不是电池驱动的工作。这项工
作应该被分解为其他功能，事实上，apm_power驱动使用一些简单的探索方法，根据电
荷、电流、电压等估算电量。但是成熟的电池模型并不是内核的工作，因为它需要浮
点计算来处理一些如微分方程、卡尔曼滤波等问题。这些工作更适合被专用的库来完
成。
