mqtt — Eenvoudige MQTT-client

De mqtt-module biedt een minimale MQTT v3.1.1-clientimplementatie die geschikt is voor gebruik op apparaten met beperkt geheugen. Hij ondersteunt het verbinden met een broker (met optionele TLS), het publiceren van berichten, het abonneren op topics, last-will-configuratie en keep-alive-pings.

Voorbeeld:

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

Uitzonderingen

exception mqtt.MQTTException

Wordt opgeworpen wanneer de broker het CONNECT-verzoek weigert of wanneer een SUBSCRIBE-verzoek wordt geweigerd. Het enige argument is de door de broker geleverde numerieke retourcode.

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)

Construeert een MQTT-client.

Argumenten:

  • client_id – unieke client-identificatie die naar de broker wordt verzonden.

  • server – hostnaam of IP-adres van de broker (omgezet met socket.getaddrinfo()).

  • port – TCP-poort van de broker (doorgaans 1883 plain of 8883 voor TLS).

  • ssl_params – indien niet None, wordt de socket gewrapt met ssl.wrap_socket() en wordt ssl_params doorgegeven als sleutelwoordargumenten. Geef {} door om TLS met standaardinstellingen in te schakelen.

  • user – optionele gebruikersnaam voor brokerauthenticatie. Indien opgegeven, moet ook password worden opgegeven.

  • password – optioneel wachtwoord dat samen met user wordt gebruikt.

  • keepalive – keep-alive-interval in seconden (0 schakelt het uit). Moet kleiner zijn dan 65536.

  • callback – aanroepbaar object dat als callback(topic, msg) wordt aangeroepen voor elke PUBLISH die door de broker wordt afgeleverd. Kan ook later worden ingesteld met set_callback().

Methoden

set_callback(f: callable) → None

Stelt de callback in die door wait_msg() en check_msg() wordt aangeroepen wanneer een PUBLISH-bericht wordt ontvangen. De callback wordt aangeroepen als f(topic, msg) met beide argumenten als bytes.

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

Configureert de MQTT Last Will and Testament. De broker publiceert msg op topic als de client de verbinding niet netjes verbreekt. Moet vóór connect() worden aangeroepen.

Argumenten:

  • topic – last-will-topic (mag niet leeg zijn).

  • msg – last-will-payload.

  • retain – indien True slaat de broker het will-bericht op als een vastgehouden bericht.

  • qos – last-will-QoS-niveau. Moet 0, 1 of 2 zijn.

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

Opent een TCP-verbinding (en optioneel TLS) naar de broker en verzendt een CONNECT-pakket.

Argumenten:

  • clean_session – indien True wordt een clean session aangevraagd; anders hervat de broker eventuele eerdere sessiestatus.

  • timeout – sockettime-out in seconden die op de onderliggende socket wordt toegepast.

Geeft de session present-vlag van de broker terug (0 of 1). Werpt MQTTException op als de broker een CONNACK-retourcode ongelijk aan nul teruggeeft.

disconnect() → None

Verzendt een DISCONNECT-pakket en sluit de onderliggende socket.

ping() → None

Verzendt een PINGREQ-pakket naar de broker. Moet periodiek worden aangeroepen als keepalive ongelijk aan nul is, zodat de broker de verbinding niet verbreekt.

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

Publiceert msg naar topic.

Argumenten:

  • topic – topicnaam waarnaar gepubliceerd moet worden.

  • msg – payload-bytes.

  • retain – indien True wordt de broker geïnstrueerd om het bericht vast te houden voor nieuwe abonnees.

  • qos – quality-of-service-niveau. 0 (fire and forget) en 1 (bevestigd) worden ondersteund. 2 is niet geïmplementeerd en zal AssertionError opwerpen.

Voor qos 1 blokkeert de aanroep totdat de bijbehorende PUBACK is ontvangen. De totale pakketgrootte moet kleiner zijn dan 2097152 bytes.

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

Abonneert op topic met het opgegeven qos-niveau. Er moet een callback zijn geregistreerd via set_callback() of zijn doorgegeven aan de constructor; anders wordt AssertionError opgeworpen.

Blokkeert totdat de bijbehorende SUBACK is ontvangen. Werpt MQTTException op als de broker het abonnement weigert (retourcode 0x80).

wait_msg() → int | None

Blokkeert in afwachting van één inkomend MQTT-pakket en verwerkt dit. PUBLISH-pakketten worden afgeleverd aan de geregistreerde callback. PINGRESP-pakketten worden stilzwijgend verwerkt. Voor andere besturingspakketten wordt de ruwe eerste byte teruggegeven. Geeft None terug als er geen gegevens beschikbaar zijn of als een PINGRESP is verwerkt.

check_msg() → int | None

Niet-blokkerende variant van wait_msg(). Pollt de socket gedurende maximaal ~50 ms met select.select(); als er gegevens in behandeling zijn, voert hij dezelfde verwerking uit als wait_msg(), anders geeft hij None terug.