1. 新版 OneNet 平台接入架构解析与工程实践

OneNet 平台自 2023 年底完成核心架构升级后，其设备接入模型已发生实质性变化。新平台取消了旧版中广为人知的“多协议接入”配置入口，转而采用以 MQTT 协议为默认承载、以物模型（Thing Model）为数据语义核心的统一接入范式。这一变更并非简单的界面调整，而是反映了物联网平台从“连接管理”向“数据建模与语义互操作”的演进方向。对于嵌入式开发者而言，这意味着配置重心从底层通信参数转向高层数据结构定义，同时对设备端的数据封装格式提出了更严格、更标准化的要求。

在 STM32 + ESP8266 的典型硬件组合中，系统职责被清晰划分：STM32F103 系列 MCU 负责传感器数据采集（如 DHT11 温湿度）、本地逻辑处理及 UART 串口通信；ESP8266 模块则作为独立的网络协处理器，运行 AT 固件，承担 WiFi 连接、MQTT 协议栈、TLS 加密及与 OneNet 云平台的全双工通信任务。这种分离式架构显著降低了主控 MCU 的软件复杂度，使开发者能将精力聚焦于业务逻辑而非网络协议细节。然而，这也要求开发者必须精确理解两个关键边界：一是 STM32 与 ESP8266 之间 UART 通信的数据帧格式与状态机协议；二是 ESP8266 AT 指令集与 OneNet 物模型数据规范之间的映射关系。任何一环的偏差都将导致数据无法上云或云端解析失败。

本实践所依托的固件版本为 ESP8266 AT 固件 v2.2.1.0 ，该版本原生支持 MQTT v3.1.1 协议，并内置了对 OneNet 平台认证机制的适配。值得注意的是，新版 OneNet 不再使用旧版的 API Key 认证方式，而是强制采用基于时间戳与设备密钥（Device Secret）动态生成的 Token 认证。这一设计极大提升了设备接入的安全性，但也要求开发者必须掌握 Token 的生成原理与工程化集成方法，而非简单地将一个静态字符串硬编码到固件中。

2. OneNet 平台侧配置全流程详解

2.1 创建产品与设备

登录新版 OneNet 开发者中心后，首先进入“产品开发”模块。与旧版不同，新平台将“产品”作为一切配置的起点，其本质是一个逻辑容器，用于定义一类具有相同功能和数据结构的设备集合。在创建产品时，“品类”选择至关重要。本例选用“环境感知”下的“温湿度检测”，此选择不仅影响平台提供的默认物模型模板，更决定了后续可选的数据协议与联网方式。完成品类选择后，进入产品基本信息填写环节：

• 产品名称 ：建议使用无空格、无特殊字符的英文标识符（如 TestEnvSensor ），该名称将在代码中作为 product_id 直接引用。
• 所属地域 ：根据设备实际部署位置选择，影响平台节点调度与数据延迟。
• 设备类型 ：必须选择“直连设备”。此选项表明设备将直接通过 MQTT 协议与 OneNet 平台建立连接，而非经由网关代理。这是 STM32+ESP8266 架构的唯一正确选项。
• 协议类型 ：固定为“MQTT”。OneNet 新平台已将 MQTT 设为标准接入协议，其他协议（如 HTTP、CoAP）需通过第三方网关桥接，不适用于本场景。
• 数据协议 ：必须选择“OneJSON”。这是新版 OneNet 专为物模型设计的轻量级 JSON 格式，其结构严格遵循 {"id":"xxx","params":{"key1":value1,"key2":value2}} 的范式，与旧版自由 JSON 格式有本质区别。
• 联网方式 ：选择“WiFi”，与 ESP8266 的物理能力匹配。
• 开发方案 ：选择“指定方案”，表示开发者将自行实现完整的设备端逻辑，而非使用 OneNet 提供的 SDK。

产品创建成功后，系统会生成唯一的 product_id （例如 5Z9X8Y2W1 ）。此 ID 是设备身份认证的核心要素之一，必须完整、准确地复制并用于后续代码配置。切勿将其与设备名称混淆。

完成产品创建后，立即进入“设备管理”模块，点击“添加设备”。此处需填写：
- 设备名称 ：同样建议使用简洁英文（如 MQTT1 ），该名称将成为设备在平台上的唯一标识符 device_name ，并在代码中与 product_id 一同构成设备身份元组。

设备添加成功后，其状态将显示为“未激活”。此时， product_id 与 device_name 已确定，但设备尚不具备接入能力，因为最关键的认证凭据——设备密钥（Device Secret）尚未获取。

2.2 获取设备密钥与生成 Token

设备密钥是 OneNet 平台为每个设备分配的、不可逆的高强度密钥，是生成 Token 的必要输入。它并非在设备创建时即时显示，而是隐藏在设备详情页中。操作路径为：“设备管理” → 找到刚创建的设备（如 MQTT1 ）→ 点击右侧“详情”按钮 → 在弹出的详情面板中，找到并展开“安全认证”区域 → 此处即显示 device_secret 字段的完整值（通常为 32 位十六进制字符串）。

Token 的生成是整个接入流程中最易出错的环节。OneNet 官方提供了离线计算工具 onenet_token_tool_v1.0.exe ，其输入参数严格遵循以下规则：
- resource 字段 ：格式为 products/{product_id}/devices/{device_name} 。例如，若 product_id 为 5Z9X8Y2W1 ， device_name 为 MQTT1 ，则 resource 应为 products/5Z9X8Y2W1/devices/MQTT1 。此字符串是 Token 签名的主体，任何字符错误（包括大小写、斜杠、空格）都将导致签名失效。
- timestamp 字段 ：一个 Unix 时间戳（秒级），代表 Token 的过期时刻。平台要求该时间戳不得早于当前时间，且建议设置为未来 30 天内（如 1735689600 对应 2025-01-01 00:00:00 UTC）。过短的时效会导致设备频繁断连重连；过长则存在安全风险。
- secret 字段 ：即上一步获取的 device_secret ，必须原样填入，不可做任何 Base64 或 Hex 编码。
- method 字段 ：固定选择 MD5 。
- version 字段 ：固定为 2018-10-31 ，这是 OneNet Token 协议的版本标识，硬编码，不可更改。

工具生成的 Token 是一个 URL 安全的 Base64 编码字符串，形如 aBcDeFgHiJkLmNoPqRsTuVwXyZ12345 。此 Token 将被嵌入到 ESP8266 的 MQTT 连接指令中，作为 username 参数传递给 OneNet 服务器。其生命周期由 timestamp 决定，一旦过期，设备将被平台拒绝连接，日志中会显示 AUTH_FAILED 错误。

2.3 构建设备 Topic 与物模型

Topic 是 MQTT 协议中消息路由的核心。OneNet 新平台为每个设备预设了标准化的 Topic 结构，其格式为 $sys/{product_id}/{device_name}/thing/property/post 。此 Topic 是设备向平台“上报属性”的唯一合法通道。任何对 Topic 的拼写错误（如遗漏 $sys 前缀、大小写错误、斜杠缺失）都将导致消息被平台静默丢弃，且不会返回任何错误响应，调试难度极高。

物模型（Thing Model）是新版 OneNet 的数据语义层，它定义了设备可以“说”什么。在“产品开发” → “TestEnvSensor” → “物模型”页面中，需要手动添加三个自定义功能点：

功能名称	标识符（Identifier）	功能类型	数据类型	取值范围	步长	单位
温度	temperature	属性	Double	0 ~ 100	0.1	℃
湿度	humidity	属性	Double	0 ~ 100	0.1	%RH
光照强度	illuminance	属性	Int32	0 ~ 100	1	lux

关键要点解析 ：
- 标识符（Identifier） ：这是物模型的“身份证”，必须与设备端代码中用于构建 OneJSON 数据体的键名（key）完全一致，包括大小写和下划线。例如，若代码中写 params.temperature = 25.6; ，则此处 Identifier 必须为 temperature ，而非 temp 或 TEMPERATURE 。
- 数据类型与步长 ： Double 类型配合 0.1 步长，确保小数点后一位能被平台正确解析和显示。若步长设为 1 ，平台将自动截断小数部分，导致精度丢失。 Int32 类型的光照值无需小数，步长为 1 即可。
- 取值范围 ：这是一个强约束。平台会校验所有上报值是否在此区间内。若 DHT11 读取到 105.0℃ （理论上不可能，但传感器异常或代码 bug 可能导致），且范围上限设为 100 ，则该温度值将被平台丢弃，不会出现在任何图表或历史数据中。因此，范围设定应留有合理余量，但不宜过大，以免掩盖真实异常。

完成物模型配置后，务必点击“发布”按钮。未发布的物模型仅存在于草稿状态，设备上报的数据将因无对应定义而被平台忽略。

3. ESP8266 AT 固件配置与通信协议深度剖析

3.1 AT 指令序列与初始化流程

ESP8266 的 AT 固件启动后，需执行一套严格的五步初始化序列才能建立与 OneNet 的稳定 MQTT 连接。该序列不是简单的命令堆砌，而是一个状态依赖的有限状态机。 esp8266_init() 函数的实现必须严格遵循此顺序，任何跳步或顺序颠倒都将导致连接失败。

第一步：AT 复位与回显确认

AT\r\n          // 发送复位指令
OK\r\n          // 期望响应

此步验证串口物理连接与固件基本功能。若无 OK 响应，需检查波特率（本例为 115200 ）、接线（TX/RX 是否交叉）及供电。

第二步：WiFi 连接

AT+CWJAP="MyWiFiSSID","MyWiFiPassword"\r\n
WIFI CONNECTED\r\n
WIFI GOT IP\r\n
OK\r\n

AT+CWJAP 指令要求 SSID 和密码均为双引号包围的字符串。响应中的 WIFI GOT IP 表明 DHCP 成功获取 IP 地址，这是后续网络通信的前提。若卡在此步，首要排查 WiFi 密码错误、信号强度不足或路由器 MAC 地址过滤。

第三步：MQTT 客户端创建

AT+MQTTCLIENTID="OneNetClient1"\r\n
OK\r\n

client_id 是 MQTT 协议中的客户端唯一标识，可自定义，但需保证在同一网络内全局唯一。OneNet 平台对此字段无特定要求，但建议包含产品或设备标识以便于日志追踪。

第四步：MQTT 连接参数配置

AT+MQTTCONN="183.230.40.39",6002,60,"{product_id}","{device_name}","{token}","{product_id}/{device_name}"

此指令是整个流程的核心，其参数含义如下：
- 183.230.40.39 ：OneNet MQTT 服务的公网 IP 地址（华东节点），端口 6002 为 TLS 加密端口。必须使用此 IP，而非域名 mqtt.heclouds.com ，因 AT 固件 DNS 解析能力有限且不稳定。
- 60 ：MQTT KeepAlive 时间（秒），平台要求最小值为 60 ，过小会增加心跳开销，过大则平台可能因超时而主动断连。
- {product_id} 与 {device_name} ：构成 username ，格式为 products/{product_id}/devices/{device_name} 。注意 products/ 和 /devices/ 前缀必须存在。
- {token} ：上一步生成的完整 Token 字符串，作为 password 。
- {product_id}/{device_name} ： client_id 的别名，用于平台内部路由，必须与第三步的 client_id 一致。

第五步：MQTT 连接建立

AT+MQTTCONNECT\r\n
CONNECT OK\r\n

AT+MQTTCONNECT 指令触发实际的 TCP 握手与 MQTT 协议协商。 CONNECT OK 响应标志着 TLS 加密隧道已建立，MQTT 会话已激活。若此步失败，90% 的原因是第四步的 username / password 格式错误或 Token 过期，需逐字符核对。

3.2 OneJSON 数据封装与 MQTT PUB 指令

设备数据上报通过 AT+MQTTPUB 指令完成，其语法为：

AT+MQTTPUB=0,"$sys/{product_id}/{device_name}/thing/property/post","{onejson_payload}",1,0

其中：
- 0 ：MQTT QoS 等级， 0 表示“最多一次”，符合传感器数据上报的场景（允许少量丢失，追求低延迟）。
- "$sys/..." ：目标 Topic，必须与物模型配置完全一致。
- {onejson_payload} ：待上报的 OneJSON 格式数据体，这是与物模型交互的唯一载体。
- 1,0 ： retain=1 （保留消息）和 dup=0 （非重复消息）标志。

OneJSON 数据体的构造是成败关键。其结构必须严格遵循 OneNet 规范：

{
  "id": "123456789",
  "params": {
    "temperature": 25.6,
    "humidity": 60.5,
    "illuminance": 45
  }
}

• id 字段：一个任意的、不重复的字符串（如毫秒级时间戳 1700000000123 ），用于平台端消息去重与追踪。在嵌入式环境中，可直接使用 HAL_GetTick() 获取。
• params 字段：一个 JSON 对象，其键（key）必须与物模型中定义的“标识符”（Identifier）完全一致。值（value）的类型必须与物模型中定义的“数据类型”匹配： temperature 和 humidity 为 double ， illuminance 为 int32 。

在 C 语言中， esp8266_send_data() 函数通过 sprintf() 进行字符串拼接：

char payload[256];
sprintf(payload, 
  "{\"id\":\"%lu\",\"params\":{\"temperature\":%.1f,\"humidity\":%.1f,\"illuminance\":%d}}", 
  HAL_GetTick(), temp_val, humi_val, illum_val);

此处 %.1f 确保浮点数只保留一位小数，与物模型的 0.1 步长匹配； %d 用于整型光照值。任何格式化错误（如对 double 使用 %d ）都会导致 JSON 语法错误，平台将返回 JSON_PARSE_ERROR 。

4. STM32 端数据采集与任务协同设计

4.1 DHT11 驱动与数据校验

DHT11 是一款成本低廉、应用广泛的单总线数字温湿度传感器。其通信协议对时序极为敏感，要求 MCU 的 GPIO 引脚能在微秒级精度上进行电平翻转。在 STM32F103 上，推荐使用 GPIO 寄存器直接操作，而非 HAL 库的 HAL_GPIO_WritePin ，以规避函数调用开销带来的时序抖动。

DHT11 的数据帧由 40 位组成：16 位湿度整数 + 16 位温度整数 + 8 位校验和。校验和为前 4 字节之和的低 8 位。 必须进行校验 ，否则传感器在高温高湿环境下极易产生 0x0000 或 0xFFFF 的错误数据，直接污染云端数据。校验代码片段如下：

uint8_t dht11_check_sum(uint8_t *data) {
  uint8_t sum = data[0] + data[1] + data[2] + data[3];
  return (sum == data[4]);
}

若校验失败，应丢弃本次数据，并在下次采集周期重试。连续多次失败后，可判定传感器故障或线路接触不良。

4.2 FreeRTOS 任务划分与资源同步

在 STM32 上运行 FreeRTOS 可显著提升系统健壮性。本项目设计两个核心任务：
- sensor_task ：优先级 osPriorityNormal ，负责周期性（如每 2 秒）读取 DHT11 和 ADC（光照）数据，并将结果存入全局结构体 sensor_data_t 中。该任务使用 HAL_Delay(2000) 实现阻塞延时。
- uart_task ：优先级 osPriorityAboveNormal ，负责与 ESP8266 的 UART 通信。它通过 xQueueReceive() 从一个队列中获取 sensor_data_t 数据包，然后调用 esp8266_send_data() 将其发送至 ESP8266。

两个任务间的共享数据 sensor_data_t 必须通过互斥量（Mutex）保护：

osMutexId_t sensor_mutex;
sensor_mutex = osMutexNew(NULL);
// 在 sensor_task 中：
osMutexAcquire(sensor_mutex, portMAX_DELAY);
sensor_data.temperature = temp;
sensor_data.humidity = humi;
sensor_data.illuminance = illum;
osMutexRelease(sensor_mutex);

// 在 uart_task 中：
osMutexAcquire(sensor_mutex, portMAX_DELAY);
memcpy(&local_data, &sensor_data, sizeof(sensor_data_t));
osMutexRelease(sensor_mutex);
esp8266_send_data(&local_data);

若省略互斥量，当 sensor_task 正在更新结构体而 uart_task 同时读取时，可能导致读取到温度为 25 、湿度为 0 的“半成品”数据，最终上报一个无效的 JSON。

4.3 UART 通信的可靠性保障

STM32 与 ESP8266 的 UART 通信是整个系统的脆弱点。为应对噪声、丢包等常见问题，必须引入软件层面的可靠性机制：
- 指令超时重试 ：对每一个 AT 指令（如 AT+MQTTCONNECT ），设置一个最大等待时间（如 5000ms）。若在此时间内未收到预期响应（如 CONNECT OK ），则认为指令失败，进行重试（最多 3 次），失败后复位 ESP8266。
- 响应缓冲区管理 ：ESP8266 的响应可能分片到达（尤其在长 Token 或大 JSON 时）。UART 接收中断服务程序（ISR）必须将所有接收到的字节缓存到一个环形缓冲区（Ring Buffer）中，主循环再从中解析完整响应行（以 \r\n 结尾）。
- 心跳保活 ：在 MQTT 连接建立后， uart_task 应定期（如每 30 秒）发送 AT+MQTTPING 指令，维持 TCP 连接活性。若 PING 失败，则主动执行 AT+MQTTDISCONNECT 并重启连接流程。

5. 调试技巧与典型故障排除

5.1 串口日志分析法

最有效的调试手段是全程监听 STM32 的 UART1（连接 PC）和 UART2（连接 ESP8266）的双向通信。使用 PuTTY 或 SecureCRT 打开两个串口窗口，将 STM32 的 printf 输出重定向至 UART1，即可看到完整的指令流与响应流。一个成功的连接日志片段如下：

[STM32] -> AT+CWJAP="MyWiFi","12345678"
[ESP8266] <- WIFI CONNECTED
[ESP8266] <- WIFI GOT IP
[STM32] -> AT+MQTTCONN="183.230.40.39",6002,60,"products/5Z9X8Y2W1/devices/MQTT1","aBcDeFgHiJkLmNoPqRsTuVwXyZ12345","5Z9X8Y2W1/MQTT1"
[ESP8266] <- CONNECT OK
[STM32] -> AT+MQTTPUB=0,"$sys/5Z9X8Y2W1/MQTT1/thing/property/post","{\"id\":\"1700000000123\",\"params\":{\"temperature\":25.6,\"humidity\":60.5,\"illuminance\":45}}",1,0
[ESP8266] <- PUB OK

若日志中出现 ERROR 、 FAIL 或长时间无响应，即可精确定位故障点。

5.2 典型故障场景与根因

• 现象：ESP8266 卡在 AT+CWJAP 步骤，返回 ERROR
• 根因 ：WiFi 密码中包含特殊字符（如 & , # , $ ），未被 AT 固件正确解析。

• 解法 ：将密码改为纯字母数字组合，或查阅 ESP8266 AT 指令手册，确认特殊字符的转义规则。

• 现象： AT+MQTTCONN 返回 CONNECT FAIL

• 根因 ： username 格式错误（遗漏 products/ 或 /devices/ 前缀）、 password （Token）过期、或 client_id 与 AT+MQTTCLIENTID 不一致。

• 解法 ：在 PC 上用 curl 模拟连接，验证 username / password 组合的有效性。

• 现象：设备在 OneNet 平台显示“在线”，但属性数据不更新

• 根因 ： AT+MQTTPUB 指令中的 Topic 错误（如 $sys 写成 $SYS ），或 OneJSON 中的 params 键名与物模型标识符不匹配。

• 解法 ：在平台“设备管理” → “MQTT1” → “调试”中，开启“消息跟踪”，查看平台是否收到了 PUB 消息。若收到但未解析，则必为 JSON 键名或格式错误。

• 现象：云端数据显示为 0 或 null

• 根因 ：DHT11 数据未校验，上报了 0x0000 ；或 sprintf 格式化错误，导致 JSON 语法破坏。
• 解法 ：在 esp8266_send_data() 函数中， printf 输出最终的 payload 字符串，肉眼检查其 JSON 合法性。

我在实际项目中曾遇到一个隐蔽的坑：ESP8266 的 AT+MQTTPUB 指令对 payload 长度有隐式限制（约 512 字节）。当 OneJSON 数据体过大（如加入大量注释或冗余字段）时，指令会静默失败。解决方法是严格控制 payload 长度，并在 sprintf 后添加 strlen(payload) < 500 的断言。

6. 工程化实践与代码组织规范

6.1 配置信息的集中化管理

所有与 OneNet 平台相关的硬编码字符串（WiFi 名称/密码、 product_id 、 device_name 、 token 、服务器 IP）必须从源文件中剥离，统一放置在 onenet_config.h 头文件中：

#ifndef ONENET_CONFIG_H
#define ONENET_CONFIG_H

#define WIFI_SSID "MyWiFiSSID"
#define WIFI_PASSWORD "MyWiFiPassword"

#define ONENET_SERVER_IP "183.230.40.39"
#define ONENET_SERVER_PORT 6002

#define ONENET_PRODUCT_ID "5Z9X8Y2W1"
#define ONENET_DEVICE_NAME "MQTT1"
#define ONENET_TOKEN "aBcDeFgHiJkLmNoPqRsTuVwXyZ12345"

#endif /* ONENET_CONFIG_H */

这种设计带来三大好处：一是便于不同环境（开发/测试/生产）的快速切换；二是避免在多个 .c 文件中重复修改同一参数；三是为未来迁移到 Kconfig 或 menuconfig 系统预留接口。

6.2 AT 指令的模块化封装

esp8266.c 文件不应是一堆 HAL_UART_Transmit 的简单堆砌，而应封装为清晰的、面向对象的 API：
- esp8266_at_cmd(const char* cmd, const char* expected_response, uint32_t timeout_ms) ：通用 AT 指令发送与响应等待。
- esp8266_mqtt_connect(void) ：封装第四、五步，内部调用 esp8266_at_cmd 。
- esp8266_mqtt_publish(const sensor_data_t* data) ：封装 AT+MQTTPUB ，负责 OneJSON 构造与发送。

每个函数都应有明确的返回值（ ESP_OK / ESP_FAIL ）和错误码，便于上层任务进行错误处理与恢复。

6.3 安全与可维护性考量

• Token 安全 ：虽然本例将 Token 硬编码在 Flash 中，但在商业产品中，必须将其存储在 ESP8266 的 flash 分区或外部 EEPROM 中，并在每次启动时动态加载。绝不可将其明文暴露在代码仓库中。
• OTA 升级 ：为支持固件远程升级，应在 STM32 端预留一个 bootloader 区域，并设计一个简单的升级协议（如通过 UART 接收新固件 bin 文件，校验 CRC 后写入 Application 区）。
• 功耗优化 ：在电池供电场景下， sensor_task 可在数据采集后，调用 HAL_PWR_EnterSTOPMode(PWR_LOWPOWERREGULATOR_ON, PWR_STOPENTRY_WFI) 进入 STOP 模式，由 RTC 告警唤醒，可将平均功耗降至微安级。

当你的 main() 函数里不再充斥着裸露的 AT+XXX 字符串，而是干净地调用 esp8266_mqtt_connect() 和 esp8266_mqtt_publish(&data) 时，你就已经完成了从“能用”到“好用”的跨越。这不仅是代码风格的提升，更是工程思维成熟的标志。