Getting Started
import paho.mqtt.client as mqtt
# The callback for when the client receives a CONNACK response from the server.
def on_connect(client, userdata, flags, rc):
print("Connected with result code "+str(rc))
# Subscribing in on_connect() means that if we lose the connection and
# reconnect then subscriptions will be renewed.
client.subscribe("$SYS/#")
# The callback for when a PUBLISH message is received from the server.
def on_message(client, userdata, msg):
print(msg.topic+" "+str(msg.payload))
client = mqtt.Client()
client.on_connect = on_connect
client.on_message = on_message
client.connect("iot.eclipse.org", 1883, 60)
# Blocking call that processes network traffic, dispatches callbacks and
# handles reconnecting.
# Other loop*() functions are available that give a threaded interface and a
# manual interface.
client.loop_forever()
Client
-
创建一个client 实例
-
用connect*()函数来连接中间人
-
调用一个loop*()函数来保持与中间人的网络通信
-
用subscribe()来订阅主题并接收信息
-
用publish()来发布消息给中间人
-
用disconnect()来断开与中间人的连接
Constructor / reinitialise
Client()
Client(client_id="", clean_session=True, userdata=None, protocol=MQTTv311)
-
client_id : 唯一的client id 字符串,当连接中间人时使用。如果client_id 长度为0,则会自动随机产生一个client_id。这种情况下 clean_session 参数必须为 True.
-
clean_session : 决定client 类型的bool 类型 参数。如果为True,当client 失去连接时中间人将删除所有关于这个client 的信息。 如果为 False,则说明这是一个持久的client,当失去连接时发布信息和队列中的消息将会被保持。注意,当失去连接时client 永远不会抛弃自己需要发出的信息,当调用connect()/reconnect() 后将会重新发送这些信息。 调用 reinitialise() 重置client到它初始化时的状态。
-
userdata:用户定义的任何类型的数据将被传输为 userdata 参数到回调函数。后面可以使用user_data_set()函数来更新这个参数。
-
protocol:client 使用的mqtt 版本。可以是 MQTTv31 或 MQTTv311
Example
import paho.mqtt.client as mqtt
mqttc = mqtt.Client()
reinitialise()
reinitialise(client_id="", clean_session=True, userdata=None)
Example
mqttc.reinitialise()
Option functions
max_inflight_messages_set()
max_inflight_messages_set(self, inflight)
message_retry_set()
Connect / reconnect / disconnect
connect()
connect(host, port=1883, keepalive=60, bind_address="")
-
host:远程中间人的主机名或IP
-
port:服务端的端口。 默认是 1883。
-
keepalive:与中间人交流允许的最大时间段。如果没有信息交流,这控制client发送ping 消息到中间人的频率。
-
bind_address:本地网络IP
Callback
Example
mqttc.connect("iot.eclipse.org")
connect_async()
connect_async(host, port=1883, keepalive=60, bind_address="")
reconnect()
reconnect()
Callback
disconnect()
disconnect()
Callback
Network loop
loop()
loop(timeout=1.0, max_packets=1)
Example
run = True
while run:
mqttc.loop()
loop_start() / loop_stop()
loop_start()
loop_stop(force=False)
Example
mqttc.connect("iot.eclipse.org")
mqttc.loop_start()
while True:
temperature = sensor.blocking_read()
mqttc.publish("paho/temperature", temperature)
loop_forever()
loop_forever(timeout=1.0, max_packets=1, retry_first_connection=False)
Publishing
publish()
publish(topic, payload=None, qos=0, retain=False)
-
topic:主题,这个消息被发送到的主题。
-
payload:实际被发送的消息。如果未给出该参数,或者设置为None,那么系统会自动定义为空字符串。如果给出的是int或float,则会被转成字符串。如果你希望发送一个int/float,用struct.pack()来创建这个参数。
-
qos:质量,服务级别
-
retain:如果设置为True,这个消息将被设置为这个主题的‘last known good’ 消息。
Callback
Subscribe / Unsubscribe
subscribe()
subscribe(topic, qos=0)
Simple string and integer
-
topic:指定需要订阅的主题
-
qos:订阅要求的服务级别,默认为0。
String and integer tuple
-
topic:一个(topic,qos)元组,都必须提供。
-
qos:未被使用。
List of string and integer tuples
Callback
unsubscribe()
unsubscribe(topic)
-
topic:可以是字符串,也可以是字符串的列表,表示需要取消订阅的主题。
Callback
Callbacks
on_connect()
on_connect(client, userdata, flags, rc)
-
client:这个回调的client 实例。
-
userdata:私人数据,设置在Client()或userdata_set()
-
flags:中间人发送的返回标志。
-
rc:连接结果。
-
-
flags[‘session present’] - 这个标志仅对clean session设置为0的client 有效,如果一个client 设置了clean session = 0,当重新连接中间人时,这个标志表示中间人是否任然有这个client 的session 信息。如果是1,则session 信息依然存在。
-
0: 连接成功
1: 连接被拒绝- 不正确的协议版本
2: 连接被拒绝 - 非法的client 标志
3: 连接被拒绝 - 服务端不可用
4: 连接被拒绝 - 错误的用户名或密码
5: 连接被拒绝 - 未被授权
Example
def on_connect(client, userdata, flags, rc):
print("Connection returned result: "+connack_string(rc))
mqttc.on_connect = on_connect
...
on_disconnect()
on_disconnect(client, userdata, rc)
-
client:回调函数的实例。
-
userdata:私人数据,设置在Client()或userdata_set()
-
rc:失去连接的结果。
Example
def on_disconnect(client, userdata, rc):
if rc != 0:
print("Unexpected disconnection.")
mqttc.on_disconnect = on_disconnect
...
on_message()
on_message(client, userdata, message)
-
client:这个回调函数的client 实例。
-
userdata:私人数据,设置在Client()或userdata_set()
-
message:一个MQTTMessage实例。MQTTMessage类有topic,payload,qos,retain成员变量。
Example
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
...
message_callback_add()
message_callback_add(sub, callback)
-
sub:订阅过滤器,用来匹配回调。对每个sub 仅可以定义一个回调函数
-
callback:回调函数,月on_message()回调函数形式相同。
message_callback_remove()
message_callback_remove(sub)
-
sub
-
the subscription filter to remove
on_publish()
on_publish(client, userdata, mid)
on_subscribe()
on_subscribe(client, userdata, mid, granted_qos)
on_unsubscribe()
on_unsubscribe(client, userdata, mid)