yhm27xx - 充电管理

作者：王世豪

一、概述

yhm27xx 核心库是针对 YHM27XX 系列充电管理芯片开发的专用控制库，提供了完整的充电参数配置和状态监控功能。

历史演进说明：

初期阶段：最早提供独立的 yhm27xx 核心库供 Air8000 使用
过渡阶段：功能被整合到 pm 库中，作为 pm.chgcmd/pm.chginfo 接口提供
当前阶段：最终统一集成到 exchg 扩展库，提供更完善的充电管理解决方案

注意：本文档保留 yhm27xx 库的完整说明以供历史项目参考，但新设计应优先考虑 exchg 扩展库。

二、核心示例

核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
更加完整和详细的 demo，请参考 yhm27xx;

local gpio_pin = 152 -- 模组与YHM27XX直连的gpio号
local chip_addr = 0x04 -- yhm27xx 芯片地址
local reg_addr = 0x08 -- YHM27XX充电IC的寄存器地址
local V_ctrl_register = 0x00 -- 电压控制寄存器地址
local I_ctrl_register = 0x01 -- 电流控制寄存器地址

--设置充电电压
result = yhm27xx.cmd(gpio_pin, chip_addr, V_ctrl_register, 0xE0)
if result == true then
    log.info("yhm27xx 设置电压成功")
else
    log.info("yhm27xx 设置电压失败")
end

--设置充电电流
result = yhm27xx.cmd(gpio_pin, chip_addr, I_ctrl_register, 0x42)
if result == true then
    log.info("yhm27xx 设置电流成功")
else
    log.info("yhm27xx 设置电流失败")
end

adc.open(adc.CH_VBAT)
while true do
    sys.wait(5000)
    yhm27xx.reqinfo(gpio_pin, chip_addr)
    local result,data = sys.waitUntil("YHM27XX_REG", 500)
    local Data_reg={}
    if result then
        for i=1,9 do
            Data_reg[i] = data:byte(i)
            log.info("yhm27xx 寄存器0x0".. i-1 .." 功能:读取数据为：", Data_reg[i])
        end
        log.info("当前电池电压", "VBAT", adc.get(adc.CH_VBAT))
        log.info("yhm27xx 寄存器0x00 功能:设置充电电压，   读取数据为：", tostring((Data_reg[1] & 0xF0)>>4))
        log.info("yhm27xx 寄存器0x01 功能:设置充电电流，   读取数据为：", tostring((Data_reg[2] & 0xE0)>>5))
        log.info("yhm27xx 寄存器0x05 功能:充电状态寄存器(只读),充电状态为：" , tostring((Data_reg[6] & 0xE0)>>5))
    end
end

三、常量详解

yhm27xx 核心库没有常量

四、函数详解

4.1 yhm27xx.cmd(gpio, chip_addr, reg_addr, data)

功能

单总线命令，配置 YHM27XX 充电 IC

注意事项

该接口只能配置型号为：YHM27xx 系列的充电 IC，不是该型号的不要调用！！！

参数

gpio

含义说明：与YHM27XX直连的gpio号；
数值类型：number；
取值范围：虽然理论上支持0-254，但实际可用的GPIO取决于具体的模组型号；
注意事项：需要明确与YHM27xx充电IC直连的gpio号，不是pin脚号；
参数示例：--如下方所示，第一个参数为与YHM27XX直连的gpio号；
        yhm27xx.cmd(2, 0x04, 0x42, 0XAA)

chip_addr

含义说明：YHM27XX充电IC的芯片地址；
数值类型：number；
取值范围：参考YHM27XX规格书；
注意事项：实际芯片地址请参考YHM27XX规格书；
参数示例：--如下方所示，第二个参数为YHM27XX充电IC的芯片地址；
        yhm27xx.cmd(2, 0x04, 0x42, 0XAA)

reg_addr

含义说明：YHM27XX充电IC的寄存器地址；
数值类型：number；
取值范围：参考YHM27XX规格书；
注意事项：需要明确与YHM27xx充电IC读写数据的寄存器地址；
参数示例：--如下方所示，第三个参数为YHM27XX的寄存器地址；
        yhm27xx.cmd(2, 0x04, 0x42, 0XAA)

data

含义说明：向YHM72XX对应功能寄存器发送的指令，不填数据则是从对应功能寄存器读取数据；
数值类型：number；
取值范围：参考YHM27XX规格书；
注意事项：需要明确与YHM27xx充电IC对应寄存器发送的明确指令，直接参考规格书即可；
参数示例：--如下方所示，第四个参数为向YHM27XX的0X42寄存器存入数据0XAA；
        yhm27xx.cmd(2, 0x04, 0x42, 0XAA)
        --如下方所示，第四个参数不填写数据，则是从0X42寄存器读取数据；
        yhm27xx.cmd(2, 0x04, 0x42)

返回值

local ret1,ret2 = yhm27xx.cmd(gpio, chip_addr, reg_addr, data)

有 2 个返回值

ret1

含义说明：yhm27xx.cmd接口读写状态；
数值类型：boolean；
取值范围：成功时返回true，失败时返回false；
注意事项：需根据所使用YHM27XX的规格书明确对应芯片地址、寄存器地址和指令；
返回示例：-- 写入操作：向GPIO2连接的YHM27XX充电IC（芯片地址0x04，寄存器0x42）写入指令0xAA
        local ret1, ret2 = yhm27xx.cmd(2, 0x04, 0x42, 0xAA)-- ret1为true表示指令发送成功
        -- 读取操作：从GPIO2连接的YHM27XX充电IC（芯片地址0x04，寄存器0x42）读取数据
        local ret1, ret2 = yhm27xx.cmd(2, 0x04, 0x42)-- ret1为true表示数据读取成功

ret2

含义说明：yhm27xx.cmd接口读取的数据；
数值类型：nil/number；
取值范围：写入操作返回nil，读取操作返回寄存器数据；
注意事项：需根据所使用YHM27XX的规格书明确对应芯片地址、寄存器地址；
返回示例：-- 写入操作：向GPIO2连接的YHM27XX充电IC（芯片地址0x04，寄存器0x42）写入指令0xAA
        local ret1, ret2 = yhm27xx.cmd(2, 0x04, 0x42, 0xAA)-- ret2返回nil
        -- 读取操作：从GPIO2连接的YHM27XX充电IC（芯片地址0x04，寄存器0x42）读取数据
        local ret1, ret2 = yhm27xx.cmd(2, 0x04, 0x42)-- ret2返回读取的寄存器数据

示例

-- 写入示例：向GPIO2连接的YHM27XX，芯片地址0x04，寄存器0x42写入0xAA
local ret1 = yhm27xx.cmd(2, 0x04, 0x42, 0XAA) -- ret1返回true表示写入成功

-- 读取示例：从GPIO2连接的YHM27XX，芯片地址0x04，寄存器0x42读取数据
local ret1, ret2 = yhm27xx.cmd(2, 0x04, 0x42)-- ret1返回true且ret2携带读取的数据表示读取成功

4.2 yhm27xx.reqinfo(gpio, chip_addr)

功能

获取最新的寄存器信息(异步)

注意事项

该接口为异步执行，不会阻塞当前代码。

异步事件处理方式（完整代码参考示例部分）:

方式一：订阅事件回调（非阻塞）
使用 sys.subscribe("YHM27XX_REG", 处理函数)
方式二：等待事件完成（阻塞当前任务）
使用 sys.waitUntil("YHM27XX_REG", 超时时间)

参数

gpio

含义说明：与YHM27XX直连的gpio号；
数值类型：number；
取值范围：虽然理论上支持0-254，但实际可用的GPIO取决于具体的模组型号；
注意事项：需要明确与YHM27xx充电IC直连的gpio号，不是pin脚号；
参数示例：--如下方所示，第一个参数为与YHM27XX直连的gpio号；
        yhm27xx.reqinfo(2, 0x04)

chip_addr

含义说明：YHM27XX充电IC的芯片地址；
数值类型：number；
取值范围：参考YHM27XX规格书；
注意事项：实际芯片地址请参考YHM27XX规格书；
参数示例：--如下方所示，第二个参数为YHM27XX充电IC的芯片地址；
        yhm27xx.reqinfo(2, 0x04)

返回值

无

示例

方式一：订阅事件回调（非阻塞）
--如下方所示，在调用yhm27xx.reqinfo前需要订阅"YHM27XX_REG"消息，
--yhm27xx.reqinfo异步执行完成后会推送"YHM27XX_REG"消息并携带所有寄存器的数据；
local function yhm27_regdata(data)
    if data then
        -- 注意, 会一次性读出0-8,总共9个寄存器值
        log.info("yhm27xx", data and data:toHex())
    end
end

sys.subscribe("YHM27XX_REG",yhm27_regdata)
yhm27xx.reqinfo(gpio_pin, chip_addr)

方式二：等待事件完成（阻塞当前任务）
yhm27xx.reqinfo(gpio_pin, chip_addr)
local result,data = sys.waitUntil("YHM27XX_REG", 500)
local Data_reg={}
if result then
    for i=1,9 do
        Data_reg[i] = data:byte(i)
        log.info("yhm27xx 寄存器0x0".. i-1 .." 功能:读取数据为：", Data_reg[i])
    end
end

五、产品支持说明

适用于支持 YHM27XX 系列充电管理芯片的模组型号，本文档保留 yhm27xx 库的完整说明以供历史项目参考，新项目推荐使用 exchg 扩展库！