mqtt — Client MQTT semplice#

Il modulo mqtt fornisce un’implementazione minimale di un client MQTT v3.1.1 adatta all’uso su dispositivi con memoria limitata. Supporta la connessione a un broker (con TLS opzionale), la pubblicazione di messaggi, la sottoscrizione a topic, la configurazione del last-will e i ping di keep-alive.

Esempio:

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

Eccezioni#

exception mqtt.MQTTException#

Sollevata quando il broker rifiuta la richiesta CONNECT o quando una richiesta SUBSCRIBE viene rifiutata. L’unico argomento è il codice di ritorno numerico fornito dal broker.

Classi#

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

Costruisce un client MQTT.

Argomenti:

  • client_id – identificatore univoco del client inviato al broker.

  • server – hostname o indirizzo IP del broker (risolto con socket.getaddrinfo()).

  • port – porta TCP del broker (tipicamente 1883 in chiaro o 8883 per TLS).

  • ssl_params – se non None, il socket viene incapsulato con ssl.wrap_socket() e ssl_params viene inoltrato come argomenti keyword. Passa {} per abilitare il TLS con le impostazioni predefinite.

  • user – nome utente opzionale per l’autenticazione al broker. Se fornito, deve essere fornita anche la password.

  • password – password opzionale usata insieme a user.

  • keepalive – intervallo di keep-alive in secondi (0 lo disabilita). Deve essere inferiore a 65536.

  • callback – callable invocato come callback(topic, msg) per ogni PUBLISH consegnato dal broker. Può anche essere impostato in seguito con set_callback().

Metodi#

set_callback(f: callable) → None#

Imposta il callback invocato da wait_msg() e check_msg() quando viene ricevuto un messaggio PUBLISH. Il callback viene chiamato come f(topic, msg) con entrambi gli argomenti di tipo bytes.

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

Configura il Last Will and Testament di MQTT. Il broker pubblica msg su topic se il client si disconnette in modo non corretto. Deve essere chiamato prima di connect().

Argomenti:

  • topic – topic del last-will (deve essere non vuoto).

  • msg – payload del last-will.

  • retain – se True, il broker memorizza il messaggio di will come messaggio retained.

  • qos – livello QoS del last-will. Deve essere 0, 1 o 2.

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

Apre una connessione TCP (e opzionalmente TLS) al broker e invia un pacchetto CONNECT.

Argomenti:

  • clean_session – se True, richiede una sessione pulita; altrimenti il broker riprende qualsiasi stato di sessione precedente.

  • timeout – timeout del socket in secondi applicato al socket sottostante.

Restituisce il flag session present del broker (0 o 1). Solleva MQTTException se il broker restituisce un codice di ritorno CONNACK diverso da zero.

disconnect() → None#

Invia un pacchetto DISCONNECT e chiude il socket sottostante.

ping() → None#

Invia un pacchetto PINGREQ al broker. Dovrebbe essere chiamato periodicamente se keepalive è diverso da zero, in modo che il broker non interrompa la connessione.

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

Pubblica msg su topic.

Argomenti:

  • topic – nome del topic su cui pubblicare.

  • msg – byte del payload.

  • retain – se True, istruisce il broker a conservare il messaggio per i nuovi subscriber.

  • qos – livello di quality-of-service. Sono supportati 0 (fire and forget) e 1 (con conferma). 2 non è implementato e solleverà AssertionError.

Per qos 1, la chiamata si blocca finché non viene ricevuto il PUBACK corrispondente. La dimensione totale del pacchetto deve essere inferiore a 2097152 byte.

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

Si sottoscrive a topic al livello qos indicato. Deve essere stato registrato un callback tramite set_callback() o fornito al costruttore; altrimenti viene sollevata AssertionError.

Si blocca finché non viene ricevuto il SUBACK corrispondente. Solleva MQTTException se il broker rifiuta la sottoscrizione (codice di ritorno 0x80).

wait_msg() → int | None#

Si blocca in attesa di un singolo pacchetto MQTT in arrivo e lo elabora. I pacchetti PUBLISH vengono consegnati al callback registrato. I pacchetti PINGRESP vengono consumati silenziosamente. Per gli altri pacchetti di controllo viene restituito il primo byte grezzo. Restituisce None se non ci sono dati disponibili o se è stato elaborato un PINGRESP.

check_msg() → int | None#

Variante non bloccante di wait_msg(). Interroga il socket per al massimo ~50 ms usando select.select(); se ci sono dati in attesa esegue la stessa elaborazione di wait_msg(), altrimenti restituisce None.