paho-mqtt 文档翻译

Getting Started

Here is a very simple example that subscribes to the broker $SYS topic tree and prints out the resulting messages:

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 类当做一个实例/类/子类 来用,一般用法如下:

  • 创建一个client 实例

  • 用connect*()函数来连接中间人

  • 调用一个loop*()函数来保持与中间人的网络通信

  • 用subscribe()来订阅主题并接收信息

  • 用publish()来发布消息给中间人

  • 用disconnect()来断开与中间人的连接


回调函数可以使得应用及时的处理事件。回调函数描述如下。

Constructor / reinitialise

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

The Client() constructor takes the following arguments:

  • 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)

如果client 已经被创建了,reinitialise() 函数重置 client 到它起始的状态. 它与Client()构造函数有相同的参数。

Example
mqttc.reinitialise()

Option functions

这些函数可以设置client 以改变它的行为。大多数情况下必须在连接中间人之前调用。

max_inflight_messages_set()
max_inflight_messages_set(self, inflight)

在QoS>0的情况下,设置最大数量的消息 ,that can be part way through their network flow at once.

默认是20。增加这个值将会增加内存的开销但是可以提高吞吐量。


message_retry_set()

    message_retry_set(retry)

设置重试时间,当中间人没有相应且QoS>0 时需要重试.

默认是5s,一般不需要修改。


Connect / reconnect / disconnect

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

connect() 函数使得client 连接到中间人(broker)。这是一个阻塞的函数,它有以下参数:

  • host:远程中间人的主机名或IP

  • port:服务端的端口。 默认是 1883。

  • keepalive:与中间人交流允许的最大时间段。如果没有信息交流,这控制client发送ping 消息到中间人的频率。

  • bind_address:本地网络IP

Callback

当client 从中间人接收到CONNACK信息,将触发on_connect()回调函数。

Example
mqttc.connect("iot.eclipse.org")
connect_async()
connect_async(host, port=1883, keepalive=60, bind_address="")

与 connect()相同,但是非阻塞。连接不会完成直到一个loop*()函数被调用。


reconnect()
reconnect()

用先前的信息重新连接中间人,在此之前必须调用过connect*()函数。

Callback

当client 从中间人接收到CONNACK信息,将触发on_connect()回调函数。

disconnect()
disconnect()

从中间人失去连接,中间人会抛弃该client 的信息。调用disconnect()将会导致将要被发送的消息丢失。

Callback

当client发送了disconnect 消息,它导致on_disconnect()被调用。

Network loop

这些函数是client 背后的驱动力量。如果它们没有被调用,进入网路的数据将不会被处理,走出网络的数据也不会被及时的发送。 实现网络循环有4种方法,这里介绍3种

loop()
loop(timeout=1.0, max_packets=1)

通常会调用这个函数来处理网络事件。 这个调用利用select()等待直到网络sokect 可被读或者写,然后处理进来或者出去的数据。这个函数最多阻塞timeout 秒,timeout 不能超过client 的 keepalive 值,否则你的client 将会定期的被中间人disconnected。

 max_packets 参数已经被废弃,不用设置。

Example
run = True
while run:
    mqttc.loop()
loop_start() / loop_stop()
loop_start()
loop_stop(force=False)

这些函数为网络循环实现了线程化的接口。在connect*()之前或之后调用一次 loop_start(),后台会启动一个线程用来自动调用loop()。这解放了主线程,主线程可以做其它需要阻塞的事情。这也会处理对中间人的重连接(reconnect)。调用loop_stop()来停止后台线程。force 参数现在已经被忽略了。

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)

这是一个阻塞形式的网络循环,直到client调用disconnect()才会返回。自动处理重连接。


Publishing

从client 给中间人发送消息。

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

这会使得一个消息被发送到中间人,随后从中间人到任何订阅了这个主题的client 。参数如下:

  • topic:主题,这个消息被发送到的主题。

  • payload:实际被发送的消息。如果未给出该参数,或者设置为None,那么系统会自动定义为空字符串。如果给出的是int或float,则会被转成字符串。如果你希望发送一个int/float,用struct.pack()来创建这个参数。

  • qos:质量,服务级别

  • retain:如果设置为True,这个消息将被设置为这个主题的‘last known good’ 消息。

返回一个元组(result,mid),result  == MQTT_ERR_SUCCESS 表示成功,result == MQTT_ERR_NO_CONN 表示client 当前未连接。mid 是publish 请求的消息ID,mid 的值可以被用来追踪publish请求。

如果主题为空,或者qos not in (0,1,2),或者payload 的长度大于268435455字节,则会触发ValueError错误。


Callback

当消息已经被发送给中间人,on_publish()回调将会被触发。


Subscribe / Unsubscribe

subscribe()
subscribe(topic, qos=0)

client 订阅一个或多个主题(topic)

Simple string and integer

e.g. subscribe("my/topic", 2)

  • topic:指定需要订阅的主题

  • qos:订阅要求的服务级别,默认为0。

String and integer tuple

e.g. subscribe(("my/topic", 1))

  • topic:一个(topic,qos)元组,都必须提供。

  • qos:未被使用。

List of string and integer tuples

e.g. subscribe([("my/topic", 0), ("another/topic", 2)])

这允许一个订阅命令可以订阅多个主题。


这个函数返回元组(result,mid),result  == MQTT_ERR_SUCCESS 表示成功,result == MQTT_ERR_NO_CONN 表示client 当前未连接。mid 是publish 请求的消息ID,mid 的值可以被用来追踪publish请求。

Callback

当中间人识别了这个订阅,on_subscribe()回调将被调用。

unsubscribe()
unsubscribe(topic)

取消client 对一个或多个主题的订阅。

  • topic:可以是字符串,也可以是字符串的列表,表示需要取消订阅的主题。

返回值是元组(result,mid)。


Callback

当中间人识别了unsubscribe,则on_unsubscibe()回调将会被触发。

Callbacks

on_connect()
on_connect(client, userdata, flags, rc)

当中间人回应我们的连接请求时被调用。

  • client:这个回调的client 实例。

  • userdata:私人数据,设置在Client()或userdata_set()

  • flags:中间人发送的返回标志。

  • rc:连接结果。

flags 是一个中间人返回的包含返回标志的字典:


    • flags[‘session present’] - 这个标志仅对clean session设置为0的client 有效,如果一个client 设置了clean session = 0,当重新连接中间人时,这个标志表示中间人是否任然有这个client 的session 信息。如果是1,则session 信息依然存在。

rc 的值表示成功与否:

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 失去连接时被调用。

  • client:回调函数的实例。

  • userdata:私人数据,设置在Client()或userdata_set()

  • rc:失去连接的结果。

rc 参数表示失去连接的状态。如果是MQTT_ERR_SUCCESS(0),这该回调函数是为了响应中间人的disconnect(),如果是其它值,则说明是其它事件引起的失去连接,比如网络问题。(意思是,该参数说明了是谁触发了该回调函数,即谁导致了失去连接)

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)

当有信息被一个订阅的主题接收,则会触发该回调函数。message_callback_add() 可以为指定的主题定义多个回调函数。

  • 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()

这个函数允许你为指定的订阅定义回调函数来处理消息,可以包含通配符。这允许你订阅诸如sensors/#,并且有一个回调函数来处理sensors/temperature 和另一个回调函数来处理sensors/humidity

message_callback_add(sub, callback)
  • sub:订阅过滤器,用来匹配回调。对每个sub 仅可以定义一个回调函数

  • callback:回调函数,月on_message()回调函数形式相同。

如果同时使用message_callback_add()和on_message() ,只有当message_callback_add()中没有匹配到时才会传给on_message()回调函数。

message_callback_remove()

Remove a topic/subscription specific callback previously registered using message_callback_add().

message_callback_remove(sub)
  • sub

  • the subscription filter to remove

on_publish()
on_publish(client, userdata, mid)

当一个信息被publish()发送给中间人后,会调用on_publish()。对于QoS为1和2的消息(message),这意味着适当的握手都已经完成了。对于QoS为0的消息,这仅仅意味着消息离开了client。mid 变量匹配publish()返回的mid变量,使得出去的消息可以被追踪。

这个回调函数很重要,因为即使publish()成功返回,也不一定总是表示消息被成功发送。

on_subscribe()
on_subscribe(client, userdata, mid, granted_qos)

当中间人响应订阅请求时调用。mid变量匹配subscribe()调用的mid 变量。granted_qos 变量是一个整数列表,为每个中间人授予的不同的订阅请求给出QoS级别。

on_unsubscribe()
on_unsubscribe(client, userdata, mid)

当中间人响应一个取消订阅(unsubscribe)的请求时调用。mid 变量匹配unsubscribe()的mid变量。


原文档:https://pypi.python.org/pypi/paho-mqtt

阅读更多
文章标签: paho mqtt java sdk
个人分类: JAVA
上一篇Javascript之BOM与DOM讲解
下一篇关于SQL中Union和Join的用法
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

关闭
关闭
关闭