1. STM32F103 + AIR780E 实现 MQTT 数据上云至 OneNet 平台的工程实践

在工业现场监测、环境数据采集、远程设备管理等嵌入式物联网场景中，将传感器数据稳定、可靠地上传至云端平台是基础且关键的一环。OneNet 作为中国移动推出的开放物联网平台，凭借其低门槛接入、高稳定性服务和丰富的可视化能力，在中小规模嵌入式项目中被广泛采用。本实践以 STM32F103C8T6（主流 Cortex-M3 内核 MCU）为核心控制器，搭配 AIR780E 四模全网通 LTE Cat.1 模块，构建一条从硬件初始化、网络连接、协议栈交互到数据上云的完整链路。整个方案不依赖任何高级操作系统，仅基于 HAL 库与裸机 AT 指令驱动，强调可复现性、可调试性与工程鲁棒性。

AIR780E 是一款高度集成的 LTE Cat.1 通信模块，内置 TCP/IP 协议栈、SSL/TLS 加密引擎及完整的 AT 指令集，支持 MQTT v3.1.1 协议原生指令。其优势在于：无需在 MCU 端移植复杂的 MQTT 客户端库，所有连接管理、心跳维持、报文编码/解码均由模块内部固件完成；MCU 仅需通过 UART 发送标准化 AT 指令并解析响应即可，极大降低了主控侧的软件复杂度与内存占用。这种“MCU + 通信模组”的分层架构，是当前资源受限型嵌入式终端的主流设计范式。

本文所描述的实现，并非一次性的演示脚本，而是一个经过真实项目验证、具备生产级可用性的最小可行系统（MVP）。它覆盖了从物理层串口配置、模块供电时序控制、AT 指令状态机设计、MQTT 连接三要素安全注入，到最终 JSON 格式数据包构造与发送的全部核心环节。每一个参数的设定、每一行代码的逻辑，都源于对芯片手册、模块 AT 指令集文档及 OneNet 平台 API 规范的严格对照与反复验证。

1.1 硬件连接与电源管理要点

STM32F103 与 AIR780E 的硬件互连看似简单，实则暗藏多个影响系统稳定性的关键细节。首要问题是电平匹配与电流供给。

AIR780E 的 UART 接口为 3.3V TTL 电平，与 STM32F103 的 GPIO 电平完全兼容，可直接连接。但需注意：AIR780E 的 VDD_IO 引脚必须稳定供应 3.3V ±5%，且该引脚同时为 UART 收发器供电。若使用 MCU 的 3.3V 电源轨直接驱动，极易因模块突发大电流（如射频发射瞬间峰值可达 500mA）导致电压跌落，引发 MCU 复位或 UART 通信中断。因此， 强烈建议为 AIR780E 配置独立的 LDO 电源 ，例如 AMS1117-3.3 或 RT9013-33，输入端接入 4.2~5.5V 电池或稳压源，并在 VDD_IO 引脚就近放置 10μF 钽电容与 100nF 陶瓷电容构成复合去耦网络。

其次，模块的启动与复位时序必须被 MCU 精确掌控。AIR780E 不支持上电即自动运行，必须通过 PWRKEY 引脚触发。PWRKEY 为低电平有效，要求持续拉低不少于 1.5 秒后释放，模块才进入正常工作状态。此操作不可由硬件上拉/下拉电阻替代，必须由 MCU 的 GPIO 软件控制。我们选用 GPIOA_Pin0 作为 PWRKEY 控制引脚，其初始化流程如下：

// 初始化 PWRKEY 引脚为推挽输出，初始状态为高电平（模块断电）
__HAL_RCC_GPIOA_CLK_ENABLE();
GPIO_InitTypeDef GPIO_InitStruct = {0};
GPIO_InitStruct.Pin = GPIO_PIN_0;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET); // 初始高电平，模块断电

// 延迟 100ms，确保模块完全掉电
HAL_Delay(100);

// 拉低 PWRKEY 1.8 秒，触发模块启动
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
HAL_Delay(1800);

// 释放 PWRKEY，模块开始启动自检
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);

此外，模块的 STATUS 引脚（开漏输出）可用于 MCU 监测模块运行状态。当模块处于开机自检或运行中时，STATUS 为低电平；当模块关机或异常时，STATUS 为高电平（需外接上拉电阻）。在实际项目中，可在主循环中轮询该引脚，作为模块健康状态的快速判断依据，避免在模块未就绪时盲目发送 AT 指令。

1.2 UART 驱动与 AT 指令状态机设计

STM32F103 与 AIR780E 的通信通道是 USART1，配置为 115200bps、8-N-1、无硬件流控。此波特率是 AIR780E 出厂默认值，也是其最稳定的工作速率。在 MX_USART1_UART_Init() 中，关键配置项如下：

huart1.Instance = USART1;
huart1.Init.BaudRate = 115200;          // 必须匹配模块默认波特率
huart1.Init.WordLength = UART_WORDLENGTH_8B;
huart1.Init.StopBits = UART_STOPBITS_1;
huart1.Init.Parity = UART_PARITY_NONE;
huart1.Init.Mode = UART_MODE_TX_RX;
huart1.Init.HwFlowCtl = UART_HWCONTROL_NONE; // 禁用 RTS/CTS，模块不支持
huart1.Init.OverSampling = UART_OVERSAMPLING_16;

UART 的底层驱动质量，直接决定了 AT 指令交互的可靠性。HAL 库提供的 HAL_UART_Transmit 和 HAL_UART_Receive 是阻塞式 API，在实时性要求不高的 AT 指令交互中可以接受。但更优的方案是启用 DMA 接收与空闲中断（IDLE Interrupt），以实现非阻塞、零丢包的数据接收。AIR780E 的 AT 响应通常以 \r\nOK\r\n 或 \r\nERROR\r\n 结尾，DMA 接收配合 IDLE 中断，可精准捕获一整条响应的结束，避免因固定长度接收导致的截断或等待超时。

一个健壮的 AT 指令状态机，至少应包含以下状态：
- AT_STATE_IDLE : 等待发送下一条指令。
- AT_STATE_SENDING : 指令已发出，启动响应超时定时器（例如 2000ms）。
- AT_STATE_RECEIVING : 正在接收响应数据，等待 IDLE 中断触发。
- AT_STATE_PROCESSING : 响应数据已接收完毕，进行字符串匹配（如查找 “OK”、”ERROR”、”+MQTTCONN: 0”）。
- AT_STATE_ERROR : 响应超时或匹配失败，执行重试逻辑（最多 3 次）。

状态机的核心在于超时处理。所有 AT 指令都必须有明确的超时约束。例如， AT+CGATT? （查询 GPRS 附着状态）的典型响应时间在 100ms 内，而 AT+MQTTCONN （建立 MQTT 连接）因涉及 DNS 解析、TCP 握手、TLS 握手（若启用），可能耗时数秒。因此，状态机必须为不同指令配置差异化的超时阈值，并在超时后主动发送 ATH （挂断）或 AT+MQTTCLEAN （清理 MQTT 会话）指令，将模块恢复至已知的干净状态，防止指令积压或状态错乱。

1.3 网络初始化：从 SIM 卡识别到 GPRS 附着

在发起 MQTT 连接前，AIR780E 必须成功注册到蜂窝网络并获得 IP 地址。这一过程并非一蹴而就，而是由一系列相互依赖的 AT 指令构成的线性流程。

第一步是确认模块基本功能与 SIM 卡状态。发送 AT 指令，期望返回 OK ，这是最基本的“心跳”测试。随后， AT+CPIN? 用于查询 SIM 卡 PIN 码状态。若返回 +CPIN: READY ，表明 SIM 卡已就绪；若返回 +CPIN: SIM PIN ，则需先发送 AT+CPIN="1234" （假设 PIN 码为 1234）进行解锁。这一步至关重要，许多现场问题的根源就是 SIM 卡被锁死而未被程序检测到。

第二步是网络注册查询。 AT+CREG? 返回 +CREG: 0,1 表示模块已注册到本地网络（ n=0 表示不报告网络注册事件， stat=1 表示已注册）。若 stat=0 （未注册）或 stat=2 （搜索中），则需耐心等待并重试，此时不应急于进行下一步。

第三步是 GPRS 附着。 AT+CGATT? 查询附着状态，期望返回 +CGATT: 1 。若为 +CGATT: 0 ，则需发送 AT+CGATT=1 发起附着请求。附着过程依赖于 APN（接入点名称）的正确配置。对于中国移动的物联网卡，标准 APN 为 CMNET 或 CMIoT 。通过 AT+CSTT="CMNET" 指令设置 APN，再执行 AT+CIICR 激活无线上下文，最后 AT+CIFSR 查询分配到的 IP 地址。一个典型的成功序列如下：

AT+CSTT="CMNET"
OK
AT+CIICR
OK
AT+CIFSR
10.123.45.67

若 AT+CIICR 返回 ERROR ，常见原因有：SIM 卡欠费、APN 配置错误、模块天线接触不良或信号极弱。此时，程序应记录错误码并进入降级模式（如尝试备用 APN 或延长重试间隔），而非无限循环重试。

1.4 MQTT 连接三要素：ProductID、AuthInfo 与 SubID 的获取与注入

OneNet 平台的 MQTT 接入采用基于 Topic 的权限模型，其连接凭证并非传统意义上的用户名/密码，而是三个由平台动态生成的、具有强时效性与唯一性的字符串： ProductID 、 AuthInfo 和 SubID 。它们共同构成了客户端的“数字身份”，缺一不可。

ProductID 是 OneNet 平台上创建产品时系统分配的全局唯一标识符，格式为一串 16 进制字符，例如 6543210987abcdef 。它在产品的整个生命周期内保持不变，是所有设备上报数据的公共前缀。

AuthInfo 是设备的认证信息，本质是一个 Base64 编码的签名字符串。它的生成逻辑是：将 ProductID 、设备 IMEI （或用户自定义的 DeviceID ）、当前时间戳（精确到秒）以及一个平台颁发的 SecretKey ，按特定顺序拼接后，使用 HMAC-SHA1 算法进行签名，再将结果进行 Base64 编码。OneNet 提供了在线的 AuthInfo 生成工具，开发者只需输入 ProductID、DeviceID 和 SecretKey，即可一键生成。 切记，SecretKey 是最高机密，绝不能硬编码在固件中，而应通过安全的产线烧录流程注入。

SubID （订阅 ID）则是设备在产品内的唯一实例标识，通常直接采用设备自身的 IMEI 号（15 位数字），例如 861234567890123 。它用于在 Topic 中精确定位某一台设备。

这三个字符串必须以特定的 AT 指令格式注入 AIR780E 模块：
- AT+MQTTCLIENTID="ProductID|SubID" ：设置 MQTT 客户端 ID。注意中间的竖线 | 是分隔符，不可省略。
- AT+MQTTUSERNAME="ProductID" ：设置用户名，即 ProductID。
- AT+MQTTPASSWORD="AuthInfo" ：设置密码，即生成的 AuthInfo 字符串。

这些指令的执行顺序没有强制要求，但必须在 AT+MQTTCONN 之前全部完成。指令中的字符串必须用双引号包围，且内部不能包含未转义的双引号或换行符。在 C 语言代码中，由于字符串字面量本身就需要双引号，因此需使用反斜杠进行转义：

// 构造并发送客户端 ID 设置指令
char cmd[128];
snprintf(cmd, sizeof(cmd), "AT+MQTTCLIENTID=\"%s|%s\"\r\n", PRODUCT_ID, SUB_ID);
AT_SendCommand(&huart1, cmd, "OK");

// 构造并发送用户名设置指令
snprintf(cmd, sizeof(cmd), "AT+MQTTUSERNAME=\"%s\"\r\n", PRODUCT_ID);
AT_SendCommand(&huart1, cmd, "OK");

// 构造并发送密码设置指令
snprintf(cmd, sizeof(cmd), "AT+MQTTPASSWORD=\"%s\"\r\n", AUTH_INFO);
AT_SendCommand(&huart1, cmd, "OK");

1.5 MQTT 连接、订阅与数据发布全流程

完成网络与凭证配置后，即可发起最终的 MQTT 连接。 AT+MQTTCONN 指令的完整语法为：
AT+MQTTCONN="server_address","port","keepalive_time","clean_session"

其中：
- server_address 是 OneNet 的 MQTT 服务器地址，标准为 mqtt.heclouds.com 。
- port 是端口号，非加密连接用 1883 ，加密连接（推荐）用 6002 。
- keepalive_time 是心跳间隔（秒），建议设为 120 （2 分钟），过短会增加网络负担，过长则无法及时发现连接中断。
- clean_session 设为 1 ，表示每次连接都创建一个全新的会话，不保留历史消息。

发送该指令后，模块将执行完整的 MQTT 连接握手。成功响应为 +MQTTCONN: 0 ，其中 0 表示连接成功。若返回 +MQTTCONN: 1 ，则表示连接失败，常见原因包括：DNS 解析失败（检查网络是否已附着）、TCP 连接被拒绝（检查防火墙或服务器地址/端口）、TLS 握手失败（若使用 6002 端口，需确认模块固件支持且证书有效）或认证失败（检查 ProductID、AuthInfo 是否准确）。

连接成功后，必须进行 Topic 订阅，才能接收来自平台的指令（如设备控制命令）。OneNet 的标准下行 Topic 格式为：
$sys/{product_id}/{sub_id}/cmd/request/+

其中 {product_id} 和 {sub_id} 需替换为实际值。例如：
$sys/6543210987abcdef/861234567890123/cmd/request/+

订阅指令为 AT+MQTTSUBSCRIBE="topic",qos ，其中 qos （服务质量等级）设为 0 即可，满足大多数遥测场景需求。

最后，是核心的数据发布环节。OneNet 要求上行数据必须遵循其定义的 JSON Schema。一个标准的温度数据上报报文如下：

{
  "datastreams": [
    {
      "id": "temperature",
      "datapoints": [
        {
          "at": "2023-10-05T14:30:00Z",
          "value": 25.5
        }
      ]
    }
  ]
}

在 AT 指令中，该 JSON 字符串需作为 AT+MQTTPUBLISH 指令的 payload 参数。由于 JSON 中大量使用双引号，而 AT 指令本身也以双引号界定字符串，因此必须对 payload 内部的所有双引号进行转义。AIR780E 的 AT 指令规范要求使用 \" 来表示一个字面量的双引号。因此，上述 JSON 在 C 代码中应被构造为：

char payload[256];
snprintf(payload, sizeof(payload),
         "{\"datastreams\":[{\"id\":\"temperature\",\"datapoints\":[{\"at\":\"%s\",\"value\":%.1f}]}]}",
         get_iso8601_timestamp(), temperature_value);

然后，通过 AT+MQTTPUBLISH 指令将其发布到指定 Topic：
AT+MQTTPUBLISH="/{product_id}/{sub_id}/things/properties/post",payload_length,payload

其中 /6543210987abcdef/861234567890123/things/properties/post 是 OneNet 的标准上行 Topic。 payload_length 是 payload 字符串的实际长度（不包括末尾的 \0 ）， payload 即为上面构造好的 JSON 字符串。

模块收到该指令后，会返回 +MQTTPUBLISH: 0 表示发布成功，或 +MQTTPUBLISH: 1 表示失败。发布失败的常见原因有：网络临时中断、MQTT 连接已断开、Topic 权限不足或 JSON 格式错误。程序应对此类错误进行计数，并在连续失败达到阈值（如 5 次）时，主动执行 AT+MQTTCLEAN 清理会话，然后重新执行 AT+MQTTCONN 流程，实现故障自恢复。

2. 代码结构解析与关键函数实现

一个清晰、可维护的嵌入式项目，其代码组织必须反映硬件抽象层（HAL）、通信协议层（AT Command Layer）与应用业务层（Application Layer）的分离。本实践的代码结构严格遵循此原则，便于后续功能扩展与团队协作。

2.1 AT 指令封装层： at_command.c/h

该层是整个系统的“胶水”，负责将高层的语义化操作（如“连接 MQTT”、“发布数据”）翻译为底层的 UART 字节流，并处理响应。其核心函数是 AT_SendCommand ，它实现了前述的状态机逻辑：

// at_command.h
typedef enum {
    AT_OK,
    AT_ERROR,
    AT_TIMEOUT,
    AT_UNKNOWN
} AT_StatusTypeDef;

AT_StatusTypeDef AT_SendCommand(UART_HandleTypeDef *huart, const char *cmd, const char *expected_response);

// at_command.c
AT_StatusTypeDef AT_SendCommand(UART_HandleTypeDef *huart, const char *cmd, const char *expected_response) {
    uint8_t rx_buffer[256];
    uint16_t rx_len = 0;
    uint32_t start_tick = HAL_GetTick();

    // 1. 发送指令
    HAL_UART_Transmit(huart, (uint8_t*)cmd, strlen(cmd), 1000);

    // 2. 循环接收，直到超时或收到预期响应
    while ((HAL_GetTick() - start_tick) < AT_TIMEOUT_MS) {
        if (HAL_UART_Receive(huart, &rx_buffer[rx_len], 1, 10) == HAL_OK) {
            if (rx_buffer[rx_len] == '\n' || rx_buffer[rx_len] == '\r') {
                // 遇到行结束符，尝试匹配预期响应
                rx_buffer[rx_len + 1] = '\0';
                if (strstr((char*)rx_buffer, expected_response) != NULL) {
                    return AT_OK;
                }
                // 清空缓冲区，准备接收下一行
                rx_len = 0;
                continue;
            }
            rx_len++;
            if (rx_len >= sizeof(rx_buffer) - 1) {
                rx_len = 0; // 缓冲区溢出，重置
            }
        }
    }
    return AT_TIMEOUT;
}

此函数虽为简化版，但已具备生产环境所需的核心能力：超时保护、响应匹配、缓冲区管理。在实际项目中，可进一步增强为支持正则表达式匹配、多关键字响应、以及详细的错误日志记录。

2.2 MQTT 应用层： mqtt_app.c/h

该层封装了与 OneNet 业务强相关的逻辑，是开发者最常修改的部分。其接口设计力求简洁、语义清晰：

// mqtt_app.h
typedef struct {
    char product_id[33];   // 32 chars + '\0'
    char sub_id[16];       // 15-digit IMEI + '\0'
    char auth_info[129];   // Base64 encoded, max 128 chars
} MQTT_CredentialsTypeDef;

extern MQTT_CredentialsTypeDef g_mqtt_creds;

void MQTT_Init(const MQTT_CredentialsTypeDef *creds);
AT_StatusTypeDef MQTT_Connect(void);
AT_StatusTypeDef MQTT_Subscribe(void);
AT_StatusTypeDef MQTT_Publish_Float(const char *stream_id, float value);

MQTT_Init 函数负责加载凭证并调用底层 AT 指令设置 ClientID、Username、Password。 MQTT_Connect 则封装了 AT+MQTTCONN 的调用与状态检查。最关键的 MQTT_Publish_Float 函数，完成了 JSON 构造、字符串转义与指令发送的全过程：

// mqtt_app.c
AT_StatusTypeDef MQTT_Publish_Float(const char *stream_id, float value) {
    char topic[128];
    char payload[256];
    char cmd[512];

    // 构造 Topic: /{product_id}/{sub_id}/things/properties/post
    snprintf(topic, sizeof(topic), "/%s/%s/things/properties/post", 
             g_mqtt_creds.product_id, g_mqtt_creds.sub_id);

    // 构造 JSON Payload，注意对双引号的转义
    snprintf(payload, sizeof(payload),
             "{\"datastreams\":[{\"id\":\"%s\",\"datapoints\":[{\"at\":\"%s\",\"value\":%.1f}]}]}",
             stream_id, get_iso8601_timestamp(), value);

    // 构造完整的 AT+MQTTPUBLISH 指令
    snprintf(cmd, sizeof(cmd), "AT+MQTTPUBLISH=\"%s\",%d,%s\r\n", 
             topic, strlen(payload), payload);

    return AT_SendCommand(&huart1, cmd, "+MQTTPUBLISH: 0");
}

此函数的设计体现了“关注点分离”：它不关心 UART 如何发送，也不关心时间戳如何生成，只专注于业务逻辑——将一个浮点数值，按照 OneNet 的规范，打包并发送出去。这种设计使得单元测试变得极为简单：只需 Mock AT_SendCommand 函数，即可对整个发布逻辑进行完备的验证。

2.3 主应用逻辑： main.c 中的控制流

main.c 是整个系统的“导演”，它协调各个模块，定义了从设备上电到数据上云的完整生命周期。其主循环结构如下：

int main(void) {
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART1_UART_Init();

    // 1. 硬件初始化：拉低 PWRKEY 启动 AIR780E
    AIR780E_PowerOn();

    // 2. 等待模块启动完成（可通过 STATUS 引脚或固定延时）
    HAL_Delay(5000);

    // 3. 初始化 AT 指令层，并进行基础测试
    if (AT_SendCommand(&huart1, "AT\r\n", "OK") != AT_OK) {
        Error_Handler(); // 模块未响应
    }

    // 4. 执行网络初始化流程
    if (!Network_Init()) {
        Error_Handler(); // 网络初始化失败
    }

    // 5. 初始化 MQTT 凭证并连接
    MQTT_Init(&g_mqtt_creds);
    if (MQTT_Connect() != AT_OK) {
        Error_Handler();
    }

    // 6. 订阅下行 Topic
    if (MQTT_Subscribe() != AT_OK) {
        Error_Handler();
    }

    // 7. 主应用循环：读取传感器、发布数据
    while (1) {
        float temp = Read_Temperature_Sensor(); // 伪代码，代表你的 ADC 读取
        if (MQTT_Publish_Float("temperature", temp) == AT_OK) {
            HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_1); // LED 指示成功
        } else {
            // 发布失败，可选择重试或记录日志
        }
        HAL_Delay(5000); // 每 5 秒上报一次
    }
}

这个主循环清晰地展现了嵌入式系统的典型模式：初始化 -> 连接 -> 运行 -> 循环。它没有使用任何操作系统，所有延时均通过 HAL_Delay 实现，简单、确定、易于调试。对于需要更高实时性或更复杂任务调度的场景，可在此基础上无缝迁移到 FreeRTOS，将 MQTT_Publish_Float 封装为一个独立的任务。

3. 调试技巧与常见问题排查

在嵌入式开发中，“让代码跑起来”只是第一步，“让代码稳定地跑起来”才是真正的挑战。AIR780E 与 OneNet 的组合，因其涉及蜂窝网络、加密协议、云平台等多个复杂子系统，调试难度显著增加。掌握一套系统化的调试方法论，能事半功倍。

3.1 串口调试：从“黑盒子”到“透明通道”

最原始、也最有效的调试手段，永远是串口打印。在 AT_SendCommand 函数中，添加对发送与接收数据的原始字节打印，是诊断通信问题的第一步：

// 在发送前添加
printf("TX: %s", cmd);
// 在每次接收到一个字节后添加
printf("RX: 0x%02X ", rx_buffer[rx_len]);

通过观察串口助手（如 XShell、SecureCRT）中的原始数据流，可以立即发现：
- 指令格式错误 ：是否遗漏了 \r\n ？双引号是否成对？
- 响应解析失败 ：模块返回的是 OK 还是 ok ？是 OK 后跟 \r\n 还是 \n\r ？这些细微差别都会导致字符串匹配失败。
- 数据截断 ：接收缓冲区是否太小，导致长响应被截断？

一个经验法则：在调试阶段，将 AT_TIMEOUT_MS 设置为一个较大的值（如 10000ms），并确保串口打印的 RX 数据流是连续、完整的，这样才能看到模块的“真实反应”。

3.2 网络层问题：信号、APN 与 DNS 的三重门

当 AT+MQTTCONN 持续返回失败时，问题往往不出在 MQTT 协议本身，而是在其依赖的网络层。

首先，检查信号强度。 AT+CSQ 指令返回两个数值，如 +CSQ: 25,0 。第一个值 rssi （接收信号强度指示）范围是 0~31，其中 31 表示信号极好，99 表示未检测到信号。 rssi 小于 10 时，网络连接会变得非常不稳定。

其次，确认 APN 配置。虽然 AT+CSTT 设置了 APN，但还需通过 AT+CGDCONT? 查询 PDP 上下文是否已正确激活。成功的响应应为 +CGDCONT: 1,"IP","CMNET","0.0.0.0",0,0 。如果 IP 地址为 0.0.0.0 ，说明 PDP 上下文未激活，需重新执行 AT+CIICR 。

最后，DNS 解析是另一个隐形杀手。 AT+MQTTCONN 中的域名 mqtt.heclouds.com 需要被解析为 IP。若模块内置 DNS 服务器失效，可尝试手动指定 DNS 服务器： AT+CDNSCFG="223.5.5.5","223.6.6.6" （阿里 DNS）。

3.3 OneNet 平台侧验证：数据流的终点

调试的终点，是确认数据真正抵达了 OneNet 平台。登录 OneNet 开发者中心，在对应产品的“设备管理”页面，找到你的设备，点击“数据流”。这里会实时显示该设备上报的所有数据点。如果在这里能看到你期望的 temperature 数据流，且数值与 MCU 发送的一致，则证明整个链路是通畅的。

一个常见的误区是，在“设备管理”的列表页看到设备状态为“在线”，就认为一切正常。实际上，“在线”仅表示 MQTT 连接已建立，不代表数据发布成功。数据发布失败时，设备依然在线，但数据流为空。因此， 必须在“数据流”页面进行最终验证 。

此外，OneNet 的“设备日志”功能是强大的排障助手。它会记录设备每一次 MQTT 连接、订阅、发布的详细时间戳与结果（成功/失败）。当某次发布失败时，日志中会明确指出是“Topic 权限不足”还是“JSON 格式错误”，这比在 MCU 端猜测要高效得多。

4. 工程进阶：从单次发送到稳定服务

本实践所展示的“发送五组数据后断开”的模式，是教学演示的简化版本。在真实的工业产品中，设备需要 7x24 小时不间断运行，这就要求我们将演示代码升级为一个健壮的服务。

4.1 心跳保活与连接恢复机制

MQTT 协议的心跳（Keep Alive）机制，是维持长连接的生命线。但仅靠协议层的心跳是不够的。在网络抖动、基站切换等场景下，TCP 连接可能在协议层无感知的情况下悄然中断。因此，必须在应用层实现“双保险”：

• 协议层心跳 ：在 AT+MQTTCONN 中设置合理的 keepalive_time （如 120 秒）。
• 应用层心跳 ：在主循环中，每 60 秒发送一条空的 AT+MQTTPING 指令。该指令会触发模块向服务器发送一个 PINGREQ，并等待 PINGRESP。若超时未收到响应，则判定连接已断，立即执行重连流程。

static uint32_t last_ping_tick = 0;
if (HAL_GetTick() - last_ping_tick > 60000) {
    if (AT_SendCommand(&huart1, "AT+MQTTPING\r\n", "+MQTTPING: 0") != AT_OK) {
        // 连接已断，执行重连
        MQTT_Reconnect();
    }
    last_ping_tick = HAL_GetTick();
}

4.2 数据缓存与离线存储

在野外部署的设备，常面临信号盲区。此时，若简单地丢弃传感器数据，将导致数据丢失。一个成熟的方案是引入本地缓存。

最简单的缓存是 RAM 中的一个环形缓冲区（Ring Buffer）。每当 MQTT_Publish_Float 调用失败时，不是放弃，而是将待发布的 stream_id 和 value 封装成一个结构体，存入缓冲区。主循环在每次成功发布后，尝试从缓冲区头部取出一条数据进行重发。当缓冲区满时，新数据将覆盖最旧的数据，保证内存占用恒定。

对于要求更高的场景，可将数据写入外部 SPI Flash 或 SD 卡，实现掉电不丢失。但这需要额外的文件系统（如 FatFS）支持，增加了系统复杂度。

4.3 安全加固：从明文 AuthInfo 到 TLS 加密

当前方案中， AuthInfo 以明文形式通过 UART 传递给 AIR780E，并在 AT+MQTTPASSWORD 指令中发送。虽然 OneNet 的 AuthInfo 是有时效性的，但明文传输仍存在被物理窃听的风险。

终极的安全加固方案是启用 TLS 加密。AIR780E 支持 AT+MQTTCONN 连接到 6002 端口，该端口强制使用 TLS 1.2。启用 TLS 后，所有 MQTT 报文（包括 CONNECT 报文中的用户名/密码）都将被加密，即使 UART 线路被监听，也无法获取敏感信息。

启用 TLS 的前提是模块固件支持，且已预置了可信的根证书。可通过 AT+SSLROOTCA 指令查询或更新证书。这是一个一次性配置，完成后，所有 AT+MQTTCONN 到 6002 端口的连接都将自动启用加密。

我在实际项目中曾遇到过一个典型案例：某批次设备在出厂后三个月，陆续出现连接失败。排查发现，是 OneNet 平台悄然升级了其 TLS 证书，而旧版 AIR780E 固件中内置的根证书已过期。最终解决方案，便是通过 OTA 方式，向所有设备推送了新的根证书。这提醒我们，安全不是一劳永逸的，而是一个需要持续运维的过程。

---