跳转至

exs_yhm2712a - 充电管理扩展库

作者：王世豪　|　最后修改：2026-07-30

一、概述

exs_yhm2712a 是 YHM2712A 充电管理芯片的 LuatOS 扩展库。YHM2712A 是一款高性能的锂电池充电管理芯片，支持多种充电模式和智能保护功能。

1.1 主要特性

  • 支持 4.2V 和 4.35V 两种电池充电截止电压设置

  • 单总线通信接口，支持灵活的引脚配置

  • 智能充电阶段管理：涓流充电→恒流充电→恒压充电→充电完成

  • 内置过温保护和过压保护功能

  • 支持船运模式

  • 自动检测电池在位和充电器在位状态

  • 提供完整的充电状态查询和事件通知

1.2 注意事项

  • 必须在 task 中运行，部分操作有阻塞时间（如 sys.waitUntil 和 sys.wait）

  • 需要手动配置 YHM2712A 的 CMD 引脚

  • 充电电流会根据电池容量和模式自动计算

  • 支持多种充电电流模式：最小电流、默认电流、最大电流

  • 芯片 ID 为固定值 0x04，初始化时会自动校验

1.3 加载方式

-- 扩展库需要 require 加载后才能调用
local exs_yhm2712a = require "exs_yhm2712a"

1.4 硬件连接

┌──────────────┐                    ┌──────────────────┐
│    主控      │                     │    YHM2712A     │
│              │                    │ 充电管理芯片      │
│              │                    │                  │
│ CMD_PIN ─────┼────────────────────┼──→ CMD           │
│              │                    │                  │
│ VCC      ────┼────────────────────┼──→ VCC           │
│              │                    │                  │
│ GND      ────┼────────────────────┼──→ GND           │
└──────────────┘                    └──────────────────┘

二、核心示例

2.1 基础充电管理示例

-- 加载扩展库
local exs_yhm2712a = require "exs_yhm2712a"

-- YHM2712A 传感器初始化配置表
local YHM2712A_CONFIG = {
    pin = 25,                      -- CMD 引脚，连接到 Air8201H 的 GPIO25
    v_battery = 4200,              -- 电池充电截止电压：4200mV（4.2V）
    cap_battery = 400,             -- 电池容量：400mAh
    i_charge = exs_yhm2712a.CCMIN  -- 充电电流：最小电流（50mA）
}

-- 应用主函数
local function yhm2712a_demo()
    -- 初始化 YHM2712A
    local result = exs_yhm2712a.setup(YHM2712A_CONFIG)

    if not result then
        log.error("exs_yhm2712a", "YHM2712A 初始化失败")
        return
    end
    log.info("exs_yhm2712a", "YHM2712A 初始化成功")

    -- 循环读取充电状态
    while true do
        local status = exs_yhm2712a.status()

        if status.result then
            log.info("exs_yhm2712a", string.format("电池电压: %d mV, 充电阶段: %d, 充电完成: %s, 电池在位: %s, 充电器在位: %s, IC过热: %s", 
                status.vbat_voltage, 
                status.charge_stage, 
                status.charge_complete and "是" or "否", 
                status.battery_present and "是" or "否", 
                status.charger_present and "是" or "否", 
                status.ic_overheat and "是" or "否"))
        else
            log.error("exs_yhm2712a", "读取充电状态失败")
        end

        sys.wait(5000) -- 每5秒读取一次
    end
end

-- 启动任务
sys.taskInit(yhm2712a_demo)

2.2 事件监听示例

-- 加载扩展库
local exs_yhm2712a = require "exs_yhm2712a"

-- YHM2712A 传感器初始化配置表
local YHM2712A_CONFIG = {
    pin = 25,
    v_battery = 4350,
    cap_battery = 500,
    i_charge = exs_yhm2712a.CCDEFAULT
}

-- 事件回调函数
function yhm2712a_event_handler(event)
    if event == exs_yhm2712a.OVERHEAT then
        log.debug("yhm2712a", "IC温度过高，停止充电")
    elseif event == exs_yhm2712a.CHARGER_IN then
        log.debug("yhm2712a", "充电器已插入")
    elseif event == exs_yhm2712a.CHARGER_OUT then
        log.debug("yhm2712a", "充电器已拔出")
    elseif event == exs_yhm2712a.SHIPPING_MODE then
        log.debug("yhm2712a", "已进入船运模式")
    end
end

-- 初始化传感器
exs_yhm2712a.setup(YHM2712A_CONFIG)

-- 设置事件回调函数
exs_yhm2712a.on(yhm2712a_event_handler)

2.3 船运模式控制示例

-- 加载扩展库
local exs_yhm2712a = require "exs_yhm2712a"

-- YHM2712A 传感器初始化配置表
local YHM2712A_CONFIG = {
    pin = 25,
    v_battery = 4200,
    cap_battery = 300
}

function ship_mode_demo()
    -- 初始化传感器
    exs_yhm2712a.setup(YHM2712A_CONFIG)

    -- 进入船运模式
    local result = exs_yhm2712a.ship_mode()
    if result then
        log.info("exs_yhm2712a", "已成功进入船运模式")
    else
        log.error("exs_yhm2712a", "进入船运模式失败")
    end
end

sys.taskInit(ship_mode_demo)

三、常量详解

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

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为扩展库可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 exs_yhm2712a.OVERHEAT

常量含义：IC过热事件；
数据类型：number；
注意事项：当充电IC温度超过120℃时触发该事件，扩展库会自动停止充电；
示例代码：if event == exs_yhm2712a.OVERHEAT then
             log.info("警告：设备温度过高！")
         end；

3.2 exs_yhm2712a.CHARGER_IN

常量含义：充电器插入事件；
数据类型：number；
注意事项：当检测到充电器插入时触发该事件；
示例代码：if event == exs_yhm2712a.CHARGER_IN then
             log.info("充电器已插入")
         end；

3.3 exs_yhm2712a.CHARGER_OUT

常量含义：充电器拔出事件；
数据类型：number；
注意事项：当检测到充电器拔出时触发该事件；
示例代码：if event == exs_yhm2712a.CHARGER_OUT then
             log.info("充电器已拔出")
         end；

3.4 exs_yhm2712a.SHIPPING_MODE

常量含义：进入船运模式事件；
数据类型：number；
注意事项：当设备进入船运模式时触发该事件；
示例代码：if event == exs_yhm2712a.SHIPPING_MODE then
             log.info("已进入船运模式")
         end；

3.5 exs_yhm2712a.CCMIN

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

3.6 exs_yhm2712a.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, 充电电流为默认电流
         exs_yhm2712a.setup(4200, 1000, exs_yhm2712a.CCDEFAULT)

3.7 exs_yhm2712a.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, 充电电流为最大电流
         exs_yhm2712a.setup(4200, 1000, exs_yhm2712a.CCMAX)

四、函数详解

4.1 初始化

4.1.1 exs_yhm2712a.setup(config)

功能

初始化 YHM2712A 充电管理芯片，配置通信引脚和充电参数；

参数

config

```Plain Text 参数含义：初始化配置表 数据类型：table 取值范围：包含以下子参数： { 参数含义：YHM2712A CMD 引脚 数据类型：number 取值范围：有效的 GPIO 引脚编号 是否必选：是 参数示例：25 config.pin,

参数含义：电池充电截止电压（单位：mV）
数据类型：number
取值范围：4200 或 4350 可选
是否必选：是
参数示例：4200
config.v_battery,

参数含义：电池容量（单位：mAh）
数据类型：number
取值范围：>= 100
是否必选：是
参数示例：400
config.cap_battery,

参数含义：恒流充电电流（）单位：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
取值范围：exs_yhm2712a.CCMIN（最小电流）/ exs_yhm2712a.CCDEFAULT（默认电流）/ exs_yhm2712a.CCMAX（最大电流）
是否必选：否
注意事项：默认值为 exs_yhm2712a.CCDEFAULT
参数示例：exs_yhm2712a.CCMIN
config.i_charge

} 是否必选：是 参数示例： -- 最小化初始化 exs_yhm2712a.setup({ pin = 25, v_battery = 4200, cap_battery = 400 })

     -- 完整配置
     exs_yhm2712a.setup({
         pin = 25,
         v_battery = 4350,
         cap_battery = 500,
         i_charge = exs_yhm2712a.CCMAX
     })

**返回值** local init_result = exs_yhm2712a.setup(config) init_resultPlain Text 含义说明：初始化是否成功 数据类型：boolean 取值范围：true（成功）, false（失败） 注意事项：失败时请检查引脚配置、通信是否正常 返回示例：local result = exs_yhm2712a.setup(4200, 400, exchg.CCMIN) log.info("exs_yhm2712a", "setup", result) ```

示例

-- YHM2712A 传感器初始化配置表（最小化）
local YHM2712A_MIN_CONFIG = {
    pin = 25,
    v_battery = 4200,
    cap_battery = 400
}

-- YHM2712A 传感器初始化配置表（完整）
local YHM2712A_FULL_CONFIG = {
    pin = 25,
    v_battery = 4350,
    cap_battery = 500,
    i_charge = exs_yhm2712a.CCMAX
}

-- 使用默认参数初始化
function setup_min()
    local result = exs_yhm2712a.setup(YHM2712A_MIN_CONFIG)
    return result
end

-- 使用自定义配置
function setup_full()
    local result = exs_yhm2712a.setup(YHM2712A_FULL_CONFIG)
    return result
end

4.2 充电控制

4.2.1 exs_yhm2712a.start()

功能

开启充电功能；

注意事项

开启充电 exs_yhm2712a.start() 默认自动执行，用户可以不用操作；

当碰到某些需要手动开启充电功能的场景时（例如在使用exs_yhm2712a.stop关闭充电功能后，可以使此接口重新开启充电功能），大家可以自行控制，当前仅为预留；

必须在task中运行，最大阻塞时间大概为700ms, 阻塞主要由sys.waitUntil("YHM27XX_REG", 500)和sys.wait(200)产生。

参数

无

返回值

local result = exs_yhm2712a.start()

result

含义说明：是否开启成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示开启成功，false表示开启失败；
返回示例：local result = exs_yhm2712a.start()
         log.info("exs_yhm2712a", "start", result)

示例

function start_charging()
    local result = exs_yhm2712a.start()
    if result then
        log.info("exs_yhm2712a", "充电已开启")
    else
        log.error("exs_yhm2712a", "开启充电失败")
    end
    return result
end

4.2.2 exs_yhm2712a.stop()

功能

关闭充电功能；

注意事项

当碰到某些需要手动关闭充电功能的场景时（例如：当充电ic温度超过120℃时，立刻调用此接口停止充电），大家可以自行控制，当前仅为预留；

必须在task中运行，最大阻塞时间大概为700ms, 阻塞主要由sys.waitUntil("YHM27XX_REG", 500)和sys.wait(200)产生；

参数

无

返回值

local result = exs_yhm2712a.stop()

result

参数含义：是否关闭成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示关闭成功，false表示关闭失败；
返回示例：local result = exs_yhm2712a.stop()
         log.info("exs_yhm2712a", "stop", result)

示例

function stop_charging()
    local result = exs_yhm2712a.stop()
    if result then
        log.info("exs_yhm2712a", "充电已停止")
    else
        log.error("exs_yhm2712a", "停止充电失败")
    end
    return result
end

4.3 状态查询

4.3.1 exs_yhm2712a.status()

功能

获取当前充电系统的完整状态，包括电池电压、充电阶段、充电状态、电池在位状态、充电器在位状态以及IC过热状态等信息。

其中充电器是否在位，中断触发，触发回调事件为CHARGER_STATE_EVENT，附带的参数 true表示充电器在位，false表示充电器不在位。

注意事项

必须在task中运行，最大阻塞时间(包括超时重试时间)大概为20s。

参数

无

返回值

table类型，返回充电状态信息，格式如下：

local status = exs_yhm2712a.status()

status

```Plain Text 含义说明：获取充电状态信息表，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 = exs_yhm2712a.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 **示例**Lua function read_charging_status() local status = exs_yhm2712a.status() if status.result then log.info("exs_yhm2712a", string.format("电池电压: %d mV, 充电阶段: %d, 充电完成: %s, 电池在位: %s, 充电器在位: %s, IC过热: %s", status.vbat_voltage, status.charge_stage, status.charge_complete and "是" or "否", status.battery_present and "是" or "否", status.charger_present and "是" or "否", status.ic_overheat and "是" or "否")) else log.error("exs_yhm2712a", "读取充电状态失败") end return status end ```

4.4 事件管理

4.4.1 exs_yhm2712a.on(func)

功能

注册事件回调函数，用于监听和响应充电系统的状态变化事件。

参数

func

```Plain Text 参数含义：exs_yhm2712a事件回调函数，回调函数的格式为： function callback(event) log.info("callback",event) end 该回调函数接收1个参数event，在不同事件类型下参数含义有所不同： -- 参数含义：具体的回调事件； -- 数据类型：number； -- 取值范围：1，对应常量 exs_yhm2712a.OVERHEAT（充电IC过热）； -- 2，对应常量 exs_yhm2712a.CHARGER_IN（充电器插入）； -- 3，对应常量 exs_yhm2712a.CHARGER_OUT（充电器拔出）； -- 4，对应常量 exs_yhm2712a.SHIPPING_MODE（进入船运模式）； -- 是否必选：是； -- 注意事项：用于标识不同的回调触事件； event 数据类型：function； 取值范围：回调函数本身无取值范围这一说法； 是否必选：是； 注意事项：多次调用 exs_yhm2712a.on() 会覆盖之前设置的回调函数，同一时间只能有一个回调函数生效； 参数示例：local function exs_yhm2712a_callback(event) if event == exs_yhm2712a.OVERHEAT then log.info("警告：设备温度过高！") elseif event == exs_yhm2712a.CHARGER_IN then log.info("充电器已插入") elseif event == exs_yhm2712a.CHARGER_OUT then log.info("充电器已拔出") elseif event == exs_yhm2712a.SHIPPING_MODE then log.info("已进入船运模式") end end 

**返回值**

无

**示例**

```Lua
-- 事件回调函数
local function yhm2712a_event_callback(event)
    if event == exs_yhm2712a.OVERHEAT then
        log.info("exs_yhm2712a", "警告：设备温度过高！")
    elseif event == exs_yhm2712a.CHARGER_IN then
        log.info("exs_yhm2712a", "充电器已插入")
    elseif event == exs_yhm2712a.CHARGER_OUT then
        log.info("exs_yhm2712a", "充电器已拔出")
    elseif event == exs_yhm2712a.SHIPPING_MODE then
        log.info("exs_yhm2712a", "已进入船运模式")
    end
end

-- 注册回调
function register_event_callback()
    exs_yhm2712a.on(yhm2712a_event_callback)
end

4.5 船运模式

4.5.1 exs_yhm2712a.ship_mode()

功能

进入船运模式，在该模式下电池FET断开，适用于产品运输和存储。

船运模式并不是一定在使用轮船运输时才可使用，仅以船运代表设备正处在运输过程中的状态，切勿误解。

实际项目中，船运模式适用于产品出厂运输、长期库存等场景，对于上电开机且出厂时必须安装好电池的产品，使用该模式进行断电控制，既能确保运输安全，又能避免设备在运输和存储过程中消耗电量。

使用船运模式的步骤为：

首先，在生产线上完成产品的测试和校准后，通过软件调用 exs_yhm2712a.ship_mode() 接口让设备进入船运模式，这样设备会断开电池与系统的连接；设备在运输和存储过程中会保持这种状态，直到用户收到产品后插入USB充电器，YHM2712A会自动检测到VIN电压并退出船运模式，唤醒设备开始正常工作。

注意事项

必须在task中运行，最大阻塞时间大概为2500ms, 阻塞由sys.waitUntil("YHM27XX_REG", 500)和sys.wait(2000)产生。

参数

无

返回值

local result = exs_yhm2712a.ship_mode()

result

```Plain Text 参数含义：是否进入船运模式成功； 数据类型：boolean； 取值范围：true/false； 注意事项：true表示成功，false表示失败； 返回示例：local result = exs_yhm2712a.ship_mode() log.info("exs_yhm2712a", "ship_mode", result) 

**示例**

```Lua
-- 进入船运模式
function enter_shipping_mode()
    local result = exs_yhm2712a.ship_mode()
    if result then
        log.info("exs_yhm2712a", "已成功进入船运模式")
    else
        log.error("exs_yhm2712a", "进入船运模式失败")
    end
    return result
end

4.6 版本管理

4.6.1 exs_yhm2712a.version()

功能

获取库文件版本信息

参数

无参数

返回值

local version= exs_yhm2712a.version()

version

```Plain Text 含义说明：库文件版本信息，string类型的年月日时分； 数据类型：string； 取值范围：12位数字； 注意事项：格式为 yyyymmddhhmm，表示 yyyy年mm月dd日hh时mm分发布的版本 返回示例："202607201900" 

**示例**

```Lua
-- 获取并显示版本号
function get_version_info()
    local ver = exs_yhm2712a.version()
    log.info("exs_yhm2712a", "版本号:", ver)
    return ver
end

五、版本更新说明

版本号：202607201900

  1. 更新时间：2026-07-20 19:00

  2. 更新内容：

    • 初版，实现 YHM2712A 充电管理芯片的完整驱动功能

    • 支持通过单总线通信控制充电功能

    • 提供充电状态查询、事件回调、船运模式等功能

    • 新增 exs_yhm2712a.version() 接口，提供库版本查询功能

六、产品支持说明

所有支持 LuatOS 二次开发的模块，具体可以查看选型手册。

搜索
AirMaster 实时解答