mqtt — Yksinkertainen MQTT-asiakas

mqtt-moduuli tarjoaa minimaalisen MQTT v3.1.1 -asiakastoteutuksen, joka soveltuu muistirajoitteisille laitteille. Se tukee yhdistämistä välittäjään (valinnaisella TLS:llä), viestien julkaisemista, aiheiden tilaamista, last-will-määritystä ja keep-alive-pingejä.

Esimerkki:

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

Poikkeukset

exception mqtt.MQTTException

Nostetaan, kun välittäjä hylkää CONNECT-pyynnön tai kun SUBSCRIBE-pyyntö evätään. Ainoa argumentti on välittäjän tarjoama numeerinen paluukoodi.

Luokat

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)

Rakentaa MQTT-asiakkaan.

Argumentit:

  • client_id – yksilöllinen asiakastunniste, joka lähetetään välittäjälle.

  • server – välittäjän isäntänimi tai IP-osoite (selvitetään socket.getaddrinfo()-funktiolla).

  • port – välittäjän TCP-portti (tyypillisesti 1883 salaamattomana tai 8883 TLS:lle).

  • ssl_params – jos ei None, soketti kääritään ssl.wrap_socket()-funktiolla ja ssl_params välitetään edelleen avainsana-argumentteina. Anna {} ottaaksesi TLS:n käyttöön oletusasetuksilla.

  • user – valinnainen käyttäjätunnus välittäjän todennusta varten. Jos annettu, myös password on annettava.

  • password – valinnainen salasana, jota käytetään yhdessä user-arvon kanssa.

  • keepalive – keep-alive-väli sekunteina (0 poistaa käytöstä). On oltava pienempi kuin 65536.

  • callback – kutsuttava, joka kutsutaan muodossa callback(topic, msg) jokaiselle välittäjältä toimitetulle PUBLISH-viestille. Voidaan asettaa myös myöhemmin set_callback()-metodilla.

Metodit

set_callback(f: callable) → None

Asettaa takaisinkutsun, jonka wait_msg() ja check_msg() kutsuvat, kun PUBLISH-viesti vastaanotetaan. Takaisinkutsu kutsutaan muodossa f(topic, msg), jossa molemmat argumentit ovat bytes.

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

Määrittää MQTT Last Will and Testament -toiminnon. Välittäjä julkaisee msg-viestin topic-aiheeseen, jos asiakas katkaisee yhteyden epäsiististi. On kutsuttava ennen connect()-metodia.

Argumentit:

  • topic – last-will-aihe (ei saa olla tyhjä).

  • msg – last-will-hyötykuorma.

  • retain – jos True, välittäjä tallentaa will-viestin säilytettynä viestinä.

  • qos – last-will-QoS-taso. On oltava 0, 1 tai 2.

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

Avaa TCP- (ja valinnaisesti TLS-) yhteyden välittäjään ja lähettää CONNECT-paketin.

Argumentit:

  • clean_session – jos True, pyytää puhdasta istuntoa; muutoin välittäjä jatkaa mahdollista aiempaa istuntotilaa.

  • timeout – sokettiin sovellettava soketin aikakatkaisu sekunteina.

Palauttaa välittäjän session present -lipun (0 tai 1). Nostaa MQTTException-poikkeuksen, jos välittäjä palauttaa nollasta poikkeavan CONNACK-paluukoodin.

disconnect() → None

Lähettää DISCONNECT-paketin ja sulkee taustalla olevan soketin.

ping() → None

Lähettää PINGREQ-paketin välittäjälle. Tulisi kutsua säännöllisesti, jos keepalive on nollasta poikkeava, jottei välittäjä katkaise yhteyttä.

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

Julkaisee msg-viestin topic-aiheeseen.

Argumentit:

  • topic – aiheen nimi, johon julkaistaan.

  • msg – hyötykuormatavut.

  • retain – jos True, ohjeistaa välittäjää säilyttämään viestin uusia tilaajia varten.

  • qos – palvelutaso. 0 (lähetä ja unohda) ja 1 (kuitattu) ovat tuettuja. 2 ei ole toteutettu ja nostaa AssertionError-poikkeuksen.

qos-tasolla 1 kutsu estyy, kunnes vastaava PUBACK vastaanotetaan. Paketin kokonaiskoon on oltava pienempi kuin 2097152 tavua.

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

Tilaa topic-aiheen annetulla qos-tasolla. Takaisinkutsu on täytynyt rekisteröidä set_callback()-metodilla tai antaa konstruktorille; muutoin nostetaan AssertionError.

Estyy, kunnes vastaava SUBACK vastaanotetaan. Nostaa MQTTException-poikkeuksen, jos välittäjä epää tilauksen (paluukoodi 0x80).

wait_msg() → int | None

Estyy odottaen yhtä saapuvaa MQTT-pakettia ja käsittelee sen. PUBLISH-paketit toimitetaan rekisteröidylle takaisinkutsulle. PINGRESP-paketit kulutetaan hiljaisesti. Muiden ohjauspakettien osalta palautetaan raaka ensimmäinen tavu. Palauttaa None, jos dataa ei ole saatavilla tai jos PINGRESP käsiteltiin.

check_msg() → int | None

wait_msg()-metodin estämätön muunnelma. Pollaa sokettia enintään ~50 ms ajan select.select()-funktiolla; jos dataa on odottamassa, se suorittaa saman käsittelyn kuin wait_msg(), muutoin palauttaa None.