# 物联网开发规范 - CODING-STANDARDS-IOT

**版本**: 2.0.0
**适用范围**: 物联网开发岗位（传感器/执行器/边缘计算/网关，平台无关）
**最后更新**: 2025-12-25

---

## 🚨 核心铁律（继承自 common.md）

> **必须遵循 common.md 的四大核心铁律**

```
铁律1: SPEC 是唯一真源（SSOT）
       - 设备协议必须符合 SPEC 定义
       - 通信、数据格式、安全以 SPEC 为准

铁律2: 智能复用与销毁重建
       - 现有驱动完全匹配 → 直接复用
       - 部分匹配 → 删除重写

铁律3: 禁止渐进式开发
       - 禁止在旧固件上添加新功能
       - 禁止保留兼容性协议

铁律4: Context7 调研先行
       - 使用成熟的 IoT 平台和 SDK
       - 禁止自己实现通信协议
```

---

## 📡 设备通信

### 无线协议
- ✅ WiFi/BLE/LoRa/Zigbee/NB-IoT
- ✅ 协议选择（功耗/距离/带宽权衡）
- ✅ 信号强度监控（RSSI）
- ✅ 自动重连机制
- ✅ 网络切换（WiFi → 蜂窝）
- ❌ 避免长时间连接失败

### 消息协议
- ✅ MQTT/CoAP/HTTP/WebSocket
- ✅ QoS级别选择（0/1/2）
- ✅ 消息序列化（JSON/Protobuf/CBOR）
- ✅ 主题命名规范
- ✅ 保留消息和遗嘱（Last Will）
- ❌ 避免消息风暴

### 数据传输
- ✅ 批量上报（减少传输次数）
- ✅ 数据压缩
- ✅ 断点续传
- ✅ 重传和去重
- ✅ 流量监控
- ❌ 避免频繁小数据传输

---

## 🔋 功耗管理

### 低功耗设计
- ✅ 深度睡眠模式
- ✅ 定时唤醒
- ✅ 中断唤醒（传感器事件）
- ✅ 动态频率调节（DVFS）
- ✅ 外设按需使能
- ❌ 避免轮询（使用中断）

### 电池优化
- ✅ 电池电量监控
- ✅ 低电量告警
- ✅ 优雅关机
- ✅ 能量收集（太阳能/振动）
- ❌ 避免电池过放

### 传输优化
- ✅ 减少连接建立次数
- ✅ 保持连接（Keep-Alive）
- ✅ 数据本地缓存（离线上传）
- ✅ 变化触发上报（而非定时）
- ❌ 避免无意义的心跳

---

## 📊 传感器和数据采集

### 传感器管理
- ✅ 传感器校准
- ✅ 采样频率配置
- ✅ 数据滤波（移动平均/卡尔曼）
- ✅ 异常值检测和剔除
- ✅ 多传感器融合
- ❌ 避免原始数据直接使用

### 数据质量
- ✅ 数据有效性验证
- ✅ 范围检查
- ✅ 时间戳记录
- ✅ 数据完整性（CRC）
- ❌ 避免传输错误数据

### 本地处理
- ✅ 边缘计算（减少云端压力）
- ✅ 本地聚合和统计
- ✅ 阈值告警
- ✅ 数据预处理
- ❌ 避免所有数据上云

---

## 🎛️ 执行器控制

### 控制逻辑
- ✅ 状态反馈
- ✅ 控制指令确认
- ✅ 安全互锁（防误操作）
- ✅ 手动优先（物理按钮）
- ❌ 避免无确认的盲控

### 远程控制
- ✅ 指令验证（签名/Token）
- ✅ 权限检查
- ✅ 操作日志
- ✅ 超时保护
- ❌ 禁止未授权控制

---

## 🔒 安全

### 设备认证
- ✅ 设备唯一标识（Device ID）
- ✅ 证书认证（X.509）
- ✅ 对称密钥/非对称密钥
- ✅ 密钥轮换
- ❌ 禁止硬编码密钥

### 通信加密
- ✅ TLS/DTLS加密传输
- ✅ 端到端加密
- ✅ 防重放攻击（Nonce/时间戳）
- ✅ 签名验证
- ❌ 禁止明文传输敏感数据

### 固件安全
- ✅ 安全启动（Secure Boot）
- ✅ 固件签名验证
- ✅ 调试接口禁用（生产）
- ✅ 固件加密存储
- ❌ 避免固件逆向

---

## 🔄 设备管理

### 设备配网
- ✅ SmartConfig/蓝牙配网/AP模式
- ✅ 配网超时和失败处理
- ✅ 网络信息加密存储
- ✅ 重置功能（恢复出厂）
- ❌ 避免配网困难

### 设备注册
- ✅ 自动注册到云平台
- ✅ 设备元数据上报
- ✅ 注册失败重试
- ✅ 设备分组
- ❌ 避免重复注册

### OTA更新
- ✅ 固件版本管理
- ✅ 差分更新（减少流量）
- ✅ 断点续传
- ✅ 更新失败回滚
- ✅ A/B分区（双系统）
- ❌ 避免更新导致砖机

---

## 🌐 云端集成

### 设备影子
- ✅ 期望状态和报告状态
- ✅ 离线消息队列
- ✅ 状态同步
- ✅ 版本控制
- ❌ 避免状态不一致

### 数据上报
- ✅ 遥测数据（Telemetry）
- ✅ 属性数据（Property）
- ✅ 事件数据（Event）
- ✅ 时间序列存储
- ❌ 避免数据丢失

### 规则引擎
- ✅ 数据联动
- ✅ 告警规则
- ✅ 场景自动化
- ✅ 条件触发
- ❌ 避免规则冲突

---

## 📈 监控和诊断

### 设备监控
- ✅ 在线状态监控
- ✅ 设备健康检查
- ✅ 异常行为检测
- ✅ 性能指标上报
- ❌ 不要忽视离线设备

### 日志和调试
- ✅ 远程日志上报
- ✅ 日志分级（Error/Warn/Info）
- ✅ 本地日志缓存
- ✅ 远程调试接口
- ❌ 避免日志泛滥（耗电）

### 故障诊断
- ✅ 错误码定义
- ✅ 故障自诊断
- ✅ 故障上报
- ✅ 看门狗复位统计
- ❌ 避免故障隐藏

---

## 🧪 测试

### 功能测试
- ✅ 传感器数据准确性
- ✅ 执行器控制正确性
- ✅ 网络连接稳定性
- ✅ OTA更新测试
- ✅ 断电恢复测试
- ❌ 不要跳过边界测试

### 环境测试
- ✅ 温度/湿度环境测试
- ✅ 电磁兼容（EMC）测试
- ✅ 跌落/振动测试
- ✅ 防水/防尘测试
- ❌ 避免只在实验室测试

### 压力测试
- ✅ 长时间运行测试
- ✅ 网络异常测试
- ✅ 大量设备并发测试
- ✅ 功耗测试
- ❌ 不要忽视极端情况

---

## 📋 物联网开发检查清单

- [ ] 无线通信协议选择和重连机制
- [ ] 低功耗设计（睡眠/唤醒）
- [ ] 传感器数据滤波和验证
- [ ] 设备认证和通信加密
- [ ] OTA更新安全（签名/回滚）
- [ ] 设备配网和注册流程
- [ ] 云端集成（MQTT/设备影子）
- [ ] 监控和日志上报
- [ ] 环境和压力测试
- [ ] 电池电量监控和低电量处理

---

---

## 🏛️ 高级 IoT 架构（20+年经验）

### 边缘计算架构
```
边缘层次：
- 设备边缘：传感器本地处理
- 网关边缘：协议转换、数据聚合
- 雾计算：区域级处理
- 云端：全局分析和存储

边缘智能：
- TinyML：MCU 上的机器学习
- 模型量化和压缩
- 增量学习
- 联邦学习

边缘编排：
- KubeEdge：K8s 延伸到边缘
- EdgeX Foundry：边缘框架
- AWS Greengrass/Azure IoT Edge
- 容器化边缘应用
```

### 大规模设备管理
```
设备生命周期：
- 设备配置（Provisioning）
- 身份注册
- 运行监控
- 固件更新
- 退役清除

Fleet 管理：
- 设备分组和标签
- 批量操作
- 配置下发
- 状态同步

零接触配置（Zero-Touch）：
- 自动发现
- 自动注册
- 自动配置
- 安全引导
```

### 数字孪生
```
孪生模型：
- 物理实体映射
- 实时状态同步
- 历史数据存储
- 预测性分析

孪生平台：
- Azure Digital Twins
- AWS IoT TwinMaker
- 自建孪生框架

应用场景：
- 设备模拟
- 预测性维护
- 场景分析
- 远程诊断
```

---

## 🔧 资深 IoT 专家必备技巧

### 通信协议深度
```
MQTT 高级：
- QoS 选择策略
- 会话持久化
- 共享订阅（负载均衡）
- MQTT 5.0 新特性（原因码、属性）

CoAP 高级：
- 观察（Observe）模式
- 块传输（Block Transfer）
- 资源发现
- DTLS 安全

低功耗广域网：
- LoRaWAN：长距离、低功耗
- NB-IoT/LTE-M：蜂窝 IoT
- Sigfox：超低功耗
- 选择考量：距离/功耗/带宽/成本
```

### 安全深度
```
设备身份：
- PKI 证书体系
- 设备证书生命周期
- 证书轮换
- 硬件安全模块（HSM/TPM）

安全引导：
- 信任根（Root of Trust）
- 安全启动链
- 固件签名
- 安全升级

端到端安全：
- 设备 → 网关 → 云加密
- 密钥派生
- 会话密钥
- 完美前向保密
```

### 功耗优化深度
```
协议层优化：
- 消息聚合
- 压缩（CBOR vs JSON）
- 连接复用
- 会话恢复

硬件层优化：
- 射频调优
- 天线设计
- 电源管理 IC
- 能量收集

电池建模：
- 电池特性曲线
- 温度影响
- 老化模型
- 剩余寿命预测
```

### 可靠性设计
```
网络容错：
- 存储转发
- 消息队列
- 重传策略
- 离线模式

设备容错：
- 看门狗层次
- 故障检测
- 自动恢复
- 备用路径

数据可靠性：
- 数据校验
- 重传确认
- 幂等处理
- 去重机制
```

---

## 🚨 资深 IoT 专家常见陷阱

### 架构陷阱
```
❌ 所有数据上云：
- 带宽浪费
- 延迟高
- 成本高
- 正确做法：边缘预处理

❌ 忽视网络不稳定：
- 假设网络总是可用
- 无离线支持
- 正确做法：存储转发，离线模式

❌ 安全后补：
- 先实现功能再加安全
- 安全作为附加功能
- 正确做法：安全内置设计
```

### 协议陷阱
```
❌ 错误的 QoS 选择：
- 关键消息用 QoS 0
- 所有消息用 QoS 2
- 正确做法：根据业务选择

❌ 心跳过于频繁：
- 功耗浪费
- 带宽浪费
- 正确做法：根据业务调整周期

❌ 消息过大：
- 单条消息过大
- 无分片机制
- 正确做法：消息拆分，块传输
```

### 运维陷阱
```
❌ OTA 无回滚：
- 更新失败变砖
- 正确做法：A/B 分区，自动回滚

❌ 无设备健康监控：
- 设备离线不知道
- 正确做法：心跳监控，离线告警

❌ 日志过多/过少：
- 功耗浪费或问题难排查
- 正确做法：分级日志，按需上报
```

---

## 📊 性能监控指标

| 指标 | 目标值 | 告警阈值 | 测量方法 |
|------|--------|----------|----------|
| 设备在线率 | > 99% | < 95% | 平台统计 |
| 消息延迟（P99） | < 1s | > 5s | 平台统计 |
| 消息送达率 | > 99.9% | < 99% | 平台统计 |
| 功耗（活动） | 根据设计 | > 预算 | 电流测量 |
| 电池寿命 | 根据设计 | < 80% 预期 | 电量监控 |
| OTA 成功率 | > 99% | < 95% | 平台统计 |
| 配网成功率 | > 95% | < 80% | 日志统计 |
| 设备重启次数 | 0/天 | > 3/天 | 日志统计 |
| 数据质量分数 | > 99% | < 95% | 数据验证 |
| 安全告警 | 0 | > 0 | 安全监控 |

---

## 📋 物联网开发检查清单（完整版）

### 通信可靠
- [ ] 协议选择合理
- [ ] 离线存储转发
- [ ] 消息确认机制
- [ ] 网络自动重连

### 安全完备
- [ ] 设备身份认证
- [ ] 通信加密
- [ ] 安全启动
- [ ] 固件签名

### 功耗优化
- [ ] 睡眠模式合理
- [ ] 通信优化
- [ ] 电池监控
- [ ] 功耗预算达标

### 运维就绪
- [ ] OTA 更新机制
- [ ] 设备监控
- [ ] 日志上报
- [ ] 故障诊断

---

**物联网开发原则总结**：
低功耗、可靠通信、边缘计算、安全认证、OTA更新、设备管理、云端集成、数据质量、监控诊断、环境适应
