mqtt — Egyszerű MQTT kliens

A mqtt modul egy minimalista MQTT v3.1.1 kliens megvalósítást nyújt, amely memóriában korlátozott eszközökön való használatra alkalmas. Támogatja a brókerhez való csatlakozást (opcionális TLS-sel), üzenetek közzétételét, témákra való feliratkozást, last-will konfigurációt és keep-alive pingeket.

Példa:

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()

Kivételek

exception mqtt.MQTTException

Akkor kerül kiváltásra, amikor a bróker elutasítja a CONNECT kérést, vagy amikor egy SUBSCRIBE kérés visszautasításra kerül. Az egyetlen argumentum a bróker által megadott numerikus visszatérési kód.

Osztályok

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)

Létrehoz egy MQTT klienst.

Argumentumok:

  • client_id – a brókernek küldött egyedi kliensazonosító.

  • server – a bróker hosztneve vagy IP-címe (a socket.getaddrinfo() segítségével feloldva).

  • port – a bróker TCP portja (jellemzően 1883 titkosítatlan vagy 8883 TLS esetén).

  • ssl_params – ha nem None, a socket a ssl.wrap_socket() segítségével becsomagolásra kerül, és az ssl_params kulcsszó-argumentumként kerül továbbításra. Adjon meg {} értéket a TLS alapértelmezésekkel való engedélyezéséhez.

  • user – opcionális felhasználónév a bróker hitelesítéséhez. Megadása esetén a password értéket is meg kell adni.

  • password – a user értékkel együtt használt opcionális jelszó.

  • keepalive – keep-alive intervallum másodpercben (0 letiltja). 65536 értéknél kisebbnek kell lennie.

  • callback – a brókerből kézbesített minden PUBLISH üzenethez callback(topic, msg) formában meghívott hívható objektum. Később is beállítható a set_callback() segítségével.

Metódusok

set_callback(f: callable) → None

Beállítja a wait_msg() és check_msg() által meghívott visszahívást, amikor PUBLISH üzenet érkezik. A visszahívás f(topic, msg) formában kerül meghívásra, mindkét argumentum bytes típusú.

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

Beállítja az MQTT Last Will and Testament üzenetet. A bróker közzéteszi a msg üzenetet a topic témán, ha a kliens szabálytalanul bontja a kapcsolatot. A connect() előtt kell meghívni.

Argumentumok:

  • topic – a last-will téma (nem lehet üres).

  • msg – a last-will hasznos teher.

  • retain – ha True, a bróker megőrzött (retained) üzenetként tárolja a will üzenetet.

  • qos – a last-will QoS szint. Értéke 0, 1 vagy 2 lehet.

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

Megnyit egy TCP (és opcionálisan TLS) kapcsolatot a brókerhez, és elküld egy CONNECT csomagot.

Argumentumok:

  • clean_session – ha True, tiszta munkamenetet kér; egyébként a bróker folytat minden korábbi munkamenet-állapotot.

  • timeout – az alatta lévő socketre alkalmazott socket időtúllépés másodpercben.

Visszaadja a bróker session present jelzőjét (0 vagy 1). MQTTException kivételt vált ki, ha a bróker nem nulla CONNACK visszatérési kódot ad vissza.

disconnect() → None

Elküld egy DISCONNECT csomagot, és lezárja az alatta lévő socketet.

ping() → None

Elküld egy PINGREQ csomagot a brókernek. Időszakosan meg kell hívni, ha a keepalive nem nulla, hogy a bróker ne bontsa a kapcsolatot.

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

Közzéteszi a msg üzenetet a topic témán.

Argumentumok:

  • topic – a téma neve, amelyre a közzététel történik.

  • msg – a hasznos teher bájtjai.

  • retain – ha True, utasítja a brókert, hogy őrizze meg az üzenetet az új feliratkozók számára.

  • qos – a szolgáltatásminőség (quality-of-service) szintje. A 0 (fire and forget) és az 1 (nyugtázott) támogatott. A 2 nincs implementálva, és AssertionError kivételt vált ki.

A 1 qos esetén a hívás blokkol, amíg a megfelelő PUBACK meg nem érkezik. A teljes csomagméretnek kisebbnek kell lennie 2097152 bájtnál.

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

Feliratkozik a topic témára a megadott qos szinten. Egy visszahívást kell regisztrálni a set_callback() segítségével, vagy átadni a konstruktornak; egyébként AssertionError kivétel kerül kiváltásra.

Blokkol, amíg a megfelelő SUBACK meg nem érkezik. MQTTException kivételt vált ki, ha a bróker visszautasítja a feliratkozást (0x80 visszatérési kód).

wait_msg() → int | None

Blokkolva vár egyetlen beérkező MQTT csomagra, és feldolgozza azt. A PUBLISH csomagok a regisztrált visszahíváshoz kerülnek kézbesítésre. A PINGRESP csomagok csendben felhasználásra kerülnek. Egyéb vezérlőcsomagok esetén a nyers első bájt kerül visszaadásra. None értéket ad vissza, ha nincs elérhető adat, vagy ha egy PINGRESP került feldolgozásra.

check_msg() → int | None

A wait_msg() nem blokkoló változata. Legfeljebb ~50 ms-ig lekérdezi a socketet a select.select() segítségével; ha adat áll rendelkezésre, ugyanazt a feldolgozást végzi, mint a wait_msg(), egyébként None értéket ad vissza.