參考文獻: paho-mqtt 1.1 steves-internet-guide
broker --- sudo apt-get install mosquitto 在ubuntu上安裝,使用MQTT Mosquitto
client ---- pip install paho-mqtt mqtt documents in python
example: 1>mqtt client python example 2>Python簡單試用MQTT服務器
Table of Contents
reinitialise(client_id="", clean_session=True, userdata=None)
connect (host , port = 1883 , keepalive = 60 , bind_address = “” )
connect_async (host , port = 1883 , keepalive = 60 , bind_address = “” )
connect_srv(domain , keepalive = 60 , bind_address = “” )
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 )
訂閱: subscribe (topic , qos = 0 )
發佈:publish(topic , payload = None , qos = 0 , retain = False )
1. on_connect (client , userdata , flags , rc )
2.on_disconnect (client , userdata , rc )
3.on_message(client, userdata, message)
4.message_callback_add (sub , callback )
5.message_callback_remove (sub )
6. on_publish (client , userdata , mid )
7.on_subscribe (client , userdata , mid , granted_qos )
8.on_unsubscribe (client , userdata , mid )
9.on_log (client , userdata , level , buf )
10.on_socket_open(client,userdata,sock)
11.on_socket_close(client,userdata,sock)
12.on_socket_register_write(client,userdata,sock)
13.on_socket_unregister_write(client,userdata,sock)
1.loop_read (max_packets = 1 )
2.loop_write (max_packets = 1 )
客戶端模塊還提供一些全局幫助程序功能。topic_matches_sub(sub,topic)
一般用法流程如下:
1.創建客戶端實例:
Client(client_id = “” , clean_session = True , userdata = None, protocol= MQTTv311 , transport = “tcp” )
client_id --- 連接到代理時使用的唯一客戶端ID字符串。如果 client_id爲零長度或無,則將隨機生成一個。在這種情況下,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。
構造函數示例:
import paho.mqtt.client as mqtt
mqttc = mqtt.Client()
reinitialise(client_id="", clean_session=True, userdata=None)
simon總結:不能正常調用,只能通過Client實例化,不能初始化。
在重新初始化()函數,就好像它剛剛創建的客戶重置爲初始狀態。它採用與Client()構造函數相同的參數。
重新初始化示例:
mqttc.reinitialise()
選項功能:
這些函數表示可以在客戶端上設置以修改其行爲的選項。在大多數情況下,必須在連接到connecting 之前完成此操作。
1>max_inflight_messages_set(self, inflight)
設置QoS> 0的最大消息數,這些消息可以一次通過其網絡流。默認爲20.增加此值將消耗更多內存,但可以增加吞吐量。
2>max_queued_messages_set (self , queue_size )
設置QoS> 0的傳出消息的最大數量,該消息可以在傳出消息隊列中掛起。默認爲0. 0表示無限制。當隊列已滿時,將丟棄任何進一步的傳出消息。
3>message_retry_set(retry)
如果代理沒有響應,則設置重試QoS> 0的消息之前的時間(以秒爲單位)。默認設置爲5秒,通常不需要更改。
4>ws_set_options (self , path = “/ mqtt” , headers = None )
設置websocket連接選項。僅當transport =“websockets”傳遞給Client()構造函數時,纔會使用這些選項。
path --- 要在代理上使用的mqtt路徑。
head --- 指定應附加到標準websocket標頭的額外標頭列表的字典,或者採用正常websocket標頭並返回帶有一組標頭以連接到代理的新字典的字典。
5>tls_set(ca_certs=None, certfile=None, keyfile=None, cert_reqs=ssl.CERT_REQUIRED,tls_version=ssl.PROTOCOL_TLS, ciphers=None)
配置網絡加密和身份驗證選項。啓用SSL / TLS支持。
ca_certs
證書頒發機構證書文件的字符串路徑,該文件將被此客戶端視爲受信任。如果這是給出的唯一選項,則客戶端將以與Web瀏覽器類似的方式運行。也就是說,它將要求代理在ca_certs中擁有由證書頒發機構簽名的證書,並使用TLS v1進行通信,但不會嘗試任何形式的身份驗證。這提供了基本的網絡加密,但可能不夠,具體取決於代理的配置方式。默認情況下,在Python 2.7.9+或3.4+上,使用系統的默認證書頒發機構。在較舊的Python版本中,此參數是必需的。
certfile,密鑰文件
字符串分別指向PEM編碼的客戶端證書和私鑰。如果這些參數不是None,那麼它們將用作基於TLS的身份驗證的客戶端信息。對此功能的支持取決於代理。請注意,如果這些文件中的任何一個加密並需要密碼才能解密,Python將在命令行中詢問密碼。目前無法定義回調來提供密碼。
cert_reqs
定義客戶端對代理施加的證書要求。默認情況下,這是ssl.CERT_REQUIRED,這意味着代理必須提供證書。有關此參數的更多信息,請參見ssl pydoc。
tls_version
指定要使用的SSL / TLS協議的版本。默認情況下(如果python版本支持它),檢測到最高的TLS版本。如果不可用,則使用TLS v1。以前的版本(所有以SSL開頭的版本)都是可能的,但由於可能存在安全問題,因此不推薦使
ciphers
指定此連接允許哪些加密密碼的字符串,或使用默認值的None。有關更多信息,請參閱ssl pydoc。
必須在connect *()之前調用。
6>tls_set_context (context = None )
配置網絡加密和認證上下文。啓用SSL / TLS支持。
content
一個ssl.SSLContext對象。默認情況下,這由ssl.create_default_context()提供(如果可用)(在Python 3.4中添加)。
如果您不確定使用此方法,請使用默認上下文,或使用tls_set方法。有關更多信息,請參閱ssl模塊文檔部分有關安全性注意事項。必須在connect *()之前調用。
7>tls_insecure_set (value )
配置服務器證書中服務器主機名的驗證。
如果value設置爲True,則無法保證您連接的主機不會模擬您的服務器。這在初始服務器測試中非常有用,但可以使惡意第三方通過DNS欺騙來模擬您的服務器。
請勿在實際系統中使用此功能。將值設置爲True意味着使用加密沒有意義。
必須在connect *()之前和tls_set()或tls_set_context()之後調用。
8>enable_logger (logger = None )
使用標準python日誌包啓用日誌記錄(請參閱PEP 282)。這可以與on_log回調方法同時使用。
如果指定了logger,那麼將使用該logging.Logger對象,否則將自動創建一個。
根據以下映射將Paho日誌記錄級別轉換爲標準級別:
泛美衛生組織 記錄
MQTT_LOG_ERR logging.ERROR
MQTT_LOG_WARNING logging.WARNING
MQTT_LOG_NOTICE logging.INFO (沒有直接的等價物)
MQTT_LOG_INFO logging.INFO
MQTT_LOG_DEBUG logging.DEBUG
9>disable_logger ()
使用標準python日誌包禁用日誌記錄。這對on_log回調沒有影響。
10>username_pw_set(username, password=None)
爲代理身份驗證設置用戶名和密碼。必須在connect *()之前調用。
11>user_data_set (userdata )
設置生成事件時將傳遞給回調的私有用戶數據。將此用於您自己的目的,以支持您的應用程序。
12>will_set (topic , payload = None , qos = 0 , retain = False )
設置要發送給經紀人的遺囑。如果客戶端在未調用disconnect()的情況下 斷開連接,則代理將代表其發佈消息。
topic話題
應該發佈遺囑消息的主題。
payload
要作爲遺囑發送的消息。如果沒有給出,或者設置爲None,則將使用零長度消息作爲遺囑。傳遞int或float將導致有效負載轉換爲表示該數字的字符串。如果您希望發送一個真正的int / float,請使用struct.pack()來創建所需的有效負載。
qos
用於意志的服務質量水平。
retain Mqtt精髓系列之保留消息Retained Messages
如果設置爲True,則will消息將被設置爲主題的“最後已知好”/保留消息。
如果qos不是0,1或2,或者topic爲 None或者字符串長度爲零,則引發ValueError。
13>reconnect_delay_set (min_delay = 1 , max_delay = 120 )
客戶端將自動重試連接。在每次嘗試之間,它將在min_delay和max_delay之間等待幾秒鐘。當連接丟失時,最初重新連接嘗試延遲 min_delay秒。在後續嘗試max_delay之間加倍。
連接完成後,延遲將重置爲min_delay(例如,收到CONNACK,而不僅僅建立TCP連接)。
2.使用connect*()函數之一連接到代理
連接/重新連接/斷開連接
connect (host , port = 1883 , keepalive = 60 , bind_address = “” )
該連接()函數的客戶端連接到代理。這是一個阻止功能。它需要以下參數:
host --- 遠程代理的主機名或IP地址
port --- 要連接的服務器主機的網絡端口。默認爲1883.請注意,MQTT over SSL / TLS的默認端口爲8883,因此如果您使用 tls_set()或tls_set_context(),則端口可能需要手動提供
keepalive --- 與代理通信之間允許的最長時間(以秒爲單位)。如果沒有交換其他消息,則控制客戶端將ping消息發送給代理的速率 心跳檢測是什麼
bind_address --- 假設存在多個接口,則綁定此客戶端的本地網絡接口的IP地址
Callback --- 當客戶端響應連接從代理接收到CONNACK消息時,它會生成on_connect()回調。
連接示例:
mqttc.connect("iot.eclipse.org")
connect_async (host , port = 1883 , keepalive = 60 , bind_address = “” )
異步連接,與loop_start()結合使用以非阻塞方式連接。在調用loop_start()之前,連接不會完成。
Callback (connect)
當客戶端響應連接從代理接收到CONNACK消息時,它會生成on_connect()回調。
connect_srv(domain , keepalive = 60 , bind_address = “” )
DNS連接,使用SRV DNS查找連接到代理以獲取代理地址。採用以下參數:
domain --- 用於搜索SRV記錄的DNS域。如果爲None,請嘗試確定本地域名。
有關keepalive和bind_address 參數的說明,請參閱connect()。
Callback(connect_srv)
當客戶端響應連接從代理接收到CONNACK消息時,它會生成on_connect()回調。
SRV Connect示例:
mqttc.connect_srv("eclipse.org")
reconnect()
使用先前提供的詳細信息重新連接到代理。在調用此函數之前,您必須調用connect *()。
Callback (reconnect)
當客戶端響應連接從代理接收到CONNACK消息時,它會生成on_connect()回調。
3.調用其中一個loop*() 函數來維護代理的網絡流量
網絡循環:Network loop
這些功能是客戶背後的驅動力。如果未調用它們,則不會處理傳入的網絡數據,並且可能無法及時發送傳出的網絡數據。管理網絡循環有四種選擇。這裏描述了三個,下面是“外部事件循環支持”中的第四個。不要混合不同的循環功能。
loop(timeout=1.0, max_packets=1)
定期致電處理網絡事件。此調用在select()中等待,直到網絡套接字可用於讀取或寫入(如果適用),然後處理傳入/傳出數據。此功能可以阻止超時秒。超時不得超過客戶端的keepalive值,否則代理將定期斷開您的客戶端。
該max_packets說法已經過時,應該保留未設置。
循環示例:
run = True
while run:
mqttc.loop()
loop_start ()/ loop_stop (force = False )
這些函數實現了網絡循環的線程接口。在connect *()之前或之後調用 loop_start()一次,在後臺運行一個線程以自動調用loop()。這釋放了可能阻塞的其他工作的主線程。此調用還處理重新連接到代理。調用loop_stop()來停止後臺線程。該部隊 目前參數將被忽略。
循環啓動/停止示例:
mqttc.connect("iot.eclipse.org")
mqttc.loop_start()
while True:
temperature = sensor.blocking_read()
mqttc.publish("paho/temperature", temperature
loop_forever (timeout = 1.0 , max_packets = 1 , retry_first_connection = False )
這是網絡循環的阻塞形式,在客戶端調用disconnect()之前不會返回。它會自動處理重新連接。
除使用connect_async時的第一次連接嘗試外,使用 retry_first_connection = True使其重試第一次連接。警告:這可能會導致客戶端保持連接到非現有主機而不會失敗的情況。
在超時和max_packets參數已過時,應保留未設置。
4.使用subscribe()訂閱主題並接收消息
訂閱: subscribe (topic , qos = 0 )
將客戶訂閱到一個或多個主題。可以通過三種不同方式調用此函數:
1. 簡單的字符串和整數
e.g. subscribe("my/topic", 2)
topic --- 指定要訂閱的訂閱主題的字符串。
Qos --- 訂閱所需的服務質量水平。默認爲0。
2. 字符串和整數元組
e.g. subscribe(("my/topic", 1))
topic -- (topic, qos)的元組。主題和qos都必須存在於元組中。
Qos --- 不曾用過。
3. 字符串和整數元組的列表
e.g. subscribe([("my/topic", 0), ("another/topic", 2)])
這允許在單個SUBSCRIPTION命令中進行多個主題訂閱,這比使用subscribe()的多個調用更有效。
topic --- 格式元組列表(主題,qos)。主題和qos都必須存在於所有元組中。
Qos --- 不曾用過。
該函數返回一個元組(result,mid),其中結果是 MQTT_ERR_SUCCESS表示成功,或者(MQTT_ERR_NO_CONN,None)如果客戶端當前未連接。 mid是訂閱請求的消息ID。中間值可用於通過檢查on_subscribe()回調中的mid參數來跟蹤訂閱請求(如果已定義)。
如果qos不是0,1或2,或者topic爲None或者字符串長度爲零,或者topic不是字符串,元組或列表,則引發ValueError。
Callback (subscribe):
當代理確認訂閱時, 將生成on_subscribe()回調。
退訂:unsubscribe(topic)
取消訂閱客戶端的一個或多個主題。
topic --- 單個字符串或作爲要取消訂閱的訂閱主題的字符串列表。
返回元組(result,mid),其中結果是MQTT_ERR_SUCCESS以指示成功,或者(MQTT_ERR_NO_CONN,None)如果客戶端當前未連接。mid是取消訂閱請求的消息ID。中間值可用於通過檢查on_unsubscribe()回調中的mid參數來跟蹤取消訂閱請求(如果已定義)。
如果topic爲None或者字符串長度爲零,或者不是字符串或列表,則引發ValueError。
Callback (unsubscribe)
當代理確認取消訂閱時, 將生成on_unsubscribe()回調。
5.使用publish()將消息發佈到代理
發佈:publish(topic , payload = None , qos = 0 , retain = False )
這會導致將消息發送到代理,然後從代理髮送到訂閱匹配主題的任何客戶端。它需要以下參數:
topic --- 應該發佈消息的主題
payload --- 要發送的實際消息。如果沒有給出,或者設置爲None,將使用零長度消息。傳遞int或float將導致有效負載轉換爲表示該數字的字符串。如果您希望發送一個真正的int / float,請使用struct.pack()來創建所需的有效負載
Qos -- 要使用的服務質量水平
retain --- 如果設置爲True,則將消息設置爲主題的“最後已知好”/保留消息。Mqtt精髓系列之保留消息Retained Messages
返回MQTTMessageInfo,它公開以下屬性和方法:
1>rc,發佈的結果。它可以是MQTT_ERR_SUCCESS以指示成功,MQTT_ERR_NO_CONN(如果客戶端當前未連接)或MQTT_ERR_QUEUE_SIZE(當max_queued_messages_set用於指示消息既未排隊也未發送時)。
2>mid是發佈請求的消息ID。中間值可用於通過檢查on_publish()回調中的mid參數來跟蹤發佈請求 (如果已定義)。wait_for_publish可能會更容易,具體取決於您的用例。
3>wait_for_publish()將阻塞,直到消息發佈。如果消息未排隊,則會引發ValueError(rc == MQTT_ERR_QUEUE_SIZE)。
4>如果消息已發佈,則is_published返回True。如果消息未排隊,則會引發ValueError(rc == MQTT_ERR_QUEUE_SIZE)。
A ValueError異常將如果主題是提高無,長度爲零或無效(包含通配符)中,如果服務質量是不爲0,1或2中的一個,或者如果所述有效載荷的長度比268435455個字節。
Callback(public)
當消息已發送到代理時,將生成on_publish()回調。
MQTT最大的優勢是解耦了發佈消息的客戶(發佈者)與訂閱消息的客戶(訂閱者)之間的關係,這意味着發佈者和訂閱者之間並不需要直接建立聯繫,只要認識同一個消息代理即可。
運用MQTT協議,設備可以很方便地連接到物聯網雲服務,管理設備並處理數據,最後應用到各種業務場景;二進制協議,緊湊、佔用空間小,協議頭只有2個字節 ,還提供了三種消息可能性保障(Qos):0:最多一次 、1:最少一次、2:只有一次。
大致模式:
6.使用disconnect()斷開與代理的連接
斷開:disconnect()
徹底斷開與經代理的聯繫。使用disconnect()不會導致代理髮送will消息。斷開連接不會等待發送所有排隊的消息,以確保傳遞所有消息,應使用來自MQTTMessageInfo的wait_for_publish()。有關詳細信息,請參閱publish()。
回調:Callback (disconnect)
當客戶端發送了斷開連接消息時,它會生成 on_disconnect()回調。
將調用回調以允許應用程序根據需要處理事件。這些回調描述如下:
7.所有回調函數:
1. on_connect (client , userdata , flags , rc )
當代理響應我們的連接請求時調用。
client --- 此回調的客戶端實例
userdata --- Client()或user_data_set()中設置的私有用戶數據
flags --- 經紀人發送的響應標誌
RC --- 連接結果
flags是一個包含來自代理的響應標誌的字典:
flags ['session present'] --- 此標誌對於客戶端非常有用
使用clean session設置爲0。如果具有乾淨 session=0的客戶端重新連接到先前已連接到的代理,則此標誌指示代理是否仍具有客戶端的會話信息。如果爲1,則會話仍然存在。
rc的值表示成功與否:
0:連接成功
1:連接被拒絕 - 協議版本
2: 錯誤-連接被拒絕 - 客戶端標識符無效
3:連接被拒絕 - 服務器不可用
4:連接被拒絕 - 用戶名或密碼錯誤
5:連接被拒絕 - 未授權6-255:當前未使用。
在連接示例:
def on_connect(client, userdata, flags, rc):
print("Connection returned result: "+connack_string(rc))
mqttc.on_connect = on_connect
...
2.on_disconnect (client , userdata , rc )
當客戶端與代理斷開連接時調用。
client --- 此回調的客戶端實例
userdata --- Client()或user_data_set()中設置的私有用戶數據
RC --- 斷開的結果
rc參數表示斷開狀態。如果MQTT_ERR_SUCCESS (0),則調用回調以響應disconnect()調用。如果有任何其他值,則斷開連接是意外的,例如。
在斷開連接示例:
def on_disconnect(client, userdata, rc):
if rc != 0:
print("Unexpected disconnection.")
mqttc.on_disconnect = on_disconnect
...
3.on_message(client, userdata, message)
在收到客戶端訂閱的主題的消息並且消息與現有主題過濾器回調不匹配時調用。使用message_callback_add()定義將爲特定主題過濾器調用的回調。當沒有匹配時,on_message將作爲後備。
client --- 此回調的客戶端實例
userdata --- Client()或user_data_set()中設置的私有用戶數據
message --- MQTTMessage的一個實例。這是一個包含成員主題,有效負載,qos,retain的類。
在消息示例:
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.message_callback_add (sub , callback )
此函數允許您定義處理特定訂閱篩選器的傳入消息的回調,包括通配符。例如,這可以讓您訂閱傳感器/#並有一個回調來處理傳感器/溫度,另一個回調 來處理傳感器/溼度。
message_callback_add (sub , callback )sub --- 要與此回調匹配的訂閱篩選器。每個文字子字符串只能定義一個回調
callback --- 要使用的回調。採用與on_message 回調相同的形式。
如果使用message_callback_add()和on_message,則只有與特定於訂閱的過濾器不匹配的消息纔會傳遞給on_message 回調。
如果多個子匹配主題,則將調用每個回調(例如,子傳感器/# 和子+ /溼度都匹配具有主題傳感器/溼度的消息,因此兩個回調將處理該消息)。
5.message_callback_remove (sub )
使用message_callback_add()刪除先前註冊的主題/訂閱特定回調 。
sub --- 要刪除的訂閱過濾器
6. on_publish (client , userdata , mid )
當使用publish()調用發送的消息已完成向代理的傳輸時調用。對於QoS級別爲1和2的消息,這意味着已完成相應的握手。對於QoS 0,這僅表示消息已離開客戶端。所述中間變量從相應的返回的中間可變匹配發布()調用,以允許跟蹤傳出消息。
此回調很重要,因爲即使publish()調用返回成功,也並不總是意味着消息已被髮送。
7.on_subscribe (client , userdata , mid , granted_qos )
當代理響應訂閱請求時調用。該中期變量從相應返回的中期可變匹配訂閱()調用。該granted_qos變量是給QoS級別的經紀人已經授予每個不同的訂閱請求的整數列表。
8.on_unsubscribe (client , userdata , mid )
當代理響應取消訂閱請求時調用。該中期變量從相應返回的中期可變匹配退訂() 調用。
9.on_log (client , userdata , level , buf )
當客戶端有日誌信息時調用。定義以允許調試。的 電平可變給出了消息的嚴重程度和將其中 MQTT_LOG_INFO,MQTT_LOG_NOTICE,MQTT_LOG_WARNING,MQTT_LOG_ERR,和MQTT_LOG_DEBUG。消息本身就是buf。
這可以與標準Python日誌記錄同時使用,可以通過enable_logger方法啓用。
10.on_socket_open(client,userdata,sock)
打開插座時調用。使用此命令註冊帶有外部事件循環的套接字以進行讀取。
11.on_socket_close(client,userdata,sock)
當插座即將關閉時調用。使用此選項從外部事件循環取消註冊套接字以進行讀取。
12.on_socket_register_write(client,userdata,sock)
當對套接字的寫操作失敗時調用,因爲它將被阻塞,例如輸出緩衝區已滿。使用此命令向外部事件循環註冊套接字以進行寫入。
13.on_socket_unregister_write(client,userdata,sock)
在先前失敗後對套接字的寫操作成功時調用。使用此選項從外部事件循環中取消註冊套接字以進行寫入。
8.外部事件循環支持:
1.loop_read (max_packets = 1 )
套接字準備好讀取時調用。max_packets已過時,應保留未設置狀態。
2.loop_write (max_packets = 1 )
套接字準備好寫入時調用。max_packets已過時,應保留未設置狀態。
3.loop_misc ()
每隔幾秒調用一次,以處理消息重試和ping。
4.socket ()
返回客戶端中使用的套接字對象,以允許與其他事件循環進行交互。此調用對基於選擇的循環特別有用。請參閱examples / loop_select.py。
5.want_write ()
如果有等待寫入的數據,則返回true,以允許客戶端與其他事件循環接口。此調用對基於選擇的循環特別有用。請參閱examples / loop_select.py。
6.STATE CALLBACKS
on_socket_open
on_socket_close
on_socket_register_write
on_socket_unregister_write
使用這些回調可以獲得有關套接字狀態更改的通知。這對於註冊或取消註冊用於讀取和寫入的套接字的事件循環特別有用。有關示例,請參閱examples / loop_asyncio.py。
打開套接字時,將調用on_socket_open。使用事件循環註冊套接字以進行讀取。
當即將關閉套接字時,將調用on_socket_close。從事件循環中取消註冊套接字以進行讀取。
當對套接字的寫入失敗,因爲它將被阻塞,例如輸出緩衝區已滿, 則調用on_socket_register_write。使用事件循環註冊套接字以進行寫入。
當下一次寫入套接字成功時,將調用on_socket_unregister_write。從事件循環中取消註冊套接字以進行寫入。
始終按此順序調用回調:
on_socket_open
Zero or more times:
on_socket_register_write
on_socket_unregister_write
on_socket_close
9.全局輔助函數:
客戶端模塊還提供一些全局幫助程序功能。
topic_matches_sub(sub,topic)
可用於檢查主題是否 與訂閱匹配。
eg:
the topic foo/bar would match the subscription foo/# or +/bar
the topic non/matching would not match the subscription non/+/+
connack_string(connack_code)
返回與CONNACK結果關聯的錯誤字符串。
error_string(mqtt_errno)
返回與Paho MQTT錯誤號關聯的錯誤字符串。
10.Publish
該模塊提供了一些輔助函數,允許以一次性方式直接發佈消息。換句話說,它們對於您希望發佈到代理的單個/多個消息的情況很有用,然後在沒有其他任何需要的情況下斷開連接。
提供的兩個函數是single()和multiple()。
single(topic, payload=None, qos=0, retain=False, hostname="localhost",
port=1883, client_id="", keepalive=60, will=None, auth=None, tls=None,
protocol=mqtt.MQTTv311, transport="tcp")
將單個消息發佈到代理,然後徹底斷開連接。
topic --- 唯一必需的參數必須是有效負載將發佈到的主題字符串。
payload --- 要發佈的有效載荷。如果爲“”或“無”,則將發佈零長度有效負載。
qos --- 發佈時使用的qos,默認爲0。
retain --- 設置要保留的消息(True)或不保留(False)。
hostname --- 包含要連接的代理的地址的字符串。默認爲localhost。
port --- 連接到代理的端口。默認爲1883。
CLIENT_ID --- 要使用的MQTT客戶端ID。如果“”或“無”,Paho庫將自動生成客戶端ID。
keepalive --- 客戶端的keepalive超時值。默認爲60秒。
will --- 包含客戶端的will參數的dict:
will = {'topic':“<topic>”,'payload':“<payload”>,'qos':<qos>,'retain':<retain>}。
topic是必需的,所有其他參數都是可選的,默認分別爲None,0和False。默認爲None,表示不應使用。
auth --- 包含客戶端身份驗證參數的dict:
auth = {'username':“<username>”,'password':“<password>”}
username是必需的,密碼是可選的,如果沒有提供,則默認爲無。默認爲None,表示不使用身份驗證。
TLS --- 包含客戶端的TLS配置參數的dict:
dict = {‘ca_certs’:”<ca_certs>”, ‘certfile’:”<certfile>”, ‘keyfile’:”<keyfile>”, ‘tls_version’:”<tls_version>”, ‘ciphers’:”<ciphers”>}
ca_certs是必需的,所有其他參數都是可選的,如果沒有提供,則默認爲None,這會導致客戶端使用默認行爲 - 請參閱paho.mqtt.client文檔。默認爲None,表示不應使用TLS。
protocol --- 選擇要使用的MQTT協議版本。使用MQTTv31或MQTTv311。
transport --- 設置爲“websockets”以通過WebSockets發送MQTT。保留默認值“tcp”以使用原始TCP。
發佈單個示例:
import paho.mqtt.publish as publish
publish.single("paho/test/single", "payload", hostname="iot.eclipse.org")
multiple(msgs, hostname="localhost", port=1883, client_id="", keepalive=60,
will=None, auth=None, tls=None, protocol=mqtt.MQTTv311, transport="tcp")
將多條消息發佈到代理,然後乾淨地斷開連接。
msg --- 要發佈的消息列表。每條消息都是字典或元組。
如果是dict,只有主題必須存在。默認值將用於任何缺少的參數。dict必須是以下形式:
msg = {'topic':“<topic>”,'payload':“<payload>”,'qos':<qos>,'retain':<retain>}
主題必須存在且可能不是空的。如果有效載荷爲“”,無或不存在,則將發佈零長度有效載荷。如果qos不存在,則使用默認值0。如果不存在retain,則使用默認值False。
如果是一個元組,那麼它必須是以下形式:
(“<topic>”,“<payload>”,qos,retain)
有關hostname,port,client_id,keepalive,will,auth,tls,protocol,transport的說明,請參閱single()。
發佈多個示例
import paho.mqtt.publish as publish
msgs = [{'topic':"paho/test/multiple", 'payload':"multiple 1"},("paho/test/multiple", "multiple 2", 0, False)]
publish.multiple(msgs, hostname="iot.eclipse.org")
11.訂閱
該模塊提供了一些輔助函數,允許直接訂閱和處理消息。提供的兩個函數是simple()和callback()。
simple(topics, qos=0, msg_count=1, retained=False, hostname="localhost",
port=1883, client_id="", keepalive=60, will=None, auth=None, tls=None,
protocol=mqtt.MQTTv311)
simple:訂閱一組主題並返回收到的消息。這是一個阻止功能。
topics --- 唯一必需的參數是客戶端將訂閱的主題字符串。如果應訂閱多個主題,則可以是字符串或字符串列表。
Qos --- 訂閱時使用的qos,默認爲0。
msg_count --- 要從代理檢索的消息數。默認爲1.如果爲1,將返回單個MQTTMessage對象。如果> 1,將返回MQTTMessages列表。
retained --- 設置爲True以考慮保留的消息,設置爲False以忽略具有保留標誌集的消息。
hostname --- 包含要連接的代理的地址的字符串。默認爲localhost。
port --- 連接到代理的端口。默認爲1883。
client_id --- 要使用的MQTT客戶端ID。如果“”或“無”,Paho庫將自動生成客戶端ID。
keeplive --- 客戶端的keepalive超時值。默認爲60秒。
will --- 包含客戶端的will參數的dict:
will = {'topic':“<topic>”,'payload':“<payload”>,'qos':<qos>,'retain':<retain>}。
主題是必需的,所有其他參數都是可選的,默認分別爲None,0和False。默認爲None,表示不應使用。
auth --- 包含客戶端身份驗證參數的dict:
auth = {'username':“<username>”,'password':“<password>”}
用戶名是必需的,密碼是可選的,如果沒有提供,則默認爲無。默認爲None,表示不使用身份驗證。
tls --- 包含客戶端的TLS配置參數的dict:
dict = {'ca_certs':“<ca_certs>”,'certfile':“<certfile>”,'keyfile':“<keyfile>”,
'tls_version':“<tls_version>”,'ciphers':“<ciphers “>}
ca_certs是必需的,所有其他參數都是可選的,如果沒有提供,則默認爲None,這會導致客戶端使用默認行爲 - 請參閱paho.mqtt.client文檔。
默認爲None,表示不應使用TLS。
protocol --- 選擇要使用的MQTT協議版本。使用MQTTv31或MQTTv311。
簡單的例子:
import paho.mqtt.subscribe as subscribe
msg = subscribe.simple("paho/test/simple", hostname="iot.eclipse.org")
print("%s %s" % (msg.topic, msg.payload))
callback(callback, topics, qos=0, userdata=None, hostname="localhost",
port=1883, client_id="", keepalive=60, will=None, auth=None, tls=None,
protocol=mqtt.MQTTv311)
訂閱一組主題並使用用戶提供的回調處理收到的消息。
callback --- 一個“on_message”回調,將用於收到的每條消息和表單
def on_message (client , userdata , message )
topic --- 客戶端將訂閱的主題字符串。如果應訂閱多個主題,則可以是字符串或字符串列表。
Qos --- 訂閱時使用的qos,默認爲0。
userdata --- 用戶提供的對象,在收到消息時將傳遞給on_message回調。
有關hostname,port,client_id,keepalive,will,auth,tls,protocol的說明,請參閱simple()。
回調示例:
import paho.mqtt.subscribe as subscribe
def on_message_print(client, userdata, message):
print("%s %s" % (message.topic, message.payload))
subscribe.callback(on_message_print, "paho/test/callback", hostname="iot.eclipse.org")