EnvSense-Box 软件设计

1. 固件概览

参数	说明
开发框架	ESP-IDF（Espressif IoT Development Framework）
操作系统	FreeRTOS
构建系统	CMake
项目名称	env_sense_box
代码仓库	https://github.com/YunStack-IoT/EnvSense-Box

2. 软件架构

3. 任务设计

系统只有一个核心 FreeRTOS 任务：

参数	值	说明
任务名	sensor_task	传感器采集主任务
优先级	5	中等优先级
栈大小	4096 字节	足以容纳传感器驱动和 JSON 格式化
创建方式	xTaskCreate()	在 app_main 中创建

4. 初始化流程

app_main() 启动
  └─→ xTaskCreate(sensor_task)
        ├─→ i2c_master_init()              ← I2C 总线 (SCL=26, SDA=27, 100kHz)
        ├─→ ws2812_led_init(GPIO5, 1)      ← WS2812 LED
        ├─→ aht20_create(i2c_bus, 0x38)     ← 温湿度传感器
        ├─→ bh1750_create(i2c_bus, 0x23)    ← 光照传感器
        │     ├─→ bh1750_power_on()
        │     └─→ bh1750_set_measure_mode(CONTINUE_1LX_RES)
        ├─→ bmp280_create(i2c_bus, 0x76)    ← 气压传感器
        │     └─→ bmp280_default_init()
        ├─→ sc8co2_init()                    ← CO₂ 传感器 (UART2)
        │
        └─→ 进入循环 (2000ms 周期)

5. 采集循环

每个周期（2000ms）执行以下步骤：

1. AHT20：aht20_trigger_measurement() → 延时 80ms 等待转换 → aht20_read_data() 读取温度和湿度
2. BMP280：bmp280_read_pressure() + bmp280_read_temperature() 读取气压和板载温度
3. BH1750：bh1750_get_data() 读取光照强度（已设为连续测量模式）
4. SC8CO2：sc8co2_read_co2() 发送 Modbus 查询指令 → 接收 14 字节响应 → CRC16 校验 → 提取 CO₂ 浓度
5. 状态判断：检查所有传感器数据是否有效（任一值为 -999 表示故障）
   • 全部有效 → WS2812 显示绿色
   • 任一故障 → WS2812 显示红色
6. JSON 输出：通过 printf() 向 UART0 输出格式化 JSON
7. vTaskDelay(2000ms) 等待下一周期

6. 传感器驱动细节

AHT20

• 组件库：ESP-IDF 注册表 aht20 组件
• 触发测量后需等待 80ms 转换完成
• 读取：aht20_read_data(handle, &temp, &humi) 一次获取温度和相对湿度

BMP280

• 组件库：ESP-IDF 注册表 bmp280 组件
• 初始化：bmp280_default_init() 加载校准参数
• 分别调用 bmp280_read_pressure() 和 bmp280_read_temperature() 获取气压（hPa）和温度（°C）

BH1750

• 组件库：ESP-IDF 注册表 bh1750 组件
• 上电：bh1750_power_on()
• 测量模式：bh1750_set_measure_mode(BH1750_CONTINUE_1LX_RES) — 连续模式，1 lx 分辨率
• 读取：bh1750_get_data(handle, &lux)

SC8CO2

• 自研驱动（components/sc8co2/），不依赖第三方组件
• UART2 配置：9600bps, 8N1, 无流控
• 协议：Modbus RTU CRC16
• 查询指令：{0x64, 0x69, 0x03, 0x5E, 0x4E}（5 字节固定帧）
• 响应帧：14 字节，前 2 字节为帧头（0x64, 0x69），字节 4-5 为 CO₂ 值（uint16, ppm），末 2 字节为 CRC16 校验
• 读超时：200ms

WS2812 LED

• 自研驱动（main/ws2812_led.c），封装 ESP-IDF led_strip 组件
• 使用 RMT 外设输出控制信号，10MHz 分辨率
• 主要接口：ws2812_led_set_all_color(r, g, b) 设置全部 LED 为同一颜色

7. 数据输出格式

固件通过 UART0 printf() 输出单行 JSON：

{"temperature":25.40,"humidity":60.50,"pressure":1013.25,"bmp_temperature":25.80,"light_intensity":1200.00,"co2_concentration":450.00}

字段	说明
temperature	AHT20 环境温度 (°C)
humidity	AHT20 相对湿度 (%RH)
pressure	BMP280 气压 (hPa)
bmp_temperature	BMP280 板载温度 (°C，不同于 AHT20 的 temperature)
light_intensity	BH1750 光照强度 (lx)
co2_concentration	SC8CO2 CO₂ 浓度 (ppm)

• 传感器故障时对应字段值为 -999.00
• JSON 为单行紧凑格式，无换行和多余空格

8. 组件依赖

组件	类型	说明
aht20	ESP-IDF 注册表	温湿度传感器驱动
bmp280	ESP-IDF 注册表	气压传感器驱动
bh1750	ESP-IDF 注册表	光照传感器驱动
sc8co2	自研 (components/sc8co2)	CO₂ 传感器驱动
ws2812_led	自研 (main/ws2812_led.c)	WS2812 LED 驱动
i2c_bus	ESP-IDF 注册表	I2C 总线抽象

9. PC 端调试工具

附带的 Python 调试工具 Software/pc/serial_debugger.py：

• 基于 PySide6 的 GUI 程序
• 串口连接（默认 115200bps），实时解析 JSON 数据
• 6 路传感器数值显示（温度、温度均值、湿度、气压、CO₂、光照）
• 内置 MQTT 转发功能（paho-mqtt），可将串口数据转发至指定 Broker 和 Topic
• MQTT 转发开关可控，支持 SSL/TLS

10. 接入 YunStack-IoT 的 TODO

当前固件仅支持 UART 串口输出，接入 IoT 平台需新增以下功能：

• [ ] 集成 WiFi 连接管理（esp_wifi + NVS 存储凭据）
• [ ] 集成 MQTT 客户端（esp_mqtt），对接 EMQX Broker
• [ ] 实现标准 Topic 协议：sys/{pid}/{did}/thing/event/property/post 上报 JSON
• [ ] 添加 ProductKey + DeviceSecret 预置（生产烧录）
• [ ] 支持 thing/config/set 接收逻辑 ID（参照平台注册流程）
• [ ] 添加 OTA 升级功能（esp_https_ota）