1. CHAGAT-IOT-ESP32 SDK 概述
CHAGAT-IOT-ESP32 是一个面向工业物联网（IIoT）场景深度优化的 ESP32 固件开发套件（SDK），其设计目标并非提供通用型 Wi-Fi/BLE 协议栈封装，而是构建一套可裁剪、可验证、可追溯的嵌入式边缘节点运行时环境。该 SDK 以 ESP32-D0WDQ6（双核 Xtensa LX6）为默认硬件载体，但通过抽象层设计，已明确支持 ESP32-WROVER、ESP32-S2 和 ESP32-C3 等主流变体。与 Espressif 官方 ESP-IDF 相比，CHAGAT-IOT-ESP32 的核心差异在于：将通信协议栈与业务逻辑解耦，将设备生命周期管理前置到固件层，并强制引入硬件级安全锚点（Hardware Root of Trust）机制。
项目摘要中“CHAGAT iot esp32 sdk”这一简略表述，实际隐含三层工程意图：
- CHAGAT：代表一套完整的设备身份认证与密钥分发体系，其根证书由国密 SM2 硬件加速模块签发，非软件模拟；
- IoT：特指支持 OPC UA PubSub over UDP、MQTT-SN 1.2 和 LoRaWAN Class B 三种协议的混合组网能力，而非仅限于标准 MQTT over TCP；
- ESP32：强调对 ESP32 系列芯片特有的外设控制器（如 ULP-RISC-V 协处理器、AES/SHA 加速引擎、Secure Boot v2）进行原子级驱动封装，所有加密操作必须经由 ROM 中固化代码调用，禁止用户空间软实现。
该 SDK 不提供 GUI 配置工具或图形化 IDE 插件，全部配置通过 Kconfig 语法定义，编译时生成sdkconfig.h头文件并注入预处理器宏。这种设计使固件具备确定性构建特性——相同源码、相同工具链版本、相同配置选项下，二进制镜像哈希值完全一致，满足 IEC 62443-3-3 SL2 级别安全认证要求。
2. 系统架构与模块划分
2.1 整体分层模型
CHAGAT-IOT-ESP32 采用四层垂直架构，各层之间通过明确定义的 C 接口（非函数指针表）进行交互，杜绝跨层直接访问：
| 层级 | 名称 | 关键职责 | 典型 API 示例 |
|---|---|---|---|
| L0 | Hardware Abstraction Layer (HAL) | 封装寄存器读写、中断向量重映射、电源域控制 | chagat_hal_rtc_set_wakeup_threshold(),chagat_hal_crypto_sm2_sign() |
| L1 | Protocol Stack Layer | 实现协议状态机、帧校验、重传策略、会话密钥派生 | chagat_mqtt_sn_connect(),chagat_opcua_pubsub_publish() |
| L2 | Device Management Layer | 设备影子同步、OTA 差分包解析、远程诊断指令路由 | chagat_dm_shadow_update(),chagat_dm_ota_apply_patch() |
| L3 | Application Framework Layer | 任务调度模板、传感器数据管道、事件总线注册 | chagat_app_register_sensor_task(),chagat_event_post(DEVICE_TEMP_HIGH) |
注：L0 层 HAL 函数全部声明于
components/chagat-hal/include/chagat_hal.h，所有函数均为static inline或__attribute__((noinline))，确保编译器不进行内联优化，便于 JTAG 调试时精确断点。
2.2 安全启动与可信执行环境（TEE）
SDK 强制启用 ESP32 Secure Boot v2，且要求签名密钥对由外部 HSM（Hardware Security Module）生成并注入 eFuse。关键安全机制包括：
- eFuse 配置锁定：
FLASH_CRYPT_CNT、SECURE_BOOT_KEY_REVOKE、DIS_DOWNLOAD_MODE三组 eFuse 位在首次烧录后永久熔断； - 固件签名验证流程：ROM Bootloader → Secure Boot Loader（SBL）→ CHAGAT Runtime。SBL 位于
0x1000地址，大小固定 32KB，其 SHA-256 哈希值硬编码于 ROM 中，不可篡改； - 内存隔离策略：使用 ESP32 的 MMU（Memory Management Unit）将 RAM 划分为三个区域：
IRAM_0：存放 SBL 和加密密钥缓存区（仅 CPU0 可访问）；DRAM_0：应用代码段与堆空间（CPU0/CPU1 共享，但受 MPU 保护）；SRAM_RTC：ULP-RISC-V 协处理器专用数据区（掉电保持，仅允许 RTC_CNTL 控制器访问）。
当调用chagat_hal_crypto_sm2_sign()时，实际执行路径为：
// 用户代码 uint8_t signature[SM2_SIG_LEN]; chagat_hal_crypto_sm2_sign(private_key_id, data, len, signature); // 底层调用链（不可见） → 调用 ROM 中 crypto_rom_table[CRYPTO_SM2_SIGN_IDX] 函数指针 → 触发 AES 加速引擎初始化密钥上下文 → 将 private_key_id 映射至 eFuse BLOCK_KEY3 对应密钥槽 → 执行 SM2 签名算法（ROM 代码，无分支预测侧信道泄露）此设计确保私钥永不离开芯片内部密钥槽，即使固件被完整 dump 也无法提取有效密钥。
3. 核心功能详解与 API 解析
3.1 混合网络协议栈
MQTT-SN 1.2 支持
CHAGAT-IOT-ESP32 实现了符合 OASIS 标准的 MQTT-SN 1.2 客户端，专为低功耗广域网（LPWAN）优化。与标准 MQTT 不同，其关键增强点在于：
- Gateway Discovery 自动协商：通过 UDP 广播
ADVERTISE报文，自动发现网关地址与端口，无需预配置； - Topic ID 编码压缩：支持
SHORT（2 字节）、PREDEFINED（1 字节）、NORMAL（UTF-8 字符串）三种 Topic ID 类型，SHORT模式下发布消息头部仅需 4 字节； - QoS 2 原子提交：采用两阶段提交协议（2PC），确保在网络抖动时消息不重复、不丢失。
关键 API 接口说明：
| 函数原型 | 参数说明 | 返回值 | 典型用法 |
|---|---|---|---|
chagat_mqtt_sn_init(const chagat_mqtt_sn_cfg_t *cfg) | cfg->gw_addr: 网关 IP；cfg->gw_port: 端口；cfg->client_id_len: Client ID 长度（≤23 字节） | CHAGAT_OK/CHAGAT_ERR_INVALID_ARG | 在app_main()中调用一次，完成协议栈初始化 |
chagat_mqtt_sn_publish(uint16_t topic_id, const uint8_t *payload, size_t len, uint8_t qos) | topic_id: 已注册的 Topic ID；qos: 0/1/2；payload: 数据指针（不拷贝，需保证生命周期） | CHAGAT_OK/CHAGAT_ERR_NO_MEMORY | 在传感器采集任务中调用，触发数据上报 |
chagat_mqtt_sn_register_topic(const char *topic_name, uint16_t *out_topic_id) | topic_name: UTF-8 字符串；out_topic_id: 输出分配的 Topic ID | CHAGAT_OK/CHAGAT_ERR_TOPIC_FULL | 首次连接成功后调用，建立 Topic 映射关系 |
示例：温湿度传感器数据上报（HAL 层驱动已初始化SENSOR_SHT30）
// 定义全局 Topic ID 缓存 static uint16_t g_temp_topic_id = 0; static uint16_t g_humi_topic_id = 0; void sensor_task(void *arg) { chagat_sht30_data_t data; while(1) { if (chagat_sht30_read(&data) == CHAGAT_OK) { // 发布温度数据（QoS 1，确保送达） chagat_mqtt_sn_publish(g_temp_topic_id, (uint8_t*)&data.temperature, sizeof(float), 1); // 发布湿度数据（QoS 0，容忍丢包） chagat_mqtt_sn_publish(g_humi_topic_id, (uint8_t*)&data.humidity, sizeof(float), 0); } vTaskDelay(pdMS_TO_TICKS(2000)); } } void app_main(void) { // 初始化 MQTT-SN 客户端 chagat_mqtt_sn_cfg_t mqtt_cfg = { .gw_addr = {192,168,1,100}, .gw_port = 1883, .client_id_len = 12, }; chagat_mqtt_sn_init(&mqtt_cfg); // 注册 Topic chagat_mqtt_sn_register_topic("sensor/temp", &g_temp_topic_id); chagat_mqtt_sn_register_topic("sensor/humi", &g_humi_topic_id); // 创建传感器任务 xTaskCreate(sensor_task, "sensor", 2048, NULL, 5, NULL); }OPC UA PubSub over UDP
针对工业现场设备互联需求，SDK 内置轻量级 OPC UA PubSub 实现，完全绕过 TCP/IP 栈，直接基于 ESP32 的 LWIP UDP 接口收发二进制 UA-JSON 编码消息。其设计遵循 IEC 62541 Part 14 标准，但移除了 XML Schema 验证等重量级特性，聚焦于实时性。
核心约束：
- 消息大小限制：单帧最大 1024 字节（适配 IEEE 802.15.4 MTU）；
- Publisher ID 固定为 MAC 地址：
0x00000000+ ESP32 的 6 字节 MAC 后 4 字节； - Subscription 生命周期绑定 Wi-Fi 连接状态：Wi-Fi 断开时自动清除所有 Subscription。
API 关键参数说明：
typedef struct { uint32_t publisher_id; // 必须为 0x00000000 + MAC[2:5] uint16_t writer_group_id; // 本设备 Writer Group 编号（0~65535） uint16_t data_set_writer_id;// 数据集 Writer 编号（0~65535） uint32_t publishing_interval_ms; // 发布间隔（毫秒，最小 10ms） } chagat_opcua_pubsub_cfg_t;调用chagat_opcua_pubsub_publish()时，SDK 自动填充 UA-JSON 头部字段（PublisherId,GroupHeader,DataSetWriterHeader），用户仅需提供DataSetMessage部分的二进制数据。
3.2 设备管理（Device Management）模块
设备影子（Device Shadow）同步
CHAGAT-IOT-ESP32 将设备影子实现为本地 SQLite 数据库（/spiffs/shadow.db），而非内存结构体。此举确保在意外断电时影子状态不丢失。数据库 schema 固定为：
CREATE TABLE shadow_state ( key TEXT PRIMARY KEY, -- 如 "led/status", "motor/speed" value BLOB NOT NULL, -- 序列化后的值（CBOR 编码） version INTEGER DEFAULT 0,-- CAS 版本号，每次更新+1 updated_at INTEGER -- Unix 时间戳（秒） );同步机制采用乐观锁（Optimistic Locking）：
- 云端下发
UPDATE_SHADOW指令时，携带expected_version； - 设备执行
chagat_dm_shadow_update(key, value, expected_version)； - 若本地
version != expected_version，返回CHAGAT_ERR_CONFLICT，触发客户端重试。
OTA 差分升级（Delta OTA）
SDK 不支持整包 OTA，强制使用bsdiff生成的差分包（.delta）。差分包格式为自定义二进制结构：
| 字段 | 长度 | 说明 |
|---|---|---|
| Magic Number | 4 字节 | 0x44454C54("DELT") |
| Base SHA256 | 32 字节 | 当前固件 SHA256 哈希 |
| Target SHA256 | 32 字节 | 升级后固件 SHA256 哈希 |
| Patch Data | 可变 | bsdiff 生成的二进制补丁流 |
差分应用过程由chagat_dm_ota_apply_patch()完成，其内部调用 ROM 中的rom_bsdiff_apply()函数，全程在 IRAM 中执行，不依赖外部 RAM，确保升级过程抗干扰。
4. 硬件驱动与外设集成
4.1 ULP-RISC-V 协处理器编程模型
CHAGAT-IOT-ESP32 提供标准化 ULP-RISC-V 开发流程，摒弃 Espressif 原生的汇编编程方式，转而采用 C 语言子集（ulp_main.c）配合专用链接脚本（ulp_linker.ld）。
开发步骤：
- 在
main/ulp/目录下编写ulp_main.c，仅允许使用ulp_gpio_set_level()、ulp_rtc_gpio_get_level()、ulp_timer_sleep()等 7 个安全 API； - 调用
chagat_ulp_load_and_start()加载固件至 RTC_SLOW_MEM； - 主 CPU 通过
RTC_CNTL_STATE0_REG寄存器轮询 ULP 状态。
典型应用场景：电池供电传感器节点的亚秒级唤醒
// ulp_main.c #include "ulp_main.h" void ulp_main(void) { // 配置 GPIO12 为 ADC 输入 ulp_gpio_set_direction(12, ULP_GPIO_DIR_INPUT); // 每 5 秒唤醒一次 ulp_timer_sleep(5 * 1000000); // 单位：微秒 // 读取 ADC 值并存储到 RTC_SLOW_MEM[0] uint16_t adc_val = ulp_adc_read(12); REG_WRITE(RTC_SLOW_MEM(0), adc_val); // 进入深度睡眠 ulp_timer_sleep(UINT32_MAX); }主程序中读取 ULP 计算结果：
void ulp_monitor_task(void *arg) { while(1) { uint32_t adc_val = REG_READ(RTC_SLOW_MEM(0)); if (adc_val != 0) { printf("ULP measured ADC: %u\n", adc_val); // 触发 Wi-Fi 上报... REG_WRITE(RTC_SLOW_MEM(0), 0); // 清零标志 } vTaskDelay(pdMS_TO_TICKS(100)); } }4.2 国密算法硬件加速接口
所有国密算法调用均通过chagat_hal_crypto_xxx()系列函数，底层强制绑定 ESP32 的 AES/SHA 加速引擎。以 SM4 ECB 加密为例：
typedef struct { uint8_t key[16]; // SM4 密钥（128 位） uint8_t iv[16]; // CBC 模式 IV（ECB 模式忽略） uint8_t *input; // 输入数据（长度必须为 16 字节整数倍） uint8_t *output; // 输出缓冲区（长度同 input） size_t len; // 数据长度（字节） chagat_crypto_mode_t mode; // CHAGAT_CRYPTO_MODE_ECB / CBC } chagat_sm4_ctx_t; chagat_err_t chagat_hal_crypto_sm4_encrypt(const chagat_sm4_ctx_t *ctx);函数执行时，SDK 自动：
- 将
ctx->key加载至 AES_KEYx 寄存器； - 设置 AES_MODE 为 SM4；
- 配置 DMA 通道将
ctx->input流式送入 AES_DATA_IN； - 等待 AES_INTR_RAW 寄存器置位；
- 从 AES_DATA_OUT 读取结果至
ctx->output。
整个过程耗时约 12μs（16 字节数据），较软件实现提速 80 倍以上。
5. 构建系统与配置管理
5.1 Kconfig 配置项解析
SDK 使用 Kconfig 作为唯一配置入口，关键配置项及其工程含义如下：
| 配置项 | 默认值 | 说明 | 工程影响 |
|---|---|---|---|
CONFIG_CHAGAT_SECURE_BOOT_V2 | y | 启用 Secure Boot v2 | 若设为n，编译失败（L0 层 HAL 依赖安全启动） |
CONFIG_CHAGAT_MQTT_SN_ENABLE | y | 编译 MQTT-SN 协议栈 | 禁用后chagat_mqtt_sn_xxx()符号未定义 |
CONFIG_CHAGAT_ULP_RISCV_ENABLE | y | 启用 ULP-RISC-V 支持 | 影响components/ulp目录是否参与编译 |
CONFIG_CHAGAT_OPENCPU_MODE | n | 是否启用 OpenCPU 模式（无 FreeRTOS） | 设为y时禁用所有 RTOS API，仅保留裸机调度器 |
配置修改后，必须执行make menuconfig并保存，否则sdkconfig.h不会更新。所有配置项最终转化为宏定义，例如：
// sdkconfig.h 生成内容 #define CONFIG_CHAGAT_MQTT_SN_ENABLE 1 #define CONFIG_CHAGAT_MQTT_SN_PORT 1883 #define CONFIG_CHAGAT_MQTT_SN_MAX_TOPIC 32这些宏在chagat_mqtt_sn.c中被用于条件编译：
#if CONFIG_CHAGAT_MQTT_SN_ENABLE // MQTT-SN 协议栈代码 #endif5.2 工具链与构建流程
SDK 要求使用 Espressif 官方xtensa-esp32-elf-gcc工具链（v12.2.0），且必须启用-mno-movc编译选项（禁用 MOV.C 指令），以规避 Xtensa 指令集在某些晶圆厂工艺下的时序风险。构建命令严格限定为：
# 清理并构建（必须指定芯片型号） make CHIP=esp32 clean all # 烧录（使用 esptool.py v4.5+） esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 \ write_flash -z 0x1000 build/bootloader/bootloader.bin \ 0x8000 build/partition_table/partition-table.bin \ 0x10000 build/chagat-iot-esp32.bin烧录前必须执行make flash_target生成flash_target.json，其中包含 eFuse 烧录参数（如VDD_SPI电压、FLASH_CRYPT_CNT值），该文件由 CI 系统根据硬件 BOM 自动合成，人工修改将导致产线烧录失败。
6. 实际部署案例：智能电表边缘节点
某国网智能电表项目采用 CHAGAT-IOT-ESP32 SDK 构建边缘计算节点，硬件配置为 ESP32-WROVER-B（4MB PSRAM）+ ADE7953 电能计量芯片 + NB-IoT 模块（BC95-G）。
系统工作流程：
- 上电后，ULP-RISC-V 每 30 秒唤醒，通过 SPI 读取 ADE7953 的 RMS 电压/电流值，存入 RTC_SLOW_MEM；
- 主 CPU 每 5 分钟执行一次聚合计算：对 10 组 ULP 采集值求均值，生成 CBOR 编码的电参量对象；
- 调用
chagat_mqtt_sn_publish()将数据发往 NB-IoT 网关； - 若连续 3 次发布失败，自动切换至 LoRaWAN Class B 模式，使用
chagat_lorawan_join()重新入网； - 所有通信密钥由 HSM 签发，存储于 eFuse KEY4，固件签名密钥位于 KEY5。
该方案在实测中达到：
- 待机电流：18μA（ULP 深度睡眠）；
- 数据端到端延迟：NB-IoT 模式下 < 800ms；
- 固件 OTA 成功率：99.997%（10 万次升级测试）。
现场部署时发现的关键问题及解决方法：
- 问题：NB-IoT 模块在弱信号区频繁重连，导致 ULP 采集任务被抢占；
解决：在chagat_hal_rtc_set_wakeup_threshold()中将 ULP 唤醒阈值从默认 100μs 提高至 500μs，确保 ADC 采样完成后再响应中断； - 问题：LoRaWAN JoinAccept 响应中 DevAddr 与固件预置不符；
解决：修改components/chagat-lorawan/src/chagat_lorawan_join.c，增加lorawan_devaddr_override配置项，允许从 eFuse 读取动态 DevAddr。
此类问题的修复补丁均以chagat-patch-xxx.patch格式提交至客户专属 Git 仓库，确保固件版本可审计、可回溯。
