MQTT#

Paho MQTT C Client、lwIP Socket、TLS 1.2

前置阅读:TCP、Wi-Fi STA 连接

WS53 的 MQTT 案例依赖 Wi-Fi STA。设备扫描并连接固定 AP,完成 DHCP 后调用 mqtt_publish_client(),通过 TLS 1.2 连接 MQTT Broker,发布一条 QoS 1 消息,等待交付完成后断开并释放客户端资源。

学习目标#

  • 理解 MQTT 发布/订阅模型和 Broker 的转发角色。

  • 掌握 WS53 从 STA 入网、TLS 配置、连接 Broker 到 QoS 1 发布的调用链。

  • 正确配置客户端证书、私钥、根 CA、URI、Topic、账号和消息。

  • 根据串口日志定位 Wi-Fi、TLS、MQTT 连接和消息交付问题。

基本概念#

MQTT 发布模型#

        flowchart LR
    D[WS53 设备] -->|Publish QoS 1| B[MQTT Broker]
    B -->|转发| S[云平台或订阅者]
    C[其他客户端] -->|Subscribe| B
    

设备不直接与手机或云平台建立应用连接,而是向 Broker 发布 Topic;Broker 再将消息转发给订阅该 Topic 的客户端。

WS53 实际流程#

        sequenceDiagram
    participant STA as WS53 Wi-Fi STA
    participant Broker as MQTT Broker
    participant Sub as 订阅客户端
    STA->>STA: 扫描并连接 AP
    STA->>STA: DHCP 获取 IP
    STA->>Broker: TLS 1.2 建立 MQTT 连接
    STA->>Broker: Publish Topic,QoS 1
    Broker-->>Sub: 转发消息
    Broker-->>STA: PUBACK / 交付完成
    STA->>Broker: Disconnect
    

QoS 等级#

QoS

含义

本案例

0

最多一次,可能丢包

未使用

1

至少一次,可能重复

使用,等待 Delivery Token

2

恰好一次,开销最大

未使用

QoS 1 只保证消息至少到达一次,Broker 或网络重试时可能产生重复消息。业务侧需要使用消息 ID 或幂等逻辑去重。

TLS 与 MQTT URI#

源码通过 MQTTClient_SSLOptions 配置 TLS 1.2,并将客户端证书、客户端私钥和根 CA 以内存字符串形式传入 Paho 客户端。URI 示例为:

ssl://192.168.80.50:8883

URI 中的协议必须与 TLS 配置匹配。Broker 的地址、端口、证书身份和信任链必须相互匹配;证书不应只因为“能连接”就关闭校验。

涉及 API#

API

用途

wifi_register_event_cb()

注册 STA 扫描和连接事件

wifi_sta_enable()

启用 Wi-Fi STA

wifi_sta_scan()

扫描 AP

wifi_sta_get_scan_info()

获取扫描结果

wifi_sta_connect()

连接目标 AP

netifapi_netif_find()

查找 wlan0

netifapi_dhcp_start()

启动 DHCP

MQTTClient_init()

初始化 MQTT 客户端资源

MQTTClient_create()

创建客户端并设置 Broker URI、Client ID

MQTTClient_connect()

建立 TLS MQTT 连接

MQTTClient_publishMessage()

发布一条 MQTT 消息

MQTTClient_waitForCompletion()

等待 QoS 交付完成

MQTTClient_disconnect()

断开 Broker 连接

MQTTClient_destroy()

销毁客户端

MQTTClient_cleanup()

清理 MQTT 全局资源

WS53 当前源码没有调用 MQTTClient_subscribe()、MQTTClient_setCallbacks(),也没有实现 connectionLost 回调。

案例说明#

案例简介#

STA DHCP 成功后,STA Sample 调用 mqtt_publish_client()。MQTT Client 初始化完成后,创建 Client ID 为 ExampleClientPub 的客户端,配置 TLS 1.2、Keep Alive 20 秒、Clean Session 和用户名密码,连接 g_mqtt_uri,向 g_mqtt_topic 发布 g_mqtt_publish_msg,QoS 为 1,等待最多 10 秒交付完成,然后断开并清理资源。

默认应用参数#

参数

源码默认值

说明

Client ID

ExampleClientPub

MQTT 客户端标识

MQTT URI

空字符串

必须修改,注释示例为 ssl://192.168.80.50:8883

Topic

'topic'

源码包含单引号字符,建议按 Broker 约定修改

用户名

admin

必须与 Broker 账号匹配

密码

admin

必须替换为测试或生产凭证

发布消息

'hello,world!'

源码包含单引号字符

QoS

1

至少一次

Retained

0

不保留消息

Keep Alive

20 秒

PING 心跳间隔

Clean Session

1

使用清理会话

TLS 版本

TLS 1.2

MQTT SSL 配置

交付等待

10000 ms

最多等待 10 秒

关键配置#

MQTT 选项依赖 STA Sample,配置应包含:

CONFIG_ENABLE_WIFI_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_STA_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_MQTT=y

SAMPLE_SUPPORT_MQTT 位于 sta_sample/Kconfig,并声明 depends on SAMPLE_SUPPORT_STA_SAMPLE。未启用 STA 时,MQTT 子项不能作为独立案例使用。

案例操作指导#

第一步:准备 Broker#

准备支持 TLS 1.2 和 MQTT QoS 1 的 Broker,确认:

  • Broker 地址和端口可从 WS53 所在局域网访问。

  • 服务端证书的域名或 IP 与连接配置匹配。

  • 已创建对应用户名、密码和发布 Topic。

  • 已使用订阅客户端订阅相同 Topic,便于验证消息。

第二步:填写证书和 MQTT 参数#

编辑 src/application/samples/wifi/mqtt_sample/mqtt_sample.c,整体替换以下内容:

g_mqtt_client_crt   // 客户端证书 PEM
g_mqtt_client_key   // 客户端私钥 PEM
g_mqtt_ca_crt       // 根 CA PEM
g_mqtt_uri          // 例如 ssl://192.168.80.50:8883
g_mqtt_topic        // 发布 Topic
g_mqtt_username     // Broker 用户名
g_mqtt_password     // Broker 密码
g_mqtt_publish_msg  // 发布内容

证书字符串必须保留 PEM 头尾和换行格式,每个物理行都必须符合 C 字符串语法;不能只替换星号占位正文而保留当前错误的断行。不要把真实私钥、生产证书或账号密码提交到公共仓库。

第三步:编译和烧录#

只有在第二步完成、并确认 mqtt_sample.c 中不存在未续行的 PEM 文本后,才执行构建:

fbb build ws53_liteos_app
fbb flash ws53_liteos_app

构建和烧录方法请参考快速入门。

第四步:验证 Wi-Fi 前置条件#

确认串口依次出现 STA 扫描、连接成功、DHCP start 和 STA DHCP success。只有 DHCP 成功后才会进入 MQTT Client。

典型日志包括:

[WIFI_STA_SAMPLE]::STA DHCP success.
[MQTT_SAMPLE]::Client Start...

如果目标 SSID 不存在,STA 会重新扫描;如果 DHCP 超时,STA 会回到初始化流程,MQTT 不会启动。

第五步:验证 TLS MQTT#

确认串口没有 Client init、Client create 或 Client connect failed。连接和发布成功后应看到:

[MQTT_SAMPLE]::Client will wait at most 10 seconds for publication ...
[MQTT_SAMPLE]::Client published ok,message with delivery token ... delivered!
[MQTT_SAMPLE]::Client Stop!

在订阅客户端确认收到目标 Topic 的消息,并核对消息内容。由于本案例只发布一次,不能用它验证周期上报或订阅下行指令。

代码详解#

1. 文件结构#

src/application/samples/wifi/
├── sta_sample/
│   ├── sta_sample.c       # Wi-Fi 扫描、连接、DHCP 和 MQTT 入口
│   ├── Kconfig            # MQTT 依赖 STA 的配置
│   └── CMakeLists.txt
└── mqtt_sample/
    ├── mqtt_sample.c      # TLS 配置、连接、发布和清理
    ├── mqtt_sample.h
    └── CMakeLists.txt

2. DHCP 成功后触发 MQTT#

STA Sample 的 DHCP 状态检查在获得 IP 后调用 mqtt_publish_client():

if (ip_addr_isany(&(netif_p->ip_addr)) == 0) {
    PRINT("STA DHCP success.");
#ifdef CONFIG_SAMPLE_SUPPORT_MQTT
    mqtt_publish_client();
#endif
    return 0;
}

MQTT 不是独立常驻任务;发布函数返回后,STA 流程继续结束。

3. TLS 连接配置#

ssl_opts.los_keyStore = &g_mqtt_client_crt_store;
ssl_opts.los_trustStore = &g_mqtt_ca_crt_store;
ssl_opts.los_privateKey = &g_mqtt_client_key_store;
ssl_opts.sslVersion = MQTT_SSL_VERSION_TLS_1_2;
conn_opts.keepAliveInterval = MQTT_KEEPALIVEINTERVAL;
conn_opts.cleansession = MQTT_CLEANSESSION;
conn_opts.ssl = &ssl_opts;
conn_opts.username = g_mqtt_username;
conn_opts.password = g_mqtt_password;

客户端证书、私钥和根 CA 存放在 cert_string、key_string 中,长度由 sizeof 字符串计算。

4. 发布和等待交付#

pubmsg.payload = (void *)g_mqtt_publish_msg;
pubmsg.payloadlen = (int)strlen(g_mqtt_publish_msg);
pubmsg.qos = MQTT_QOS;
pubmsg.retained = 0;

MQTTClient_publishMessage(client, g_mqtt_topic, &pubmsg, &token);
MQTTClient_waitForCompletion(client, token, MQTT_TCP_TIMEOUT_MS);

发布成功后打印 Delivery Token;无论连接、发布或等待结果如何,函数都会进入断开、销毁和全局清理路径。

5. 资源清理和错误路径#

初始化失败时调用 MQTTClient_cleanup();连接失败时跳过发布,销毁客户端;发布失败或等待超时后断开并销毁。源码没有重连循环,下一次连接需要由上层重新触发 STA/MQTT 流程。