26 aircharge 充电管理

一、 aircharge 概述

1.1 历史背景与使用限制

本文档最初专为内置 YHM2712 充电 IC 的 Air8000/8000G/8000XB/8000GB 等型号设计。然而，在实际应用中，该内置充电管理方案被发现存在一些固有问题，因此，含有此类内置充电 IC 的型号已不再推荐使用。

主要问题与风险如下：

1、供电路径管理复杂：内置充电 IC 不仅负责充电，还管理供电路径和提供短路保护。当使用充电器等外部电源（而非电池）供电时，若电路设计不当，极易导致电流流向错误（如向 DCDC 电路反向充电），造成 VBAT 供电网络混乱。

2、易触发短路保护导致“死机”：在快速断电又上电的情况下，充电 IC 会因检测到电压快速跌落而误判为电源短路，从而主动切断 VBAT 供电。其直接表现为：

• 无法开机

• 无法下载程序

• 电脑无法识别 USB 端口

3、保护状态恢复困难：一旦触发短路保护，常规复位手段无效。必须等待板载电容的余电完全放尽（使充电 IC 保护功能复位），或通过连接充电器（需接入 VCHG 引脚）来强制退出保护状态。这个等待时间可能长达数分钟，严重影响用户体验和设备可靠性。

4、对设计兼容性差：即使在电池供电系统中，若设计了拨动开关等硬复位电路，快速开关机同样会触发上述保护机制，导致设备需要等待较长时间（电容放电完毕）才能重新启动。

1.2 定位与适用场景

本文档主要面向 "电池供电 + 需要充电" 的应用场景。在此场景下，aircharge 提供对 Air8000 系列内置 YHM2712 充电管理 IC 的功能管理与状态监控，核心功能包括：

• 电池充电管理：配置电池参数，注册事件回调，处理充电状态变化。

• 电池过放保护：在电池电压骤降到 1V 以下时，自动切断供电电路，防止电池过放。

• 充电完成检测：监控充电状态，并在充电完成后触发相应事件。

• 电池电压测量：实时测量电池电压，监控电池状态。

重要提示：关于 Air8000 系列的更多特别说明，请参阅官方文档：Air8000 系列产品注意事项

二、演示功能概述

本文档所演示的功能如下：

1. 初始化 YHM2712 充电 IC

2. 配置电池参数

3. 注册事件回调

4. 处理充电状态变化

三、准备硬件环境

Air8000 开发板一块 + 可充电锂电池一块：

• 电池通过白色电池卡扣接入到 Air8000 开发板；

TYPE-C USB 数据线一根 ，Air8000 开发板和数据线的硬件接线方式为：

• Air8000 开发板通过 TYPE-C USB 口 对电池进行充电；（外部供电/USB 供电 拨动开关 拨到 USB 供电一端）

• TYPE-C USB 数据线直接插到核心板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

四、准备软件环境

4.1 软件环境

在开始实践本示例之前，先筹备一下软件环境：

1. 烧录工具：Luatools 工具；

2. 内核固件：本demo开发测试时使用的固件为Air8000 V2018 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试；

3. 脚本文件：点击此处查看；

4. LuatOS 运行所需要的 lib 文件：使用 Luatools 烧录时，勾选 添加默认 lib 选项，使用默认 lib 脚本文件。

准备好软件环境之后，接下来查看如何烧录项目文件到 Air8000 开发板中，将本篇文章中演示使用的项目文件烧录到 Air8000 开发板中。

4.2 API 介绍

1. pm 库：https://docs.openluat.com/osapi/core/pm/#410-pmchgcmdgpio-chip_add-reg-data

2. exchg 扩展库是基于 pm 库中的 pm.chgcmd 和 pm.chginfo 两个 api 接口实现的二次封装库。

此扩展库是专为内置 YHM2712 充电 IC 的 Air8000 系列型号所设计，如在模组外部使用了同型号的充电 IC，请使用 pm 库的pm.chgcmd和pm.chginfo两个 api 接口来实现充电管理功能，exchg 扩展库可作为一个参考。

接下来介绍 exchg 扩展库：

4.2.1 常量详解

扩展库常量，在 exchg 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

4.2.1.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)

4.2.1.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)

4.2.1.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)

4.2.1.4 exchg.CCMIN

常量含义：最小充电电流；
数据类型：string；
注意事项：虽然常量本身取值为"MIN"，但在实际应用中，所有容量电池对应的具体最小充电电流值一致，均为50mA（单位：mA）
示例代码: -- 设置电池充电截止电压为4.2V, 电池容量为1000mAh, 充电电流为最小电流
         exchg.setup(4200, 1000, exchg.CCMIN)

4.2.1.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)

4.2.1.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.2.2 函数详解

4.2.2.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.2.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.2.2.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.2.2.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.2.2.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)

五、程序结构

main.lua
aircharge.lua
exchg.lua
readme.md

5.1 文件说明

• main.lua：主程序入口文件。

• aircharge.lua ：电池充电管理主逻辑

• exchg.lua：充电管理扩展库

• readme.md ：项目说明文档

六、模块讲解

6.1 主程序（main.lua）

主程序文件 main.lua 是整个项目的入口点。它负责初始化系统环境。

6.2 aircharge.lua

功能 : 实现电池充电管理的业务逻辑和状态监控

内容 :

• 配置电池参数（充电截止电压、容量、充电电流）

• 注册充电事件回调，处理充电器插入/拔出、过热等事件

• 实现电池电压测量和电量百分比计算

• 定期监控充电状态，包括充电阶段、电池电压、充电完成状态等

• 实现过热保护逻辑，当充电 IC 过热时暂停充电

• 显示充电状态信息，记录状态变化

local exchg = require("exchg")

-- 配置参数
local BATTERY_VOLTAGE = 4200                -- 电池充电截止电压(mV): 4200或4350
local BATTERY_CAPACITY = 400                -- 电池容量(mAh)，根据实际电池容量设置
local CHARGE_CURRENT_MODE = exchg.CCDEFAULT -- 充电电流模式: exchg.CCMIN/exchg.CCDEFAULT/exchg.CCMAX

-- 上次充电状态，用于状态变化检测
local last_charge_status = nil
local last_battery_voltage = 0
local last_charger_state = false

-- 充电状态描述映射
local charge_stage_map = {
    [0] = "放电模式",
    [1] = "预充电模式",
    [2] = "涓流充电",
    [3] = "恒流快速充电",
    [4] = "预留状态",
    [5] = "恒压快速充电",
    [6] = "预留状态",
    [7] = "充电完成",
    [8] = "未知状态"
}

-- 事件回调函数
local function exchg_event_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 format_battery_voltage(voltage)
    if voltage < 0 then
        if voltage == -1 then return "当前阶段不需要测量" end
        if voltage == -2 then return "电压测量失败" end
        if voltage == -3 then return "仅充电器就绪（无电池）" end
        return "未知错误"
    end
    return string.format("%.2fV", voltage / 1000)
end

-- 计算电池电量百分比（简单估算）
local function calculate_battery_percentage(voltage)
    if voltage < 0 then return 0 end

    -- 简单的电压到百分比映射，实际应根据电池特性调整
    local min_voltage = 3300            -- 3.3V，电池最低电压
    local max_voltage = BATTERY_VOLTAGE -- 充电截止电压

    if voltage <= min_voltage then
        return 0
    elseif voltage >= max_voltage then
        return 100
    end

    -- 线性计算百分比（简单估算）
    local percentage = (voltage - min_voltage) / (max_voltage - min_voltage) * 100
    return math.floor(percentage)
end

-- 显示充电信息的函数
local function display_charge_info(status)
    if not status.result then
        log.error("充电管理", "获取充电状态失败")
        return
    end

    -- 计算电量百分比
    local percentage = calculate_battery_percentage(status.vbat_voltage)

    -- 格式化日志输出
    log.info("充电管理", string.format("电池电压: %s (%d%%)",
        format_battery_voltage(status.vbat_voltage), percentage))
    log.info("充电管理", string.format("充电阶段: %s",
        charge_stage_map[status.charge_stage] or "未知"))
    log.info("充电管理", string.format("充电完成: %s",
        status.charge_complete and "是" or "否"))
    log.info("充电管理", string.format("电池在位: %s",
        status.battery_present and "是" or "否"))
    log.info("充电管理", string.format("充电器在位: %s",
        status.charger_present and "是" or "否"))
    log.info("充电管理", string.format("IC过热: %s",
        status.ic_overheat and "是" or "否"))

    -- 检测并记录状态变化
    if last_charge_status ~= status.charge_stage then
        log.info("充电管理", string.format("状态变化: %s -> %s",
            charge_stage_map[last_charge_status] or "未知",
            charge_stage_map[status.charge_stage] or "未知"))
        last_charge_status = status.charge_stage
    end

    -- 检测电池电压变化超过100mV
    if math.abs(status.vbat_voltage - last_battery_voltage) > 100 and status.vbat_voltage > 0 then
        log.info("充电管理", string.format("电压变化显著: %.2fV", status.vbat_voltage / 1000))
        last_battery_voltage = status.vbat_voltage
    end

    -- 检测充电器状态变化
    if last_charger_state ~= status.charger_present then
        last_charger_state = status.charger_present
        log.info("充电管理", "充电器状态变化: " .. (status.charger_present and "连接" or "断开"))
    end
end

-- 电池管理任务
local function battery_management_task()
    log.info("充电管理", "初始化电池管理...")

    -- 注册事件回调
    exchg.on(exchg_event_callback)

    -- 设置电池参数
    log.info("充电管理", string.format("设置电池参数: %.2fV, %dmAh, %s",
        BATTERY_VOLTAGE / 1000, BATTERY_CAPACITY, CHARGE_CURRENT_MODE))

    local setup_result = exchg.setup(BATTERY_VOLTAGE, BATTERY_CAPACITY, CHARGE_CURRENT_MODE)
    if setup_result then
        log.info("充电管理", "电池参数设置成功")
    else
        log.error("充电管理", "电池参数设置失败，检查芯片是否支持")
        return
    end

    -- 启动充电（可选，根据exchg库说明，通常不需要手动调用）
    -- 但为了演示完整流程，这里包含调用示例
    log.info("充电管理", "尝试启动充电...")
    local start_result = exchg.start()
    if start_result then
        log.info("充电管理", "充电启动成功")
    else
        log.warn("充电管理", "充电启动失败或已自动启动")
    end

    log.info("充电管理", "开始监控电池状态...")

    -- 主循环，定期检查电池状态
    while true do
        -- 获取充电状态
        local status = exchg.status()
        if status then
            -- 显示充电信息
            display_charge_info(status)

            -- 如果电池充满电，可以添加相应处理
            if status.charge_complete and status.charger_present then
                log.info("充电管理", "电池已充满！")
            end

            -- 如果充电IC过热，采取保护措施
            if status.ic_overheat then
                log.warn("充电管理", "充电IC过热，正在暂停充电...")
                exchg.stop()
                log.info("充电管理", "充电已暂停，请等待设备降温")
                -- 等待一段时间后再次尝试
                sys.wait(60000) -- 等待60秒
                log.info("充电管理", "尝试恢复充电...")
                exchg.start()
            end
        else
            log.error("充电管理", "无法获取充电状态")
        end

        -- 根据状态调整检查频率
        if last_charger_state then
            -- 充电中，更频繁地检查
            sys.wait(20000) -- 20秒
        else
            -- 未充电，降低检查频率
            sys.wait(60000) -- 60秒
        end
    end
end

-- 系统初始化完成后执行
sys.taskInit(battery_management_task)

6.3 exchg.lua

功能: 基于 pm 库中的 pm.chgcmd 和 pm.chginfo 两个 api 接口进行二次封装。

内容:

• 定义充电电流常量 (exchg.CCMIN、exchg.CCDEFAULT、exchg.CCMAX)

• 定义事件常量 (exchg.OVERHEAT、exchg.CHARGER_IN、exchg.CHARGER_OUT)

• 提供 5 个 API:

• exchg.start() - 开启充电

• exchg.stop() - 关闭充电

• exchg.setup() - 设置电池参数（充电截止电压、容量、充电电流）

• exchg.status() - 获取充电系统状态

• exchg.on() - 注册事件回调函数

• 内部实现充电状态检测、电池电压测量、过热保护等功能

注：代码内容过多，故不在此处展示，请下载源码查看。

七、演示功能

代码烧录成功后，自动开机运行，通过 luatools 日志可以观察到以下信息：

八、总结

本文档通过 aircharge 示例代码，演示了如何基于 exchg 扩展库实现完整的电池充电管理功能。

但是需要注意，此示例代码仅适用于内置 YHM27XX 充电 IC 的 Air8000 系列型号。外置 YHM27XX 充电 IC 方案请直接使用 pm 库接口，本示例可作为架构参考。