企业官网建设流程全解析

下班路上最想干的一件事，就是先把家里的空调打开、把灯点亮，进门不用摸黑。这个念头最终催生了这套 STM32 + 华为云IoT + Qt 的跨平台智能家居控制系统：设备端用 STM32 采集温湿度、光照，控制继电器；云端选华为云IoT平台负责设备接入、消息路由、设备影子；控制端用 Qt 写跨平台客户端，Windows、Linux、macOS 都能跑同一套代码。这篇东西不是跑通一个 Demo 就收工的玩具，而是我从选型、架构、设备端固件、云平台配置、Qt 客户端到联调排错的全过程记录。适合正在折腾 STM32 上云、卡在 MQTT 鉴权、或者 Qt 界面里死活刷不出设备数据的同学。看完你至少能复刻出一套远程看温湿度、远程开关继电器的完整系统。

1. 选型逻辑：为什么不用"傻瓜方案"，非要用三层架构

1.1 主控：从几块钱芯片到一块能干活的最小系统

平时聊智能家居，最常见的选择其实是买现成的智能插座和网关，APP 一绑定就完事。但那种方案最大的问题是你只能按照厂商设定的逻辑玩，想加一个"根据光照自动开灯并把状态同步到桌面端"的联动，几乎不可能。自己从 STM32 做起，核心原因就三个：可编程、可扩展、可学习。

STM32F103C8T6 这个级别的芯片，一片几块钱，片上集成了 USART、I2C、ADC、GPIO、PWM，做智能家居的数据采集和控制刚好够用。配合 STM32CubeMX 生成工程，底层的时钟树、引脚复用、外设初始化全都不用自己抠寄存器，写业务代码的时间比原来少了三分之一。

第二个理由是它的生态太成熟了。HAL 库、老牌调试器、网上大量开源例程，遇到问题基本搜得到答案。对一个人维护的 домашний 项目来说，这意味着低试错成本。后面想升级到 F407 甚至 H7 系列，代码迁移成本也不高，外设接口基本一致。

1.2 云端：别自己搭服务器，平台帮你兜住消息与连接

设备端联网之后，数据要往哪送？最原始的做法是自己买一台服务器或者用家里的电脑开一个 MQTT Broker，做端口映射，再写一层设备管理。这个路线不是不行，但你会被一堆"不该你操心"的事情拖住：Broker 崩了怎么办、证书怎么配、设备离线怎么感知、数据要不要存历史、App 怎么安全地访问。

华为云IoT 这类平台本质上是把这些脏活累活全包了。你不需要自己在公网维护任何服务，只要照着平台的协议把设备接进去，设备鉴权、消息 Topic、设备影子、规则引擎、在线日志都有现成的。最值钱的我认为是设备影子，它相当于云端给每个设备放了一个"状态寄存柜"，现场设备把最新状态放进去，客户端随时来取，两边不用同时在线。

对个人项目来说，平台本身有免费或低成本的额度，学习阶段跑测试绰绰有余，等真正上量再考虑商用的钱也不迟。

1.3 客户端：Qt 让同一套代码跑遍桌面端

客户端这块，我用 Qt 而不是 Web 页面或 Electron，主要是因为它和嵌入式生态天然贴合。C++ 调自家平台 API、和底层硬件逻辑共享同一套概念，排查问题的时候不用来回切换语言思维。

Qt 的跨平台不是"网页套壳"，而是真正的原生控件加自绘引擎。同一份代码在 Windows 上编译出 exe，在 Linux 上编译出可执行文件，在 macOS 上打包成 app，UI 用的是同一套 QSS/QML 描述，不用给每个平台单独写界面。对智能家居控制台这种密度不高、但要求响应快的界面，Qt Widgets 或 Qt Quick 都足够，而且它可以不加浏览器内核就有一个像样的界面，部署体积小很多。

当然也有代价——Qt 的许可和打包链路需要花点时间摸熟，这部分我在后面第六节专门讲。

做个方案对比，大家心里更有数：

2. 系统架构与数据契约：动手前先把路画出来

2.1 三层三端的角色划分

很多同学一上来就写代码，写到一半发现数据格式对不上，又来来回回改。我的经验是先把"谁负责什么"画清楚。这套系统一共三层，三层里一共有三个"端"：

设备端（STM32 + 传感器 + 继电器）负责采集物理世界的数据、执行物理开关动作。它只跟华为云IoT打交道，不关心你的 Qt 界面长什么样。

平台端（华为云IoT）负责登记设备、校验身份、转发消息、保存状态、补发离线指令。它像一个中转邮局，两端不直接通信，都通过它递消息。

客户端（Qt 应用）负责展示数据、接收用户操作、下发指令。它通过平台的应用侧 API 读取设备影子和下发命令，不直接连接 STM32。

这个分工的意义在于：任何一端坏了，其他两端都不受影响。比如 STM32 断电了，Qt 里仍然能看到"设备离线"而不是直接报错；Qt 没打开，设备端照常上报，影子会存着最新值。

2.2 一条温湿度数据从传感器走到 Qt 界面的完整链路

把链路走一遍，你就能理解每个环节的作用。假设 STM32 刚读完 DHT11：

1. DHT11 返回温湿度原始数据，STM32 校验完数据合法性。
2. STM32 把数值拼成符合平台格式的 JSON，通过串口发给 WiFi 模组。
3. WiFi 模组以 MQTT 协议发布到 Topic，报文进华为云IoT平台。
4. 平台校验设备身份、解析 JSON，将属性值更新到设备影子。
5. Qt 客户端每隔几秒调用平台的查询接口，读取设备影子。
6. Qt 解析 JSON 后发信号刷新界面上的温度、湿度曲线。

反向的指令链路同理：用户在 Qt 点"开灯"→ 客户端调用平台命令下发接口 → 平台把命令包成 MQTT 消息推到设备的订阅 Topic → STM32 收到后控制继电器 → STM32 再把新状态上报回影子 → Qt 下次轮询时看到的开关状态就变了。

这里有个关键点：两端永远是"订阅/查询"关系，而不是"长连接互捅"。这也是我坚持走平台而不是局域网直连的原因——我在办公室登录 Qt，家里的设备在卧室，中间经过平台转发，完全不需要公网 IP 和 NAT 映射。

2.3 物模型与 Topic 规划：先定义"字典"再写代码

华为云IoT 里有个概念叫物模型，通俗讲就是"平台的字典"。它规定了这个设备有哪些服务、每个服务有哪些属性、支持哪些命令。STM32 上报数据时用的是属性名，Qt 下发命令时用的是命令名，两边要完全对得上，否则平台直接丢弃或报格式错误。

所以动手写固件之前，我强烈建议先把物模型的 JSON 草稿写出来，哪怕写在记事本里都行。下面是我这个项目用到的简化定义，两个服务：Sensor 负责环境数据，Switch 负责继电器控制。

{ "services": [ { "service_id": "Sensor", "properties": [ { "property_name": "temperature", "data_type": "int", "min": -20, "max": 80, "step": 1, "unit": "℃" }, { "property_name": "humidity", "data_type": "int", "min": 0, "max": 100, "step": 1, "unit": "%" }, { "property_name": "light", "data_type": "int", "min": 0, "max": 65535, "step": 1, "unit": "lux" } ], "commands": [ { "command_name": "set_relay", "paras": [ { "para_name": "relay", "data_type": "int", "min": 0, "max": 1 } ] } ] } ] }

Topic 是平台的"邮路"。设备上报属性固定走$oc/devices/{device_id}/sys/properties/report，订阅命令固定走$oc/devices/{device_id}/sys/commands/#。这些 Topic 是平台规定好的，不能自己发明，{device_id}要替换成控制台里那个完整的设备 ID（一般是"产品ID_设备标识"）。

把物模型和 Topic 定下来之后，写代码就是照着字典填空，后面联调出的问题会少一大半。

3. STM32 设备端实战：从裸机到第一条 MQTT 消息

3.1 器件清单与引脚规划

我这个项目用的器件都很常见，清单供参考：

引脚规划我建议这样：DHT11 数据脚接 PA7；BH1750 走 I2C1 的 PB6/PB7；继电器的控制脚接 PC13 或 PA1（注意模块触发电平，常见是低电平触发，接反会导致上电误动作）；ESP8266 通过 USART2 的 PA2/PA3 通信，波特率 115200；USART1 的 PA9/PA10 留给串口打印调试。给继电器模块供电时务必单独用外部 5V，不要从 STM32 板子的 3.3V 引脚取，否则继电器吸合瞬间的电流波动会把单片机拉死机。

3.2 联网模组选择：AT 固件透传最省心

联网方案我推荐用 ESP8266 的 AT 固件，原因很简单：STM32 不需要自己去实现 MQTT 协议栈和 TCP/TLS。ESP8266 模块上电后，STM32 通过串口发 AT 指令让它连接 WiFi，再发 AT+MQTT 系列指令完成 MQTT 连接和发布订阅，消息推送由模块主动上报给串口。这就把复杂的协议栈全部隔离在模组内部，MCU 代码量小、稳定性高。

市面上 ESP8266 模组出厂固件可能版本不一，建议先用串口助手验证是否支持AT+MQTTUSERCFG、AT+MQTTCONN、AT+MQTTSUB、AT+MQTTPUB这几条指令。不支持就重新刷一遍 AT 固件。整个联网流程如下，先把 WiFi 连上，再做 MQTT 配置和连接：

AT+CWMODE=1 AT+CWJAP="你的WiFi名","你的WiFi密码" # 等待返回 WIFI GOT IP AT+MQTTUSERCFG=0,1,"clientId","username","password",0,0,"" AT+MQTTCONN=0,"平台接入地址",1883,1

注意，不同版本 AT 固件对AT+MQTTUSERCFG的参数顺序略有差别，务必以你手上固件的指令表为准。连接成功后，订阅命令 Topic、发布属性数据：

AT+MQTTSUB=0,"$oc/devices/你的完整设备ID/sys/commands/#",1 AT+MQTTPUB=0,"$oc/devices/你的完整设备ID/sys/properties/report",1,"{\"services\":[{\"service_id\":\"Sensor\",\"properties\":{\"temperature\":26,\"humidity\":58}}]}",0

如果平台返回拒绝连接，八成是下面的鉴权参数算错了，这是整个项目里最容易卡住的地方。

3.3 鉴权参数计算：华为云IoT的 MQTT 密码到底怎么来

华为云IoT 的设备接入鉴权，不是直接用设备密钥当 MQTT 密码，而是用"密钥 + 时间戳"做 HMAC-SHA256 动态摘要。这样即使通信被人截获，密码也在不断变化，不能重放。三个字段的生成规则如下：

完整代码逻辑大概长这样，HMAC-SHA256 函数你可以直接用嵌入式库里现成的实现，或者编译一个独立的 hmac_sha256 小文件：

static void build_mqtt_auth(const char *device_id, const char *secret, char *client_id, char *username, char *password) { uint64_t ts_ms = get_epoch_ms(); // 毫秒级 Unix 时间戳 char ts[24]; snprintf(ts, sizeof(ts), "%llu", (unsigned long long)ts_ms); uint8_t digest[32]; char hex[65]; hmac_sha256((const uint8_t *)secret, strlen(secret), (const uint8_t *)ts, strlen(ts), digest); bytes_to_hex_lower(digest, 32, hex); snprintf(client_id, sizeof(client_id), "%s_0_0_%s", device_id, ts); snprintf(username, sizeof(username), "%s", device_id); snprintf(password, sizeof(password), "%s_%s", hex, ts); }

这里有个大坑：毫秒时间戳从哪里来？STM32F103 内部没有 RTC 秒级时钟，更别说毫秒。别自己瞎估一个基准时间，平台那边校验不通过。我的做法是：WiFi 连上后先让 ESP8266 去 NTP 服务器同步一次时间，拿到当前 Unix 秒，再叠加 SysTick 维护的毫秒计数，凑成毫秒时间戳。AT 指令一般长这样：

AT+CIPSNTPCFG=1,8,"一个公共NTP服务器地址" AT+CIPSNTPTIME? # 返回类似 +CIPSNTPTIME: Thu Jul 04 10:15:30 2024

如果你用的是已经集成了 SNTP 的 WiFi 方案，直接在模组侧读时间也行。核心原则就一句话：用来算 HMAC 的时间戳必须来自真实时钟，不能是拍脑袋从 1970 年开始数的假时间。

3.4 裸机状态机：上报、订阅、断线重连一锅端

STM32 端我不建议为了这个项目硬上 RTOS，用裸机状态机就够清爽。整个设备端的行为可以拆成几个状态，每个状态做一件事：

• NET_INIT：初始化串口、GPIO、传感器。
• WIFI_JOIN：发 AT+CWJAP，轮询等待WIFI GOT IP。
• NTP_SYNC：同步时间，生成后续鉴权用的时间基准。
• MQTT_CONN：计算 clientId/username/password，发 AT+MQTTCONN。
• SUB_CMD：订阅$oc/devices/{device_id}/sys/commands/#。
• READY：周期采集、发布属性；同时处理串口收到的命令推送。

READY 状态里一个 5 秒周期的采集中断即可：读 DHT11 和 BH1750，组 JSON，调用 AT+MQTTPUB。串口回环收到的+MQTTSUBRECV行则交给解析函数。

命令推送的原始格式长这样：

+MQTTSUBRECV:0,"$oc/devices/你的设备ID/sys/commands/request_id=123456",78,{"object_device_id":"你的设备ID","command_name":"set_relay","service_id":"Switch","paras":{"relay":1}}

STM32 拿到后要做两件事：先按行缓存解析出 payload 里的command_name和paras，执行对应动作；然后向响应的 Topic 发一条回执，告诉平台"我收到了并执行了"。用 cJSON 之类轻量解析库即可：

cJSON *root = cJSON_Parse((char *)payload); cJSON *paras = cJSON_GetObjectItem(root, "paras"); cJSON *relay = cJSON_GetObjectItem(paras, "relay"); if (relay && relay->valueint == 1) { HAL_GPIO_WritePin(RELAY_PORT, RELAY_PIN, GPIO_PIN_RESET); report_relay_status(1); } cJSON_Delete(root); // 回复平台 // AT+MQTTPUB=0,"$oc/devices/设备ID/sys/commands/response/request_id=123456",1,"{...}",0

断线重连是设备端最容易写崩的地方。我的建议是：不要一失败就猛连，用一个退避策略，失败次数越多，重连间隔越长，比如 2 秒、4 秒、8 秒……封顶 60 秒。每次重连都要把"连 WiFi—同步时间—MQTT 鉴权—订阅 Topic"整套流程重新走一遍，别只重连 MQTT 而不管 WiFi 状态。

4. 华为云IoT控制台配置：产品、设备与调试三板斧

4.1 创建产品并定义物模型

进入华为云IoT平台控制台后，第一步是创建产品。选 MQTT 协议，节点类型选"直连设备"即可。创建完产品后，在"产品—模型定义"里把前面草稿的物模型配进去。控制台支持可视化逐个添加服务和属性，也可以直接导入 JSON 模型。

我强烈建议你逐步添加而不是一次性导入大 JSON，因为控制台会自动检查字段合法性，比如service_id不能以数字开头、属性名不能包含下划线以外的特殊符号。如果后面 STM32 上报时平台一直提示"service not exist"，多半就是这里定义的 service_id 和固件里 JSON 的 service_id 没对上。

4.2 注册设备与密钥管理

产品建好后，在产品下添加设备。填写"设备标识"时可以自己起一个，比如home_gateway_01。注册完成后，平台会生成一个"设备ID"和"设备密钥"，这两个值就是上一节鉴权代码里的device_id和secret。

提示：设备密钥在注册成功后只完整展示一次，页面关掉就再也看不到了。我建议当场把密钥存到本地一个加密的文本文件里，或者至少抄在不会被别人看到的地方。丢了密钥只能重新注册设备，前面的调试记录全部作废。

另外注意区分两个 ID："设备标识"（nodeId）是你自己起的用于接入的别名；"设备ID"是平台生成的完整 ID，形如产品ID_设备标识，MQTT 的 username 和 Topic 里用的都是后者，不要搞混。

4.3 设备影子与在线调试：不写代码也能先验证链路

平台的价值在调试阶段最能体现。设备接进去后，你在控制台"设备详情"里能看到"设备影子"页面，里面会实时刷新设备上报的属性。这里有个非常实用的验证顺序：

1. 先用控制台自带的"在线调试"功能模拟设备上报一条属性。如果模拟上报成功，说明平台侧产品和模型没问题。
2. 再用真实 STM32 上报。如果真实设备上报成功但影子没更新，说明问题出在你设备端的 Topic 或 JSON 格式。
3. 最后用控制台的"命令下发"按钮向设备发一条set_relay命令，观察 STM32 是否收到。

这套顺序能把问题快速定位到"设备端"还是"平台端"，避免两个人互相甩锅的局面。平台的"消息跟踪"和"运行日志"也要用起来，上报失败时日志里会给出非常具体的错误原因，比如"password not match"或"payload format error"，比瞎猜高效得多。

5. Qt 跨平台客户端：影子轮询、命令下发与界面刷新

5.1 两种接入姿势：为什么我推荐 REST 轮询而不是 MQTT 直连

Qt 客户端和平台通信，主流有两条路：一是走平台的应用侧 REST API，客户端定时查询设备影子、调用命令下发接口；二是让 Qt 也以 MQTT 设备身份接入平台，直接订阅设备消息。我最终选了 REST 轮询。

原因很现实：如果 Qt 以 MQTT 设备身份接入，它订阅的是自己这个"设备"的 Topic，没法直接订阅另一个物理设备的系统 Topic，平台机制不允许跨设备订阅。确实可以在平台规则引擎里把数据再转发出来，但配置链路一下子复杂了好几倍。而 REST API 是给"应用"用的，本来就是用来做这种上位机客户端的，轮询设备影子在几秒级别的刷新周期下体验完全够用，代码也短很多。

5.2 登录鉴权与请求封装：Token 管理、轮询与异常重试

Qt 端调用平台 API 需要先登录获取临时 Token。整个过程是：用平台账号信息调用认证接口拿到 Token，之后每次请求都在 HTTP Header 里带X-Auth-Token。Token 有有效期（一般是 24 小时），过期后接口会返回 401，客户端的请求封装里要捕获这个状态码，重新登录拿到新 Token 再重试一次。

我建议封装一个CloudApiClient类，统一处理：BaseUrl、Token 刷新、超时、错误码映射。核心请求就两个：

读取影子：

QNetworkRequest req(QUrl("https://{平台接入地址}/v5/iot/{项目ID}/devices/{设备ID}/shadow")); req.setRawHeader("X-Auth-Token", token.toUtf8()); QNetworkReply *reply = manager.get(req); connect(reply, &QNetworkReply::finished, this, [=]() { QByteArray body = reply->readAll(); QJsonDocument doc = QJsonDocument::fromJson(body); // 从响应中解析 reported 区段，得到最新温湿度和开关状态 reply->deleteLater(); });

下发命令：

QJsonObject paras; paras.insert("relay", 1); QJsonObject cmd; cmd.insert("command_name", "set_relay"); cmd.insert("service_id", "Switch"); cmd.insert("paras", paras); QNetworkRequest req(QUrl("https://{平台接入地址}/v5/iot/{项目ID}/devices/{设备ID}/commands")); req.setHeader(QNetworkRequest::ContentTypeHeader, "application/json"); req.setRawHeader("X-Auth-Token", token.toUtf8()); manager.post(req, QJsonDocument(cmd).toJson());

5.3 线程模型：别把 HTTP 请求塞进 UI 线程

Qt 客户端最容易犯的错，是在 UI 线程里用同步方式调用网络。QNetworkAccessManager 本身是异步的，回调在事件循环里触发，这没问题。但如果你图省事直接manager.get(...)然后调用waitForFinished()阻塞等待，界面就会在请求期间完全卡死，转圈都转不动。

我的做法是：用一个专门的后台工作对象管理轮询 Timer，每 2 秒触发一次影子查询，把解析好的数据通过信号发回界面线程。信号里只传值对象或共享指针，不要在界面线程里直接操作工作线程的成员。轮询还有个隐藏问题：如果上一次请求还没返回，下一个 Timer 又触发了，会堆积大量并发请求。解决办法很简单，用一个isFetching标志防止重入，或者用单次定时器QTimer::singleShot在回调返回后再调度下一次查询。

5.4 从数据到面板：仪表、曲线与开关的联动

界面我用 Qt Widgets + QSS 做的，核心区域三块：左侧环境面板显示温湿度数值，用 Qt Charts 画 24 小时曲线；中间是继电器开关面板，QPushButton 可点击；右侧是事件日志，记录每一条上报和命令记录。

数值展示不要直接刷新整块区域，单独更新对应的 QLabel 文本即可。曲线数据维护一个固定长度的环形缓冲，新数据来了就 append，超过窗口长度就丢弃最旧的，图表刷起来非常平滑。

开关按钮的交互逻辑注意一个细节：用户点下去之后，按钮先进入"下发中"状态并禁用，等平台返回命令下发结果，再通过下一次影子轮询拿到设备实际状态后，才把按钮设置成最终状态。这样即使命令丢了你也不会误以为操作成功了。

6. 联调排错全记录：我踩过的坑和整套排查方法

6.1 设备一直显示"未激活"，问题出在时间戳

第一次把固件烧进去，控制台上设备状态死活是"未激活"，消息跟踪里显示 MQTT 连接被拒绝。排查过程我按下面几步走：

第一步，查平台日志，错误码指向鉴权失败。第二步，检查 username 和 clientId 格式，确认用的是完整设备ID而不是 nodeId。第三步，检查 password 生成逻辑，发现我本地模拟时间戳用的是秒而不是毫秒，而且没有做 NTP 校准。把时间戳改成毫秒并让模组先同步 NTP 后，设备状态立刻变更为"在线"。

这个坑很典型，平台文档里说的是"毫秒时间戳"，日志里也提示密码错误，但不会告诉你"你的时间并不准"。记住：HMAC 的时间戳必须来自真实时钟，差太多同样会被判定无效。

6.2 控制台能看到数据，Qt 客户端却刷不出来

设备上线、影子也更新了，但 Qt 界面一直是空。我在 Qt 端加了调试输出才发现，影子查询接口返回的 JSON 结构和我想的完全不一样：服务列表是数组，属性嵌在properties对象里，而且历史影子可能有多条记录。直接用doc["temperature"]取当然什么也拿不到。

解决方法是把影子响应先打印出来，对着真实返回结构写解析代码，不要凭文档猜。这类问题几乎都是"我以为是这个结构"和"实际是那个结构"的错位。建议在解析器写完后，用一个固定的测试 JSON 文件跑单测，以后改结构不会把解析写坏。

6.3 继电器收不到指令，或者时灵时不灵

命令下发失败分几种情况。一是设备离线，平台默认命令不缓存，离线期间下发的指令直接丢失，Qt 端会返回超时。要保存"离线也能执行"的语义，应该在平台开启命令缓存并设置合理过期时间。二是 Topic 订阅没成功，检查 STM32 是否真的执行了AT+MQTTSUB，并且收到过+MQTTSUBRECV推送；如果只订阅没收到过推送，先看订阅返回码是否为 0。三是 QoS 语义问题：我一开始上报和订阅都用 QoS 0，WiFi 环境一抖动消息就丢，后来属性和命令订阅都改成 QoS 1，丢消息情况明显减少。

这类排查的通用套路是"先看平台日志，再看模组串口，最后怀疑代码"。平台日志能告诉你命令有没有发出去，模组串口能告诉你命令有没有到达，两边一对比，问题在中间哪一段就清楚了。

6.4 跨平台编译与部署：同样一份代码，三套系统都要伺候

Qt 跨平台最大的幻觉是"一次编写到处编译"，实际上每个平台都有各自的部署细节。Windows 上发布程序要跑windeployqt拷贝 Qt 运行库，否则目标机器缺 DLL；Linux 上建议打成 AppImage 或 deb 包，注意目标系统 glibc 版本不能太老；macOS 上要处理应用签名和 notarization，否则别人一打开就被系统拦。

还有两个细节容易被忽略：一是高 DPI 屏幕，务必在 main 函数最前面设置高分屏支持属性，不然在 Retina 类屏幕上字是糊的；二是 Qt Charts 等模块在安装 Qt 时要勾选，否则编译到一半报找不到头文件。我个人的经验是：每编译出一个平台的包，就在对应的真机环境里跑一次完整的"读取影子+下发命令"流程，能早发现问题，别等到给用户演示时才翻车。

最后分享一个让我少走很多弯路的小习惯：无论设备端还是客户端，都在关键节点打印带时间戳的日志。STM32 串口日志记录"发了什么、收到什么"，Qt 端记录"请求了什么、返回了什么"。两边日志各存一份，联调时放到一起按时间轴对齐，绝大多数问题都能在三分钟内定位。这套系统现在每天还在我家跑着，远程开会前看一眼客厅温度，回家路上按一下热水器开关，踏实的很。