菜单

MQTT功能使用手册

概览

MQTT（Message Queuing Telemetry Transport）是一种轻量级、基于发布-订阅模式的消息传输协议，适用于资源受限的设备和低带宽、高延迟或不稳定的网络环境。它在物联网应用中广受欢迎，能够实现传感器、执行器和其它设备之间的高效通信。

  • QoS

    • QoS（Quality of Service）指消息传输的服务质量。分别可在消息发送端和消息消费端设置。

      • 发送端的QoS设置：影响发送端发送消息到服务器消息队列 MQTT 版的传输质量。

      • 消费端的QoS设置：影响服务器消息队列 MQTT 版服务端投递消息到消费端的传输质量。

    • QoS包括以下级别：

      • QoS0：代表最多分发一次。

      • QoS1：代表至少达到一次。

      • QoS2：代表仅分发一次。

本手册使用一台WINDOWS电脑作为MQTT Broker，一台个人电脑和一台工智机作为客户端，实现相互订阅和发布信息。如下图所示：

下表概述了本手册各个产品组件

产品组件 描述说明
iotmqtt_0.0.2_amd64.deb 工智机MQTT组件
MQTT_Client.projectarchive PLC工程存档
sf4202_iotmqtt_1.0.2.0.library PLC工程库文件
emqx-5.3.2-windows-amd64.zip EMQX压缩文件（MQTT Broker）
MQTTX-Setup-1.11.0-x64.exe MQTT客户端安装程序

安装卸载

安装要求

  • 中科时代出厂的工智机的自带系统；

  • SX、SP全系工智机

  • 工智机可以访问互联网；

安装过程

1、安装EMQX（MQTT Broker）

将官网下载的emqx-5.3.2-windows-amd64.zip进行解压缩，自行解压到相应的文件夹中。

打开文件夹目录bin，在文件夹位置处输入“cmd”，回车。

在命令行中输入——emqx start——回车

启动完成

EMQX端口号：

端口号 说明
1833 TCP 端口
8883 WebSocket 端口
8884 WebSocket Secure 端口
8883 SSL/TLS 端口
18083 Broker的Dashboard访问端口

可以通过18083端口访问MQTT Broker可视化界面

本机访问：127.0.0.1:18083/

外部访问：192.168.110.147:18083/

(192.168.110.147是本例MQTT Broker的IP地址)

用户名：admin

密码：public

首次登录会提示修改密码，也可以选择跳过。

Dashboard界面，可以进行Broker的设置以及查看客户端连接情况、消息订阅等等。

WINDOWS个人电脑安装MQTTX

本手册使用MQTTX作为客户端进行消息的发布和订阅。

打开从官方网站下载的MQTTX-Setup-x64.exe程序，选择安装选项—下一步。

选择安装目录—安装

安装完成后，点击MQTTX图标——新建连接。

填写客户端

参数 说明 设定例
Name 客户名字 user1
Host 主机IP地址 192.168.110.147
Port 端口 1883
Client ID 客户端ID，必须是唯一标识 mqtt_user1

点击右上角“Connect”进行连接，连接成功后：

在MQTT Broker界面可以看到连接数变为1.

点击客户端，显示客户端ID、连接情况、IP地址等信息：

回到MQTTX客户端，发布消息，格式为Plaintext，主题为a，负载内容为a=0

Broker界面可以看到消息流入数为1，由于没有客户端订阅主题a，所有消息被丢弃。

3、工智机安装iotmqtt_0.0.2_amd64.deb组件

参考附录一，使用Windows cmd输入命令将iotmqtt_0.0.2_amd64.deb文件安装至工智机中。

shell 复制代码 
scp -P 2224 iotmqtt_0.0.2_amd64.deb sinsegye@192.168.110.137:~
ssh -p 2224 sinsegye@192.168.110.137
sudo dpkg -i iotmqtt_0.0.2_amd64.deb
sudo nano /usr/local/etc/SinsegyeRTE/SinsegyeRTE.cfg
修改ComponentManager
sudo reboot

4、工智机安装iotmqtt.library库文件

打开MetaFacture程序，选择“工具”——“库存储”

选择“安装”

选择从中科时代官方下载的iotmqtt.library库文件

安装完成

更新安装

参考上一章《安装过程》，将新的deb文件和库文件覆盖安装即可更新。

卸载过程

1、停止EMQX（MQTT Broker）

打开EMQX文件夹——打开目录bin，在文件夹位置处输入“cmd”，回车。

在命令行中输入——emqx stop——回车

等待片刻后，停止EMQX服务。

2、使用控制面板卸载MQTTX

3、卸载工智机iotmqtt_0.0.2_amd64.deb组件

1 使用dpkg -r命令进行卸载

shell 复制代码 
sudo dpkg -r iotmqtt

3.2 修改RTE的配置文件，ComponentManger模块下去掉iotmqtt

shell 复制代码 
sudo nano /usr/local/etc/SinsegyeRTE/SinsegyeRTE.cfg

删除Component.8=iotmqtt

3.3 重启工智机

shell 复制代码 
sudo reboot

4、卸载MetaFacture中的库文件iotmqtt.library

4.1 打开软件，点击“工具”—“库存储”

4.2 在“杂项”中找到需要卸载的库文件，选中后点击“卸载”

技术说明

快速启动

（一）本例软、硬件配置

硬件： 软件：
1.工智机SX20 1.服务端软件emqx-5.3.2
2.服务端电脑（WINDOWS） 客户端软件MQTTX 1.11.0
3.个人电脑（WINDOWS） 工智机组件iotmqtt_0.0.2_amd64.deb
4.PLC库文件iotmqtt.library
5.PLC存档工程MQTT_Client.projectarchive
6.中科时代MetaFacture V1.0.6.3

（二）本例实验操作步骤

1.实验要求

a.MQTT Broker成功运行EMQX；

b.个人电脑安装MQTTX，并与Broker成功连接，并订阅主题“zksd”；

c.工智机成功安装iotmqtt_0.0.2_amd64.deb组件

d.MetaFacture成功安装库文件iotmqtt.library

2.实验原理图

3.实验步骤

3.1 使用MetaFacture打开PLC存档工程“MQTT_Client.projectarchive”。登录设备，下载PLC程序并启动运行。

3.2 点击PLC程序“Connect”，配置Broker端的IP地址和端口，将变量bConnect置TRUE，工智机连接Broker。

可以在Broker Dashboard界面查看到连接的客户端情况。

3.3 点击PLC程序“Publish”，将变量bPublish置TRUE。在MQTTX客户端可以收到订阅消息。

3.4 点击PLC程序“Subscribe”，将变量bSubscribe置TRUE。订阅三个主题“x”“y”“z”。在MQTTX客户端中发送三个主题消息。PLC程序变量topic和playload可以收到主题和内容。

发送主题消息：

3.5 点击PLC程序“Unbscribe”，将变量bUnSubscribe置TRUE。取消订阅“x”“y”“z”。在Broker Dashboard界面—订阅管理可以看到已经取消订阅。

3.6 MQTTX客户端断开重连后，可以收到标记为Retained的保留消息。

3.7 工智机手动拔除网线，约5秒后，MQTTX客户端收到一条“offine”的遗嘱消息。

示例

创建工程

打开中科时代MetaFacture V1.0.6.3,选择“文件”——“新建工程”

选择标准工程——命名为MQTT_Client——点击“确定”

选择Sinsegye工智机以及编程语言（本例为ST语言）

选择“库管理器”——“添加库”——在杂项中选择“iotmqtt”——点击“确定”。

PLC工程中完成库文件添加。

建立MQTT客户端

鼠标右键“Application”——“添加对象”——“全局变量列表”

命名全局变量列表名称

添加如下变量：

实例名称 功能块名称 说明
Client TMP.FB_IotMqttClient 实例化MQTT客户端
MessageQueue TMP.FB_IotMqttMessageQueue 存放订阅的消息队列
Message TMP.FB_IotMqttMessage 取出的单条订阅消息

鼠标右键“Application”——“添加对象”——“POU”

将程序命名为“Connect”，选择ST语言后，点击“添加”

在Connect的PLC中，鼠标右键空白处，选择“输入助手”

点击“实例调用”——找到工程Application的GVL中的Client，点击“确定”

添加参数Client ID、Host IP、Host Port、心跳时间、消息队列指针。

关于功能块的参数说明，详见功能介绍章节。

参数 说明 设定例
sClientId 客户端ID ‘Sinsegye’
sHostName 连接IP地址 ‘192.168.110.147’
nHostPort 连接端口号 1883
nKeepAlive 心跳报文发送间隔时间，单位s 60
ipMessageQueue 指向消息队列 ADR(MessageQueue)

连接MQTT Broker

声明BOOL型连接变量bConnect

使用Client.Execute()方法进行连接，将变量bConnect作为实参传入方法。

关于方法参数说明详见功能介绍章节。

点击PLC_PRG程序，调用Connect程序。

登录工智机，将PLC下载至工智机中。

启动PLC

将bConnect变量置为TRUE,Ctrl+F7写入变量，客户端与MQTT Broker进行连接。

查看Broker的Dashboard的客户端界面，可以看到mqttx_user1是个人电脑使用MQTTX创建的客户端，而Sinsegye是工智机创建的客户端。

发布消息

新建一个POU程序，命名为Publish。

声明变量

添加PLC程序，其中bPublish_Trig功能块作用是取bPubish变量的上升沿。

使用Client.Publish()方法发布消息，

发布主题为zksd，内容为This is Sinsegye的消息。

关于方法参数说明详见功能介绍章节

在个人电脑侧MQTTX客户端，订阅zksd主题

点击PLC_PRG程序，调用Publisht程序。

登录工智机，将PLC下载至工智机中，启动PLC。

1.先将bConnect变量置为TRUE,Ctrl+F7写入变量，客户端与MQTT Broker进行连接。

2.再将bPublish变量置为TRUE,Ctrl+F7写入变量，发布消息。

MQTTX客户端收到主题为zksd的消息

订阅消息

新建一个POU程序，命名为Subscribe。

声明变量

添加PLC程序。使用Client.Subscribe()方法订阅消息。

本例订阅了三个主题，分别为‘x’、‘y’和‘z’

关于方法参数说明详见功能介绍章节。

当消息发送过来后，存储再消息队列中，需要取出消息，添加消息取出的PLC代码：

在PLC_PRG中调用Subscribe程序

登录工智机，将PLC下载至工智机中，启动PLC。

1.先将bConnect变量置为TRUE,Ctrl+F7写入变量，客户端与MQTT Broker进行连接。

2.再将bSubscribe变量置为TRUE,Ctrl+F7写入变量，订阅三个主题的消息。

订阅成功

可以在Broker的 订阅管理中，看到订阅成功

在个人电脑MQTTX客户端中发布消息进行测试

发布消息序列 主题 内容
1 x x=1
2 y y=2
3 z z=3
4 x x=4

在PLC程序中，变量topic记录了历史消息的主题

变量playload记录了历史消息的内容

取消订阅

新建一个POU程序，命名为UnSubscribe，声明如下变量。

添加PLC程序。使用Client.UnSubscribe()方法取消订阅。传入String类型的主题字符，取消订阅‘x’、‘y’和‘z’主题消息

关于方法参数说明详见功能介绍章节。

在PLC_PRG中调用UnSubscribe程序

登录工智机，将PLC下载至工智机中，启动PLC。

1.先将bConnect变量置为TRUE,Ctrl+F7写入变量，客户端与MQTT Broker进行连接。;查看Broker的订阅管理，Sinsegye订阅了三个主题

2.再将bUnsubscribe变量置为TRUE,Ctrl+F7写入变量，取消订阅三个主题的消息。

取消成功

查看Broker的订阅管理，点击“刷新”，Sinsegye取消订阅。

保留消息

MQTT保留消息(Retained Messages)是一种在MQTT中发布持久化消息的方式。当客户端发布一条保留消息，它会在MQTT服务器上保存这条消息。当新的订阅者连接到服务器时，服务器会将这条保留消息发送给新的订阅者。一个主题只会存储一条保留消息，新的保留消息会替换旧的保留消息。

设置使用Client.Publish()方法的bRetain参数为TRUE，发布的消息即为保留消息.

登录工智机，将PLC下载至工智机中，启动PLC。

1.先将bConnect变量置为TRUE,Ctrl+F7写入变量，客户端与MQTT Broker连接。

2.再将bPublish变量置为TRUE,Ctrl+F7写入变量，发布保留消息。

如果发送保留消息时，订阅zksd的MQTTX客户端在线，则正常收到消息。

如果发送保留消息时，订阅zksd的MQTTX客户端离线，则当MQTTX上线后会收到标记为Retained的保留消息。

遗嘱消息

遗嘱消息是一种特殊的消息，用于客户端异常断开连接时，向其他订阅者通知其离线状态的消息。

在Connect程序中，声明遗嘱消息。

设定遗嘱消息结构体成员，并将结构体传入Client客户端的stWill参数。同时，为了方便演示异常断开，将心跳报文发送时间设为5s

遗嘱结构体成员 类型 设定例 说明
sTopic String ‘zksd’ 遗嘱消息主题为zksd
pPayload Pointer ADR(WillingPayload) 遗嘱消息内容指针
nPayloadSize UDINT INT_TO_UDINT(Len(WillingPayload)) 遗嘱消息数据长度
eQoS UINT 2 eQoS消息质量等级2
bRetain Bool FALSE 不是保留消息

登录工智机，将PLC下载至工智机中，启动PLC。

1.先将bConnect变量置为TRUE,Ctrl+F7写入变量，客户端与MQTT Broker连接。

2.手动断开工智机网络连接线。

3.在MQTTX客户端，收到遗嘱消息。

最近修改: 2025-07-31