exchg - 充电管理扩展库
作者：王世豪
一、概述
本扩展库适用于Air8000/Air7000/Air6000等集成了内置电池充电方案的模组型号； Air8000/Air7000/Air6000内置的充电IC为YHM2712，exchg扩展库基于本充电IC进行设计。
二、核心示例
local function exchg_task_func()
exchg.setup(4200, 400)
while true do
local status = exchg.status()
if status.result then
log.info("电池电压:", status.vbat_voltage,
"充电阶段:", status.charge_stage,
"充电是否完成:", status.charge_complete,
"电池在位:", status.battery_present,
"充电器在位:", status.charger_present,
"IC过热:", status.ic_overheat)
end
sys.wait(20000)
end
end
-- 事件回调函数
local function exchg_callback(event)
if event == exchg.OVERHEAT then
log.info("警告：设备温度过高！")
elseif event == exchg.CHARGER_IN then
log.info("充电器已插入")
elseif event == exchg.CHARGER_OUT then
log.info("充电器已拔出")
end
end
-- 注册回调
exchg.on(exchg_callback)
sys.taskInit(exchg_task_func)
三、常量详解
核心库常量，顾名思义是由合宙LuatOS内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
3.1 exchg.OVERHEAT
常量含义：IC过热事件；
数据类型：number；
取值范围：1；
示例代码：local function overheatCallback()
log.info("IC过热")
end
exchg.on(exchg.OVERHEAT, overheatCallback)
3.2 exchg.CHARGER_IN
常量含义：充电器插入事件；
数据类型：number；
取值范围：2；
示例代码：local function chargerInCallback()
log.info("充电器已插入")
end
exchg.on(exchg.CHARGER_IN, chargerInCallback)
3.3 exchg.CHARGER_OUT
常量含义：充电器拔出事件；
数据类型：number；
取值范围：3；
示例代码：local function chargerOutCallback()
log.info("充电器已拔出")
end
exchg.on(exchg.CHARGER_OUT, chargerOutCallback)
3.4 exchg.CCMIN
常量含义：最小充电电流；
数据类型：string；
取值范围："MIN"；
注意：虽然常量本身取值为"MIN"，但在实际应用中，所有容量电池对应的具体最小充电电流值一致，均为50mA（单位：mA）
示例代码: exchg.setup(4200, 1000, exchg.CCMIN) -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为最小电流
3.5 exchg.CCDEFAULT
常量含义：默认充电电流；
数据类型：string；
取值范围："DEFAULT"；
注意：虽然常量本身取值为"DEFAULT"，但在实际应用中，不同电池容量对应的具体默认充电电流值不同。以下是不同容量对应的CCDEFAULT具体数值（单位：mA）：
- 电池容量为100mAh时，CCDEFAULT对应50mA
- 电池容量为200mAh时，CCDEFAULT对应125mA
- 电池容量为300mAh时，CCDEFAULT对应175mA
- 电池容量为400mAh时，CCDEFAULT对应225mA
- 电池容量为500mAh时，CCDEFAULT对应250mA
- 电池容量为600mAh时，CCDEFAULT对应250mA
- 电池容量为700mAh时，CCDEFAULT对应375mA
- 电池容量为800mAh时，CCDEFAULT对应375mA
- 电池容量为900mAh时，CCDEFAULT对应375mA
- 电池容量为1000mAh时，CCDEFAULT对应500mA
- 电池容量大于1000mAh时，CCDEFAULT与1000mAh保持一致，对应500mA
示例代码: exchg.setup(4200, 1000, exchg.CCDEFAULT) -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为默认电流
3.6 exchg.CCMAX
常量含义：最大充电电流；
数据类型：string；
取值范围："MAX"；
注意：虽然常量本身取值为"MAX"，但在实际应用中，不同电池容量对应的具体最大充电电流值不同。以下是不同容量对应的CCMAX具体数值（单位：mA）：
- 电池容量为100mAh时，CCMAX对应50mA
- 电池容量为200mAh时，CCMAX对应125mA
- 电池容量为300mAh时，CCMAX对应175mA
- 电池容量为400mAh时，CCMAX对应225mA
- 电池容量为500mAh时，CCMAX对应250mA
- 电池容量为600mAh时，CCMAX对应375mA
- 电池容量为700mAh时，CCMAX对应500mA
- 电池容量为800mAh时，CCMAX对应500mA
- 电池容量为900mAh时，CCMAX对应500mA
- 电池容量为1000mAh时，CCMAX对应750mA
- 电池容量大于1000mAh时，CCMAX与1000mAh保持一致，对应750mA
示例代码: exchg.setup(4200, 1000, exchg.CCMAX) -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为最大电流
四、函数详解
4.1 exchg.start()
功能
开启充电；
注意事项
开启充电 exchg.start() 默认自动执行，用户可以不用操作；
当碰到某些需要手动开启充电功能的场景时，大家可以自行控制，当前仅为预留；
必须在task中运行，最大阻塞时间大概为700ms, 阻塞主要由sys.waitUntil("YHM27XX_REG", 500)和sys.wait(200)产生。
参数
无
返回值
local result = exchg.start()
result
参数含义：是否开启成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示开启成功，false表示开启失败；
示例
local result = exchg.start()
log.info("exchg", "start", result)
4.2 exchg.stop()
功能
关闭充电
注意事项
当碰到某些需要手动关闭充电功能的场景时，大家可以自行控制，当前仅为预留；
必须在task中运行，最大阻塞时间大概为700ms, 阻塞主要由sys.waitUntil("YHM27XX_REG", 500)和sys.wait(200)产生。
参数
无
返回值
local result = exchg.stop()
result
参数含义：是否关闭成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示关闭成功，false表示关闭失败；
示例
local result = exchg.stop()
log.info("exchg", "stop", result)
4.3 exchg.setup(v_battery, cap_battery, i_charge)
功能
设置电池的充电截止电压,电池容量,充电电流;
注意事项
必须在task中运行，最大阻塞时间大概为700ms, 阻塞主要由sys.waitUntil("YHM27XX_REG", 500)和sys.wait(200)产生。
参数
v_battery
参数含义：电池充电截止电压；
数据类型：number；
取值范围：4200或4350可选；
是否必选：是；
注意事项：作为必需参数，若不提供会导致错误；
示例代码：4200
cap_battery
参数含义：电池容量；
数据类型：number；
取值范围：>= 100；
是否必选：是；
注意事项：作为必需参数，若不提供会导致错误；
参数示例：1000
i_charge
参数含义：电池充电电流；
数据类型：string；
取值范围：exchg.CCMIN(最小电流) 或 exchg.CCDEFAULT(默认电流) 或 exchg.CCMAX()；
是否必选：否；
注意事项：不传入时默认值为exchg.CCDEFAULT；
参数示例：exchg.CCMIN
返回值
local result = exchg.setup(4200, 1000, exchg.CCMIN)
result
参数含义：是否设置成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示设置成功，false表示设置失败；
示例
-- 设置电池充电截止电压为4.2V, 电池容量为400mAh, 充电电流为最小电流
local result = exchg.setup(4200, 400, exchg.CCMIN)
log.info("exchg", "setup", result)
4.4 exchg.status()
功能
获取当前充电系统的完整状态，包括电池电压、充电阶段、充电状态、电池在位状态、充电器在位状态以及IC过热状态等信息。
其中充电器是否在位，中断触发，触发回调事件为CHARGER_STATE_EVENT，附带的参数 true表示充电器在位，false表示充电器不在位。
注意事项
必须在task中运行，最大阻塞时间(包括超时重试时间)大概为20s。
参数
无
返回值
table类型，返回充电状态信息，格式如下：
local status = exchg.status()
status
{
result = boolean, -- true: 成功, false: 失败
vbat_voltage = number, -- 电池电压值（单位：mV），特殊值含义：
-- -1: 当前阶段不需要测量
-- -2: 电压测量失败
-- -3: 仅充电器就绪（无电池）
charge_stage = number, -- 当前充电阶段描述，可能值：
-- 0 : 放电模式
-- 1 : 预充电模式
-- 2 : 涓流充电
-- 3 : 恒流快速充电
-- 4 : 预留状态
-- 5 : 恒压快速充电
-- 6 : 预留状态
-- 7 : 充电完成
-- 8 : 未知状态
charge_complete = boolean, -- true: 充电完成, false: 充电未完成
battery_present = boolean, -- true: 电池在位, false: 电池不在位
charger_present = boolean, -- true: 充电器在位, false: 充电器不在位
ic_overheat = boolean -- true: 充电IC过热, false: 充电IC未过热
}
示例
local status = exchg.status()
if status.result then
log.info("电池电压:", status.vbat_voltage,
"充电阶段:", status.charge_stage,
"充电是否完成:", status.charge_complete,
"电池在位:", status.battery_present,
"充电器在位:", status.charger_present,
"IC过热:", status.ic_overheat)
end
4.5 exchg.on(func)
功能
注册事件回调函数，用于监听和响应充电系统的状态变化事件。
注意事项
无
参数
func
参数含义：exchg事件回调函数，回调函数的格式为：
function call_back(event)
-- 事件处理逻辑
end
该回调函数接收一个参数event，event为事件类型，事件类型如下：
-- 事件类型
exchg.OVERHEAT -- 充电IC过热
exchg.CHARGER_IN -- 充电器插入
exchg.CHARGER_OUT -- 充电器拔出
数据类型：function；
取值范围：回调函数本身无取值范围这一说法；
是否必选：是；
参数示例：-- 如下方所示，这是注册exchg事件的回调函数写法；
local function exchg_callback(event)
if event == exchg.OVERHEAT then
log.info("警告：设备温度过高！")
elseif event == exchg.CHARGER_IN then
log.info("充电器已插入")
elseif event == exchg.CHARGER_OUT then
log.info("充电器已拔出")
end
end
-- 注册回调
exchg.on(exchg_callback)
返回值
无
示例
local function exchg_callback(event)
if event == exchg.OVERHEAT then
log.info("警告：设备温度过高！")
elseif event == exchg.CHARGER_IN then
log.info("充电器已插入")
elseif event == exchg.CHARGER_OUT then
log.info("充电器已拔出")
end
end
-- 注册回调
exchg.on(exchg_callback)
五、产品支持说明
本扩展库适用于Air8000/Air7000/Air6000等集成了内置电池充电方案的模组型号