mqtt — Prosty klient MQTT

Moduł mqtt dostarcza minimalną implementację klienta MQTT v3.1.1, odpowiednią do użycia na urządzeniach o ograniczonej pamięci. Obsługuje łączenie z brokerem (z opcjonalnym TLS), publikowanie wiadomości, subskrypcję tematów, konfigurację last-will oraz pingi keep-alive.

Przykład:

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

Wyjątki

exception mqtt.MQTTException

Zgłaszany, gdy broker odrzuci żądanie CONNECT lub gdy żądanie SUBSCRIBE zostanie odmówione. Jedynym argumentem jest dostarczony przez brokera numeryczny kod zwrotny.

Klasy

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)

Konstruuje klienta MQTT.

Argumenty:

  • client_id – unikalny identyfikator klienta wysyłany do brokera.

  • server – nazwa hosta lub adres IP brokera (rozwiązywany za pomocą socket.getaddrinfo()).

  • port – port TCP brokera (zwykle 1883 dla połączenia jawnego lub 8883 dla TLS).

  • ssl_params – jeśli nie ma wartości None, gniazdo jest opakowywane za pomocą ssl.wrap_socket(), a ssl_params jest przekazywane jako argumenty nazwane. Podaj {}, aby włączyć TLS z ustawieniami domyślnymi.

  • user – opcjonalna nazwa użytkownika do uwierzytelnienia w brokerze. Jeśli zostanie podana, należy także podać password.

  • password – opcjonalne hasło używane razem z user.

  • keepalive – interwał keep-alive w sekundach (0 wyłącza). Musi być mniejszy niż 65536.

  • callback – obiekt wywoływalny wywoływany jako callback(topic, msg) dla każdego komunikatu PUBLISH dostarczonego od brokera. Może też zostać ustawiony później za pomocą set_callback().

Metody

set_callback(f: callable) → None

Ustawia wywołanie zwrotne wywoływane przez wait_msg() i check_msg(), gdy odebrana zostanie wiadomość PUBLISH. Wywołanie zwrotne jest wywoływane jako f(topic, msg), gdzie oba argumenty są typu bytes.

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

Konfiguruje Last Will and Testament MQTT. Broker publikuje msg na topic, jeśli klient rozłączy się w sposób nieprawidłowy. Musi zostać wywołane przed connect().

Argumenty:

  • topic – temat last-will (nie może być pusty).

  • msg – ładunek last-will.

  • retain – jeśli ma wartość True, broker zachowuje wiadomość last-will jako wiadomość zatrzymaną (retained).

  • qos – poziom QoS last-will. Musi wynosić 0, 1 lub 2.

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

Otwiera połączenie TCP (i opcjonalnie TLS) z brokerem oraz wysyła pakiet CONNECT.

Argumenty:

  • clean_session – jeśli ma wartość True, żąda czystej sesji; w przeciwnym razie broker wznawia wszelki wcześniejszy stan sesji.

  • timeout – limit czasu gniazda w sekundach stosowany do bazowego gniazda.

Zwraca flagę session present brokera (0 lub 1). Zgłasza MQTTException, jeśli broker zwróci niezerowy kod zwrotny CONNACK.

disconnect() → None

Wysyła pakiet DISCONNECT i zamyka bazowe gniazdo.

ping() → None

Wysyła pakiet PINGREQ do brokera. Powinien być wywoływany okresowo, jeśli keepalive jest niezerowy, aby broker nie zerwał połączenia.

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

Publikuje msg na topic.

Argumenty:

  • topic – nazwa tematu, na którym ma nastąpić publikacja.

  • msg – bajty ładunku.

  • retain – jeśli ma wartość True, poleca brokerowi zachować wiadomość dla nowych subskrybentów.

  • qos – poziom quality-of-service. Obsługiwane są 0 (wyślij i zapomnij) oraz 1 (potwierdzany). 2 nie jest zaimplementowane i zgłosi AssertionError.

Dla qos 1 wywołanie blokuje do czasu odebrania pasującego PUBACK. Całkowity rozmiar pakietu musi być mniejszy niż 2097152 bajtów.

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

Subskrybuje topic na podanym poziomie qos. Musi zostać zarejestrowane wywołanie zwrotne za pomocą set_callback() lub przekazane do konstruktora; w przeciwnym razie zgłaszany jest AssertionError.

Blokuje do czasu odebrania pasującego SUBACK. Zgłasza MQTTException, jeśli broker odmówi subskrypcji (kod zwrotny 0x80).

wait_msg() → int | None

Blokuje, oczekując na pojedynczy przychodzący pakiet MQTT, i przetwarza go. Pakiety PUBLISH są dostarczane do zarejestrowanego wywołania zwrotnego. Pakiety PINGRESP są przyjmowane po cichu. Dla innych pakietów sterujących zwracany jest surowy pierwszy bajt. Zwraca None, jeśli żadne dane nie są dostępne lub jeśli przetworzono PINGRESP.

check_msg() → int | None

Nieblokujący wariant wait_msg(). Odpytuje gniazdo przez maksymalnie ~50 ms za pomocą select.select(); jeśli dane oczekują, wykonuje takie samo przetwarzanie jak wait_msg(), w przeciwnym razie zwraca None.