Baji_Rtc_Toy/main/boards/common/wifi_board.h

#ifndef WIFI_BOARD_H
#define WIFI_BOARD_H

/**
 * @file wifi_board.h
 * @brief WiFi板级管理模块头文件
 *
 * 本文件定义了WiFi板级管理的相关接口，包括WiFi连接管理、
 * BLE蓝牙配网流程控制、网络状态监控等功能。
 * 集成了蓝牙配网功能，提供完整的网络连接解决方案。
 */

#include "board.h"
#include "bluetooth_provisioning.h"
// #include "ble_service.h"  // BLE JSON Service 暂不使用
#include <string>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

// 前向声明
class Application;

/**
 * @class WifiBoard
 * @brief WiFi板级管理类
 *
 * 继承自Board基类，负责管理ESP32的WiFi连接、BLE蓝牙配网流程和网络状态监控。
 * 提供完整的网络连接解决方案，包括自动连接、配网模式切换、网络状态监控等功能。
 */
class WifiBoard : public Board {
protected:
    bool wifi_config_mode_ = false;                    ///< WiFi配置模式标志，true表示进入配网模式
    bool ble_provisioning_active_ = false;             ///< BLE配网激活状态标志
    bool ble_provisioning_success_ = false;            ///< BLE配网成功状态标志
    TickType_t ble_start_time_ = 0;                    ///< BLE配网开始时间戳
    static const TickType_t BLE_PROV_TIMEOUT_MS = 300000; ///< BLE配网超时时间（5分钟）
    BluetoothProvisioning bluetooth_provisioning_;     ///< BLE蓝牙配网实例对象
    // BleJsonService ble_json_service_;                  ///< BLE JSON 配网服务实例（暂不使用）

    /**
     * @brief 构造函数
     * 初始化WiFi板级管理对象，读取配置参数
     */
    WifiBoard();

    /**
     * @brief 进入WiFi配置模式
     * 启动BLE蓝牙配网流程，等待用户通过手机APP配置WiFi信息
     */
    void EnterWifiConfigMode();

    /**
     * @brief 广播验证码
     * @param code 验证码字符串
     * @param application 应用程序实例引用
     * 用于在配网过程中向用户显示验证码信息
     */
    void BroadcastVerificationCode(const std::string& code, Application& application);

    /**
     * @brief 启动BLE蓝牙配网
     * @return true 启动成功
     * @return false 启动失败
     * 初始化并启动BLE蓝牙配网服务，等待手机连接
     */
    bool StartBleProvisioning();

    // // 使用 BLE JSON Service 进行配网（暂不使用）
    // bool StartBleJsonProvisioning();

    /**
     * @brief 监控BLE配网进程
     * 监控配网状态变化，处理超时和异常情况
     */
    void MonitorBleProvisioning();

    /**
     * @brief BLE配网事件处理函数
     * @param event 配网事件类型
     * @param data 事件数据指针
     * 处理BLE配网过程中的各种事件
     */
    void OnBleProvisioningEvent(BluetoothProvisioningEvent event, void* data);

    /**
     * @brief BLE配网静态回调函数
     * @param event 配网事件类型
     * @param data 事件数据指针
     * @param user_data 用户数据指针
     * 静态回调函数，用于处理BLE配网事件
     */
    static void BleProvisioningCallback(BluetoothProvisioningEvent event, void* data, void* user_data);

    /**
     * @brief 清理现有蓝牙服务
     * 在进入配网模式前，清理application.cc中启动的蓝牙服务，避免重复初始化
     */
    void CleanupExistingBluetoothService();

    /**
     * @brief 清理现有WiFi服务
     * 在进入配网模式前，清理现有的WiFi服务，为BLE重新初始化做准备
     */
    void CleanupExistingWiFiService();

    /**
     * @brief 获取板级配置JSON字符串
     * @return std::string 板级配置的JSON格式字符串
     * 重写基类方法，返回WiFi板级的配置信息
     */
    virtual std::string GetBoardJson() override;

public:
    /**
     * @brief 获取板级类型
     * @return std::string 返回"wifi"字符串
     * 重写基类方法，标识当前板级为WiFi类型
     */
    virtual std::string GetBoardType() override;

    /**
     * @brief 启动网络连接
     * 根据配置启动WiFi连接或BLE配网流程
     * 重写基类方法，实现WiFi网络的启动逻辑
     */
    virtual void StartNetwork() override;

    virtual Http* CreateHttp() override;
    virtual WebSocket* CreateWebSocket() override;
    virtual Mqtt* CreateMqtt() override;
    virtual Udp* CreateUdp() override;
    virtual const char* GetNetworkStateIcon() override;
    virtual void SetPowerSaveMode(bool enabled) override;
    virtual void ResetWifiConfiguration();

    /**
     * @brief 检查BLE配网是否激活
     * @return true BLE配网正在进行中
     * @return false BLE配网未激活
     */
    bool IsBleProvisioningActive() const { return ble_provisioning_active_; }

    /**
     * @brief 早期检测是否需要配网（读NVS，无需WiFi/BLE已初始化）
     * @return true 需要配网（无WiFi凭据或force_ap=1）
     * 用于在板级构造函数和Application::Start()中提前跳过不必要的外设初始化
     */
    static bool NeedsProvisioning();
};

#endif // WIFI_BOARD_H