ESP-ADF battery_service电压报告控制详解

ESP-ADF battery_service电压报告控制详解

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

本章节分析的源码位于 /components/battery_service/battery_service.c 文件

电压报告控制函数分析

battery_service_vol_report_switch

battery_service_vol_report_switch函数用于开启或关闭电池电压报告。下面是其源码实现：

/**
 * @brief 开启或关闭电池电压报告
 * 
 * 该函数完成以下主要操作：
 * 1. 检查服务句柄是否有效
 * 2. 获取内部服务数据结构
 * 3. 根据开关状态发送相应的控制消息
 * 
 * 开启后，电池电压监控器会按照设定的频率报告电池电压
 * 关闭后，将停止电池电压的定时报告
 * 
 * @param handle 服务句柄
 * @param on_off 开关状态，true表示开启，false表示关闭
 * @return esp_err_t 成功返回ESP_OK，失败返回错误码
 */
esp_err_t battery_service_vol_report_switch(periph_service_handle_t handle, bool on_off)
{
    // 检查句柄有效性
    AUDIO_NULL_CHECK(TAG, handle, return ESP_ERR_INVALID_ARG);
    
    // 获取服务内部数据
    battery_service_t *service = periph_service_get_data(handle);
    AUDIO_NULL_CHECK(TAG, service, return ESP_ERR_INVALID_ARG);
    
    // 根据开关状态发送不同的消息
    if (on_off) {
        // 开启电压报告
        return battery_service_msg_send(service->serv_q, BATTERY_VOL_REPORT_START, NULL);
    } else {
        // 关闭电压报告
        return battery_service_msg_send(service->serv_q, BATTERY_VOL_REPORT_STOP, NULL);
    }
}

下面的时序图展示了 battery_service_vol_report_switch 函数的执行流程：

这个函数是控制电池电压报告开关的核心接口，它通过消息传递机制，将开关控制命令传递给电池服务任务，由任务来实际控制电压监控器的报告状态。这种设计将控制接口与实际执行逻辑分离，提高了系统的灵活性和可维护性。

battery_service_set_vol_report_freq

battery_service_set_vol_report_freq函数用于设置电池电压报告频率。下面是其源码实现：

/**
 * @brief 设置电池电压报告频率
 * 
 * 该函数完成以下主要操作：
 * 1. 检查服务句柄是否有效
 * 2. 获取内部服务数据结构
 * 3. 将频率参数作为消息数据发送控制消息
 * 
 * 通过该函数可以调整电池电压的报告时间间隔
 * 频率参数通常表示报告间隔的秒数
 * 
 * @param handle 服务句柄
 * @param freq 电压报告频率，单位为秒
 * @return esp_err_t 成功返回ESP_OK，失败返回错误码
 */
esp_err_t battery_service_set_vol_report_freq(periph_service_handle_t handle, int freq)
{
    // 检查句柄有效性
    AUDIO_NULL_CHECK(TAG, handle, return ESP_ERR_INVALID_ARG);
    
    // 获取服务内部数据
    battery_service_t *service = periph_service_get_data(handle);
    AUDIO_NULL_CHECK(TAG, service, return ESP_ERR_INVALID_ARG);
    
    // 发送设置频率消息，将freq作为消息数据传递
    return battery_service_msg_send(service->serv_q, BATTERY_VOL_SET_REPORT_FREQ, (void *)freq);
}

下面的时序图展示了 battery_service_set_vol_report_freq 函数的执行流程：

这个函数与battery_service_vol_report_switch类似，也是通过消息传递机制来控制电池服务的行为。它允许应用程序动态调整电池电压的报告频率，从而在电池状态监控和系统功耗之间取得平衡。频率设置越高（间隔越短），电池状态更新越及时，但会消耗更多系统资源；频率设置越低（间隔越长），系统功耗越低，但电池状态更新不够及时。

内部实现机制

从上面的分析可以看出，电压报告控制函数实际上是通过消息传递机制与电池服务任务交互的。当应用程序调用这些函数时，实际的处理逻辑是在battery_task中完成的：

case BATTERY_VOL_SET_REPORT_FREQ: {
    // 设置电压报告频率
    if (service->vol_monitor != NULL) {
        vol_monitor_set_report_freq(service->vol_monitor, (int)msg.pdata);
    }
    break;
}
case BATTERY_VOL_REPORT_START:
    // 开始电压报告
    if (service->vol_monitor != NULL) {
        vol_monitor_start_freq_report(service->vol_monitor);
    }
    break;
case BATTERY_VOL_REPORT_STOP:
    // 停止电压报告
    if (service->vol_monitor != NULL) {
        vol_monitor_stop_freq_report(service->vol_monitor);
    }
    break;

这种设计有以下几个优点：

1. 解耦：控制接口与实际执行逻辑分离，降低了系统耦合度
2. 线程安全：所有操作都在同一个任务中执行，避免了多线程访问的并发问题
3. 异步处理：控制函数可以立即返回，不需要等待实际操作完成
4. 统一管理：所有电池服务相关操作都通过同一个消息队列处理，便于管理和扩展

应用示例

下面是一个使用电压报告控制函数的简单示例：

// 创建电池服务实例
battery_service_config_t bat_cfg = BATTERY_SERVICE_DEFAULT_CONFIG();
bat_cfg.vol_monitor = vol_handle; // 假设已创建电压监控器
periph_service_handle_t bat_service = battery_service_create(&bat_cfg);

// 开启电池电压报告
esp_err_t ret = battery_service_vol_report_switch(bat_service, true);
if (ret != ESP_OK) {
    ESP_LOGE(TAG, "Failed to start battery voltage report");
}

// 设置报告频率为30秒一次
ret = battery_service_set_vol_report_freq(bat_service, 30);
if (ret != ESP_OK) {
    ESP_LOGE(TAG, "Failed to set battery report frequency");
}

// ... 应用运行 ...

// 停止电池电压报告
battery_service_vol_report_switch(bat_service, false);

通过这两个函数，应用程序可以灵活地控制电池电压的报告行为，根据实际需求调整电池状态监控的策略，从而在电池状态及时性和系统功耗之间取得平衡。