【汇总】EMQX 函数API、安装与使用说明

前言全局说明

EMQX 函数说明

一、说明

二、Client的基本使用流程

创建客户端实例
使用 connect*() 函数之一连接到代理
调用 loop*() 函数之一来维护与代理的网络流量
使用 subscribe() 订阅主题并接收消息
使用 publish() 将消息发布到代理
使用 disconnect() 断开与代理的连接

三、Client类与方法

3.1 Client的构建与重置

3.1.1 原型：

Client(client_id="", clean_session=True, userdata=None, protocol=MQTTv311, transport="tcp")
reinitialise(client_id="", clean_session=True, userdata=None)

3.1.2 使用示例如下：

import paho.mqtt.client as mqtt
# 构建一个Client
mqttc = mqtt.Client()
# 重置一个Client
mqttc.reinitialise()

3.1.3 参数说明

client_id:
连接到代理时使用的唯一客户端 ID 字符串。如果 client_id 为零长度或 None ，则将随机生成一个。在这种情况下，clean_session 参数必须为 True。
 
clean_session:
确定客户端类型的布尔值。如果为 True，代理将在断开连接时删除有关此客户端的所有信息。如果为 False，则客户端是持久客户端，并且在客户端断开连接时将保留订阅信息和排队消息。
注意，客户端永远不会在断开连接时丢弃自己的传出消息。调用 connect() 或 reconnect() 将导致消息被重新发送。使用 reinitialise() 将客户端重置为其原始状态。
 
userdata:
作为 userdata 参数传递给回调的任何类型的用户定义数据。稍后可能会使用 user_data_set() 函数对其进行更新。
 
protocol:
用于此客户端的 MQTT 协议版本。可以是 MQTTv31 或 MQTTv311
 
transport:
设置为“websockets”以通过 WebSockets 发送 MQTT。保留默认值“tcp”以使用原始 TCP。

3.2 连接至代理/重新连接/与代理断开连接

3.2.1 原型：

connect(host, port=1883, keepalive=60, bind_address="")
reconnect()
disconnect()
 

3.2.2 使用示例如下：

# 已构建一个Client：mqttc
mqttc.connect("mqtt.eclipseprojects.io") 
# 使用reconnect与disconnect之前必须已经调用过connect
mqttc.reconnect()
mqttc.disconnect()

3.2.3 参数说明

host:
远程代理的主机名或 IP 地址
port:
要连接的服务器主机的网络端口。 默认为 1883。请注意，基于 SSL/TLS 的 MQTT 的默认端口为 8883，因此如果您使用 tls_set() 或 tls_set_context()，则可能需要手动提供端口
keepalive:
与代理通信之间允许的最长间隔（以秒为单位）。 如果没有其他消息正在交换，这将控制客户端向代理发送 ping 消息的速率。
 
需要指出，MQTT协议规定，在 1.5倍的keepalive时间内，如果代理没有收到来自客户端的任何数据包，那么代理将认为它和这个客户端之间的连接已经断开；而如果客户端没有收到来自 代理的任何数据包，那么这个客户端会认为它和代理之间的连接已经断开。为维持正常的连接，如果代理与客户端之间没有其他数据传输，客户端会每隔keepalive时间向代理发送一次ping消息（由loop()来维护）。keepalive的缺省时间是60s。
 
bind_address:
假设存在多个接口，要将此客户端绑定到的本地网络接口的 IP 地址

3.3 网络回路控制

3.3.1 原型：

loop(timeout=1.0, max_packets=1)
loop_start()
loop_stop(force=False)
loop_forever(timeout=1.0, max_packets=1, retry_first_connection=False)

3.3.2 使用示例如下：

3.3.3 参数说明

mqttc.connect("mqtt.eclipseprojects.io")
mqttc.loop_start()
# do something else
while True:
    temperature = sensor.blocking_read()
    mqttc.publish("paho/temperature", temperature)
 
mqttc.loop_stop()

3.4 订阅/取消订阅

3.4.1 原型：

subscribe(topic, qos=0)
unsubscribe(topic)

3.4.2 使用示例如下：

mqttc.subscribe(("my/topic", 1))
mqttc.subscribe([("my/topic", 0), ("another/topic", 2)])
mqttc.unsubscribe("my/topic")
mqttc.unsubscribe(["my/topic", "another/topic"])

3.4.3 参数说明

topic:
一个字符串，指定要订阅的订阅主题。
qos:
订阅所需的服务质量(quality of service)级别。 默认为 0，可选0，1，2。

3.5 发布

3.5.1 原型：

publish(topic, payload=None, qos=0, retain=False)

3.5.2 使用示例如下：

mqttc.publish(topic="my/topic", payload=None, qos=0, retain=True)

3.5.3 参数说明

topic:
消息应该发布到的主题
payload:
要发送的实际消息。 如果没有给出，或者设置为 None 将使用零长度消息。 传递 int 或 float 将导致有效负载转换为表示该数字的字符串。 如果您希望发送真正的 int/float，请使用 struct.pack() 创建您需要的有效负载。
qos:
要使用的服务质量（quality of service）水平，默认为 0，可选0，1，2。
retain:
如果设置为 True，则该消息将被设置为该主题的保留消息。保留消息的作用是使新订阅某个主题的客户端能够收到该主题中上一次发布的消息。

四、回调

4.1 连接

4.1.1 原型：

on_connect(client, userdata, flags, rc)

4.1.2 使用示例如下：

def on_connect(client, userdata, flags, rc):
    print("Connection returned result: "+connack_string(rc))
 
mqttc.on_connect = on_connect
...

4.1.3 参数说明

client:
此回调的客户端实例
userdata:
在 Client() 或 user_data_set() 中设置的私有用户数据
flags:
代理发送的响应标志
rc:
连接结果

4.2 断开连接

4.2.1 原型：

on_disconnect(client, userdata, rc)

4.2.2 使用示例如下：

def on_disconnect(client, userdata, rc):
    if rc != 0:
        print("Unexpected disconnection.")
 
mqttc.on_disconnect = on_disconnect
...

4.2.3 参数说明

client:
此回调的客户端实例
userdata:
在 Client() 或 user_data_set() 中设置的私有用户数据
flags:
代理发送的响应标志
rc:
断开结果

4.3 收到消息

4.3.1 原型：

on_message(client, userdata, message)
message_callback_add(sub, callback)
message_callback_remove(sub)

4.3.2 使用示例如下：

def on_message(client, userdata, message):
    print("Received message '" + str(message.payload) + "' on topic '"
        + message.topic + "' with QoS " + str(message.qos))
 
mqttc.on_message = on_message
...

4.3.3 参数说明

client:
此回调的客户端实例
userdata:
在 Client() 或 user_data_set() 中设置的私有用户数据
message:
MQTTMessage信息实例，这是一个包含成员 topic、payload、qos、retain 的类。
sub:
特定主题
callback:
定义的callback函数

4.4 发布消息

4.3.1 原型：

on_publish(client, userdata, mid)

4.3.2 使用示例如下：

4.3.3 参数说明

4.5 订阅主题

4.3.1 原型：

on_subscribe(client, userdata, mid, granted_qos)

4.3.2 使用示例如下：

4.3.3 参数说明

4.6 取消订阅

4.3.1 原型：

on_unsubscribe(client, userdata, mid)

4.3.2 使用示例如下：

4.3.3 参数说明

4.6 收到日志

4.3.1 原型：

on_log(client, userdata, level, buf)

4.3.2 使用示例如下：

4.3.3 参数说明

---

免责声明：本号所涉及内容仅供安全研究与教学使用，如出现其他风险，后果自负。

---

参考、来源：
https://github.com/emqx/MQTT-Client-Examples （官方源码）
https://docs.emqx.com/zh/cloud/latest/connect_to_deployments/python_sdk.html (官方说明)
https://www.cnblogs.com/steven-dou/articles/13921825.html （paho-mqtt 模块使用和API分析）
https://blog.csdn.net/zbgjhy88/article/details/98112017 （API使用）
https://wenku.csdn.net/answer/c4f5f24eff7949e983a21ccdaaa7638e
https://blog.csdn.net/qq_45664055/article/details/135497850
https://blog.51cto.com/u_16213324/11147532
https://www.jb51.net/article/160686.htm