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 TLS con le impostazioni predefinite. Il modulo ssl viene importato in modo lazy alla connessione, quindi le connessioni in chiaro (e il modulo stesso) funzionano sulle build del firmware senza supporto SSL.

  • 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.