萬字技術指南STM32F103C8T6 + ESP8266-01 連接 OneNet 平臺 MQTT/HTTP

此博客為一份詳細的指南，涵蓋 STM32F103C8T6 通過 ESP8266-01 連接 OneNet 平臺，并使用 MQTT/HTTP 進行數據通信的完整流程。這份文檔包括：

OneNet 平臺的介紹與功能概覽
在 OneNet 上創建和配置設備的方法
STM32CubeIDE 的開發環境搭建
ESP8266 AT 指令解析及如何連接 OneNet
STM32 通過 MQTT 向 OneNet 發送/接收數據的詳細實現
使用 OneNet API 進行 HTTP 交互的方式
從設備到云端再到 App 的完整示例代碼及解析

本指南詳細講解如何使用 STM32F103C8T6 微控制器通過 ESP8266-01 WiFi 模塊接入中國移動 OneNet 物聯網平臺，并通過 MQTT 和 HTTP 協議實現數據通信的完整流程。內容涵蓋 OneNet 平臺簡介、設備創建配置、硬件與開發環境準備、ESP8266 AT 指令聯網流程、STM32 通過 MQTT 發送/接收數據、移動 App 通過 HTTP 獲取數據，以及從設備到云端再到手機 App 的綜合示例演示。文中包含詳細的步驟、代碼示例、配置方法和常見問題解答，幫助讀者從零開始完成項目集成。

1. OneNet 物聯網平臺簡介與功能概覽

OneNet 平臺概述： OneNet 是中國移動提供的物聯網開放平臺，屬于 PaaS（Platform as a Service）層服務。在物聯網架構中，OneNet 扮演連接設備終端和上層應用的橋梁角色，為設備側提供可靠的接入手段，為應用開發者提供豐富的 API 和數據管理能力。開發者可以通過 OneNet 對設備進行在線管理、數據存儲分析、命令下發和應用構建。OneNet 支持海量設備的高并發接入，提供 99.9% 的服務可用性保障，同時通過分布式架構和多重機制確保數據安全存儲與傳輸。借助 OneNet，企業和個人開發者能夠快速搭建物聯網應用，實現設備數據上云和遠程監控控制等功能。

主要功能特點： OneNet 平臺支持多種主流物聯網協議，包括 MQTT、HTTP、LwM2M（NB-IoT）、EDP（設備協議）、TCP 透傳、ModBus、JT/T808 等等。這意味著各種類型的終端設備都可以選擇合適的協議與平臺通信。在資源模型上，OneNet 采用“用戶 -> 產品 -> 設備 -> 數據流”的組織架構：每個用戶賬戶下可創建多個產品，每個產品下可添加多個設備，并為每臺設備定義數據流、觸發器、應用等資源。平臺提供數據存儲（數據流/數據點）、命令下發、觸發器（滿足條件自動動作）、應用托管等完整的 IoT 功能。此外，OneNet 通過可視化界面和開放 API，使開發者既能在網頁端監控管理設備，也能通過 RESTful API 或 SDK 將平臺能力集成到自己開發的 App、服務器中。

MQTT 與 HTTP 在 OneNet 中的應用： MQTT 和 HTTP 是 OneNet 平臺最常用的兩種設備接入和數據交互方式。MQTT（Message Queuing Telemetry Transport）是一種輕量級發布/訂閱模型的消息協議，適合資源受限設備和不穩定網絡環境，在 IoT 領域廣泛使用。在 OneNet 中，MQTT 通常用于設備實時上線、上傳傳感數據、接收平臺指令等場景。設備通過 MQTT 與 OneNet 的消息Broker保持長連接，采用主題 (Topic) 訂閱/發布機制交換數據。OneNet 支持 MQTT 3.1.1 標準協議，并針對設備數據上傳和命令下發定義了一系列系統主題格式，使物模型數據的上報和下發更加規范。例如，OneNet 平臺允許設備發布傳感數據到 $sys/{產品ID}/{設備名稱}/thing/property/post 主題，并從 $sys/{產品ID}/{設備名稱}/thing/property/set 主題接收下發的屬性控制指令。同時，OneNet 也允許設備自由創建和訂閱自定義主題，以便實現設備間的消息交互（同一產品內不同設備可訂閱彼此發布的主題消息）。相比之下，HTTP 則是一種請求/響應式通信協議，更適合應用服務器或移動App和平臺進行交互。OneNet 提供完整的 RESTful 風格 API，允許第三方應用通過 HTTP(S) 請求查詢設備數據、下發命令、管理設備等。比如，應用可以通過 HTTP GET 請求獲取某設備最新的數據點，或通過 HTTP POST 請求調用 OneNet API 向設備發送命令。由于 HTTP 通信不需要保持長連接，通常設備本身不使用 HTTP 實時上線（除非設備無法使用MQTT而周期性通過HTTP上報數據點），但應用層（如手機App、Web后臺）會通過 HTTP API 來獲取云端已存儲的數據或觸發控制操作。

簡而言之，OneNet 提供了 MQTT 和 HTTP 兩種互補的通信方式：設備側傾向于使用 MQTT 保持長連接進行實時數據傳輸和指令接收，而應用側多通過 HTTP API 實現數據查詢和控制下發。在本項目中，我們將利用這兩者的配合：STM32+ESP8266 設備以 MQTT 協議將傳感數據上傳到 OneNet，同時我們的手機 App 則通過 OneNet 的 HTTP API 獲取設備數據，實現從傳感器到云端再到用戶界面的閉環。

2. OneNet 平臺上的設備創建與配置

在將設備連入 OneNet 之前，需要先在平臺上進行賬戶注冊、產品和設備的創建，并獲取相關的身份認證信息（如設備ID和APIKey）。以下是具體步驟：

2.1 注冊 OneNet 開發者賬戶： 打開 OneNet 官方網站 open.iot.10086.cn 并完成賬戶注冊流程。注冊時需要提供手機號進行驗證。注冊成功后，使用賬號登錄 OneNet，進入平臺“開發者中心”。OneNet 平臺分為老版和新版界面，當前版本通常需要先點擊首頁右上角的“控制臺”，再選擇“前往Studio”進入新版開發者中心 (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)。開發者中心是管理產品和設備的主要界面。

2.2 創建產品： 在開發者中心內，找到“產品管理”或直接點擊“添加產品”。根據提示填寫產品名稱、描述等基本信息。設備接入協議選項非常重要，這里請選擇“公開協議產品”并指定MQTT協議（如果你的設備走MQTT）或 HTTP 協議（如果設備打算通過HTTP直連）。對于本項目，我們選擇 MQTT 協議，因為設備通過 ESP8266 使用 MQTT 上報數據。此外，聯網方式可根據設備使用的網絡類型選擇（如 WiFi、蜂窩等，影響統計信息，不妨選擇 Wi-Fi）。產品創建后，系統會分配一個全局唯一的產品ID。進入產品詳情頁面，能看到“產品概況”，其中包含“產品ID”等關鍵信息。請記錄下產品ID，后續設備連接和 API 調用都需要它。

2.3 創建設備： 在產品的管理頁面下，找到“設備管理”并點擊“添加設備”。填寫設備名稱（例如“STM32_Sensor01”）和設備描述等。每個設備會被分配一個設備ID（一般是純數字）以及初始鑒權信息。在 OneNet 新版 Studio 平臺中，設備鑒權有兩種方式：一種是設備有設備秘鑰（Device APIKey），另一種是每次連接時使用動態 Token。如果平臺生成了設備APIKey（通常在設備詳情的鑒權信息中可以查看），建議將它記錄下來。有些新版界面可能沒有直接顯示設備APIKey，而是需要用戶使用 OneNet 的 Token 生成工具計算一個 Token 來作為密碼（后文詳細說明）。**注意：**產品ID、設備ID、設備名稱、設備APIKey/鑒權信息都是后續設備 MQTT 連接和 HTTP API 訪問所需的重要參數，一定要保存好。在OneNet上，每個設備也可以選擇不同接入協議，如果是在 MQTT 協議的產品下添加設備，則默認該設備使用 MQTT 協議接入；如果在 HTTP 產品下，則設備通過HTTP上報數據等。

2.4 設備接入方式介紹： OneNet 支持多協議，最常用的還是 MQTT 和 HTTP。對于MQTT接入，前面已經提到設備連接時需要用到三元組：設備ID（作為客戶端ID）、產品ID（作為用戶名）、鑒權信息（作為密碼）。設備連上 OneNet MQTT Broker 成功后，即可通過發布/訂閱主題與平臺通信（平臺不需要預先創建Topic，除系統主題外皆可動態使用，這簡化了開發）。而對于HTTP接入，設備可以通過HTTP請求將數據點上傳至 OneNet 的REST API（例如通過POST發送JSON數據），通常需要在HTTP請求的Header中包含API-Key用于鑒權 (輕松使用中移物聯網平臺Onenet，MQTT協議快速接入實驗 - ThingsKit)。HTTP方式也可以用于定期上報數據或讓不適合長連接的設備與平臺交互。在本項目中，我們主要采用 MQTT 連接實時上傳數據，HTTP 則用于應用側讀取數據。但了解HTTP接入也有助于理解OneNet API，例如通過HTTP可以方便地測試數據上傳和下發。后續章節會詳細介紹通過HTTP API 獲取設備數據并在App中顯示的過程。

小貼士：如果是首次使用 OneNet 平臺，建議先在 OneNet 后臺熟悉各項操作：瀏覽產品概況查看產品ID、在設備列表查看設備ID、在設備詳情頁查看**鑒權信息（設備秘鑰或Token）**等。一旦產品和設備設置完成，并確認這些信息，才能進入下一步的硬件配置和編碼。

3. 硬件環境與開發環境準備

在軟件配置妥當后，我們需要準備硬件環境（STM32F103C8T6 開發板和 ESP8266-01 模塊的連接）以及開發調試所需的軟件工具。

3.1 STM32F103C8T6 硬件介紹

STM32F103C8T6 是 STM32F1系列中非常經典的一款 MCU，基于 ARM Cortex-M3 內核，主頻 72MHz，擁有64KB Flash和20KB SRAM，以及豐富的片上外設（USART、SPI、I2C、ADC、TIM 等）。由于其性價比高、資源適中，被廣泛用于入門開發板（如“藍色小板” BluePill）。本項目中，我們選用 STM32F103C8T6 作為主控，負責采集傳感器數據（例如溫濕度）、通過串口與 ESP8266 通信，并處理來自云端的控制指令。請確保您的 STM32 開發板已燒錄了合適的 Bootloader 或固件，或者通過 SWD 接口連接了調試器（如 ST-Link），以便我們后續下載程序進行調試。

引腳資源回顧： STM32F103C8T6 有多個通用異步收發器 UART/USART。其中 USART1（PA9 TX, PA10 RX）和 USART2（PA2 TX, PA3 RX）經常用于與外部模塊通信或打印日志。由于我們的 ESP8266-01 使用串口通信，需要占用STM32的一個 USART 接口。USART1通常連接ST-Link的虛擬串口用于調試打印，因此我們可選擇USART2與 ESP8266 通信（當然，用 USART1 給 ESP8266 通信、USART2 用于調試也行，這取決于具體開發板的引出和需求）。無論選擇哪個串口，需要確保STM32能以 ESP8266 默認的波特率通信（ESP8266 默認波特率多為 115200bps，某些版本也可能是9600bps，可通過AT指令配置）。另外，STM32需提供3.3V電源給ESP8266模塊，且兩個器件共地。

3.2 ESP8266-01 硬件介紹及接線方式

ESP8266-01 模塊簡介： ESP8266-01（簡稱 ESP-01）是基于樂鑫 ESP8266 芯片的最小系統WiFi模塊。它體積小巧（約 25mm x 14mm），板上有 8 個引腳，包含ESP8266所需的最小Flash存儲和天線。ESP-01 自帶完整的 TCP/IP 協議棧，可以通過 AT 指令集由外部主控（如 STM32）進行控制，實現 WiFi 聯網和數據通信。ESP8266-01 的優點是價格便宜、功耗適中，并且通過 UART 串口即可控制，非常適合作為 MCU 的 WiFi 擴展模塊。在默認的 AT 固件下，ESP8266-01 可以執行各種網絡操作指令，如連接路由器 (AT+CWJAP)、啟動TCP連接(AT+CIPSTART)等。通過升級到最新的 MQTT AT 固件，它甚至直接支持 MQTT 客戶端的內置指令，如連接 MQTT 服務器、發布/訂閱消息等。本項目將利用 ESP8266-01 以 AT 指令模式連接到 WiFi，并通過 MQTT AT 指令連接 OneNet 平臺。

ESP8266-01 引腳定義： ESP-01 有 8 個引腳，典型分布和功能如下 (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)：

VCC：3.3V 電源輸入（切勿使用5V，否則會燒毀模塊）。
GND：電源地。
TXD：UART 串口數據發送端 (模塊發送數據給STM32，接STM32 RX 引腳) (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。
RXD：UART 串口數據接收端 (模塊接收數據，從STM32 TX 引腳獲取) (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。
CH_PD（或 EN）：芯片使能引腳，**必須接高電平（3.3V）**使模塊工作 (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客) (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。拉低該引腳會讓芯片休眠/禁用。
RST：復位引腳，低電平有效。可以接STM32一個GPIO用于軟件復位，或簡單地接高電平通過手動斷電復位 (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。
GPIO0：引導引腳0。懸空或拉高= 正常運行模式；拉低= 串口下載模式 (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。平時要確保 GPIO0 不被誤拉低，否則模塊會進入固件下載模式無法正常運行。通常上電時 GPIO0 接高（內部有上拉可懸空）。
GPIO2：引導引腳2。需拉高運行（上電時禁止為低） (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。一般直接懸空即可（內部上拉）。

ESP8266-01 與 STM32 連接： 按照上面的引腳功能，連接方式如下 (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)：

將 ESP8266-01 的 VCC 引腳接 3.3V 電源。確保電源能提供足夠電流（建議至少500mA裕量），因為 ESP8266 WiFi 發射時瞬時電流可達數百毫安。使用穩壓的 3.3V 且在模塊VCC和GND間加旁路電容以穩定供電。
GND 接地：連接 ESP8266-01 和 STM32 開發板的地線，保證兩者參考電平一致。
ESP-01 TX 接 STM32 的 RX 引腳（例如 STM32 PA3 若用USART2作為接收） (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。
ESP-01 RX 接 STM32 的 TX 引腳（例如 STM32 PA2 若用USART2發送） (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。請注意 ESP8266 RX 引腳默認3.3V邏輯，STM32F103也是3.3V GPIO，因此可以直接相連。如果主控是5V邏輯，則需要電平轉換。STM32F103C8T6 在3.3V下運行，無需電平轉換。
CH_PD/EN 引腳接 3.3V（可與 VCC 短接）。這個引腳必須為高，等效于使能芯片 (ESP8266-01引腳說明與連接_esp01引腳定義-CSDN博客)。可以通過 10k 上拉電阻上拉到3.3V。如果希望STM32控制使能，也可接STM32一個GPIO，但通常直接上拉更簡單。
GPIO0 引腳保持懸空或上拉（默認就有上拉）。若您的模塊未集成上拉，可用電阻上拉到3.3V。除非要刷固件，否則無需專門連接STM32引腳。
GPIO2 引腳一般懸空（內部有上拉即可滿足正常啟動要求）。
RST 引腳可以暫時懸空或通過上拉電阻拉高。如果需要STM32復位模塊，可以將其接到STM32一個GPIO（通過低脈沖復位）。簡化起見也可不接，由需要時斷電重啟模塊代替。

連接后，請仔細檢查線路：特別是電源和地要可靠連接，串口交叉連接（TX對RX），CH_PD確實為高電平。一個常見的錯誤是忘記給 CH_PD 上電，導致模塊沒有響應；或者串口接反。正確連線后，給模塊上電，ESP8266 藍色指示燈會在上電或復位時閃爍一下（ESP-01 上通常有一個藍色LED連接在UART TX上，每次串口發送數據會閃爍）。如果有 USB 轉TTL 模塊，可在PC上通過串口工具接ESP8266測試 AT 指令響應，以確認模塊工作正常。

3.3 STM32CubeIDE 的安裝及配置

開發環境選擇： STM32F103 的開發可以使用多種IDE，例如 Keil MDK、IAR、PlatformIO 等。本指南采用 ST 官方的免費開發環境 STM32CubeIDE，它集成了 STM32CubeMX 圖形配置和 Eclipse/CDT 編譯調試功能，適合構建 HAL 庫或 LL 庫項目。如果尚未安裝，請從 ST 官方網站下載安裝 STM32CubeIDE，安裝過程中選擇相應的包支持 STM32F1 系列。

啟動新工程： 打開 STM32CubeIDE，選擇 File -> New STM32 Project。在 Target Selector 中搜索 STM32F103C8（或選擇相應開發板型號），然后 Next。輸入項目名稱，如 "STM32_OneNet_Demo"，選擇使用 CubeMX 初始化。CubeIDE 將創建包含 CMSIS 和 HAL 庫的基本工程。接下來會自動打開 CubeMX 配置界面。

3.4 使用 STM32CubeMX 配置 STM32 外設（USART、GPIO 等）

在 CubeMX 圖形配置中，我們需要啟用并配置以下外設：用于與 ESP8266 通信的 USART、一些 GPIO（可能用作ESP8266 RST控制或板上LED）、如果連接傳感器還需要相應接口（如I2C/SPI等），以及調試所需配置。

USART 配置： 找到用于連接 ESP8266 的串口。例如我們選用 USART2：在 CubeMX 的 Pinout & Configuration 中，展開 Connectivity -> USART2，將其模式設置為 Asynchronous。CubeMX 會自動將 PA2/PA3 配置為 USART2 TX/RX。然后在 USART2 參數中，將 Baud Rate 設置為 115200（與 ESP8266 AT默認波特率匹配 (STM32與物聯網01-ESP8266基本操作 - 博客園)），數據位8，無奇偶校驗，1個停止位，硬件流控 None。開啟 **USART2 的中斷（NVIC Settings）**以便后續用中斷接收數據，或者使用 DMA 接收（可選）。如果打算通過另一個串口打印調試信息，可以同時開啟 USART1 并將其TX引腳映射到SWO或者PA9，引出給ST-Link虛擬串口。但簡化起見本指南主要描述 USART2 用于WiFi通信。

GPIO 配置： 將用于控制 ESP8266 的 RST 引腳配置為推挽輸出（如果需要）。例如我們可用 PB0 連到 ESP8266 RST，那么在 CubeMX 中將 PB0 設置為 GPIO_Output，初始狀態設置為高（不復位）。另外，可以配置板載 LED（如 PC13）為輸出用于指示狀態。

時鐘與其他配置： 確保啟用了外部高速晶振HSE（如使用外部8MHz晶振的板子），設置系統時鐘 72MHz，以獲得準確的USART波特率。如果使用內部晶振，需要校準以確保串口通信可靠。開啟需要用的定時器（用于延時或心跳）、I2C/SPI/ADC（用于傳感器）等。本項目例如使用定時器中斷做一個1秒的計時，或者使用 SysTick 實現簡單延時函數。

配置完成后，點擊 Generate Code。CubeIDE 將根據CubeMX配置生成初始化代碼，包括 MX_USART2_Init()、MX_GPIO_Init() 等函數。至此，STM32 外設配置就緒，我們可以編寫代碼控制USART收發 AT指令來驅動 ESP8266。

開發環境準備小結： 我們現在擁有：STM32F103 硬件連接好 ESP8266-01，并在CubeIDE項目中初始化好了串口和必要引腳。接下來需要考慮 ESP8266 的固件和AT指令用法，然后編寫 STM32 程序通過串口發送AT指令，驅動 ESP8266 完成 WiFi聯網和 MQTT 連接 OneNet 的流程。

4. ESP8266（AT 模式）連接 OneNet 的基本流程

ESP8266 模塊將作為 WiFi調制解調器，通過 AT 指令集由 STM32 來控制。我們首先要確保 ESP8266-01 上燒錄了合適的 AT 固件版本，且支持 MQTT 功能。目前常見的方案有：

使用樂鑫官方 AT 固件（例如 ESP-AT），版本要求支持 MQTT AT 指令。如果您的模塊固件版本較舊（AT+GMR可查看版本號），可能不直接支持 MQTT，需要更新到新版本。
或使用第三方定制的 MQTT AT 固件（如安信可提供的 MQTT 版AT固件）。更新固件需要將 ESP8266 IO0 拉低進入下載模式，通過 USB 轉串口燒錄。考慮到步驟復雜，本指南假設已獲得支持 MQTT指令的ESP8266 AT固件。

OneNet 平臺允許使用標準 MQTT 協議，我們可以直接利用 ESP8266 的 MQTT AT命令集來連接 OneNet，無需在 STM32 上編寫MQTT協議棧。這大大簡化了工作。下面分步驟介紹 ESP8266 AT 指令實現從聯網到 MQTT 連接的流程。

4.1 常用 AT 指令簡介

ESP8266 AT 指令是一系列以“AT”開頭的文本命令，用于配置 WiFi模塊參數和控制網絡操作。以下是我們將用到的一些指令及其功能：

AT：測試AT連通性。發送AT\r\n模塊應返回OK，用于驗證串口通信是否正常。
AT+RST：重啟模塊。模塊會復位并重新上電自檢。
AT+GMR：查詢固件版本號，用于確認固件支持情況。
AT+CWMODE：設置 WiFi 工作模式。AT+CWMODE=1 將模塊設為 Station模式（STA），即作為客戶端連接路由器。
AT+CWJAP="SSID","PWD"：加入WiFi網絡。參數為 WiFi 熱點的 SSID 和密碼。執行成功后模塊會連接到指定路由器并獲取IP。
AT+CIPSTA?：查詢模塊當前的 IP 地址（可選，確認聯網成功）。
AT+MQTTUSERCFG=<...>：配置 MQTT 客戶端參數。這個是 MQTT 擴展指令，格式較復雜，詳見后文。
AT+MQTTCONN=<...>：建立 MQTT 連接，指定服務器地址和端口等。
AT+MQTTSUB=<...>：訂閱 MQTT 主題。
AT+MQTTPUB=<...>：發布 MQTT 消息。
AT+MQTTPUBRAW=<...>：發布 MQTT 原始消息（需先指定長度，再發送數據）。
AT+MQTTCLEAN：斷開 MQTT 連接（視固件支持情況）。

其中，AT+MQTTUSERCFG、AT+MQTTCONN、AT+MQTTSUB、AT+MQTTPUB 等屬于新版固件中增加的 MQTT 命令集。若輸入這些命令提示未知，說明固件不支持MQTT，需要升級固件。

4.2 ESP8266 連接 WiFi 并接入 OneNet

步驟1：模塊上電自檢 – 給ESP8266上電后，等待1~2秒它完成自檢。STM32 向ESP8266串口發送一次AT\r\n，若返回OK則表示串口通信正常。如果無響應，可嘗試發送AT+RST\r\n復位模塊，或檢查串口接線/波特率。

步驟2：設置 WiFi 模式 – 發送AT+CWMODE=1\r\n，將ESP8266切換到 STA（Station）模式。默認有些固件可能已是1，但確認一下最好。期望收到OK回應。若返回ERROR可能是指令格式錯誤或模塊不支持，請檢查指令拼寫和換行符。

步驟3：連接到路由器 – 發送 AT+CWJAP="你的WiFi名稱","WiFi密碼"\r\n。此命令執行時間相對較長（數秒），模塊會嘗試加入指定AP。成功時返回WIFI CONNECTED和WIFI GOT IP消息以及最終的OK (STM32使用esp8266的AT指令連接mqtt服務器，以Thing Cloud為例（標準庫和HAL庫）_stm32 mqtt at指令-CSDN博客)。若返回FAIL，請檢查SSID/密碼是否正確，或模塊距離路由器過遠信號不好。成功獲取IP后，可以用AT+CIFSR或AT+CWJAP?驗證IP地址。至此，ESP8266 已連接互聯網。

步驟4（可選）：時間/NTP 配置 – OneNet MQTT可能要求時間戳（一般不需要此步，但部分物模型功能可能涉及時間）。示例中有使用 AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"\r\n 設置NTP (STM32使用esp8266的AT指令連接mqtt服務器，以Thing Cloud為例（標準庫和HAL庫）_stm32 mqtt at指令-CSDN博客)。這步可選，僅確保模塊時間同步，對MQTT連接OneNet不是必須。

步驟5：解析 OneNet MQTT 連接參數 – 在發起 MQTT 連接前，我們需要準備好 OneNet 的服務器地址、端口以及客戶端身份參數。根據 OneNet MQTT 接入規范，我們總結出如下參數：

服務器地址：OneNet MQTT Broker 的域名或IP。官方文檔顯示 OneNet 公共云 MQTT 接入地址可以使用 183.230.40.39（這是OneNet華北主站IP）和端口 6002。也可以使用域名 mqtt.heclouds.com 或 mqtts.heclouds.com。據近期實踐，OneNet 新平臺也開放了標準端口1883 供非TLS連接。例如域名 mqtt.heclouds.com:1883 也指向 OneNet MQTT 服務 (oneNet之MQTT按鍵控制LED 原創 - Csdn博客)。本指南選擇傳統地址 183.230.40.39:6002（非加密），對應 MQTT 3.1 協議。
客戶端ID：即設備ID。在 OneNet 平臺設備列表中可找到，例如創建設備時給出的數字ID（假設為 "123456789"）。
用戶名：即產品ID。可在產品概況頁面查看，如 "98765"。
密碼：即鑒權信息。OneNet 支持直接使用 設備APIKey 作為 MQTT 密碼 (oneNet之MQTT按鍵控制LED_在檢測mqtt用以執行其它按鍵-CSDN博客) (oneNet之MQTT按鍵控制LED_在檢測mqtt用以執行其它按鍵-CSDN博客)。例如設備的APIKey（16或24位字符串，如 "aFKcWTrm6VJfgfF1pQqW2=NWDck=" (oneNet之MQTT按鍵控制LED_在檢測mqtt用以執行其它按鍵-CSDN博客)）。新版OneNet也允許使用通過產品ID、設備名和設備秘鑰計算的 Token 值作為密碼。計算 Token 一般需要時間戳和簽名，這里為了簡便，我們直接使用 設備APIKey，假定平臺允許。注意，如果你的 OneNet 產品是新物模型類型，設備可能沒有獨立APIKey，需要通過 OneNet 提供的 Token 生成工具計算一個 token 字符串，再用作 MQTT 密碼 (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客) (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)。生成token的規則通常是：token = version=2018-10-31&res=products/<產品ID>/devices/<設備名稱>&et=<過期時間>&method=md5&sign=<簽名> (ESP8266/01s AT指令連接OneNET MQTT篇上報和下發數據_onenet mqtt 命令下發-CSDN博客)。簽名是把上述信息和產品MasterKey一起MD5生成的字符串。這較復雜，如非必要可使用設備APIKey簡單連接。

搞清上述參數后，我們組裝 MQTT 用戶配置命令。ESP8266 MQTT AT指令 AT+MQTTUSERCFG 用于設置這些參數，其格式為：

AT+MQTTUSERCFG=<鏈接ID>,<生存周期>,<客戶端ID>,<用戶名>,<密碼>,<KEEPTIME>,<cleansession>,<LWTTOPIC>

各字段含義：

鏈接ID：0（ESP8266可以維護多個MQTT連接，0表示第一個）。
生存周期：1（MQTT版本，0=3.1, 1=3.1.1）。
ClientID：設備ID字符串。
Username：產品ID字符串。
Password：鑒權信息字符串（設備APIKey或生成的Token）。
KEEPTIME：心跳時間（單位s），OneNet默認可用無關緊要值如0表示默認60s。
cleansession：0或1，設置會話清理，一般設0保持會話，設1表示每次連接不保留會話。
LWTTOPIC：遺囑消息主題，可留空""無遺囑。

例如，假設設備ID為123456789，產品ID為98765，設備APIKey為abc123XYZ...，則命令為：

AT+MQTTUSERCFG=0,1,"123456789","98765","abc123XYZ...",0,0,""

發送該命令，模塊應返回OK表示參數接受成功 (STM32使用esp8266的AT指令連接mqtt服務器，以Thing Cloud為例（標準庫和HAL庫）_stm32 mqtt at指令-CSDN博客)。如果返回錯誤，請檢查參數格式，特別是引號、逗號是否正確。

步驟6：建立 MQTT 連接 – 接下來發送 AT+MQTTCONN=0,"183.230.40.39",6002,1\r\n。其中參數依次為：鏈接ID=0，服務器地址，端口號，最后的1表示clean session（這里設1或者0需跟前面的 cleansession 保持一致，否則可能出錯）。注意 OneNet MQTT 非TLS，用 6002 端口；如用1883端口將域名改為mqtt.heclouds.com相應調整。建立連接后，ESP8266會嘗試和OneNet進行MQTT握手。成功的話，會收到 OK 和一個 MQTT 狀態指示，比如：+MQTTCONNECTED:0。如果連接失敗，常見錯誤代碼包括：

ERROR 直接報錯：檢查域名/IP是否可達，端口是否正確。
+MQTTCONNECTED: -1 或 +MQTTCONNECTED:4 等：這些是MQTT Connect 報文被服務端拒絕的返回碼。例如 4表示登錄被拒絕（可能用戶名/密碼錯誤）。請核對產品ID/設備ID/APIKey是否正確對應，或Token是否過期。
+CME ERROR: Recv timeout：表示在超時時間內沒收到響應，可能網絡問題或參數有誤。

當 OneNet 平臺收到正確的 ClientID(設備ID)、Username(產品ID)和Password(APIKey/token)后，會建立 MQTT 連接，OneNet 后臺設備列表應該能看到該設備上線。成功連接后，我們就可以進行 MQTT 數據收發了。

4.3 OneNet MQTT 通信主題格式解析

OneNet 平臺的數據交互通過 MQTT 主題（Topic）完成。OneNet 有一些系統主題專門用于物模型設備的數據上下行，為統一格式，通常以 $sys/{產品ID}/{設備名稱}/thing/ 開頭。例如：

上報設備屬性（數據點）使用主題：$sys/{產品ID}/{設備名稱}/thing/property/post。設備向該主題發布屬性值的JSON數據。
平臺下發寫屬性命令使用主題：$sys/{產品ID}/{設備名稱}/thing/property/set。設備需訂閱該主題來接收指令。
屬性上報回復主題：$sys/{產品ID}/{設備名稱}/thing/property/post/reply，平臺每次收到設備上報數據會反饋結果，設備可選擇訂閱此主題確認數據是否成功被平臺接收。
屬性設置回復主題：$sys/{產品ID}/{設備名稱}/thing/property/set_reply，當設備執行完平臺下發的屬性設置指令后，需向該主題回復執行結果（如成功或錯誤）以通知平臺。

這些主題含有產品ID和設備名稱，是OneNet新版物模型統一的路徑。如果你的產品在OneNet上創建了物模型（數據流模板）并定義了屬性，建議使用上述系統主題來上傳和下發數據，平臺將自動解析 JSON 格式數據點并存儲到對應的屬性中。如果沒有用物模型，OneNet 也支持另一種數據流透傳方式：設備可以向主題 $dp 發布數據點（Data Point）消息 (10.2. MQTT協議:2上傳數據點到OneNET平臺 — mPython掌控 2.2.0 documentation)。$dp 是 OneNet 定義的特殊主題，用于簡化數據上報，它要求發布的消息為特定格式：前3字節指示JSON數據長度和類型，后面跟實際JSON內容 (10.2. MQTT協議:2上傳數據點到OneNET平臺 — mPython掌控 2.2.0 documentation)。例如 micropython 客戶端通過 c.publish("$dp", pubdata(message)) 上報數據點 (10.2. MQTT協議:2上傳數據點到OneNET平臺 — mPython掌控 2.2.0 documentation)。但考慮到 $dp 較舊且需要自己構造報文頭，我們更推薦使用物模型主題直接發 JSON 字符串，這也便于與OneNet Studio中的設備屬性對應。

本項目主題規劃： 假設我們定義了兩個屬性數據流：溫度(temp)和濕度(humi)。我們將在設備端通過 $sys/{產品ID}/{設備名稱}/thing/property/post 發布屬性數據，JSON格式如：{"id":"123","params":{"temp":{"value":23.5},"humi":{"value":60}}}。平臺處理后，可在OneNet設備詳情看到 temp和humi的數據點各自更新。為了接收平臺對上報的響應，我們可以訂閱 $sys/{產品ID}/{設備名稱}/thing/property/post/reply（但其實OneNet當前對post上報一般不需要特殊確認，error=0說明成功）。更重要的是，為了讓手機App通過平臺控制設備（比如打開設備上的LED），平臺會通過 property/set 下發命令，因此設備需要訂閱 $sys/{產品ID}/{設備名稱}/thing/property/set 主題。一旦收到此主題消息，STM32 就觸發對應的控制，并回復執行結果到 set_reply 主題。

4.4 配置 ESP8266 訂閱 OneNet 主題

在 MQTT 連接建立后，ESP8266 可以通過 AT 命令訂閱所需主題。使用指令格式：

AT+MQTTSUB=<鏈接ID>,"<主題>",<QoS>

其中 QoS 為服務質量等級，0最多送一次，1至少送一次。OneNet 支持 QoS0 和 QoS1，這里用 QoS0 足矣。

訂閱設備下行主題： STM32應發送：

AT+MQTTSUB=0,"$sys/{產品ID}/{設備名稱}/thing/property/set",0\r\n

這樣當 OneNet 平臺有對該設備的控制指令下發時，ESP8266會收到，并通過串口通知STM32。ESP8266 固件在收到訂閱的消息時，會通過一種 URC 非命令的格式輸出，比如：

+MQTTSUBRECV:0,"$sys/pid/devName/thing/property/set","{...json...}"

具體格式視固件有所不同，可能還帶消息長度等信息。但一般包含鏈接ID、主題、以及消息內容。STM32 程序需解析出消息內容中的 JSON，然后根據指令執行相應動作（如打開LED或改變閾值等）。

（可選）訂閱上報回復主題： 若希望確認每次數據上報平臺是否成功，可訂閱 $sys/{產品ID}/{設備名稱}/thing/property/post/reply。平臺在收到屬性上報后會返回類似：{"id":"123","code":0,"msg":"success"}，表示id為123的請求成功（code=0）。ESP8266 收到后STM32可讀取+MQTTSUBRECV并判斷 code 是否為0，非0可重試上報。訂閱指令同理：

AT+MQTTSUB=0,"$sys/{產品ID}/{設備名稱}/thing/property/post/reply",0\r\n

回復 OK 則訂閱成功。

ESP8266 可以一次訂閱多個主題，順序發送多條 AT+MQTTSUB 命令即可。OneNet 支持動態創建主題，訂閱不存在的主題也會成功（只要格式合法），這點和其他云（如阿里IoT）需要預定義Topic不同。所以無須在OneNet平臺額外配置這些主題。

注意： 每條 AT 命令都應有相應 OK/ERROR 來指示執行結果。我們在 STM32 程序中通常會發送命令后等待特定應答字符串。例如，發送 MQTTSUB 后等待 "OK" 確認。如果一直等不到（超時），應考慮重發或判定失敗。合理的延時和重試機制可以提高連接成功率。

4.5 綜合：ESP8266 連接過程命令序列

將上面所有配置串聯起來，ESP8266 從上電到訂閱完成的大致 AT 指令序列如下（帶簡要注釋）：

AT → 模塊應答 OK（測試通信）
AT+RST → OK（重啟模塊）
（模塊重啟后會輸出一些啟動信息，等待1~2秒繼續）
AT+CWMODE=1 → OK（設置為Station模式）
AT+CWJAP="SSID","PWD" → WIFI CONNECTED WIFI GOT IP ... OK（連接WiFi，聯網成功）
AT+MQTTUSERCFG=0,1,"<DeviceID>","<ProductID>","<APIKey/token>",0,0,"" → OK（配置MQTT參數） (STM32使用esp8266的AT指令連接mqtt服務器，以Thing Cloud為例（標準庫和HAL庫）_stm32 mqtt at指令-CSDN博客)
AT+MQTTCONN=0,"183.230.40.39",6002,1 → 若成功：OK 和可能的 +MQTTCONNECTED:0
AT+MQTTSUB=0,"$sys/<pid>/<dev>/thing/property/post/reply",0 → OK（訂閱上報回復主題，可選）
AT+MQTTSUB=0,"$sys/<pid>/<dev>/thing/property/set",0 → OK（訂閱平臺下行控制主題）

到此，設備已做好與 OneNet 云通信的準備。接下來，STM32 就可以根據應用需要發布數據或者接收指令進行處理了。

5. STM32 通過 MQTT 向 OneNet 發送/接收數據

這一部分我們關注 STM32 程序如何控制 ESP8266 完成 MQTT 數據通信。核心是通過串口發送上節的 AT 指令序列，實現設備數據上報（Publish）和云端命令下發接收（Subscribe）。

5.1 STM32 串口通信控制 ESP8266

USART 通信實現： 在 STM32 中，我們可以使用 HAL 庫提供的 HAL_UART_Transmit() 和 HAL_UART_Receive() 函數與 ESP8266 通信，也可以使用中斷或 DMA 提高效率。典型地，我們會實現一個函數 ESP8266_SendCmd(const char* cmd, const char* ack, uint32_t timeout) 用于發送 AT 命令并等待某個應答關鍵字。例如，偽代碼：

uint8_t rxBuf[128];
uint8_t ESP8266_SendCmd(const char* cmd, const char* ack, uint32_t timeout) {HAL_UART_Transmit(&huart2, (uint8_t*)cmd, strlen(cmd), 1000);// 清空接收緩沖memset(rxBuf, 0, sizeof(rxBuf));// 等待接收，循環直到發現 ack 或超時uint32_t t0 = HAL_GetTick();uint8_t found = 0;while(HAL_GetTick() - t0 < timeout) {// 假設我們使用中斷將數據搬到rxBuf并隨時檢查if(strstr((char*)rxBuf, ack) != NULL) {found = 1;break;}if(strstr((char*)rxBuf, "ERROR") != NULL) {break;}}return found;
}

上面使用 strstr 查找應答。為此，我們需要在UART接收中斷中持續填充 rxBuf 緩沖區。可以開USART接收空閑中斷，把每次接收到的新字節追加到 rxBuf 末尾。為了簡單，也可以采用 HAL_UART_Receive polling 方式讀字符，邊讀邊檢查字符串，但效率略低。在實際代碼中，還要考慮Buffer溢出以及必要時清除舊應答。

AT 指令發送順序： STM32上電后，按4.2節流程逐條調用 ESP8266_SendCmd 發送。比如：

ESP8266_SendCmd("AT\r\n", "OK", 500);
ESP8266_SendCmd("AT+RST\r\n", "ready", 2000); // 等待重啟后的 "ready" 字樣
ESP8266_SendCmd("AT+CWMODE=1\r\n", "OK", 500);
ESP8266_SendCmd("AT+CWJAP=\"MyWiFi\",\"password\"\r\n", "GOT IP", 10000);
sprintf(cmdBuf, "AT+MQTTUSERCFG=0,1,\"%s\",\"%s\",\"%s\",0,0,\"\"\r\n", deviceID, productID, apiKey);
ESP8266_SendCmd(cmdBuf, "OK", 1000);
sprintf(cmdBuf, "AT+MQTTCONN=0,\"183.230.40.39\",6002,1\r\n");
ESP8266_SendCmd(cmdBuf, "OK", 5000);
ESP8266_SendCmd("AT+MQTTSUB=0,\"$sys/xxx/yyy/thing/property/set\",0\r\n", "OK", 1000);

如上所示，在每一步等待適當的應答。其中連接WiFi可能耗時較長，要給出足夠 timeout（10秒甚至更長），而MQTT 連接也需要幾秒完成 TLS 握手/認證等（OneNet非TLS會快些）。確保每一步都判斷結果，若失敗可以重試或進入錯誤處理（比如重新初始化ESP8266）。

常見錯誤處理：

如果 AT 測試不通，可能是串口問題，可重發幾次AT或者直接指示錯誤閃LED。
AT+CWJAP 返回 FAIL，可嘗試再次發送或讓用戶檢查WiFi憑據。
AT+MQTTCONN 若返回錯誤，需要檢查鑒權。OneNet常見是用戶名密碼不對導致 Connect 報文返回 4 (Connection Refused: bad user/pass)。這種情況下，可打印調試信息 (比如將 ESP8266 返回的整個字符串通過調試串口輸出) 來分析。
整個流程若卡在某一步超過重試次數，可考慮重啟模塊(AT+RST)重來。

經過上述步驟，假設 STM32 最終在MQTT連接和訂閱主題上都收到 OK，我們就進入正常通信階段了。

5.2 發布 MQTT 數據（設備上傳）

構造發布命令： 發布屬性數據使用 AT+MQTTPUB 或 AT+MQTTPUBRAW。區別是：MQTTPUB 可以直接附帶消息字符串，但需要對消息內的特殊字符轉義，而且長度有限制；MQTTPUBRAW 則分兩步發送，可避開轉義問題。我們用普通 AT+MQTTPUB 簡化流程。

格式：

AT+MQTTPUB=0,"<主題>","<消息>",<QoS>,<retain>\r\n

其中 QoS=0, retain=0 即可（OneNet 暫無保留消息需求）。

例如上傳溫濕度：
主題 $sys/pid/dev/thing/property/post，消息內容：{"id":"123","params":{"temp":{"value":23.5},"humi":{"value":60}}}
則命令為：

sprintf(cmdBuf, "AT+MQTTPUB=0,\"$sys/%s/%s/thing/property/post\",\"{\\\"id\\\":\\\"123\\\",\\\"params\\\":{\\\"temp\\\":{\\\"value\\\":%.1f},\\\"humi\\\":{\\\"value\\\":%.1f}}}\",0,0\r\n", productID, deviceName, temperature, humidity);
ESP8266_SendCmd(cmdBuf, "OK", 1000);

注意在C字符串中雙引號和反斜杠需要轉義（如 \" 和 \\\"）。上例用了 %.1f 代入浮點溫濕度值并保留1位小數。id 字段可用來匹配應答，這里隨意給"123"即可，每次上報可增1或使用時間戳字符串。

發送該命令，如果ESP8266返回 OK，表示消息已發出。OneNet 平臺會將數據解析寫入設備屬性data流。如果我們之前訂閱了 post/reply 主題，那么ESP8266稍后會輸出一行，例如：

+MQTTSUBRECV:0,"$sys/pid/dev/thing/property/post/reply","{"id":"123","code":0,"msg":"success"}"

STM32 程序在 UART 接收數據中檢測到有 +MQTTSUBRECV 字樣，就可以進一步解析出主題和內容。可以通過尋找引號來截取主題字符串，再根據主題決定處理方式。如果是 post/reply，解析 JSON 看 code是否為0。如果為0則表示平臺接受數據成功；非0表示失敗，此時可選擇重發該數據或者上報錯誤狀態。一般 code 非0的情況很少出現，除非 JSON 格式不符合物模型定義、數據類型錯誤等。

循環發布數據： 實際應用中，STM32 會周期性采集傳感器數據然后發布。例如每隔 10秒發送一次溫濕度。可以使用定時中斷或RTOS任務來調用發布函數。確保不要發太頻繁以免淹沒網絡，一般 OneNet 對MQTT上報頻率沒有苛刻限制，但合理的間隔有助于功耗和流量。

發布調試： 在開發時可以借助 OneNet 平臺的“設備調試”功能或 MQTT.fx 等客戶端來觀察數據是否到云端。OneNet Studio 提供“數據流”或“設備詳情”頁面，可以看到屬性的最新值和歷史曲線，驗證我們的發布確實成功。

5.3 訂閱主題消息處理（設備下行）

STM32 需要處理 ESP8266 通過串口反饋的訂閱消息，即當平臺有命令下發時，ESP8266 會打印類似 +MQTTSUBRECV: 的信息。我們需要在 UART 接收回調中尋找這個標志并提取其中的 JSON 命令。

示例： 平臺通過 HTTP API 或控制臺調用下發命令，OneNet 會向主題 $sys/pid/dev/thing/property/set 發送消息。例如讓設備LED開關，OneNet 定義了屬性 "LED" 為布爾或數值，那么下發 JSON 可能是：{"id":"4","params":{"LED":{"value":1}}}。ESP8266收到，會輸出：

+MQTTSUBRECV:0,"$sys/pid/dev/thing/property/set","{"id":"4","params":{"LED":{"value":1}}}"

STM32 程序需解析 params 內的內容。可以采用和發布相同的 cJSON 庫（如果使用嵌入式JSON解析庫的話）或者簡單字符串查找方法。例如，查找 "LED":{"value": 子串，取其后緊跟的數字。或者更通用地，把整個 JSON 文本提取出來，然后用 JSON parser 獲取鍵值。由于OneNet物模型下發格式就是這個 "params":{...}，我們可以硬編碼尋找目標屬性。

執行命令并回復： 一旦提取出 LED 要設置為1，我們就在 STM32 控制相應GPIO點亮 LED。然后需要回復平臺，告知命令已執行。回復主題 $sys/pid/dev/thing/property/set_reply，內容一般包含同樣的 id 以及 code 表示結果。OneNet 希望收到 code 200 表示設備已成功執行，或其他錯誤碼。示例如ESP8266命令：

AT+MQTTPUB=0,"$sys/pid/dev/thing/property/set_reply","{"id":"4","code":200,"msg":"success"}",0,0

來回應 id=4 的指令執行成功。在 AT 指令里，雙引號要轉義，同發布類似：

sprintf(cmdBuf, "AT+MQTTPUB=0,\"$sys/%s/%s/thing/property/set_reply\",\"{\\\"id\\\":\\\"%s\\\",\\\"code\\\":200,\\\"msg\\\":\\\"success\\\"}\",0,0\r\n",productID, deviceName, cmdIdString);
ESP8266_SendCmd(cmdBuf, "OK", 1000);

其中 cmdIdString 是收到命令 JSON 里的 id（例如 "4"），需要原樣放回。發送完成后，OneNet 運維頁面“API調試”處將顯示 code:0 表示平臺收到了設備的確認。若不回復或回復不正確，平臺可能視為設備未執行命令，會顯示超時。

總結設備下行處理：

STM32監聽串口數據，捕獲 +MQTTSUBRECV 行。
判斷主題是 property/set 還是別的。可通過在該行字符串中搜索 "thing/property/set" 來確定。如果以后還有別的訂閱主題，也類似判斷。
提取 JSON 字符串。因為包含引號，我們可以找到第一個出現的 { 和最后一個 } 括號的位置，截取之間的字符串作為 JSON。
根據具體的物模型字段解析需要控制的項和值。對簡單項目，也可以通過 strstr尋找屬性名然后取其后 value值。
執行相應動作（如控制硬件）。
構造 set_reply 消息發送確認。

整個過程應盡量迅速完成，避免下一條UART數據覆蓋尚未處理的數據。可以考慮把 JSON 放到任務中處理，以免阻塞UART中斷。不過對于一般速度的消息和STM32F1性能，這樣處理是足夠的。

6. App 與 OneNet 平臺的數據交互（HTTP）

在設備通過 MQTT 將數據上傳云端后，我們希望手機 App 或其他上層應用能夠獲取這些數據并展示，同時也能夠通過 App 控制設備（本例中如遠程開關LED等）。OneNet 平臺提供了豐富的 HTTP API 來滿足這些需求。開發者可以通過 HTTP 請求查詢設備狀態、讀取數據流、觸發命令下發等。下面介紹 OneNet HTTP API 的基礎用法，并以使用 Postman 測試為例，演示如何從云端獲取設備數據。

6.1 OneNet 提供的 HTTP API 介紹

OneNet 的 HTTP API 遵循 RESTful 風格，對外統一以 api.heclouds.com 域名提供服務。不同的資源（設備、數據流、數據點、命令等）都有各自的 URL 路徑。新版本的 OneNet 也提供了 open.iot.10086.cn 下更嚴格鑒權的接口（需要使用 Token），但為了簡單起見，這里介紹經典的基于 API-Key 的接口，因為操作方便易測且足夠滿足大部分應用。

常用 API 概覽：

獲取設備信息：GET http://api.heclouds.com/devices/<設備ID>
獲取數據流信息：GET http://api.heclouds.com/devices/<設備ID>/datastreams/<數據流ID>
獲取數據點：GET http://api.heclouds.com/devices/<設備ID>/datapoints?datastream_id=<數據流ID>&limit=<n> (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客)
例如獲取最新1條數據點，可用 limit=1。
批量獲取多個數據流的數據點：GET http://api.heclouds.com/devices/<設備ID>/datapoints?datastream_id=temp,humi&limit=1 （多個流用逗號隔開）。
下發命令到設備：POST http://api.heclouds.com/cmds?device_id=<設備ID>，在HTTP Body中寫入命令內容（但OneNet的命令接口與MQTT互通需要設備實現特定邏輯，使用Topic更直接，后文詳述）。
直接向設備的 MQTT 主題發送消息：OneNet 有相應 API，可通過HTTP發布一條消息到某設備的某主題。如果設備訂閱了該主題，就能收到。此接口在OneNet稱為HTTP透傳或發布主題消息。調用方式如：
POST http://api.heclouds.com/mqtt?topic=<TopicName>&device_id=<設備ID>
Body中是消息內容文本 (Python Onenet 實現指南 - 51CTO博客)。這種方式本質上等價于服務器端代替我們去發布MQTT消息。

上述 API 調用均需要鑒權。鑒權通過在請求 Header 中加入 api-key 字段實現。api-key可以使用產品的 Master APIKey（具有該產品下所有設備操作權限），或者使用某臺設備的 APIKey（只對該設備的數據有權限）。出于安全考慮，App 端通常不直接用Master Key，而是用設備的APIKey來獲取該設備的數據。如果只讀數據也可以給APIKey配置只讀權限。我們的應用只是查看數據和發命令給自己的設備，用設備APIKey即可。

6.2 通過 HTTP 獲取設備數據

使用 Postman 測試 GET 請求： 首先在 OneNet 開發者中心找到我們設備的 設備ID 和設備APIKey（或產品APIKey）。假設設備ID為123456789，數據流ID為temp。我們想獲取最新的溫度值。可以構造 HTTP GET 請求：

GET http://api.heclouds.com/devices/123456789/datapoints?datastream_id=temp&limit=1
Header:api-key: <設備APIKey>

使用 Postman 或瀏覽器插件發出請求。如果成功，OneNet會返回一個 JSON 數據。例如：

{"errno": 0,"data": {"count": 1,"datastreams": [{"id": "temp","datapoints": [{"at": "2025-03-10 06:30:00","value": 23.5}]}]},"error": "succ"
}

這里 "errno":0 表示無錯誤，"data" 下包含我們請求的數據點。count是本次返回的數據點數，datastreams數組列出了請求的各數據流以及數據點列表。可以看到最新數據點的時間戳和值 (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客) (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客)。App 可以解析此 JSON 提取所需數值。

如果想獲取多個數據流的值（如溫度和濕度一起），可以把 datastream_id 設為兩個ID組合，或者干脆不指定 datastream_id 讓其返回設備下所有數據流的最近點。返回格式會有多個 datastreams 條目，要根據 id 匹配。

注意： OneNet 平臺在設備通過物模型上報屬性后，會把每個屬性映射為一個獨立的數據流，其 ID 一般就是屬性名。因此用以上接口獲取屬性值是可行的。例如屬性 "humi" 也能通過 datastream_id=humi 查詢。同理，也可以通過 OneNet Studio 提供的新接口獲取設備的影子信息，但那需要 token 方式，不在本次討論。

解析返回數據： 在 App 端，我們可以使用 JSON 庫解析。例如在Android應用中，可以用 org.json 或 Gson 等庫將返回字符串解析成對象 (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客)。在解析后，就能得到溫度值 23.5（數字類型）。我們可以將其顯示在 App 界面的文本框中。

周期獲取 vs 推送： 由于我們這里使用 HTTP，是一種輪詢獲取機制。App 需要隔一定時間就發送 GET 請求刷新數據，才能近乎實時顯示最新值。可以每隔5秒或10秒請求一次，根據應用需求和流量權衡。如果不想頻繁輪詢，OneNet 也提供推送機制（通過TCP長連接或MQTT方式），但移動App一般用HTTP輪詢簡單可靠。

示例：使用 Python 獲取數據： 除了 Postman，我們也可以用簡單的 Python 腳本測試 API。例如：

import requests
device_id = "123456789"
api_key = "abcdef...你的設備APIKey"
url = f"http://api.heclouds.com/devices/{device_id}/datapoints?datastream_id=temp&limit=1"
headers = {"api-key": api_key}
res = requests.get(url, headers=headers)
data = res.json()
print(data)

這段Python代碼發送 GET 請求到 OneNet 數據點 API，獲取 JSON 數據并打印 (Python Onenet 實現指南 - 51CTO博客) (Python Onenet 實現指南 - 51CTO博客)。若配置正確，會輸出類似上面的 JSON。你可以在 PC 上用這個方法測試設備數據獲取是否正常，然后再把邏輯移植到App。

6.3 通過 HTTP 控制設備（命令下發）

App 不僅讀取數據，還需能夠控制設備。例如用戶在手機上按下“打開LED”按鈕，我們希望通過 OneNet 讓設備收到這個指令。實現方式有兩種：

方法A：調用 OneNet 命令下發 API – OneNet 提供專門的命令通道API，即前述的 POST /cmds?device_id=<id> 接口。使用這個接口需要在HTTP body中寫命令內容，該內容會通過OneNet內部下發到設備。傳統OneNet設備（如使用EDP協議）能直接收到這個命令。但對于MQTT設備，OneNet后臺其實會將命令轉為 MQTT 消息發送到設備。所以方法A本質也要落到某個主題消息。具體來說，當我們調用/cmds接口發送一條命令字符串，OneNet 平臺會將此字符串封裝為 MQTT 消息，發送到設備的系統命令主題，即 $sys/{productID}/{deviceName}/cmd/request 等主題（老版OneNet MQTT的做法）。但新版本物模型設備未必使用這個路徑，因此方法A適用于不使用自定義Topic的場景。

方法B：直接通過Topic API發送 – 如前面提到的 MQTT HTTP透傳接口，可以在HTTP請求中指定發往設備的哪個Topic，這樣更靈活。因為我們的設備已經訂閱了 $sys/pid/dev/thing/property/set 主題，最自然的是讓App通過HTTP直接發布一條消息到此主題。OneNet 有相應文檔說明此用法 (Python Onenet 實現指南 - 51CTO博客)。

考慮我們已經采用物模型主題，那使用方法B更直接：App 調用HTTP接口，OneNet立刻把內容推給設備，無需定義其他命令通道。示例：我們希望設置 LED=1，可發送：

POST http://api.heclouds.com/mqtt?topic=$sys/<pid>/<dev>/thing/property/set&device_id=123456789
Header:api-key: <MasterAPIKey或設備APIKey>
Body (application/json):{"id":"app1","params":{"LED":{"value":1}}}

其中 device_id 參數確保消息發往特定設備，topic 參數指定主題。Body 就是設備 set 主題所需的 JSON 格式。我們可以用 Postman 發這個請求嘗試。OneNet 返回的響應如果 errno:0 則表示消息已發送 (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客)。此時在設備端，ESP8266 會收到與平臺UI下發命令相同的內容，通過 UART 通知STM32。STM32 執行后再MQTTPUB回復，平臺將轉發回復給HTTP調用方（App）。但是HTTP接口是否能直接拿到回復需要查詢結果，因為HTTP是短連接并不能等回復。

更簡單的做法是，App 下發命令后，可以隔幾秒重新 GET 一次設備數據，看看對應狀態改變沒有。例如，App發送 LED=1 后，設備會執行點亮LED，同時也可以選擇上報 LED 狀態改變（比如作為一個數據流）。然后App輪詢看到 LED狀態流已變為1，則表示命令生效。這樣就不需要App等待同步響應。

小結： HTTP API 非常強大也相對直觀。一般流程是：設備->OneNet (MQTT) 實時上報數據；App->OneNet (HTTP) 請求讀取數據，App->OneNet (HTTP) 發送控制、OneNet->設備 (MQTT) 轉發控制。OneNet充當了中介，讓設備和應用解耦。開發者要關注API使用是否正確，參數是否匹配。此外注意 APIKey 的保密和有效期。MasterKey權限很高，應妥善保存或在服務器端使用，不要放在App內。如果必須在App內調用，可以創建設備級APIKey（OneNet控制臺的APIKey管理可添加，只賦予特定資源權限）來代替 MasterKey。

使用 HTTP API 的調試技巧： 善用 Postman 之類工具構造HTTP請求，并查看返回結果。OneNet官方文檔詳細列出了各接口的URL和返回格式 (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)。當遇到問題時，檢查HTTP狀態碼和返回的 errno、error信息。例如 errno=10可能是api-key無效，errno=6可能是設備未找到等。使用正確的 Content-Type（application/json）和 Header 是必要的，否則OneNet會報輸入格式錯誤。

7. 綜合示例：從設備到云端再到手機 App 的完整流程

這一節我們以一個具體的應用場景串起前面的所有環節：使用 STM32F103C8T6 定期采集環境溫濕度，通過 ESP8266 MQTT 上傳至 OneNet；OneNet 云端存儲數據并提供查詢；用戶使用手機App通過HTTP獲取實時溫濕度并顯示。同時，用戶可在App上按下按鈕控制遠端STM32點亮或熄滅一個指示LED，通過 OneNet 平臺的指令下發實現。

7.1 設備端（STM32 + ESP8266）過程

系統初始化： STM32上電后，初始化 USART、GPIO、傳感器接口等。重置ESP8266并配置好WiFi連接和MQTT連接 OneNet（按第4章和第5章流程）。假設成功上線后，STM32訂閱了屬性設置主題以及上報回復主題。
采集傳感數據： STM32 通過連接的傳感器（如 DHT11 溫濕度傳感器）獲取環境溫度和濕度。DHT11 通常用單總線協議，可通過定時GPIO讀取，本例略去實現細節，只假定我們得到兩個變量 float temperature 和 float humidity。初始讀取可能得到溫度25.0℃，濕度60%。
上傳數據： STM32 將上述值封裝 JSON，通過 AT+MQTTPUB 發布至 OneNet。發布內容：
```
{"id": "1", "params": { "temp": { "value": 25.0 }, "humi": { "value": 60.0 } } }
```
OneNet 收到后會回應一個確認到 $sys/.../post/reply，ESP8266 收到打印，STM32讀取到 "code":0，表示上報成功。此時在 OneNet 平臺，這臺設備的 temp 數據流和 humi 數據流各新增了一個數據點 25.0 和 60.0。
周期運行： STM32 設置一個定時，比如每隔10秒執行一次溫濕度采集并上報。這樣設備會持續地將環境數據發送到云端，云端形成時間序列數據。在等待間隔時，STM32也保持監聽ESP8266串口以捕獲可能的下行指令。
接收控制命令： 當用戶在App上按下“打開LED”時，會觸發云端下發。具體過程見后文App側。此時 OneNet 平臺會向 $sys/pid/dev/thing/property/set 發送:
```
{"id": "100", "params": { "LED": { "value": 1 } } }
```
ESP8266輸出：
```
+MQTTSUBRECV:0,"$sys/pid/dev/thing/property/set","{"id":"100","params":{"LED":{"value":1}}}"
```
STM32 UART收到后，解析出 LED value = 1。它隨即設置連接在 PB1（舉例）的LED GPIO 輸出高點亮 LED。然后構造回復 JSON：
```
{"id": "100", "code": 200, "msg": "success"}
```
并通過 AT+MQTTPUB 發送到 $sys/pid/dev/thing/property/set_reply 主題。OneNet 平臺接收到回復，確認設備已執行命令。
狀態上報（可選）： STM32 也可以選擇在執行命令后，將LED的新狀態通過屬性上報機制通知平臺。例如再發布一次屬性：
```
{"id":"2","params":{ "LED": { "value": 1 } } }
```
這樣平臺上也有 LED 狀態的數據流更新。這在需要記錄設備狀態的應用中很有用。不過若只是瞬時動作也可以不必每次都上報。
等待其他指令或定期上報： LED 打開后，設備繼續每10秒上報溫濕度。假如一段時間后，用戶在App點擊“關閉LED”，流程類似以上，再將 LED value=0 下發，設備熄滅LED并回復。

設備端的整個邏輯可以用偽代碼描述如下：

while(1) {if(time_to_sample) {read_temperature_humidity(&temp, &humi);send_mqtt_property_post(temp, humi);reset_timer();}if(uart_received_flag) {parse_uart_buffer();if(received_topic == PROPERTY_SET) {if(cmd.LED.value == 1) {HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET);} else {HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET);}send_mqtt_set_reply(cmd.id, 200);}clear_uart_flag();}// ... (other tasks)
}

7.2 云端平臺過程

當設備上線并訂閱主題后，OneNet 將設備標記為“在線”，設備管理列表中可見在線狀態。隨后每次設備發布數據點，OneNet 平臺都會驗證數據格式并存儲。如果數據對應物模型屬性，則在設備詳情的屬性標簽頁顯示最新值和歷史趨勢圖。開發者中心也可以通過數據瀏覽API調試看到原始JSON。
平臺接收到 thing/property/post 上報，返回 result code=0。如有訂閱post/reply的設備則收得到。
平臺在設備屬性發生變化時，可觸發觸發器或推送（這里沒深入）。
當 App 或用戶通過平臺下發控制時，平臺將指令推送至設備的 MQTT 連接。在OneNet Studio界面，如果使用“在線調試”的“設置設備屬性”功能填寫 LED=1，也會以相同機制發送命令。App 通過HTTP接口發送時，平臺收到HTTP請求，立即在后臺把消息轉發到設備 MQTT連接上的property/set主題。
平臺等待設備在超時時間內（比如默認3秒）回應 set_reply。如果收到 code=200，則在平臺UI上顯示執行成功；若超時未收到，平臺可認為設備可能未在線或未執行，這時UI/接口會給出相應反饋（如設備無響應）。
平臺將 LED 屬性新值存儲更新。所以App再查詢 LED 狀態就會看到value=1。

7.3 移動 App 端過程

初始化： 用戶打開手機App（假設已經實現好UI界面，包括顯示溫濕度的文本和一個LED開關按鈕）。App 內可能寫死或從用戶配置得到設備ID和 APIKey。
獲取最新數據： App 啟動時調用 OneNet HTTP GET 接口獲取溫濕度。拿到返回 JSON 后解析出value，例如溫度25.0、濕度60.0，更新界面顯示“25.0°C, 60%”。App 可以每隔 10秒自動刷新一次，以跟蹤變化 (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客) (APP通過http獲取OneNet數據與命令下發〖應用層〗_onenet下發內容-CSDN博客)。
控制操作： 當用戶點擊LED開關（比如一個toggle按鈕從OFF滑到ON），App捕捉到事件，構造HTTP請求：
```
POST http://api.heclouds.com/mqtt?topic=$sys/pid/dev/thing/property/set&device_id=123456789
Header: api-key: <APIKey>
Body: {"id":"app1","params":{"LED":{"value":1}}}
```
并發送。OneNet返回一個 HTTP響應 JSON：
```
{ "errno": 0, "data": {}, "error": "succ" }
```
表示平臺已將消息發出 (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)（注意，這不代表設備執行成功，只是發送成功）。
等待結果： 為了確認設備是否真的打開LED，App 可以在發送幾秒后再次 GET 設備屬性或者設備LED狀態數據流。由于我們的設備在執行后可能上報LED狀態（如果實現了），那么大約1-2秒后，OneNet 平臺的 LED 數據流就更新為1，App 下一次拉取會得到 LED value=1，于是可以在UI上將LED狀態顯示為“已打開”。如果應用需要即時反饋，也可以在按下按鈕后，暫時假定成功改變UI狀態，但最好在一定時間后核實。
用戶觀察： App 上看到溫濕度在定時刷新，比如逐漸溫度變化。用戶再次操作LED按鈕關閉LED，App發送value=0，下發OneNet。設備執行后LED熄滅。下次App拉數據發現LED狀態變0，于是同步UI。

整個流程打通后，我們實現了一個完整的IoT應用：STM32采集環境數據上云 -> 云端存儲并提供查詢 -> 移動端獲取數據顯示 -> 移動端發送控制指令 -> 設備執行并反饋，閉環完成。

7.4 常見問題與解答

問1: 為什么 STM32 一直無法連上 OneNet MQTT，AT+MQTTCONN 收到 ERROR 或一直超時？
答: 可能原因很多：

檢查產品ID、設備ID、APIKey 是否對應正確 (連接onenet云mqtt報文_183.230.40.96-CSDN博客)。尤其別把設備ID和產品ID弄混。設備ID一般是純數字，產品ID可能是數字或長度較短字符串。
如果使用 Token 作為密碼，要確保 Token 正確生成且未過期 (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)。Token 的 et(過期時間)默認可能很短或需要自行設定較長時間。
端口和服務器地址要匹配。如果用183.230.40.39，端口必須6002；用mqtt.heclouds.com則建議端口1883。若固件不支持域名，可以用IP。
MQTTUSERCFG 的 cleansession 參數要與 MQTTCONN 的 clean session 保持一致，否則會連不上。有的固件實現要求這個匹配（例如都用1）。
檢查 ESP8266 是否早先有保持的連接沒有斷開。可以在嘗試前 AT+MQTTCLEAN=0 斷開舊連接（若支持），或干脆復位模塊再連。
確認你的 OneNet 產品的接入協議確實是 MQTT，設備也在MQTT列表里。如果產品是HTTP類型，用MQTT連接可能會被拒絕協議不匹配。

問2: ESP8266 AT 指令總是返回 weird symbols 或 ERROR？
答: 如果收到亂碼，可能是波特率不對。ESP8266 默認波特率常為115200；確認 STM32 USART 初始化也設為115200 (STM32與物聯網01-ESP8266基本操作 - 博客園)。若還是亂碼，可以嘗試降低ESP8266的波特率來匹配STM32，比如先用串口調試工具連ESP8266發送 AT+UART=9600,8,1,0,0 將其改為9600, 然后STM32也配置9600通信。
如果返回ERROR多出現在發送長命令時，可能是命令格式有誤或串口數據丟失。要確保字符串沒有拼寫錯誤且包含必要的引號和逗號。此外檢查ESP8266接收緩沖是否足夠處理長命令（如MQTTPUBRAW發送時注意分兩步）。另外，先發的指令沒結束響應又發下一個也會引發 ERROR，因此必須串行等待上條命令OK后再發下一條。可以在指令間加入適當延時 (STM32使用esp8266的AT指令連接mqtt服務器，以Thing Cloud為例（標準庫和HAL庫）_stm32 mqtt at指令-CSDN博客)。

問3: 數據上報成功了，但在 OneNet 平臺看不到曲線或數據？
答: 首先，用 OneNet 開發者中心的“設備調試”或API調試工具查看設備是否有數據。如果 MQTT 連接和上報都OK，檢查 JSON 格式和數據類型：OneNet 區分數據類型（數值、字符串等），如果物模型里屬性定義為數值，你上傳的 JSON value必須是數值而非字符串，否則平臺可能拒絕入庫。另一個可能原因：OneNet Studio需要你先為產品添加**數據流模板（物模型）**才能在可視化中看到圖表。如果沒定義過數據流，OneNet老平臺會自動根據首次上報創建數據流，但新Studio里盡管數據收到了，也許不會顯示曲線，除非在物模型里注冊該屬性。建議提前在產品的“數據流模板”里添加 temp 和 humi 屬性。
如果以上都檢查過還是無數據，考慮設備APIKey權限。若用Master APIKey上傳HTTP數據，要在請求Header帶對的 key (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)。對于 MQTT 上報，只要連上成功一般不會有權限問題。可嘗試用 MQTT.fx 工具模擬上傳看平臺表現，以分辨問題出在設備端還是平臺端。

問4: HTTP 獲取數據時返回 {"errno":10, "error":"key invalid"} 或類似錯誤？
答: errno=10表示 APIKey 無效或沒有權限。請檢查HTTP請求Header中的 api-key 是否正確（注意不要拼成 apikey 或 Api-Key，必須全小寫中間有連字符） (輕松使用中移物聯網平臺Onenet，MQTT協議快速接入實驗 - ThingsKit)。并確認使用的Key對應設備。若設備ID與APIKey不匹配，也會無權限（比如用A設備的APIKey去查B設備的數據）。可以在 OneNet 控制臺的設備管理中點設備詳情，看右上角是否可以獲取該設備的APIKey，或者使用產品的 Master APIKey嘗試。如果Master Key也提示無效，可能是key填錯或已失效（OneNet某些操作需要先激活產品）。
另外，如果你的HTTP請求用了 https://open.iot.10086.cn/studio/http 之類的新域名，則不能用APIKey，要改用Token鑒權 (最新版Onenet云平臺HTTP協議接入上傳數據_onenet物聯網postman軟件-CSDN博客)。建議使用api.heclouds.com方便。

問5: 移動App能否直接用MQTT而不是HTTP？
答: 當然可以。App 其實也能作為 MQTT 客戶端連接 OneNet Broker（用手機流量/WiFi），只要提供正確的產品ID/設備ID/APIKey。但通常手機App不被視為OneNet的“設備”，而是一種應用。如果App以設備身份MQTT接入，會占用一個設備ID，而且OneNet沒有針對應用的MQTT通道，只能讓App也作為同產品下的“另一設備”加入。這帶來管理和安全的復雜度，不如調用HTTP API方便。因此常見實踐是：設備用MQTT，App用HTTP。不過OneNet也允許第三方服務器通過MQTT訂閱設備數據實現實時推送功能，如果需要，可以研究 OneNet 提供的應用MQTT接口或者結合使用OneNet的MQTT橋接能力。對于本案例，HTTP 足矣，實時性要求不高且實現簡單。

問6: STM32 處理 MQTT 下行消息時有時解析不完整，可能丟字符，怎么辦？
答: 這可能因為 UART 接收緩沖過小或處理不及時。如果命令JSON較長，而STM32沒有用中斷/DMAdma持續接收，很可能丟失部分數據。建議開啟UART空閑中斷，將每次接收的數據放入循環緩沖，然后解析一整幀。也可考慮降低ESP8266的UART發送速度或拆分消息。因為ESP8266收到MQTT消息后，一次性通過串口吐出，對于72MHz MCU還是能處理的，只是要確保接收中斷優先級高且處理快。可以簡單做法：利用 '\n' 換行判斷一條消息結束，然后處理。OneNet的MQTTURC一般一條消息就是一行。

問7: 能否在 OneNet 平臺直接讓設備把數據轉發到我自己的服務器？
答: OneNet 提供數據轉發和HTTP觸發器等功能，可以配置當設備上傳數據或事件發生時，平臺自動向你的業務服務器發送HTTP POST通知。這屬于OneNet更高級的應用功能。對于初學者，先實現基本的云存儲和查詢較好。如果將來要大規模部署設備，并在自己服務器匯總處理數據，可考慮使用 OneNet OpenAPI 拉取數據，或配置觸發器使OneNet推送數據到指定URL。詳細可以查閱OneNet開放平臺文檔中的“數據轉發”和“觸發器”章節。

至此，我們完整地介紹了 STM32F103C8T6 + ESP8266-01 連接 OneNet 平臺并通過 MQTT/HTTP 進行數據通信的流程。從 OneNet 平臺準備、硬件連接、固件指令、到STM32代碼邏輯、再到應用層接口都進行了說明和示例。希望通過本指南，讀者能夠搭建起自己的物聯網小系統，實現設備數據上云和遠程控制。OneNet 平臺功能豐富，在掌握上述基礎后，可以進一步探索如：數據觸發報警、設備分享、更多傳感類型接入、以及結合微信小程序等擴展，實現更加完善的物聯網應用。