mqtt — Jednoduchý MQTT klient

Modul mqtt poskytuje minimalistickou implementaci MQTT v3.1.1 klienta vhodnou pro použití na zařízeních s omezenou pamětí. Podporuje připojení k brokeru (s volitelným TLS), publikování zpráv, odběr témat, konfiguraci last-will a keep-alive pingy.

Příklad:

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

Výjimky

exception mqtt.MQTTException

Vyvolá se, když broker odmítne požadavek CONNECT nebo když je odmítnut požadavek SUBSCRIBE. Jediným argumentem je číselný návratový kód poskytnutý brokerem.

Třídy

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)

Vytvoří MQTT klienta.

Argumenty:

  • client_id – jedinečný identifikátor klienta odeslaný brokeru.

  • server – hostname nebo IP adresa brokeru (rozlišená pomocí socket.getaddrinfo()).

  • port – TCP port brokeru (typicky 1883 pro nešifrované nebo 8883 pro TLS).

  • ssl_params – pokud není None, soket se obalí pomocí ssl.wrap_socket() a ssl_params se předá jako pojmenované argumenty. Předáním {} se TLS povolí s výchozím nastavením.

  • user – volitelné uživatelské jméno pro autentizaci u brokeru. Pokud je zadáno, musí být dodáno také password.

  • password – volitelné heslo používané společně s user.

  • keepalive – interval keep-alive v sekundách (0 jej zakáže). Musí být menší než 65536.

  • callback – volatelný objekt vyvolaný jako callback(topic, msg) pro každou zprávu PUBLISH doručenou od brokeru. Lze jej nastavit i později pomocí set_callback().

Metody

set_callback(f: callable) → None

Nastaví callback vyvolaný metodami wait_msg() a check_msg() při přijetí zprávy PUBLISH. Callback se volá jako f(topic, msg), kde oba argumenty jsou typu bytes.

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

Nakonfiguruje MQTT Last Will and Testament. Broker publikuje msg na topic, pokud se klient odpojí nekorektně. Musí se zavolat před connect().

Argumenty:

  • topic – téma last-will (nesmí být prázdné).

  • msg – payload last-will.

  • retain – pokud True, broker uloží zprávu will jako retained zprávu.

  • qos – úroveň QoS pro last-will. Musí být 0, 1 nebo 2.

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

Otevře TCP (a volitelně TLS) připojení k brokeru a odešle paket CONNECT.

Argumenty:

  • clean_session – pokud True, požádá o čistou relaci; jinak broker obnoví případný předchozí stav relace.

  • timeout – timeout soketu v sekundách aplikovaný na podkladový soket.

Vrací brokerův příznak session present (0 nebo 1). Vyvolá MQTTException, pokud broker vrátí nenulový návratový kód CONNACK.

disconnect() → None

Odešle paket DISCONNECT a uzavře podkladový soket.

ping() → None

Odešle brokeru paket PINGREQ. Měl by se volat periodicky, pokud je keepalive nenulové, aby broker nezrušil připojení.

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

Publikuje msg na topic.

Argumenty:

  • topic – název tématu, na které se publikuje.

  • msg – bajty payloadu.

  • retain – pokud True, pokyn brokeru, aby zprávu uchoval pro nové odběratele.

  • qos – úroveň kvality služby. Podporovány jsou 0 (odeslat a zapomenout) a 1 (potvrzené). 2 není implementováno a vyvolá AssertionError.

Pro qos 1 volání blokuje, dokud není přijato odpovídající PUBACK. Celková velikost paketu musí být menší než 2097152 bajtů.

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

Přihlásí se k odběru topic na zadané úrovni qos. Musí být zaregistrován callback pomocí set_callback() nebo dodán konstruktoru; jinak se vyvolá AssertionError.

Blokuje, dokud není přijato odpovídající SUBACK. Vyvolá MQTTException, pokud broker odběr odmítne (návratový kód 0x80).

wait_msg() → int | None

Blokuje a čeká na jeden příchozí MQTT paket a zpracuje jej. Pakety PUBLISH se doručí zaregistrovanému callbacku. Pakety PINGRESP se tiše zkonzumují. Pro ostatní řídicí pakety se vrátí surový první bajt. Vrací None, pokud nejsou k dispozici žádná data nebo pokud byl zpracován PINGRESP.

check_msg() → int | None

Neblokující varianta wait_msg(). Dotazuje soket nejvýše ~50 ms pomocí select.select(); pokud čekají data, provede stejné zpracování jako wait_msg(), jinak vrátí None.