umqtt - MQTT Protocol
This feature is used to create MQTT clients to publish and subscribe to topics.
umqtt is implemented in Python source code. If the corresponding firmware version does not support it by default, users can use the source code umqtt.py and put it in the default directory /usr. When using it, change from umqtt import MQTTClient to from usr.umqtt import MQTTClient.
Initialize MQTT#
MQTTClient
#
Creates MQTT clients.
- Parameter
Parameter | Type | Description |
---|---|---|
client_id | String | Client ID. Each client ID is unique. |
server | String | Server address, which can be an IP address or domain name. |
port | Integer | Server port (optional). Default value: 1883. The default port of MQTT over SSL/TLS is 8883. |
user | String | Username registered on the server (optional). |
password | String | Password registered on the server (optional). |
keepalive | Integer | Timeout of keep-alive (optional). Default value: 60. Unit: s. |
ssl | bool | Enable or disable SSL/TSL encryption. |
ssl_params | String | SSL/TLS parameter (optional). |
reconn | bool | Enable or disable the internal reconnection mechanism (optional). Default value: True (enable). |
version | Integer | The selected MQTT version (optional). version=3 indicates MQTTv3.1. Default value: 4. version=4 indicates MQTTv3.1.1. |
- Return Value
An MQTT client.
Set Callback Function#
MQTTClient.set_callback
#
Sets the callback function of receiving messages.
- Parameter
Parameter | Type | Description |
---|---|---|
callback | function | The callback function of receiving messages. |
- Return Value
None
MQTTClient.error_register_cb
#
Sets the callback function of error occurrence. When the MQTT internal thread is abnormal, the error message is returned by the callback function. The callback function can be called only when the internal reconnection is not enabled.
- Parameter
Parameter | Type | Description |
---|---|---|
callback | function | The callback function of error occurrences. |
- Return Value
None
Example
MQTTClient.set_last_will
#
Sets the last will to be sent to the MQTT server. If a client ungracefully disconnects from the server without calling MQTTClient.disconnect(), the last will will be sent to other clients.
- Parameter
Parameter | Type | Description |
---|---|---|
topic | String | Last-will topic. |
msg | String | Last-will content |
retain | bool | When retain = True, the MQTT broker will retain the message. Default value: False. |
qos | Integer | Quality of Service, 0 or 1. |
- Return Value
None
MQTT Connection Related Features#
MQTTClient.connect
#
Connects to MQTT server. Failed connection leads to an MQTT exception.
- Parameter
Parameter | Type | Description |
---|---|---|
clean_session | bool | Client session type, optional parameter. If this value is True, the MQTT server will delete all information about the client when the client disconnects from the MQTT server. If this value is False, the client session is persistent, that is, when the client disconnects from the MQTT server, the subscription and queuing information will be retained. Default value: False. |
- Return Value
0 – Successful execution
Error message – Failed execution
MQTTClient.disconnect
#
Disconnects from the MQTT server.
- Parameter
None
- Return Value
None
MQTTClient.close
#
Releases socket resources. (Please note the differences between MQTTClient.disconnect() and MQTTClient.close(), where MQTTClient.close() only releases socket resources but MQTTClient.disconnect() releases resources including threads.)
Note: This method can be used only when the client needs to reconnect to the MQTT server. See *Example of MQTT Reconnection After Ungraceful Disconnection* below for details. Call MQTTClient.disconnect() to normally disconnect from the MQTT server.
- Parameter
None
- Return Value
None
MQTTClient.ping
#
Pings to MQTT server to check the connection when keepalive is not 0. When keepalive is 0, this method is disabled.
- Parameter
None
- Return Value
None
Publish and Subscribe Related Features#
MQTTClient.publish
#
Publishes messages.
- Parameter
Parameter | Type | Description |
---|---|---|
topic | String | Message topic. |
msg | String | Data to be sent. |
retain | bool | Default value: False. If this value is set to True when you send a message, the message is retained. The MQTT server retains the last received message with a RETAIN flag bit of True on the server. Whenever the MQTT client connects to the MQTT server and subscribes to a topic, if there is a Retained message under that topic, the MQTT server immediately pushes the Retained message to the client. Note: The MQTT server will only save the last received message with the RETAIN flag bit of True for each topic, that is, if the MQTT server saves one retained message for a Topic, when the client publishes a new retained message, the original message on the server is overwritten. |
qos | Integer | MQTT QoS, 0 or 1. Default value: 0. 0 – The sender sends a message only once. 1 – The sender sends a message at least once and guarantees that the message has been delivered to the MQTT broker. |
- Return Value
None
MQTTClient.subscribe
#
Subscribes to MQTT topics.
- Parameter
Parameter | Type | Description |
---|---|---|
topic | String | topic |
qos | Integer | MQTT QoS, 0 or 1. Default value: 0. 0 – The sender sends a message only once. 1 – The sender sends a message at least once and guarantees that the message has been delivered to the MQTT broker. |
- Return Value
None
MQTTClient.check_msg
#
Checks whether the MQTT server has messages to be processed.
- Parameter
None
- Return Value
None
MQTTClient.wait_msg
#
Blocks waiting for a message response from the MQTT server.
If this method is called in a thread, it is necessary to ensure that the thread stack created is >= 16K. For details, please refer to the mqtt reconnection sample code.
- Parameter
None
- Return Value
None
MQTTClient.get_mqttsta
#
Gets MQTT connection status.
Note:
BG95 series module does not support the API.
If you call MQTTClient.disconnect() before calling MQTTClient.get_mqttsta(), -1 will be returned, because the created object resources are released.
- Parameter
None
- Return Value
0 – Successful connection
1 – Connecting
2 – Server connection closed
-1 – Connection error
Example
Example of MQTT Reconnection After Ungraceful Disconnection
Note:
The parameter reconn in the following example enables or disables the internal reconnection mechanism. Default value: True (enable).
If you need to test or use the external reconnection mechanism, please refer to this example code below. Before testing, set reconn to False, otherwise, the internal reconnection mechanism will be used by default.