← 返回内置版参考 · 二进制数据专题 · 全部使用指导

MQTT客户端内置版使用指导

准备与工作原理

在通信连接分类拖入内置的MQTT客户端，重命名为 MqttClient1，再加入案例中的按钮、文本输入框与一个标签 标签1。

准备自己有权限访问的 MQTT Broker；属性面板配置服务器、端口、协议和账号，每个设备使用不同 ClientID。两个客户端订阅相同主题，一个发布另一个应收到。内置版保留基础连接与文本/字节收发，不含拓展的遗嘱、自签名证书等高级入口。

案例一：连接并订阅

when 按钮_连接.Click() {
  MqttClient1.Connect(true)
}
when MqttClient1.ConnectionStateChanged(新状态, 状态文本) {
  标签1.Text = 状态文本
  if MqttClient1.IsConnected {
    MqttClient1.Subscribe("demo/status", 0)
  }
}
when MqttClient1.ErrorOccurred(操作名, 错误代码, 错误信息) {
  标签1.Text = 错误信息
}

案例二：发布并接收文本

when 按钮_发布.Click() {
  if MqttClient1.IsConnected {
    MqttClient1.Publish("demo/status", 文本输入框_消息.Text)
  }
}
when MqttClient1.MessageReceived(主题, 负载, 消息, 保留标志, 重复标志) {
  标签1.Text = join(主题, "：", 消息)
}
when 按钮_断开.Click() {
  MqttClient1.Disconnect()
}

常见问题与验收

• 先确认连接成功事件或连接属性，再订阅、发送；收到消息时检查主题/服务和实际内容。
• 对比成功与失败事件。没有消息时，核对服务器或外设端配置，不仅检查应用按钮是否被点击。
• 断开后再次连接并收发一条消息；远端离线时应显示失败或断开状态。
• 真机联机调试需包含本内置组件的新伴侣；拓展版项目的积木名称可能不同，按内置版 API核对。

完整协议背景、硬件准备及更多案例见专题文档。

完整 .aia 源码与操作指导

下载 .aia 源码

使用真实MQTT Broker，需要联网。默认TLS8886采用系统可信证书；另一组官方公开测试账号用于TCP1884。客户端ID与主题每次启动自动生成，收发只用该独立主题；数据仅为演示温度，保留消息测试后用清除按钮清理，再改主题或退出。

导入 UrsPahoMqttClientAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

MQTT通信

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 使用真实MQTT Broker，需要联网。默认TLS8886采用系统可信证书；另一组官方公开测试账号用于TCP1884。客户端ID与主题每次启动自动生成，收发只用该独立主题；数据仅为演示温度，保留消息测试后用清除按钮清理，再改主题或退出。 覆盖检查 30/30。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。

公开测试配置与硬件接入

测试地址及公开账号来自 Mosquitto官方测试服务：TLS8886无需账号，认证TCP1884使用公开的 rw / readwrite。公共测试服务会重启或维护；真实设备应用请把输入区改成自己的Broker、账号、主题，并按协议选择TCP或TLS。本页没有把公网可达检查当成手机MQTT已连接。

硬件也连接同一Broker，订阅手机界面显示的独立主题即可收到手机数据；硬件往该主题发布，手机的收到消息事件可读取原始字节。如果固件约定设备主题，请把手机输入区改成同一个主题。二进制负载直接用Payload列表交给二进制组件解析，不能先把乱码Message转回字节。

QoS下拉同时控制新订阅和完整发布，普通发布及字节发布保持组件约定的QoS0、不保留。保留消息测试仅使用自动生成的独立主题；清除按钮发空负载保留消息，针对本次记录的主题，即使输入主题改过也不会误清新主题。清除前不要继续向其他主题发保留消息。

电脑端与手机互发

安装 Python 3.9+，执行 python -m pip install paho-mqtt。将下面保存为 mqtt-peer.py，把命令中主题替换为手机界面显示的完整独立主题；例如：

python mqtt-peer.py fun123/component-case/你的客户端ID/sensor

手机使用默认TLS8886配置。电脑显示“已订阅”后输入 text 电脑温度23.5 或 hex A5 01 02 DC 05，手机先订阅同一主题，即可看到真实消息；手机发布时电脑会打印收到的原始字节。输入 quit 退出。若手机切换认证TCP1884，电脑命令也加 --tcp --port 1884 --user rw --password readwrite。这些是官方公开测试凭据；自建服务请填写自己的配置。

#!/usr/bin/env python3
"""MQTT电脑对端：订阅手机实际主题，打印原始负载，按输入发布文本或字节。"""
import argparse
import threading
import uuid
import paho.mqtt.client as mqtt


def main():
    参数 = argparse.ArgumentParser(description=__doc__)
    参数.add_argument("topic", help="复制手机界面的完整独立主题")
    参数.add_argument("--broker", default="test.mosquitto.org")
    参数.add_argument("--port", type=int, default=8886)
    参数.add_argument("--tcp", action="store_true", help="使用普通TCP；否则启用系统CA验证的TLS")
    参数.add_argument("--user", default="")
    参数.add_argument("--password", default="")
    设置 = 参数.parse_args()
    客户端 = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="desktop-peer-" + uuid.uuid4().hex[:20])
    就绪 = threading.Event()
    失败 = []

    def 连接完成(连接, _数据, _标志, 原因, _属性):
        if 原因.is_failure:
            失败.append(str(原因))
            就绪.set()
        else:
            连接.subscribe(设置.topic, qos=1)

    def 订阅完成(_连接, _数据, _编号, 原因列表, _属性):
        if any(原因.is_failure for 原因 in 原因列表):
            失败.append("订阅被服务器拒绝")
        就绪.set()

    def 收到消息(_连接, _数据, 消息):
        print("收到主题：", 消息.topic, "；原始字节：", 消息.payload.hex(" ").upper(),
              "；文本视图：", 消息.payload.decode("utf-8", errors="replace"), flush=True)

    客户端.on_connect = 连接完成
    客户端.on_subscribe = 订阅完成
    客户端.on_message = 收到消息
    if not 设置.tcp:
        客户端.tls_set()
    if 设置.user:
        客户端.username_pw_set(设置.user, 设置.password)
    try:
        客户端.connect(设置.broker, 设置.port, keepalive=30)
        客户端.loop_start()
        if not 就绪.wait(15) or 失败:
            raise RuntimeError("连接或订阅失败：" + ";".join(失败))
        print("已订阅。输入text 内容或hex A5 01 02 DC 05；quit退出。", flush=True)
        while True:
            try:
                行 = input().strip()
            except EOFError:
                break
            if 行 == "quit":
                break
            if 行.startswith("hex "):
                try:
                    负载 = bytes.fromhex(行[4:])
                except ValueError:
                    print("十六进制格式无效，请修正后重试。", flush=True)
                    continue
            elif 行.startswith("text "):
                负载 = 行[5:].encode("utf-8")
            else:
                print("请输入text 内容、hex 字节或quit。", flush=True)
                continue
            结果 = 客户端.publish(设置.topic, 负载, qos=1, retain=False)
            结果.wait_for_publish(timeout=10)
            print("已发布", len(负载), "字节；接收结果由真实消息回调显示。", flush=True)
    except KeyboardInterrupt:
        pass
    finally:
        客户端.disconnect()
        客户端.loop_stop()


if __name__ == "__main__":
    main()

对端采用 Eclipse Paho 官方Python客户端 的第二版回调接口。电脑客户端实测记录不代表安卓或鸿蒙客户端已经真机联调。

重连、订阅与切换页面

连接后再订阅，断开后等待状态变为已断开，再发起下一次连接。使用清除会话的连接方式时，每次重新连上都应重新订阅需要的主题。重复订阅同一主题不表示每条消息会收到多份；测试时分别查看连接状态、订阅结果和实际收到的消息。

切换真实Screen会涉及不同的组件实例，不能把上一屏的连接状态当作新屏已经连接。可使用同屏布局切换来保留一个客户端；若使用多个Screen，每屏都明确处理建立连接、订阅和退出清理。

本机测试已覆盖同一客户端与同一服务地址5轮连接、订阅、收消息、取消订阅、再次订阅、断开。EasyIoT公网服务和真实手机尚需单独联调；本机测试通过不等于这些环境已经通过。

平台支持范围

安卓客户端支持 TCP 与 TLS。当前鸿蒙客户端支持 TCP，设置 SSL/TLS 会返回连接失败，不能使用本页默认的 TLS 8886 配置；进行非敏感演示时改用公开测试服务的 TCP 1884 配置。需要 TLS 的生产项目须等待对应原生能力补齐，不能用普通 TCP 替代安全连接。