mqtt — לקוח MQTT פשוט

המודול mqtt מספק מימוש מינימלי של לקוח MQTT v3.1.1 המתאים לשימוש בהתקנים מוגבלי זיכרון. הוא תומך בהתחברות ל-broker (עם TLS אופציונלי), פרסום הודעות, הרשמה ל-topics, הגדרת last-will ו-keep-alive pings.

דוגמה:

from mqtt import MQTTClient

def callback(topic, msg):
    print(topic, msg)

client = MQTTClient("openmv", "broker.example.com", 1883)
client.set_callback(callback)
client.connect()
client.subscribe(b"openmv/in")
client.publish(b"openmv/out", b"hello")
while True:
    client.check_msg()

חריגות

exception mqtt.MQTTException

מועלית כאשר ה-broker דוחה את בקשת ה-CONNECT או כאשר בקשת SUBSCRIBE נדחית. הארגומנט היחיד הוא קוד החזרה המספרי שסופק על ידי ה-broker.

מחלקות

class mqtt.MQTTClient(client_id: bytes | str, server: str, port: int, ssl_params: dict | None = None, user: bytes | str | None = None, password: bytes | str | None = None, keepalive: int = 0, callback: callable | None = None)

בונה לקוח MQTT.

ארגומנטים:

  • client_id – מזהה לקוח ייחודי הנשלח ל-broker.

  • server – שם המארח או כתובת ה-IP של ה-broker (נפתר באמצעות socket.getaddrinfo()).

  • port – פורט ה-TCP של ה-broker (בדרך כלל 1883 רגיל או 8883 עבור TLS).

  • ssl_params – אם אינו None, ה-socket עטוף באמצעות ssl.wrap_socket() ו-ssl_params מועבר כארגומנטים בעלי שם. העבירו {} כדי לאפשר TLS עם ברירות מחדל.

  • user – שם משתמש אופציונלי לאימות מול ה-broker. אם ניתן, יש לספק גם password.

  • password – סיסמה אופציונלית המשמשת יחד עם user.

  • keepalive – מרווח keep-alive בשניות (0 משבית). חייב להיות קטן מ-65536.

  • callback – ניתן-לקריאה המופעל כ-callback(topic, msg) עבור כל PUBLISH המסופק מה-broker. ניתן גם להגדירו מאוחר יותר באמצעות set_callback().

מתודות

set_callback(f: callable) → None

מגדירה את פונקציית ה-callback המופעלת על ידי wait_msg() ו-check_msg() כאשר מתקבלת הודעת PUBLISH. ה-callback נקראת כ-f(topic, msg) כששני הארגומנטים הם bytes.

set_last_will(topic: bytes | str, msg: bytes | str, retain: bool = False, qos: int = 0) → None

מגדירה את ה-Last Will and Testament של MQTT. ה-broker מפרסם את msg על topic אם הלקוח מתנתק באופן לא תקין. חייבת להיקרא לפני connect().

ארגומנטים:

  • topic – topic של ה-last-will (חייב להיות לא-ריק).

  • msg – מטען (payload) של ה-last-will.

  • retain – אם True, ה-broker מאחסן את הודעת ה-will כהודעה שמורה (retained).

  • qos – רמת QoS של ה-last-will. חייבת להיות 0, 1 או 2.

connect(clean_session: bool = True, timeout: float = 5.0) → int

פותחת חיבור TCP (ובאופן אופציונלי TLS) אל ה-broker ושולחת חבילת CONNECT.

ארגומנטים:

  • clean_session – אם True, מבקש session נקי; אחרת ה-broker מחדש כל מצב session קודם.

  • timeout – timeout של ה-socket בשניות המוחל על ה-socket הבסיסי.

מחזירה את דגל ה-session present של ה-broker (0 או 1). מעלה MQTTException אם ה-broker מחזיר קוד החזרה של CONNACK שונה מאפס.

disconnect() → None

שולחת חבילת DISCONNECT וסוגרת את ה-socket הבסיסי.

ping() → None

שולחת חבילת PINGREQ אל ה-broker. יש לקרוא לה מעת לעת אם keepalive שונה מאפס כדי שה-broker לא ינתק את החיבור.

publish(topic: bytes | str, msg: bytes | str, retain: bool = False, qos: int = 0) → None

מפרסמת את msg אל topic.

ארגומנטים:

  • topic – שם ה-topic לפרסום אליו.

  • msg – בייטים של המטען (payload).

  • retain – אם True, מורה ל-broker לשמור את ההודעה עבור מנויים חדשים.

  • qos – רמת איכות-שירות (quality-of-service). 0 (שלח ושכח) ו-1 (מאושר) נתמכות. 2 אינה ממומשת ותעלה AssertionError.

עבור qos 1, הקריאה נחסמת עד שמתקבל ה-PUBACK התואם. גודל החבילה הכולל חייב להיות קטן מ-2097152 בייט.

subscribe(topic: bytes | str, qos: int = 0) → None

נרשמת ל-topic ברמת ה-qos הנתונה. חייבת להיות רשומה callback באמצעות set_callback() או שסופקה לבנאי; אחרת מועלית AssertionError.

נחסמת עד שמתקבל ה-SUBACK התואם. מעלה MQTTException אם ה-broker מסרב להרשמה (קוד החזרה 0x80).

wait_msg() → int | None

נחסמת בהמתנה לחבילת MQTT נכנסת יחידה ומעבדת אותה. חבילות PUBLISH מסופקות ל-callback הרשומה. חבילות PINGRESP נצרכות בשקט. עבור חבילות בקרה אחרות מוחזר הבייט הראשון הגולמי. מחזירה None אם אין נתונים זמינים או אם עובדה PINGRESP.

check_msg() → int | None

וריאנט לא-חוסם של wait_msg(). סוקרת את ה-socket למשך כ-50 ms באמצעות select.select(); אם נתונים ממתינים היא מבצעת את אותו עיבוד כמו wait_msg(), אחרת מחזירה None.