入门¶

本文说明电池与充电基础功能的接入流程，帮助开发者完成 ADC、电量检测和充电器配置。

1. 参考代码¶

文件	作用
`solution\components\battery\battery_detect\battery_detection.c`	电池电压检测：ADC 采样、电压换算和检测入口
`solution\components\battery\battery_service\battery_service.c`	电池服务：电池状态维护和事件上报

2. 应用例程¶

场景	文件	调用接口
电池设置页面	`setting_battery_gui.c`	`app_rt_data_info_get()`
低电/充电弹窗	`popup_battery.c`	`app_rt_data_info_get()`

入门篇介绍电池管理配置、外部充电芯片驱动添加等，目的是让充电和电池电量测量功能工作起来。

3. 任务分工¶

52x
- 单核平台，所有的任务都在HCPU上完成；
56x/55x/58x 双核架构，大小核需要任务分工协作：
- 在小核（LCPU）启动前，电池电量检测由大核（HCPU）负责；充电插入检测等中断事件由大核处理；
- 小核启动后，电量采集工作移交至小核，由小核上报给大核。

4. menuconfig配置¶

4.1 配置使能ADC¶

单核平台在 HCPU 配置，双核平台在 LCPU 配置；按原理图选择实际 ADC 实例和通道。

路径	配置项	说明
`SiFli SDK configuration → Board Config → On-chip Peripherals → ADC`	`BSP_USING_ADC`	ADC 总开关，打开后会选中 `RT_USING_ADC`。PC Simulator 不显示该板级菜单。
同上	`BSP_USING_ADC1`	GPADC1 开关，按硬件连接选择是否启用。

4.2 配置charger¶

单核平台在 HCPU 配置，双核平台 HCPU 和 LCPU 都要配置。先启用 GPIO，再打开 Charger。

路径	配置项	说明
`RTOS → RT Thread → RT-Thread Components → Device Drivers`	`RT_USING_PIN`	Charger 依赖 GPIO 驱动，需先打开。
`SiFli SDK configuration → Board Config → Board Peripherals → Charger`	`BSP_USING_CHARGER`	Charger 总开关。PC Simulator 不显示该板级菜单。
`... → Charger → Charger Device`	`CHARGE_USING_SIFLI` / `CHARGE_USING_SGM40561`	按硬件选择充电芯片；SF32LB52X 使用内置 Charger，其他 SoC 默认 SGM40561。

../../_images/battery_config_56x_lcpu.png

5. charger配置的详细说明¶

charger配置包括了电量检测，充电设备选择，充电插入检测，充电pin配置，NTC温度检测等功能。

5.1 charge device select¶

../../_images/battery_config_charger_chip_select.png

using SIFLI charge 52x可选择使用芯片内部的充电模块；
using charge sgm40561 使用外部充电芯片sgm40561；
using charge aw32001 使用外部充电芯片aw32001；

5.2 chargeing measure vbat adc mode¶

../../_images/battery_config_charger_mode.png

charging measure vbat adc mode suspend adc采集电池电量的时候暂停充电；
chargeing measure vbat adc mode CURVE (默认) 充电时，同样百分比电压要比不充电时要高。采用充电曲线避免百分比计算不准确；

这两种方式都能解决充电时电压升高，导致充电时计算的电量百分比偏高的问题。例如：没充电时，电池电压3.7v时，插入充电器，电池电压会立刻升到3.85v。此时如果按照3.85v计算电池电量百分比，就会得到偏高的百分比。优劣势对比，如下：

模式	优势	劣势
adc采集电池电量的时候暂停充电	完全规避充电的影响	整体充电时间会变长，且依赖于充电能够具备暂停功能
充电曲线	不会影响充电时间	充电曲线制作难度大，且会受负载电流的影响

充电曲线以数据的形式保存在solution\framework\service\battery\battery_curve_table.h; 其中：充电曲线

static const battery_curve_t charging_curve_table[] = {};

放电曲线

static const battery_curve_t discharge_curve_table[] =  {};

5.3 charg pin number config¶

../../_images/battery_config_charger_pin.png

配置pin的序号；
- pin不存在的时候，配置-1;
- pin存在的时候，序号采用rt_driver的序号配置，即：大核 0~95；小核96~191；
配置有效状态；
- detect pin level is high if charge plug in
  - 选中，充电插入检测pin，高有效；
  - 不选，充电插入检测pin，低有效
- charging pin level is high when charging
  - 选中，充电中状态，高有效；
  - 不选，充电中状态，低有效
- detect pin level is high when charge full
  - 选中，充满状态，高有效；
  - 不选，充满状态，低有效

5.4 charg adc config¶

../../_images/battery_config_charger_adc.png

选择合适的adc以及合适的通道；

5.5 NTC temp config¶

NTC 用于采集电池温度，先启用 Charger，再配置 ADC 和计算方式。

路径	配置项	说明
`Board Peripherals → Charger → NTC Temperature Config`	`CHARGE_MONITOR_TEMP_CONFIG`	打开 NTC 温度检测；仅在 `BSP_USING_CHARGER` 启用后显示。
同上	`BSP_NTC_TEMP_ADC` / `BSP_NTC_TEMP_ADC_CHANNEL`	选择 NTC 使用的 ADC 设备和通道。
`... → NTC Value Computing Method`	`BSP_NTC_TEMP_METHOD_FORMULA_COMPUTE` / `BSP_NTC_TEMP_METHOD_LOOKUP_TABLE`	选择公式法或查表法，默认公式法。

../../_images/battery_config_charger_ntc.png

配置NTC使用的adc及通道；
配置NTC的计算方式 ntc value computing method;
- 公式计算 formula compute
- 查表法 lookup table

5.6 Use charger detect¶

充电插入检测用于判断外部电源插拔。先启用 Charger，再配置检测引脚。

路径	配置项	说明
`Board Peripherals → Charger`	`BSP_USING_CHARGER_DETECT`	打开充电插入检测；仅在 `BSP_USING_CHARGER` 启用后显示。
`... → Charger pin number config`	`CHARGE_PIN_CONFIG`	检测引脚配置开关，默认开启。
同上	`BSP_CHARGER_INT_PIN`	配置充电检测引脚和有效电平。

6. 外部充电芯片添加¶

52x/56x/55x/58x都可以使用外部充电芯片。下面以外部充电芯片sgm40561为例，介绍如何添加外部充电芯片。

  sdk/customer/peripherals/charger/sgm40561/
   ├── Kconfig
   ├── SConscript
   ├── sgm40561.c
   └── sgm40561.h

以下是具体的步骤：

6.1 新建文件夹¶

在sdk/customer/peripherals/charger/目录下增加充电芯片的文件夹

../../_images/battery_charger_drvier_0.png

6.2 新建SConscript文件¶

添加编译脚本SConscript，确保添加的文件能够被编译到；

from building import *

cwd = GetCurrentDir()
src = Glob('*.c')
CPPPATH = [cwd]
group = DefineGroup('Drivers', src, depend = ['CHARGE_USING_SGM40561'], CPPPATH = CPPPATH)

Return('group')

SConscript 的语法规则参考SCons 函数

6.3 新建kconfig¶

增加 SGM40561的控制宏（CHARGE_USING_SGM40561）。注意：宏的依赖关系。

menu "Charger config"

    config BSP_USING_CHARGER
        bool "Use charger"
        default n

    if BSP_USING_CHARGER
        choice
            prompt "charge device select"
            default CHARGE_USING_SIFLI if SOC_SF32LB52X
            default CHARGE_USING_SGM40561 if !SOC_SF32LB52X

            config CHARGE_USING_SIFLI
                depends on SOC_SF32LB52X
                bool "using SIFLI charge"

            config CHARGE_USING_SGM40561
                depends on !SOC_SF32LB52X
                bool "using charge sgm40561"
        endchoice
    endif
endmenu

kconfig 的语法规则参考kconfig语法

6.4 运行menuconfig配置新增加宏¶

../../_images/battery_charger_drvier_3.png

6.5 修改驱动文件¶

驱动必须实现的功能

接口初始化
注册 charge 设备
驱动初始化

驱动初始化

int sgm40561_init(void)
{
    sgm40561_pin_init();
    rt_charge_register(&charge_device, &sgm40561_ops, &RT_NULL);
    return RT_OK;
}
INIT_PREV_EXPORT(sgm40561_init);

control代码实现

一般需要实现的如下几个功能：
- RT_CHARGE_GET_STATUS 获取充电状态；
- RT_CHARGE_GET_DETECT_STATUS 获取插入检测状态；
- RT_CHARGE_GET_FULL_STATUS 获取充满的状态；

rt_err_t sgm40561_control(rt_charge_device_t *charge, int cmd, void *args)
{
    rt_charge_err_t ret = RT_CHARGE_EOK;

    switch (cmd)
    {
    case RT_CHARGE_GET_STATUS:
    {
....
    }
    break;

    case RT_CHARGE_GET_DETECT_STATUS:
    {
....
    }
    break;

    case RT_CHARGE_GET_FULL_STATUS:
    {
....

    }
    break;

    default:
        ret = RT_CHARGE_ERROR_UNSUPPORTED;
        break;
    }
    return ret;
}

control command参考

typedef enum
{
    RT_CHARGE_ENABLE = 0x100 + 1,
    RT_CHARGE_GET_STATUS,
    RT_CHARGE_GET_FULL_STATUS,
    RT_CHARGE_GET_DETECT_STATUS,
    RT_CHARGE_FORCE_ENABLE_CHARGING,
    RT_CHARGE_FORCE_SUSPEND_CHARGING,
    RT_CHARGE_FORCE_RESUME_CHARGING,
    RT_CHARGE_GET_HW_STATE,
    RT_CHARGE_SET_PRECC_CURRENT,
    RT_CHARGE_SET_CC_CURRENT,
    RT_CHARGE_SET_TARGET_VOLT,
    RT_CHARGE_SET_REPVOLT,
    RT_CHARGE_SET_OVER_VOLT,
} rt_charge_cmd_t;

7. 预期效果¶

配置完成后，效果如下：

插入和拔掉充电器，UI界面会弹出或关闭充电窗口
- 充电中界面如下：
- 充电完成界面如下：

可以从log中看到以下打印信息

电量采集Log

ch[7]voltage=41756;
[4350430] BAT: rt_adc_read:  41756
[4350435] BAT: battery_get_original_voltage: volt 4175
[4350442] BAT: battery_get_voltage: volt 4175 smooth volt: 4166
battery_get_voltage_ex, pre_adc = 4089, cur_adc =4166;
[4350457] BAT: original voltage:4104 filtered voltage: 4079;
[4350465] BAT: remain_percent(94)

说明：log的电池电量：94%

温度监控Log

ch[4]voltage=7354;
[7022134] temp_ctrl: adc:7354, r:138433, t:18.48;
[7022148] temp_ctrl: core temp: 16;
[7022152] temp_ctrl: NTC ave temp:[18.33], mode:[NORmal Mode];

说明：log的NTC温度：16℃。