mqtt — Einfacher MQTT-Client

Das Modul mqtt stellt eine minimale MQTT-v3.1.1-Client-Implementierung bereit, die für den Einsatz auf speicherbeschränkten Geräten geeignet ist. Sie unterstützt das Verbinden mit einem Broker (mit optionalem TLS), das Veröffentlichen von Nachrichten, das Abonnieren von Topics, die Konfiguration eines Last Will sowie Keep-Alive-Pings.

Beispiel:

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

Ausnahmen

exception mqtt.MQTTException

Wird ausgelöst, wenn der Broker die CONNECT-Anfrage ablehnt oder wenn eine SUBSCRIBE-Anfrage abgelehnt wird. Das einzige Argument ist der vom Broker gelieferte numerische Rückgabecode.

Klassen

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)

Konstruiert einen MQTT-Client.

Argumente:

  • client_id – eindeutige Client-Kennung, die an den Broker gesendet wird.

  • server – Hostname oder IP-Adresse des Brokers (aufgelöst mit socket.getaddrinfo()).

  • port – TCP-Port des Brokers (typischerweise 1883 unverschlüsselt oder 8883 für TLS).

  • ssl_params – falls nicht None, wird der Socket mit ssl.wrap_socket() umhüllt und ssl_params wird als Schlüsselwortargumente weitergegeben. Übergeben Sie {}, um TLS mit Standardwerten zu aktivieren.

  • user – optionaler Benutzername für die Broker-Authentifizierung. Falls angegeben, muss auch password angegeben werden.

  • password – optionales Passwort, das zusammen mit user verwendet wird.

  • keepalive – Keep-Alive-Intervall in Sekunden (0 deaktiviert es). Muss kleiner als 65536 sein.

  • callback – aufrufbares Objekt, das für jede vom Broker zugestellte PUBLISH-Nachricht als callback(topic, msg) aufgerufen wird. Kann auch später mit set_callback() gesetzt werden.

Methoden

set_callback(f: callable) → None

Setzt den Callback, der von wait_msg() und check_msg() aufgerufen wird, wenn eine PUBLISH-Nachricht empfangen wird. Der Callback wird als f(topic, msg) aufgerufen, wobei beide Argumente vom Typ bytes sind.

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

Konfiguriert das MQTT Last Will and Testament. Der Broker veröffentlicht msg auf topic, wenn sich der Client nicht ordnungsgemäß trennt. Muss vor connect() aufgerufen werden.

Argumente:

  • topic – Last-Will-Topic (darf nicht leer sein).

  • msg – Last-Will-Payload.

  • retain – falls True, speichert der Broker die Will-Nachricht als beibehaltene Nachricht.

  • qos – Last-Will-QoS-Stufe. Muss 0, 1 oder 2 sein.

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

Öffnet eine TCP-Verbindung (und optional TLS) zum Broker und sendet ein CONNECT-Paket.

Argumente:

  • clean_session – falls True, wird eine saubere Sitzung angefordert; andernfalls setzt der Broker etwaigen vorherigen Sitzungszustand fort.

  • timeout – Socket-Timeout in Sekunden, das auf den zugrunde liegenden Socket angewendet wird.

Gibt das session present-Flag des Brokers zurück (0 oder 1). Löst MQTTException aus, wenn der Broker einen CONNACK-Rückgabecode ungleich null zurückgibt.

disconnect() → None

Sendet ein DISCONNECT-Paket und schließt den zugrunde liegenden Socket.

ping() → None

Sendet ein PINGREQ-Paket an den Broker. Sollte periodisch aufgerufen werden, wenn keepalive ungleich null ist, damit der Broker die Verbindung nicht abbricht.

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

Veröffentlicht msg auf topic.

Argumente:

  • topic – Topic-Name, auf dem veröffentlicht werden soll.

  • msg – Payload-Bytes.

  • retain – falls True, wird der Broker angewiesen, die Nachricht für neue Abonnenten beizubehalten.

  • qos – Quality-of-Service-Stufe. 0 (fire and forget) und 1 (bestätigt) werden unterstützt. 2 ist nicht implementiert und löst AssertionError aus.

Bei qos 1 blockiert der Aufruf, bis das passende PUBACK empfangen wird. Die Gesamtpaketgröße muss kleiner als 2097152 Bytes sein.

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

Abonniert topic auf der angegebenen qos-Stufe. Es muss ein Callback über set_callback() registriert oder dem Konstruktor übergeben worden sein; andernfalls wird AssertionError ausgelöst.

Blockiert, bis das passende SUBACK empfangen wird. Löst MQTTException aus, wenn der Broker das Abonnement ablehnt (Rückgabecode 0x80).

wait_msg() → int | None

Blockiert und wartet auf ein einzelnes eingehendes MQTT-Paket und verarbeitet es. PUBLISH-Pakete werden an den registrierten Callback zugestellt. PINGRESP-Pakete werden stillschweigend verarbeitet. Bei anderen Steuerpaketen wird das rohe erste Byte zurückgegeben. Gibt None zurück, wenn keine Daten verfügbar sind oder wenn ein PINGRESP verarbeitet wurde.

check_msg() → int | None

Nicht blockierende Variante von wait_msg(). Fragt den Socket für höchstens ~50 ms mit select.select() ab; falls Daten anstehen, führt sie dieselbe Verarbeitung wie wait_msg() durch, andernfalls gibt sie None zurück.