exchg - 充电管理扩展库
作者：王世豪 | 最后修改：2026-03-11
一、概述
本扩展库适用于集成了内置电池充电方案的模组型号，例如Air8000；
Air8000内置的充电IC为YHM2712，exchg扩展库基于本充电IC进行设计。
二、核心示例
-
核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
-
核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
-
更加完整和详细的 demo，请参考 LuatOS 仓库 中支持充电管理的产品目录下的 demo/aircharge；
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；
注意事项：当检测到IC过热时，系统自动调用注册的回调函数，触发该事件；
示例代码：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)
3.2 exchg.CHARGER_IN
常量含义：充电器插入事件；
数据类型：number；
注意事项：当检测到充电器插入时，系统自动调用注册的回调函数，触发该事件；
示例代码：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)
3.3 exchg.CHARGER_OUT
常量含义：充电器拔出事件；
数据类型：number；
注意事项：当检测到充电器拔出时，系统自动调用注册的回调函数，触发该事件；
示例代码：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)
3.4 exchg.CCMIN
常量含义：最小充电电流；
数据类型：string；
注意事项：虽然常量本身取值为"MIN"，但在实际应用中，所有容量电池对应的具体最小充电电流值一致，均为50mA（单位：mA）
示例代码: -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为最小电流
exchg.setup(4200, 1000, exchg.CCMIN)
3.5 exchg.CCDEFAULT
常量含义：默认充电电流；
数据类型：string；
注意事项：虽然常量本身取值为"DEFAULT"，但在实际应用中，不同电池容量对应的具体默认充电电流值不同；
以下是不同容量对应的CCDEFAULT具体数值（单位：mA）：
- 电池容量为100-149mAh时，CCDEFAULT对应50mA
- 电池容量为150-249mAh时，CCDEFAULT对应125mA
- 电池容量为250-349mAh时，CCDEFAULT对应175mA
- 电池容量为350-449mAh时，CCDEFAULT对应225mA
- 电池容量为450-549mAh时，CCDEFAULT对应250mA
- 电池容量为550-649mAh时，CCDEFAULT对应250mA
- 电池容量为650-749mAh时，CCDEFAULT对应375mA
- 电池容量为750-849mAh时，CCDEFAULT对应375mA
- 电池容量为850-949mAh时，CCDEFAULT对应375mA
- 电池容量为950-1000mAh时，CCDEFAULT对应500mA
- 电池容量大于1000mAh时，CCDEFAULT对应500mA
示例代码: -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为默认电流
exchg.setup(4200, 1000, exchg.CCDEFAULT)
3.6 exchg.CCMAX
常量含义：最大充电电流；
数据类型：string；
注意事项：虽然常量本身取值为"MAX"，但在实际应用中，不同电池容量对应的具体最大充电电流值不同；
以下是不同容量对应的CCMAX具体数值（单位：mA）：
- 电池容量为100-149mAh时，CCMAX对应50mA
- 电池容量为150-249mAh时，CCMAX对应125mA
- 电池容量为250-349mAh时，CCMAX对应175mA
- 电池容量为350-449mAh时，CCMAX对应225mA
- 电池容量为450-549mAh时，CCMAX对应250mA
- 电池容量为550-649mAh时，CCMAX对应375mA
- 电池容量为650-749mAh时，CCMAX对应500mA
- 电池容量为750-849mAh时，CCMAX对应500mA
- 电池容量为850-949mAh时，CCMAX对应500mA
- 电池容量为950-1000mAh时，CCMAX对应750mA
- 电池容量大于1000mAh时，CCMAX对应750mA
示例代码: -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为最大电流
exchg.setup(4200, 1000, exchg.CCMAX)
四、函数详解
4.1 exchg.start()
功能
开启充电；
注意事项
开启充电 exchg.start() 默认自动执行，用户可以不用操作；
当碰到某些需要手动开启充电功能的场景时（例如在使用exchg.stop关闭充电功能后，可以使此接口重新开启充电功能），大家可以自行控制，当前仅为预留；
必须在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)
示例
local result = exchg.start()
log.info("exchg", "start", result)
4.2 exchg.stop()
功能
关闭充电
注意事项
当碰到某些需要手动关闭充电功能的场景时（例如：当充电ic温度超过120℃时，立刻调用此接口停止充电），大家可以自行控制，当前仅为预留；
必须在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)
示例
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
参数含义：电池充电截止电压，单位：mV；
数据类型：number；
取值范围：4200或4350可选；
是否必选：是；
注意事项：作为必需参数，若不提供会导致错误；
参数示例：4200；
cap_battery
参数含义：电池容量，单位：mAh；
数据类型：number；
取值范围：>= 100；
是否必选：是；
注意事项：作为必需参数，若不提供会导致错误；
参数示例：1000；
i_charge
参数含义：恒流充电电流，单位：mA；
锂电池充电过程有5个阶段：
1. 预充电，Pre-Charge ，预充电电流(IPRE)默认3mA；
2. 涓流充电，Trichle-Charge ，涓流充电电流(ITRICKLE)默认12.5mA；
3. 恒流充电，Constant-Current，可以通过exchg.setup接口设置；
4. 恒压充电，Constant-Voltage，当电池电压接近 Vreg 时，YHM2712A 进入恒压模式，
充电电流开始逐渐减小，下降到终止电流阈值时，充电结束。
5. 重新充电，Auto-Recharge，当电池电压低于Vreg电压120mV时开启，
其电流值由触发重新充电时电池的电压决定,可能是IPRE，ITRICKLE或者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表示设置失败；
返回示例：local result = exchg.setup(4200, 400, exchg.CCMIN)
log.info("exchg", "setup", result)
示例
-- 设置电池充电截止电压为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
含义说明：获取充电状态信息表，table内容格式说明如下：
{
-- 参数含义：状态查询是否成功；
-- 数据类型：boolean；
-- 取值范围：true(成功) / false(失败)；
-- 是否必选：是；
-- 注意事项：所有其他字段的有效性取决于此字段是否为true；
result
-- 参数含义：电池电压值；
-- 数据类型：number；
-- 取值范围：正常为实际电压值(mV)，特殊值如下：
-- -1 : 当前阶段不需要测量（预充电或涓流充电阶段不测量电压）；
-- -2 : 电压测量失败；
-- -3 : 仅充电器就绪，无电池；
-- 是否必选：是；
-- 注意事项：在预充电或涓流充电阶段(charge_stage=1或2)返回-1；
-- 电压测量失败时返回-2；
-- 仅充电器在位时返回-3
vbat_voltage
-- 参数含义：当前充电阶段描述；
-- 数据类型：number；
-- 取值范围：整数0-8,具体取值如下所示：
-- 0 : 放电模式
-- 1 : 预充电模式
-- 2 : 涓流充电
-- 3 : 恒流快速充电
-- 4 : 预留状态
-- 5 : 恒压快速充电
-- 6 : 预留状态
-- 7 : 充电完成
-- 8 : 未知状态
-- 是否必选：是；
-- 注意事项：数值对应不同充电阶段，可用于判断当前充电状态和进度；
charge_stage
-- 参数含义：充电是否完成；
-- 数据类型：boolean；
-- 取值范围：true(充电完成) / false(充电未完成)；
-- 是否必选：是；
-- 注意事项：当充电阶段为7时此字段为true；
charge_complete
-- 参数含义：电池是否在位；
-- 数据类型：boolean；
-- 取值范围：true(电池在位) / false(电池不在位)；
-- 是否必选：是；
-- 注意事项：可用于检测电池是否连接到设备；
battery_present
-- 参数含义：充电器是否在位；
-- 数据类型：boolean；
-- 取值范围：true(充电器在位) / false(充电器不在位)；
-- 是否必选：是；
-- 注意事项：指示USB充电器是否连接，同时会触发对应的CHARGER_IN/CHARGER_OUT事件；
charger_present
-- 参数含义：充电IC是否过热；
-- 数据类型：boolean；
-- 取值范围：true(充电IC过热) / false(充电IC未过热)；
-- 是否必选：是；
-- 注意事项：当充电IC温度过高时为true，同时会触发OVERHEAT事件；
ic_overheat
}
数据类型：table；
取值范围：符合上述结构的table对象；
是否必选：是；
注意事项：所有状态字段的有效性都依赖于result字段是否为true，在使用任何其他字段前应先检查result值；
参数示例：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
示例
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 callback(event)
log.info("callback",event)
end
该回调函数接收1个参数event，在不同事件类型下参数含义有所不同：
-- 参数含义：具体的回调事件；
-- 数据类型：number；
-- 取值范围：1，对应常量 exchg.OVERHEAT（充电IC过热）；
-- 2，对应常量 exchg.CHARGER_IN（充电器插入）；
-- 3，对应常量 exchg.CHARGER_OUT（充电器拔出）；
-- 是否必选：是；
-- 注意事项：用于标识不同的回调触事件；
event
数据类型：function；
取值范围：回调函数本身无取值范围这一说法；
是否必选：是；
注意事项：多次调用 exchg.on() 会覆盖之前设置的回调函数，同一时间只能有一个回调函数生效；
参数示例：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
返回值
无
示例
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。