【彙總】EMQX 函式API、安裝與使用說明

悟透發表於2024-07-17
MQ函式API

前言全域性說明

EMQX 函式說明


一、說明


二、Client的基本使用流程

建立客戶端例項
使用 connect*() 函式之一連線到代理
呼叫 loop*() 函式之一來維護與代理的網路流量
使用 subscribe() 訂閱主題並接收訊息
使用 publish() 將訊息釋出到代理
使用 disconnect() 斷開與代理的連線

三、Client類與方法

3.1 Client的構建與重置

3.1.1 原型：
Client(client_id="", clean_session=True, userdata=None, protocol=MQTTv311, transport="tcp")
reinitialise(client_id="", clean_session=True, userdata=None)
3.1.2 使用示例如下：
import paho.mqtt.client as mqtt
# 構建一個Client
mqttc = mqtt.Client()
# 重置一個Client
mqttc.reinitialise()
3.1.3 引數說明
client_id:
連線到代理時使用的唯一客戶端 ID 字串。如果 client_id 為零長度或 None ，則將隨機生成一個。在這種情況下，clean_session 引數必須為 True。

clean_session:
確定客戶端型別的布林值。如果為 True，代理將在斷開連線時刪除有關此客戶端的所有資訊。如果為 False，則客戶端是持久客戶端，並且在客戶端斷開連線時將保留訂閱資訊和排隊訊息。
注意，客戶端永遠不會在斷開連線時丟棄自己的傳出訊息。呼叫 connect() 或 reconnect() 將導致訊息被重新傳送。使用 reinitialise() 將客戶端重置為其原始狀態。

userdata:
作為 userdata 引數傳遞給回撥的任何型別的使用者定義資料。稍後可能會使用 user_data_set() 函式對其進行更新。

protocol:
用於此客戶端的 MQTT 協議版本。可以是 MQTTv31 或 MQTTv311

transport:
設定為“websockets”以透過 WebSockets 傳送 MQTT。保留預設值“tcp”以使用原始 TCP。

3.2 連線至代理/重新連線/與代理斷開連線

3.2.1 原型：
connect(host, port=1883, keepalive=60, bind_address="")
reconnect()
disconnect()
3.2.2 使用示例如下：
# 已構建一個Client：mqttc
mqttc.connect("mqtt.eclipseprojects.io") 
# 使用reconnect與disconnect之前必須已經呼叫過connect
mqttc.reconnect()
mqttc.disconnect()
3.2.3 引數說明
host:
遠端代理的主機名或 IP 地址
port:
要連線的伺服器主機的網路埠。 預設為 1883。請注意，基於 SSL/TLS 的 MQTT 的預設埠為 8883，因此如果您使用 tls_set() 或 tls_set_context()，則可能需要手動提供埠
keepalive:
與代理通訊之間允許的最長間隔（以秒為單位）。 如果沒有其他訊息正在交換，這將控制客戶端向代理傳送 ping 訊息的速率。

需要指出，MQTT協議規定，在 1.5倍的keepalive時間內，如果代理沒有收到來自客戶端的任何資料包，那麼代理將認為它和這個客戶端之間的連線已經斷開；而如果客戶端沒有收到來自 代理的任何資料包，那麼這個客戶端會認為它和代理之間的連線已經斷開。為維持正常的連線，如果代理與客戶端之間沒有其他資料傳輸，客戶端會每隔keepalive時間向代理傳送一次ping訊息（由loop()來維護）。keepalive的預設時間是60s。

bind_address:
假設存在多個介面，要將此客戶端繫結到的本地網路介面的 IP 地址

3.3 網路迴路控制

3.3.1 原型：
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)
3.3.2 使用示例如下：
3.3.3 引數說明
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()

3.4 訂閱/取消訂閱

3.4.1 原型：
subscribe(topic, qos=0)
unsubscribe(topic)
3.4.2 使用示例如下：
mqttc.subscribe(("my/topic", 1))
mqttc.subscribe([("my/topic", 0), ("another/topic", 2)])
mqttc.unsubscribe("my/topic")
mqttc.unsubscribe(["my/topic", "another/topic"])
3.4.3 引數說明
topic:
一個字串，指定要訂閱的訂閱主題。
qos:
訂閱所需的服務質量(quality of service)級別。 預設為 0，可選0，1，2。

3.5 釋出

3.5.1 原型：
publish(topic, payload=None, qos=0, retain=False)
3.5.2 使用示例如下：
mqttc.publish(topic="my/topic", payload=None, qos=0, retain=True)
3.5.3 引數說明
topic:
訊息應該釋出到的主題
payload:
要傳送的實際訊息。 如果沒有給出，或者設定為 None 將使用零長度訊息。 傳遞 int 或 float 將導致有效負載轉換為表示該數字的字串。 如果您希望傳送真正的 int/float，請使用 struct.pack() 建立您需要的有效負載。
qos:
要使用的服務質量（quality of service）水平，預設為 0，可選0，1，2。
retain:
如果設定為 True，則該訊息將被設定為該主題的保留訊息。保留訊息的作用是使新訂閱某個主題的客戶端能夠收到該主題中上一次釋出的訊息。

四、回撥

4.1 連線

4.1.1 原型：
on_connect(client, userdata, flags, rc)
4.1.2 使用示例如下：
def on_connect(client, userdata, flags, rc):
    print("Connection returned result: "+connack_string(rc))

mqttc.on_connect = on_connect
...
4.1.3 引數說明
client:
此回撥的客戶端例項
userdata:
在 Client() 或 user_data_set() 中設定的私有使用者資料
flags:
代理傳送的響應標誌
rc:
連線結果

4.2 斷開連線

4.2.1 原型：
on_disconnect(client, userdata, rc)
4.2.2 使用示例如下：
def on_disconnect(client, userdata, rc):
    if rc != 0:
        print("Unexpected disconnection.")

mqttc.on_disconnect = on_disconnect
...
4.2.3 引數說明
client:
此回撥的客戶端例項
userdata:
在 Client() 或 user_data_set() 中設定的私有使用者資料
flags:
代理傳送的響應標誌
rc:
斷開結果

4.3 收到訊息

4.3.1 原型：
on_message(client, userdata, message)
message_callback_add(sub, callback)
message_callback_remove(sub)
4.3.2 使用示例如下：
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
...
4.3.3 引數說明
client:
此回撥的客戶端例項
userdata:
在 Client() 或 user_data_set() 中設定的私有使用者資料
message:
MQTTMessage資訊例項，這是一個包含成員 topic、payload、qos、retain 的類。
sub:
特定主題
callback:
定義的callback函式

4.4 釋出訊息

4.3.1 原型：
on_publish(client, userdata, mid)
4.3.2 使用示例如下：
4.3.3 引數說明

4.5 訂閱主題

4.3.1 原型：
on_subscribe(client, userdata, mid, granted_qos)
4.3.2 使用示例如下：
4.3.3 引數說明

4.6 取消訂閱

4.3.1 原型：
on_unsubscribe(client, userdata, mid)
4.3.2 使用示例如下：
4.3.3 引數說明

4.6 收到日誌

4.3.1 原型：
on_log(client, userdata, level, buf)
4.3.2 使用示例如下：
4.3.3 引數說明

免責宣告：本號所涉及內容僅供安全研究與教學使用，如出現其他風險，後果自負。



參考、來源：
https://github.com/emqx/MQTT-Client-Examples （官方原始碼）
https://docs.emqx.com/zh/cloud/latest/connect_to_deployments/python_sdk.html (官方說明)
https://www.cnblogs.com/steven-dou/articles/13921825.html （paho-mqtt 模組使用和API分析）
https://blog.csdn.net/zbgjhy88/article/details/98112017 （API使用）
https://wenku.csdn.net/answer/c4f5f24eff7949e983a21ccdaaa7638e
https://blog.csdn.net/qq_45664055/article/details/135497850
https://blog.51cto.com/u_16213324/11147532
https://www.jb51.net/article/160686.htm



相關文章