ESP-ADF battery_service组件之voltage_monitor子模块详解

ESP-ADF battery_service组件之voltage_monitor子模块详解

版本信息: v2.7-65-gcf908721

模块概述

电压监控（vol_monitor）是 battery_service 组件的核心子模块，负责实时监控电池电压，并在满足特定条件时向上层应用报告电池状态。该模块提供了灵活的电压监控机制，支持定期报告电压数值、电池电量过低/满电量事件通知等功能，为电池管理提供基础支持。

功能特点

• 定期采样：根据配置的频率定期读取电池电压
• 定期报告：支持按指定频率向上层应用报告电池电压值
• 阈值触发：支持电池电量过低/满电量事件触发通知
• 可配置性：支持灵活配置采样频率、报告频率和阈值等参数
• 事件回调：提供事件回调机制，方便上层应用处理电池状态变化

工作原理

电压监控模块通过定时器定期调用用户提供的电压读取函数获取当前电池电压，然后根据配置的报告频率和电压阈值，触发相应的事件回调。模块内部维护电压监控状态，包括读取计数、报告状态、满电量/低电量报告状态等，以确保事件触发的准确性和一致性。

公共接口

数据类型和结构

事件类型枚举

/**
 * @brief 电池电压监控事件类型
 */
typedef enum {
    VOL_MONITOR_EVENT_FREQ_REPORT,  /*!< 定期电压报告事件 */
    VOL_MONITOR_EVENT_BAT_FULL,     /*!< 电池满电量事件 */
    VOL_MONITOR_EVENT_BAT_LOW,      /*!< 电池低电量事件 */
} vol_monitor_event_t;

电压监控参数结构

/**
 * @brief 电池电压监控配置参数
 */
typedef struct {
    bool (*init)(void *);   /*!< 电压读取初始化函数 */
    bool (*deinit)(void *); /*!< 电压读取反初始化函数 */
    int (*vol_get)(void *); /*!< 电压读取接口函数 */
    void *user_data;        /*!< 回调函数参数 */
    int read_freq;          /*!< 电压读取频率，单位：秒 */
    int report_freq;        /*!< 电压报告频率，电压将以（`read_freq` * `report_freq`）间隔进行报告 */
    int vol_full_threshold; /*!< 满电量电压阈值，单位：mV */
    int vol_low_threshold;  /*!< 低电量电压阈值，单位：mV */
} vol_monitor_param_t;

句柄类型定义

/**
 * @brief 电压监控句柄
 */
typedef void *vol_monitor_handle_t;

回调函数定义

/**
 * @brief 回调函数定义
 */
typedef void (*vol_monitor_event_cb)(int msg_id, void *data, void *user_ctx);

函数声明

创建电压监控实例

/**
  * @brief     创建电压监控实例
  *
  * @param[in]  config      指向 'vol_monitor_param_t' 结构的指针
  *
  * @return
  *    - NULL:  失败
  *    - 其他值: 成功
  */
vol_monitor_handle_t vol_monitor_create(vol_monitor_param_t *config);

销毁电压监控实例

/**
  * @brief     销毁电压监控实例
  *
  * @param[in]  handle      指向 'vol_monitor_handle_t' 结构的指针
  *
  * @return
  *    - ESP_OK:  成功
  *    - 其他值: 失败
  */
esp_err_t vol_monitor_destroy(vol_monitor_handle_t handle);

设置事件回调函数

/**
  * @brief     设置事件回调函数
  *
  * @param[in]  handle      指向 'vol_monitor_handle_t' 结构的指针
  * @param[in]  event_cb    用于处理电压监控事件的回调函数
  * @param[in]  user_ctx    用户数据
  *
  * @return
  *    - ESP_OK:  成功
  *    - 其他值: 失败
  */
esp_err_t vol_monitor_set_event_cb(vol_monitor_handle_t handle, vol_monitor_event_cb event_cb, void *user_ctx);

启动定期电压报告

/**
  * @brief     以配置的频率启动电压报告
  *
  * @param[in]  handle      指向 'vol_monitor_handle_t' 结构的指针
  *
  * @return
  *    - ESP_OK:  成功
  *    - 其他值: 失败
  */
esp_err_t vol_monitor_start_freq_report(vol_monitor_handle_t handle);

停止定期电压报告

/**
  * @brief     停止定期电压报告
  *
  * @param[in]  handle      指向 'vol_monitor_handle_t' 结构的指针
  *
  * @return
  *    - ESP_OK:  成功
  *    - 其他值: 失败
  */
esp_err_t vol_monitor_stop_freq_report(vol_monitor_handle_t handle);

设置电压报告频率

/**
  * @brief     设置电压报告频率
  *
  * @param[in]  handle      指向 'vol_monitor_handle_t' 结构的指针
  * @param[in]  freq        电压报告频率
  *
  * @return
  *    - ESP_OK:  成功
  *    - 其他值: 失败
  */
esp_err_t vol_monitor_set_report_freq(vol_monitor_handle_t handle, int freq);

核心流程分析

电压监控创建流程

电压报告流程

报告控制流程

接口汇总

创建与销毁

函数名	功能描述
vol_monitor_create	创建电压监控实例
vol_monitor_destroy	销毁电压监控实例

事件处理

函数名	功能描述
vol_monitor_set_event_cb	设置事件回调函数

电压报告控制

函数名	功能描述
vol_monitor_start_freq_report	启动定期电压报告
vol_monitor_stop_freq_report	停止定期电压报告
vol_monitor_set_report_freq	设置电压报告频率

事件类型

事件	说明
VOL_MONITOR_EVENT_FREQ_REPORT	定期电压报告事件
VOL_MONITOR_EVENT_BAT_FULL	电池满电量事件
VOL_MONITOR_EVENT_BAT_LOW	电池低电量事件

使用示例

下面是一个使用电压监控模块的简单示例：

// 电压读取相关函数实现
static bool adc_init(void *user_data) {
    // 初始化 ADC
    return true;
}

static bool adc_deinit(void *user_data) {
    // 反初始化 ADC
    return true;
}

static int adc_read(void *user_data) {
    // 读取 ADC 并转换为电压值（mV）
    return 3800; // 示例值
}

// 电压事件回调函数
static void vol_event_cb(int msg_id, void *data, void *user_ctx) {
    int voltage = (int)data;
    
    switch (msg_id) {
        case VOL_MONITOR_EVENT_FREQ_REPORT:
            printf("当前电压: %d mV\n", voltage);
            break;
        case VOL_MONITOR_EVENT_BAT_FULL:
            printf("电池已充满: %d mV\n", voltage);
            break;
        case VOL_MONITOR_EVENT_BAT_LOW:
            printf("电池电量低: %d mV\n", voltage);
            break;
        default:
            break;
    }
}

// 主函数
void app_main() {
    // 配置电压监控
    vol_monitor_param_t vol_config = {
        .init = adc_init,
        .deinit = adc_deinit,
        .vol_get = adc_read,
        .user_data = NULL,
        .read_freq = 5,           // 每5秒读取一次
        .report_freq = 12,        // 每12次读取报告一次（即60秒）
        .vol_full_threshold = 4100, // 满电量阈值: 4100mV
        .vol_low_threshold = 3300,  // 低电量阈值: 3300mV
    };
    
    // 创建电压监控
    vol_monitor_handle_t monitor = vol_monitor_create(&vol_config);
    if (monitor == NULL) {
        printf("创建电压监控失败\n");
        return;
    }
    
    // 设置回调函数
    vol_monitor_set_event_cb(monitor, vol_event_cb, NULL);
    
    // 启动电压报告
    vol_monitor_start_freq_report(monitor);
    
    // ... 应用主循环 ...
    
    // 在应用退出时销毁电压监控
    // vol_monitor_destroy(monitor);
}