mqtt — Client MQTT simple

Le module mqtt fournit une implémentation minimale d’un client MQTT v3.1.1 adaptée à une utilisation sur des appareils à mémoire limitée. Il prend en charge la connexion à un broker (avec TLS optionnel), la publication de messages, l’abonnement à des sujets, la configuration du testament (last-will) et les pings de maintien (keep-alive).

Exemple

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

Exceptions

exception mqtt.MQTTException

Levée lorsque le broker rejette la requête CONNECT ou lorsqu’une requête SUBSCRIBE est refusée. L’unique argument est le code de retour numérique fourni par le broker.

Classes

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)

Construit un client MQTT.

Arguments :

  • client_id – identifiant client unique envoyé au broker.

  • server – nom d’hôte ou adresse IP du broker (résolu avec socket.getaddrinfo()).

  • port – port TCP du broker (typiquement 1883 en clair ou 8883 pour TLS).

  • ssl_params – s’il est différent de None, le socket est encapsulé avec ssl.wrap_socket() et ssl_params est transmis sous forme d’arguments nommés. Passez {} pour activer TLS avec les valeurs par défaut.

  • user – nom d’utilisateur optionnel pour l’authentification auprès du broker. S’il est fourni, password doit également l’être.

  • password – mot de passe optionnel utilisé conjointement avec user.

  • keepalive – intervalle de maintien en secondes (0 le désactive). Doit être inférieur à 65536.

  • callback – appelable invoqué sous la forme callback(topic, msg) pour chaque PUBLISH délivré par le broker. Peut également être défini ultérieurement avec set_callback().

Méthodes

set_callback(f: callable) → None

Définit la fonction de rappel invoquée par wait_msg() et check_msg() lorsqu’un message PUBLISH est reçu. La fonction de rappel est appelée sous la forme f(topic, msg) avec les deux arguments de type bytes.

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

Configure le testament MQTT (Last Will and Testament). Le broker publie msg sur topic si le client se déconnecte de manière incorrecte. Doit être appelé avant connect().

Arguments :

  • topic – sujet du testament (ne doit pas être vide).

  • msg – charge utile du testament.

  • retain – si True, le broker stocke le message du testament comme message retenu.

  • qos – niveau de QoS du testament. Doit valoir 0, 1 ou 2.

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

Ouvre une connexion TCP (et optionnellement TLS) vers le broker et envoie un paquet CONNECT.

Arguments :

  • clean_session – si True, demande une session propre ; sinon, le broker reprend tout état de session antérieur.

  • timeout – délai d’attente du socket en secondes appliqué au socket sous-jacent.

Renvoie l’indicateur session present du broker (0 ou 1). Lève MQTTException si le broker renvoie un code de retour CONNACK non nul.

disconnect() → None

Envoie un paquet DISCONNECT et ferme le socket sous-jacent.

ping() → None

Envoie un paquet PINGREQ au broker. Doit être appelé périodiquement si keepalive est non nul afin que le broker ne coupe pas la connexion.

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

Publie msg sur topic.

Arguments :

  • topic – nom du sujet sur lequel publier.

  • msg – octets de la charge utile.

  • retain – si True, demande au broker de retenir le message pour les nouveaux abonnés.

  • qos – niveau de qualité de service. 0 (envoi sans confirmation) et 1 (avec accusé de réception) sont pris en charge. 2 n’est pas implémenté et lèvera AssertionError.

Pour qos 1, l’appel bloque jusqu’à la réception du PUBACK correspondant. La taille totale du paquet doit être inférieure à 2097152 octets.

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

S’abonne à topic au niveau de qos donné. Une fonction de rappel doit avoir été enregistrée via set_callback() ou fournie au constructeur ; sinon, AssertionError est levée.

Bloque jusqu’à la réception du SUBACK correspondant. Lève MQTTException si le broker refuse l’abonnement (code de retour 0x80).

wait_msg() → int | None

Bloque en attendant un seul paquet MQTT entrant et le traite. Les paquets PUBLISH sont délivrés à la fonction de rappel enregistrée. Les paquets PINGRESP sont consommés silencieusement. Pour les autres paquets de contrôle, le premier octet brut est renvoyé. Renvoie None si aucune donnée n’est disponible ou si un PINGRESP a été traité.

check_msg() → int | None

Variante non bloquante de wait_msg(). Interroge le socket pendant environ 50 ms au maximum à l’aide de select.select() ; si des données sont en attente, elle effectue le même traitement que wait_msg(), sinon elle renvoie None.