小龙虾
00ce8dbbb5
- 新增 storage/gd32_flash_store.cpp 组件，提供 GD32 Flash 存储抽象层 - 修改 ota_coordinator.cpp/h 使其继承 IRelayListener 接口，实现与 OtaRelay 的解耦设计 - 将 GD32 相关存储操作统一通过协调器访问，解决 H3 绕过协调器的问题 - 添加完整的 Doxygen 注释到所有公共接口和关键函数 - 更新 CMakeLists.txt 构建配置，添加 storage 组件依赖 - 重构元数据加载/清除操作使用 Gd32FlashStore 实例而非 OtaRelay 直接访问 - 添加中继事件回调接口实现，使 OtaRelay 可通知协调器状态变化
337 lines
12 KiB
C++
337 lines
12 KiB
C++
/*
|
||
* ota_coordinator.h - 全局 OTA 协调器
|
||
*
|
||
* OtaCoordinator 是系统级 OTA 状态的唯一权威来源，负责：
|
||
* 1. 串行化 GD32 中继与 ESP32 OTA 操作（同一时刻只能进行一种）
|
||
* 2. 为传输层（WiFi/BLE）提供统一的 OTA 操作入口
|
||
* 3. 通过 FreeRTOS 队列向 OtaRelay task 投递中继命令
|
||
* 4. 向上层（web UI / status API）暴露系统级状态
|
||
*
|
||
* 线程模型：
|
||
* - 状态读写由内部 mutex 保护
|
||
* - begin/complete 接口可在任意任务中调用
|
||
* - triggerGd32Relay() 向 OtaRelay task 的 dispatchQueue 发送消息
|
||
*/
|
||
#ifndef OTA_COORDINATOR_H
|
||
#define OTA_COORDINATOR_H
|
||
|
||
#include <stdint.h>
|
||
#include "freertos/FreeRTOS.h"
|
||
#include "freertos/semphr.h"
|
||
#include "esp_err.h"
|
||
#include "storage/gd32_flash_store.h"
|
||
#include "relay/ota_relay.h" // IRelayListener 接口定义（H4 解耦）
|
||
|
||
// ============================================================
|
||
// 系统级 OTA 状态枚举
|
||
// ============================================================
|
||
typedef enum {
|
||
OTA_SYS_IDLE = 0,
|
||
OTA_SYS_GD32_STORING, // 正在从传输层接收 GD32 固件
|
||
OTA_SYS_GD32_STORED, // GD32 固件已完整存储，等待中继触发
|
||
OTA_SYS_GD32_RELAYING, // 正在通过 SPI 向 GD32 中继固件
|
||
OTA_SYS_GD32_COMPLETE, // GD32 OTA 完成（APP 已存活确认）
|
||
OTA_SYS_ESP32_RECEIVING, // 正在接收 ESP32 自身固件
|
||
OTA_SYS_ESP32_FINALIZING, // 正在收尾 ESP32 OTA（SHA校验 + end + set_boot）
|
||
OTA_SYS_ESP32_REBOOTING, // 即将重启 ESP32
|
||
OTA_SYS_ERROR // 错误状态
|
||
} ota_system_state_t;
|
||
|
||
/**
|
||
* @brief ESP32 OTA 收尾结果（由 finalizeForReboot 返回）。
|
||
* err 为 ESP_OK 时 device_sha_hex 有效；SHA 不匹配时也填充 device_sha_hex 供前端核对。
|
||
*/
|
||
typedef struct {
|
||
esp_err_t err; ///< ESP_OK / ESP_ERR_INVALID_VERSION(SHA不匹配) / 其他
|
||
char device_sha_hex[65]; ///< 设备端 SHA hex（成功或 SHA 不匹配时填充）
|
||
} Esp32FinalizeResult;
|
||
|
||
/**
|
||
* @brief 全局 OTA 协调器（单例）
|
||
*
|
||
* 提供系统级 OTA 状态管理与操作串行化。
|
||
* 传输层（WiFi/BLE）通过本协调器发起所有 OTA 操作，
|
||
* 不再直接调用 OtaRelay / Esp32OtaCore 的底层接口。
|
||
*/
|
||
class OtaCoordinator : public IRelayListener {
|
||
public:
|
||
/**
|
||
* @brief 获取 OtaCoordinator 单例实例。
|
||
* @return OtaCoordinator 单例引用。
|
||
*/
|
||
static OtaCoordinator& instance();
|
||
|
||
// ── 初始化 ──
|
||
/**
|
||
* @brief 初始化协调器（创建 mutex 和队列）。
|
||
* 在 OtaRelay task 创建前调用。
|
||
*/
|
||
void init();
|
||
|
||
// ── GD32 存储阶段（传输层 → Flash）──
|
||
/**
|
||
* @brief 传输层开始接收 GD32 固件前调用。
|
||
* 若系统正忙（ESP32 OTA 进行中或 GD32 中继中），返回失败。
|
||
* @param total_size 固件总字节数。
|
||
* @return ESP_OK 成功，ESP_ERR_INVALID_STATE 系统忙。
|
||
*/
|
||
esp_err_t beginGd32Storage(uint32_t total_size);
|
||
|
||
/**
|
||
* @brief GD32 固件接收完毕时调用。
|
||
* 更新系统状态为 OTA_SYS_GD32_STORED。
|
||
*/
|
||
void completeGd32Storage();
|
||
|
||
// ── GD32 存储操作（传输层通过协调器操作 Flash，解决 H3 绕过问题）──
|
||
/**
|
||
* @brief 向 GD32 Flash 分区写入固件数据块。
|
||
* 传输层（WiFi/BLE）通过此接口写入，不再直接调用 Gd32FlashStore。
|
||
* @param offset 写入偏移。
|
||
* @param data 数据缓冲区。
|
||
* @param len 数据长度。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t writeGd32Chunk(uint32_t offset, const uint8_t *data, size_t len);
|
||
|
||
/**
|
||
* @brief 保存 GD32 OTA 元数据。
|
||
* @param meta 元数据结构体。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t saveGd32Meta(const ota_meta_t *meta);
|
||
|
||
/**
|
||
* @brief 加载 GD32 OTA 元数据。
|
||
* @param meta 输出元数据结构体。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t loadGd32Meta(ota_meta_t *meta);
|
||
|
||
/**
|
||
* @brief 更新 GD32 OTA 元数据的进度。
|
||
* @param stored_size 已存储大小。
|
||
* @param last_seq 最后包序号。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t updateGd32Meta(uint32_t stored_size, uint32_t last_seq);
|
||
|
||
/**
|
||
* @brief 清除 GD32 OTA 元数据。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t clearGd32Meta();
|
||
|
||
/**
|
||
* @brief 校验前端 SHA-256 与设备端固件是否一致。
|
||
* @param frontend_sha32 前端 32 字节 SHA。
|
||
* @param out_device_sha 输出设备端 32 字节 SHA（可为 nullptr）。
|
||
* @return ESP_OK 匹配，ESP_ERR_INVALID_CRC 不匹配。
|
||
*/
|
||
esp_err_t verifyGd32Firmware(const uint8_t frontend_sha32[32],
|
||
uint8_t out_device_sha[32]);
|
||
|
||
/**
|
||
* @brief 计算 GD32 固件 SHA-256 并写入元数据。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t finalizeGd32Checksum();
|
||
|
||
/**
|
||
* @brief 擦除 GD32 OTA 分区。
|
||
* @param size 擦除大小。
|
||
* @return ESP_OK 成功。
|
||
*/
|
||
esp_err_t eraseGd32Partition(uint32_t size);
|
||
|
||
// ── GD32 中继阶段 ──
|
||
/**
|
||
* @brief 触发 GD32 中继转发。
|
||
* 向 OtaRelay task 的 dispatchQueue 发送启动消息。
|
||
* @return ESP_OK 消息已投递，ESP_ERR_INVALID_STATE 不允许触发。
|
||
*/
|
||
esp_err_t triggerGd32Relay();
|
||
|
||
/**
|
||
* @brief OtaRelay task 回调：中继已开始。
|
||
* 由 OtaRelay 在开始 forwardFirmware() 时调用。
|
||
*/
|
||
void notifyRelayStarted();
|
||
|
||
/**
|
||
* @brief OtaRelay task 回调：中继已完成。
|
||
* 由 OtaRelay 在 forwardFirmware() 返回后调用。
|
||
* @param success true 成功，false 失败。
|
||
*/
|
||
void notifyRelayComplete(bool success);
|
||
|
||
// ── ESP32 OTA 阶段 ──
|
||
/**
|
||
* @brief ESP32 OTA 开始接收固件。
|
||
* 内部委托 Esp32OtaCore::begin()。
|
||
* @param total_size 固件总字节数。
|
||
* @return ESP_OK 成功，ESP_ERR_INVALID_STATE 系统忙或通道被占用。
|
||
*/
|
||
esp_err_t beginEsp32Ota(uint32_t total_size);
|
||
|
||
/**
|
||
* @brief 发起 ESP32 OTA，若被 ESP_ERR_INVALID_STATE 拒绝则 forceCleanup 后重试一次。
|
||
* 封装 BLE/WiFi 两端完全相同的重试模式，调用方只需调一次。
|
||
* @param total_size 固件总字节数。
|
||
* @return ESP_OK 成功；其他 = 协调器拒绝或 Esp32OtaCore::begin 失败。
|
||
*/
|
||
esp_err_t beginEsp32OtaWithRetry(uint32_t total_size);
|
||
|
||
/**
|
||
* @brief ESP32 OTA 固件接收完毕，准备收尾。
|
||
* 更新系统状态为 OTA_SYS_ESP32_FINALIZING。
|
||
*/
|
||
void notifyEsp32ReceiveComplete();
|
||
|
||
/**
|
||
* @brief ESP32 OTA 收尾完成（finalize 成功）。
|
||
*/
|
||
void notifyEsp32FinalizeComplete();
|
||
|
||
/**
|
||
* @brief ESP32 即将重启。
|
||
*/
|
||
void notifyEsp32Rebooting();
|
||
|
||
/**
|
||
* @brief ESP32 OTA 收尾（统一封装 BLE/WiFi 两端重复的收尾序列）。
|
||
* 步骤：notifyEsp32ReceiveComplete → Esp32OtaCore::finalize(reboot=false)
|
||
* → 成功则 notifyEsp32FinalizeComplete。
|
||
* 不重启；调用方负责把 device_sha_hex 上报前端后再调 restartEsp32()。
|
||
* @param frontend_sha_hex 前端 64 字符 hex SHA-256，nullptr 表示跳过比对。
|
||
* @return Esp32FinalizeResult，err 为 ESP_OK/ESP_ERR_INVALID_VERSION/其他。
|
||
*/
|
||
Esp32FinalizeResult finalizeForReboot(const char *frontend_sha_hex);
|
||
|
||
/**
|
||
* @brief 重启 ESP32（统一封装 BLE/WiFi 两端重复的重启序列）。
|
||
* 步骤：notifyEsp32Rebooting → vTaskDelay(500ms) → esp_restart()。
|
||
* 应在 finalizeForReboot 成功并完成前端上报后调用。不会返回。
|
||
*/
|
||
void restartEsp32();
|
||
|
||
// ── 中止 ──
|
||
/**
|
||
* @brief 中止当前 OTA 操作（GD32 或 ESP32）。
|
||
* 内部调用对应子系统的 abort/reset。
|
||
*/
|
||
void abortCurrent();
|
||
|
||
// ── 状态查询 ──
|
||
/**
|
||
* @brief 获取当前系统级 OTA 状态。
|
||
* @return 当前 ota_system_state_t 状态值。
|
||
*/
|
||
ota_system_state_t getSystemState() const;
|
||
|
||
/**
|
||
* @brief 检查系统是否空闲（可接受新的 OTA 请求）。
|
||
* @return true 系统空闲（IDLE/STORED/COMPLETE）。
|
||
*/
|
||
bool isIdle() const;
|
||
|
||
/**
|
||
* @brief 检查是否有 GD32 相关操作正在进行。
|
||
* @return true 表示 STORING 或 RELAYING。
|
||
*/
|
||
bool isGd32Busy() const;
|
||
|
||
/**
|
||
* @brief 检查是否有 ESP32 OTA 正在进行。
|
||
* @return true 表示 RECEIVING/FINALIZING/REBOOTING。
|
||
*/
|
||
bool isEsp32Busy() const;
|
||
|
||
/**
|
||
* @brief 获取系统状态的可读字符串描述。
|
||
* @return 状态名称字符串（如 "IDLE"、"GD32_STORING" 等）。
|
||
*/
|
||
const char* getSystemStateString() const;
|
||
|
||
// ── GD32 状态（供 status API 使用，委托给 OtaRelay 查询）──
|
||
/**
|
||
* @brief 获取 GD32 APP 存活状态。
|
||
* @return true 表示 GD32 APP 存活。
|
||
*/
|
||
bool getGd32AppAlive() const;
|
||
|
||
/**
|
||
* @brief GD32 固件存储完成标志（供状态查询）。
|
||
* @return true 表示固件已完整存储。
|
||
*/
|
||
bool isGd32StorageDone() const;
|
||
|
||
// ── 完全复位 ──
|
||
/**
|
||
* @brief 完全复位协调器和所有子系统状态。
|
||
*/
|
||
void reset();
|
||
|
||
// ── ESP32 OTA finalize 错误分类（BLE/WiFi 共用）──
|
||
/**
|
||
* @brief 把 finalize 返回的 esp_err_t 映射为前端可读的事件码。
|
||
* 统一 BLE/WiFi 两端语义，便于日志/状态一致。
|
||
* @param err finalize 返回的 esp_err_t。
|
||
* @return 0=成功；1=SHA 不匹配；2=其他失败。
|
||
*/
|
||
static int esp32FinalizeErrCategory(esp_err_t err);
|
||
|
||
// ── IRelayListener 接口实现（H4: OtaRelay 通过接口回调通知协调器）──
|
||
/**
|
||
* @brief IRelayListener 回调：中继已开始。
|
||
* 由 OtaRelay task 在 forwardFirmware() 前通过 s_relayListener 调用。
|
||
*/
|
||
void onRelayStarted() override;
|
||
|
||
/**
|
||
* @brief IRelayListener 回调：中继已完成。
|
||
* 由 OtaRelay task 在 forwardFirmware() 返回后通过 s_relayListener 调用。
|
||
* @param success true 成功，false 失败。
|
||
*/
|
||
void onRelayComplete(bool success) override;
|
||
|
||
private:
|
||
OtaCoordinator() = default;
|
||
~OtaCoordinator() = default;
|
||
OtaCoordinator(const OtaCoordinator&) = delete;
|
||
OtaCoordinator& operator=(const OtaCoordinator&) = delete;
|
||
|
||
// 线程安全辅助
|
||
// ★ lock() 返回是否成功 take；unlock(handle) 据此决定是否 give。
|
||
// 旧实现用共享 bool m_locked 记录 take 结果，多任务并发 lock() 时
|
||
// 超时方会把 m_locked 置 false，覆盖持锁方的 true，导致 unlock() 跳过 give，
|
||
// mutex 永久死锁 → 后续 take 超时触发 vTaskPriorityDisinherit assert → PANIC。
|
||
bool lock();
|
||
void unlock(bool handle);
|
||
|
||
// ★ 卡死自愈检查：若忙状态停留超过 watchdog 超时，强制转为 ERROR。
|
||
// 用于在中继 task 因任何原因（崩溃/SPI 死锁/看门狗复位残留）未能回调
|
||
// notifyRelayComplete/notifyEsp32*Complete 时，让协调器自动脱离卡死状态。
|
||
// 必须在已持锁状态下调用。
|
||
void watchdogCheckLocked();
|
||
|
||
// 系统状态
|
||
ota_system_state_t m_sysState = OTA_SYS_IDLE;
|
||
|
||
// 进入当前忙状态的时刻（tick）。IDLE/STORED/COMPLETE/ERROR 时为 0。
|
||
TickType_t m_busySinceTick = 0;
|
||
|
||
// GD32 存储跟踪
|
||
bool m_gd32StorageDone = false;
|
||
|
||
// 互斥锁
|
||
SemaphoreHandle_t m_mutex = nullptr;
|
||
static constexpr TickType_t kLockTimeout = pdMS_TO_TICKS(100);
|
||
|
||
// ★ 忙状态 watchdog 超时。GD32 中继理论最大耗时 ≈ 60s(全局超时) + 15s(APP存活轮询) + 1s(bootloader) ≈ 76s，
|
||
// 取 90 s，正常流程远不会触及，仅在 task 卡死时触发自愈。
|
||
static constexpr TickType_t kBusyWatchdogTicks = pdMS_TO_TICKS(90U * 1000U);
|
||
};
|
||
|
||
#endif // OTA_COORDINATOR_H
|