mqtt — Enkel MQTT-klient

Modulen mqtt tillhandahåller en minimal implementation av en MQTT v3.1.1-klient lämplig för användning på minnesbegränsade enheter. Den stöder anslutning till en broker (med valfri TLS), publicering av meddelanden, prenumeration på ämnen, konfiguration av last-will och keep-alive-pingar.

Exempel:

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

Undantag

exception mqtt.MQTTException

Utlöses när brokern avvisar CONNECT-förfrågan eller när en SUBSCRIBE-förfrågan nekas. Det enda argumentet är den numeriska returkod som brokern tillhandahåller.

Klasser

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)

Konstruerar en MQTT-klient.

Argument:

  • client_id – unik klientidentifierare som skickas till brokern.

  • server – brokerns värdnamn eller IP-adress (löses upp med socket.getaddrinfo()).

  • port – brokerns TCP-port (vanligtvis 1883 för okrypterad eller 8883 för TLS).

  • ssl_params – om inte None lindas socketen med ssl.wrap_socket() och ssl_params vidarebefordras som nyckelordsargument. Skicka {} för att aktivera TLS med standardvärden.

  • user – valfritt användarnamn för brokerautentisering. Om det anges måste även password anges.

  • password – valfritt lösenord som används tillsammans med user.

  • keepalive – keep-alive-intervall i sekunder (0 inaktiverar). Måste vara mindre än 65536.

  • callback – anropbar funktion som anropas som callback(topic, msg) för varje PUBLISH som levereras från brokern. Kan även anges senare med set_callback().

Metoder

set_callback(f: callable) → None

Anger det återanrop som anropas av wait_msg() och check_msg() när ett PUBLISH-meddelande tas emot. Återanropet anropas som f(topic, msg) med båda argumenten som bytes.

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

Konfigurerar MQTT Last Will and Testament. Brokern publicerar msg på topic om klienten kopplar från på ett icke graciöst sätt. Måste anropas före connect().

Argument:

  • topic – last-will-ämne (får inte vara tomt).

  • msg – last-will-nyttolast.

  • retain – om True lagrar brokern will-meddelandet som ett kvarhållet meddelande.

  • qos – last-will-QoS-nivå. Måste vara 0, 1 eller 2.

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

Öppnar en TCP-anslutning (och eventuellt TLS) till brokern och skickar ett CONNECT-paket.

Argument:

  • clean_session – om True begärs en ren session; annars återupptar brokern eventuellt tidigare sessionstillstånd.

  • timeout – socket-timeout i sekunder som tillämpas på den underliggande socketen.

Returnerar brokerns session present-flagga (0 eller 1). Utlöser MQTTException om brokern returnerar en CONNACK-returkod som inte är noll.

disconnect() → None

Skickar ett DISCONNECT-paket och stänger den underliggande socketen.

ping() → None

Skickar ett PINGREQ-paket till brokern. Bör anropas periodiskt om keepalive inte är noll så att brokern inte bryter anslutningen.

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

Publicerar msg till topic.

Argument:

  • topic – ämnesnamn att publicera till.

  • msg – nyttolast i byte.

  • retain – om True instrueras brokern att kvarhålla meddelandet för nya prenumeranter.

  • qos – quality-of-service-nivå. 0 (skicka och glöm) och 1 (bekräftad) stöds. 2 är inte implementerad och utlöser AssertionError.

För qos 1 blockerar anropet tills matchande PUBACK tas emot. Den totala paketstorleken måste vara mindre än 2097152 byte.

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

Prenumererar på topic på den angivna qos-nivån. Ett återanrop måste ha registrerats via set_callback() eller angetts till konstruktorn; annars utlöses AssertionError.

Blockerar tills matchande SUBACK tas emot. Utlöser MQTTException om brokern nekar prenumerationen (returkod 0x80).

wait_msg() → int | None

Blockerar i väntan på ett enskilt inkommande MQTT-paket och bearbetar det. PUBLISH-paket levereras till det registrerade återanropet. PINGRESP-paket konsumeras tyst. För andra kontrollpaket returneras den råa första byten. Returnerar None om ingen data är tillgänglig eller om ett PINGRESP bearbetades.

check_msg() → int | None

Icke-blockerande variant av wait_msg(). Pollar socketen i högst ~50 ms med select.select(); om data väntar utförs samma bearbetning som wait_msg(), annars returneras None.