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.