Python paho-mqtt 模块使用和API分析

Python paho-mqtt 模块使用和API分析

标签（空格分隔）： python mqtt paho-mqtt iot
本文主要参考和翻译paho-mqtt模块中的英文注释写成，希望给需要使用这个模块的人一些参考。

---

一、Client模块

与MQTT代理（broker）进行通信的主要类。

---

（一）使用流程

• 使用connect()/connect_async() 连接MQTT代理
• 频繁的调用loop()来维持与MQTT代理之间的流量
  
  • 或者使用loop_start()来设置一个线程为你调用loop()
  • 或者在一个阻塞的函数中调用loop_forever()来为你调用loop()
• 使用subscribe()订阅一个主题（topic）并接受消息（messages）
• 使用publish()来发送消息
• 使用disconnect()来断开与MQTT代理的连接

---

（二）回调(Callbacks)

1.基本概念

使用回调处理从MQTT代理返回的数据，要使用回调需要先定义回调函数然后将其指派给客户端实例（client）。
例如：

# 定义一个回调函数
def on_connect(client, userdata, flags, rc):
    print("Connection returned " + str(rc))

# 将回调函数指派给客户端实例
client.on_connect = on_connect

所有的回调函数都有client和userdata参数。
client是调用回调的客户端实例；
userdata可以使任何类型的用户数据，可以在创建新客户端实例时设置或者使用user_data_set(userdata)设置。

2.回调种类

（1）on_connect()

当代理响应连接请求时调用。
on_connect(client, userdata, flags, rc):
flags是一个包含代理回复的标志的字典；
rc的值决定了连接成功或者不成功：

值	连接情况
0	连接成功
1	协议版本错误
2	无效的客户端标识
3	服务器无法使用
4	错误的用户名或密码
5	未经授权

（2）on_disconnect()

当与代理断开连接时调用

on_disconnect(client, userdata, rc):

rc参数表示断开状态。
如果MQTT_ERR_SUCCESS（0），回调被调用以响应disconnect（）调用。 如果以任何其他值断开连接是意外的，例如可能出现网络错误。

（3）on_message()

on_message(client, userdata, message):

当收到关于客户订阅的主题的消息时调用。
message是一个描述所有消息参数的MQTTMessage。

（4）on_publish()

当使用使用publish()发送的消息已经传输到代理时被调用。

on_publish(client, userdata, mid):

对于Qos级别为1和2的消息，这意味着已经完成了与代理的握手。
对于Qos级别为0的消息，这只意味着消息离开了客户端。
mid变量与从相应的publish()返回的mid变量匹配，以允许跟踪传出的消息。

此回调很重要，因为即使publish（）调用返回，但并不总意味着消息已发送。

（5）on_subscribe()

当代理响应订阅请求时被调用。

on_subscribe(client, userdata, mid, granted_qos):

mid变量匹配从相应的subscri
be()返回的mid变量。
‘granted_qos’变量是一个整数列表，它提供了代理为每个不同的订阅请求授予的QoS级别。

（6）on_unsubscribe()

当代理响应取消订阅请求时调用。

on_unsubscribe(client, userdata, mid):

mid匹配从相应的unsubscribe（）调用返回的中间变量。

（7）on_log()

当客户端有日志信息时调用

on_log(client, userdata, level, buf):

level变量给出了消息的严重性，并且将是MQTT_LOG_INFO，MQTT_LOG_NOTICE，MQTT_LOG_WARNING，MQTT_LOG_ERR和MQTT_LOG_DEBUG中的一个。
buf变量用于存储信息。

---

（三）方法

1.构造函数Client（）

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

参数	含义
client_id	连接到代理时使用的唯一客户端ID字符串。 如果client_id长度为零或无，则会随机生成一个。 在这种情况下，clean_session参数必须为True。
clean_session	一个决定客户端类型的布尔值。 如果为True，那么代理将在其断开连接时删除有关此客户端的所有信息。 如果为False，则客户端是持久客户端，当客户端断开连接时，订阅信息和排队消息将被保留。
userdata	用户定义的任何类型的数据作为userdata参数传递给回调函数。 它可能会在稍后使用user_data_set（）函数进行更新。
protocol	用于此客户端的MQTT协议的版本。 可以是MQTTv31或MQTTv311。
transport	设置为“websockets”通过WebSockets发送MQTT。 保留默认的“tcp”使用原始TCP。

示例：

import paho.mqtt.client as mqtt
client = mqtt.Client()

2.reinitialise()

reinitialise(client_id="", clean_session=True, userdata=None)

reinitialise（）函数将客户端重置为其开始状态，就像它刚刚创建一样。 它采用与Client（）构造函数相同的参数。
示例：

client.reinitialise()

3.选项函数

这些函数表示可以在客户端上设置以修改其行为的选项。 在大多数情况下，这必须在连接到代理之前完成。

（1）max_inflight_messages_set()

max_inflight_messages_set(self, inflight)

设置QoS> 0的消息的最大数量，该消息一次可以部分通过其网络流量。默认为20.增加此值将消耗更多内存，但可以增加吞吐量。

（2）max_queued_messages_set()

max_queued_messages_set(self, queue_size)

设置传出消息队列中可等待处理的具有QoS> 0的传出消息的最大数量。默认为0表示无限制。 当队列已满时，任何其他传出的消息都将被丢弃。

（3）message_retry_set（）