MQTT (Message Queuing Telemetry Transport) is a lightweight instant messaging protocol, related introduction can be found at: Introduction to MQTT .
Paho is an open source MQTT client project of Eclipse, which provides MQTT client implementations in multiple languages, including C, C++, C#, Java, Python, JavaScript, etc. In the Python environment, the Paho MQTT Python client is supported by the paho-mqtt module.
Install the Paho MQTT Python client
Paho MQTT Python client depends on Python 2.7.9 or later and Python 3.5 or later. The test environment of this article is Python 3.7.1.
Install paho-mqtt with pip as follows:
pip install paho-mqtt
Common APIs
paho-mqtt mainly consists of three modules: Client module, Publish module and Subscribe module. The Publish module and the Subscribe module are relatively seldom used, and the meaning of the parameters is similar to the parameters of the publish and subscribe methods of the Client module. This article will not introduce it due to space limitations.
The basic usage process of Client
The basic usage process of Client is as follows:
- Create a client instance
- Connect to the broker using one of the connect*() functions
- Call one of the loop*() functions to maintain network traffic with the proxy
- Use subscribe() to subscribe to topics and receive messages
- Publish the message to the broker using publish()
- Use disconnect() to disconnect from the broker
It is worth noting that there are many callbacks during the use of the Client, which can help the Client handle various events, which we will introduce in detail later.
Client classes and methods
(1) Construction and reset of Client
The construction and reset of Client are undertaken by the following two methods:
Client(client_id="", clean_session=True, userdata=None, protocol=MQTTv311, transport="tcp")
reinitialise(client_id="", clean_session=True, userdata=None)
The specific parameters are described as follows:
client_id :
A unique client ID string to use when connecting to the broker. If client_id is zero-length or None, one will be randomly generated. In this case, the clean_session parameter must be True.
clean_session :
A boolean that determines the client type. If True, the broker will delete all information about this client on disconnect. If False, the client is a durable client and will retain subscription information and queued messages when the client disconnects.
Note that the client never discards its own outgoing messages on disconnect. Calling connect() or reconnect() will cause the message to be resent. Use reinitialise() to reset the client to its original state.
userdata :
Any type of user-defined data passed to the callback as the userdata parameter. It may be updated later using the user_data_set() function.
protocol :
The MQTT protocol version to use for this client. Can be MQTTv31 or MQTTv311
transport :
Set to "websockets" to send MQTT over WebSockets. Leave the default "tcp" to use raw TCP.
An example of use is as follows:
import paho.mqtt.client as mqtt
# 构建一个Client
mqttc = mqtt.Client()
# 重置一个Client
mqttc.reinitialise()
(2) Connect to proxy/reconnect/disconnect from proxy
The corresponding method is:
connect(host, port=1883, keepalive=60, bind_address="")
reconnect()
disconnect()
Note that the essence of MQTT is a low-consumption protocol for maintaining a long connection between the client and the broker. Therefore, both for the agent and the client, they need to know clearly whether the connection between the two is disconnected, and whether it is a normal disconnection or an abnormal disconnection (normal disconnection (the client uses the disconnect method) does not need to Special action; in case of abnormal disconnection, the client needs to try to reconnect, and the agent needs to send a will). This point runs through the protocol design and "connection" of MQTT.
The specific parameters are described as follows:
host :
The host name or IP address of the remote proxy port
: The
network port of the server host to connect to. The default is 1883. Note that the default port for MQTT over SSL/TLS is 8883, so if you use tls_set() or tls_set_context() you may need to manually provide the port keepalive: The longest
interval allowed between
communications with the broker (in seconds ). This controls the rate at which the client sends ping messages to the broker if no other messages are being exchanged.
It should be pointed out that the MQTT protocol stipulates that within 1.5 times the keepalive time, if the proxy does not receive any data packets from the client, the proxy will consider that the connection between it and the client has been disconnected; and if the client does not receive If it sees any packets from the proxy, the client will think that the connection between itself and the proxy has been broken. In order to maintain a normal connection, if there is no other data transmission between the proxy and the client, the client will send a ping message to the proxy every keepalive time (maintained by loop()). The default time of keepalive is 60s.
bind_address :
The IP address of the local network interface to bind this client to, assuming multiple interfaces exist
An example of use is as follows:
# 已构建一个Client：mqttc
mqttc.connect("mqtt.eclipseprojects.io")
# 使用reconnect与disconnect之前必须已经调用过connect
mqttc.reconnect()
mqttc.disconnect()
Note that these three methods are process-blocking.
(3) Network loop control
Network loop control is the driving force behind the client's control of incoming and outgoing data, and it also sends ping messages (heartbeat messages) according to the client's keepalive settings to refresh the connection. If the network loopback method is not called, the client will not process incoming network data and may not send outgoing network data in a timely manner. Its function can be represented by the following figure:
Related methods include:
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)
Contains three sets of logic, one is to call loop() to block the process in a loop: the timeout parameter defines the timeout period for the loop() to block the process, and the max_packets parameter is outdated and should remain unset. timeout must not exceed the client's keepalive value, otherwise the client will be periodically disconnected by the proxy.
The use case is as follows:
mqttc.connect("mqtt.eclipseprojects.io")
while True:
mqttc.loop(timeout=1.0)
# do something else
The second is to use loop_start() and loop_stop() to create and stop background threads to automatically call loop(). This way frees up the main thread. loop_start() can be called before or after connect*(). This call also handles reconnection with the proxy. Call loop_stop() to stop the background thread. The force parameter is currently ignored.
Called periodically to handle network events. This call waits in select() until the network socket is available for reading or writing (as appropriate), and then handles incoming/outgoing data. This function blocks for at most timeout seconds.
The use case is as follows:
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()
The third is to use loop_forever() to continuously block the process (no external loop is required), and the connection will be maintained until the client calls disconnect(). The timeout and max_packets parameters are obsolete and should be left unset. retry_first_connection=True makes it retry the first connection. WARNING: This can lead to situations where clients keep connecting to non-existent hosts without failing. Since the main thread is blocked, other operations cannot be performed on the main thread, and other operations including disconnect() need to be performed through the callback function.
The use case is as follows:
mqttc.connect("mqtt.eclipseprojects.io")
mqttc.loop_forever(retry_first_connection=False)
(4) Subscribe/Unsubscribe
Subscribes a client to, or unsubscribes from, one or more topics.
subscribe(topic, qos=0)
unsubscribe(topic)
Specific parameter description:
topic :
A string specifying the subscription topic to subscribe to.
qos :
The level of quality of service required for the subscription. Default is 0, optional 0, 1, 2.
Example:
mqttc.subscribe(("my/topic", 1))
mqttc.subscribe([("my/topic", 0), ("another/topic", 2)])
mqttc.unsubscribe("my/topic")
mqttc.unsubscribe(["my/topic", "another/topic"])
(5) publish
Publishing causes messages to be sent to the broker, which in turn sends them to any clients subscribed to a matching topic.
Related methods:
publish(topic, payload=None, qos=0, retain=False)
The specific parameters are described as follows:
topic :
The topic the message should be published to
payload :
The actual message to send. If not given, or set to None a zero-length message will be used. Passing an int or float will cause the payload to be converted to a string representing that number. If you wish to send a real int/float, use struct.pack() to create the payload you need.
qos :
The quality of service level to use, the default is 0, optional 0, 1, 2.
retain :
If set to True, the message will be set as a retained message for the topic. The purpose of retaining messages is to enable clients newly subscribing to a topic to receive the last published message in the topic.
The use case is as follows:
mqttc.publish(topic="my/topic", payload=None, qos=0, retain=True)
call back
Callback refers to the corresponding processing triggered by an event. Seven types of callback functions provide processing methods for seven types of events: connection, disconnection, received message, published message, subscribed topic, unsubscribed topic, and received log .
(1) connection
on_connect(): Called when the proxy responds to the client's connection request.
on_connect(client, userdata, flags, rc)
The specific parameters are described as follows:
client :
the client instance for this callback
userdata :
the private user data set in Client() or user_data_set()
flags :
the response flag sent by the proxy
rc :
the connection result
Example:
def on_connect(client, userdata, flags, rc):
print("Connection returned result: "+connack_string(rc))
mqttc.on_connect = on_connect
...
(2) Disconnect
on_disconnect(): Called when the client disconnects from the broker.
on_disconnect(client, userdata, rc)
The specific parameters are described as follows:
client :
the client instance for this callback
userdata :
the private user data set in Client() or user_data_set()
flags :
the response flag sent by the proxy
rc :
the disconnect result
Example:
def on_disconnect(client, userdata, rc):
if rc != 0:
print("Unexpected disconnection.")
mqttc.on_disconnect = on_disconnect
...
(3) received the message
on_message(): Called when a message is received for a topic to which the client is subscribed and the message does not match an existing topic filter callback (defined by message_callback_add()) . message_callback_add(): Called when a message is received for a topic to which the client is subscribed and the message matches
an existing topic filter callback . message_callback_remove(): Removes a topic filter callback previously defined with message_callback_add()
on_message(client, userdata, message)
message_callback_add(sub, callback)
message_callback_remove(sub)
The specific parameters are described as follows:
client :
the client instance of this callback
userdata :
the private user data set in Client() or user_data_set()
message :
MQTTMessage information instance, which is a class containing members topic, payload, qos, retain.
sub :
specific topic
callback :
defined callback function
Example for on_message():
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
...
In addition, give an example to explain when to use message_callback_add(). If the client subscribes to the sensors/# series of topics (# is a wildcard), and the topics that may receive messages include sensors/temperature and sensors/humidity, you can use message_callback_add( ) defines two topic filter callbacks to process messages received under these two topics respectively.
def temperature_callback(client, userdata, message):
...
def humidity_callback(client, userdata, message):
...
mqttclient.message_callback_add("sensors/temperature", temperature_callback)
mqttc.message_callback_add("sensors/humidity", humidity_callback)
mqttc.subscribe("sensors/#")
(4) Release news
on_publish()：
on_publish(client, userdata, mid)
(5) Subscribe to topics
on_subscribe(): Called when the broker responds to a subscription request.
on_subscribe(client, userdata, mid, granted_qos)
(6) Unsubscribe
on_unsubscribe(): Called when the broker responds to an unsubscribe request.
on_unsubscribe(client, userdata, mid)
(7) Log received
on_log(): Called when the client has log information. Define this callback to be useful for debugging. The level variable gives the severity of the message and will be one of MQTT_LOG_INFO, MQTT_LOG_NOTICE, MQTT_LOG_WARNING, MQTT_LOG_ERR and MQTT_LOG_DEBUG.
on_log(client, userdata, level, buf)
References
Paho Python Client Documentation
Paho MQTT Python GitHub Repository
Steve’s Internet Guide