从模拟到真实：小熊派硬件接入 IoT 平台的全过程记录
📌原创声明：本文基于本人课程实训期间独立开发的智慧路灯 IoT 管理平台（Spring Boot + EMQX + TDengine）实战经验整理，为第一手踩坑记录，内容已脱敏。项目代码已开源：https://github.com/smart-lighting-backend/SmartLightingExp
实战复盘 · 物联网硬件对接
项目背景：智慧路灯 IoT 管理平台最初使用模拟数据生成器（MockDataGenerator）模拟遥测上报，本文记录接入真实硬件（小熊派 BearPi-HM_Nano）的全过程——固件开发、MQTT 对接、边缘决策、远程控制。
一、为什么从模拟切到真实硬件
模拟数据只能验证"软件逻辑通不通"，但物联网系统的真正挑战在硬件侧：设备断网重连、真实传感器噪声、边缘计算能力、固件与云端协议对齐。接入真实硬件后，很多"模拟环境永远暴露不了"的问题浮出水面。
二、硬件与固件
| 组件 | 型号 | 说明 |
|---|---|---|
| 开发板 | BearPi-HM_Nano | 小熊派 HarmonyOS 开发板 |
| 扩展板 | E53_SC1 | BH1750 光照传感器 + LED 灯 |
| 通信 | WiFi + MQTT | 通过 EMQX 连接后端 |
| 存储 | Flash | 配网信息持久化 |
固件功能（E1_smartlighting_device示例）：
- Flash 配置存储：WiFi/MQTT 配置持久化，断电不丢
- AT 串口配网：通过串口指令配置 WiFi
- WiFi/MQTT 连接：断线自动重连
- 边缘决策：断网时本地判断开/关/调光
- 远程控制：接收云端 MQTT 指令
三、关键改造：设备数据源区分
数据库device表新增source字段，区分设备来源：
sourceVARCHAR(20)DEFAULT'SIMULATED'COMMENT'设备来源: SIMULATED=模拟, REAL=真实硬件'核心改动：MockDataGenerator（模拟数据生成器）跳过真实设备：
// 只给模拟设备生成数据，真实硬件自己上报mockDataGenerator 查询条件加.ne(Device::getSource,"REAL")四、设备 MQTT 鉴权落地
真实硬件接入要求每台设备独立 MQTT 凭据（详见《IoT 设备 MQTT 鉴权四层防护实战》）：
- EMQX 内置认证用户：
Real_CS_001（对应真实设备） - 每设备独立用户名/密码
- ACL Topic 隔离：设备只能访问自己的
streetlight/{deviceId}/#主题 - 修复：ACL 订阅 Topic 从
control改为command+config，匹配后端实际下发路径
五、协议对齐的坑
5.1 字段命名不一致
模拟器用的字段名（action/controlSource）与真实硬件上报的字段名（led_status/led_source）不一致，前端展示和控制状态判断都要兼容两种字段。
解决：前端/移动端解析时做双字段兼容：
// 模拟设备：action 字段; 真实硬件 BearPi：led_status 字段valaction=parseLatestField(latestData,"action")if(action!=null)returnwhen(action){"ON"->true;"OFF"->false;else->null}valled=parseLatestField(latestData,"led_status")if(led!=null)returnled=="ON"5.2 时间戳时区
TDengine 存储 UTC，真实硬件上报时间与模拟器格式不一致，需要统一为 UTC 存储 + 前端转北京时间展示。
5.3 WiFi 远程配置
新增PUT /devices/{id}/wifi-config接口，通过 MQTT config Topic 下发 WiFi 参数：
设备详情页 → 输入 SSID/密码 → 后端下发 streetlight/{deviceId}/config → 设备写入 Flash → 进入等待重启模式 → 自动重连新 WiFi六、边缘决策：设备断网也能干活
模拟环境永远测不出的场景——设备断网后怎么办。本项目通过"云端 + 边缘双层决策"解决：
- 云端：
DecisionEngine评估遥测 → 下发控制指令 - 边缘：
ConditionEvaluator纯函数实现（与云端逻辑一致，可迁移到硬件），设备断网时本地自主判断
关键设计：边缘评估逻辑用纯函数编写，不依赖任何框架，因此可以烧录到硬件端——同一套决策逻辑，云端边缘双跑。
七、经验总结
- "模拟能跑"和"真机能跑"是两回事：字段命名、时区、断网重连、协议对齐，都是硬件接入才暴露的问题
- 数据源字段（source）是必备设计：模拟/真实设备共存是 IoT 开发常态，必须有字段区分并让模拟器跳过真实设备
- 双层决策是 IoT 的关键架构：纯函数化决策逻辑，云端边缘复用，断网不瘫痪
- 协议兼容要做双字段适配：真实硬件字段与既有系统不一致时，兼容层比强制改硬件更务实
- 远程配置设备是刚需：WiFi 参数下发 + Flash 持久化 + 等待重启流程，是真实硬件设备管理的标配能力
