mqtt — Cliente MQTT simple#

El módulo mqtt proporciona una implementación mínima de cliente MQTT v3.1.1 adecuada para su uso en dispositivos con memoria limitada. Admite la conexión a un broker (con TLS opcional), la publicación de mensajes, la suscripción a temas, la configuración de last-will y los pings de keep-alive.

Ejemplo:

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

Excepciones#

exception mqtt.MQTTException#

Se lanza cuando el broker rechaza la solicitud CONNECT o cuando se rechaza una solicitud SUBSCRIBE. El único argumento es el código de retorno numérico proporcionado por el broker.

Clases#

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

Construye un cliente MQTT.

Argumentos:

  • client_id – identificador único de cliente enviado al broker.

  • server – nombre de host o dirección IP del broker (resuelto con socket.getaddrinfo()).

  • port – puerto TCP del broker (normalmente 1883 sin cifrar o 8883 para TLS).

  • ssl_params – si no es None, el socket se envuelve con ssl.wrap_socket() y ssl_params se reenvía como argumentos de palabra clave. Pase {} para habilitar TLS con los valores predeterminados. El módulo ssl se importa de forma diferida al conectar, por lo que las conexiones sin cifrar (y el propio módulo) funcionan en compilaciones de firmware sin soporte SSL.

  • user – nombre de usuario opcional para la autenticación con el broker. Si se proporciona, también debe suministrarse password.

  • password – contraseña opcional utilizada junto con user.

  • keepalive – intervalo de keep-alive en segundos (0 lo desactiva). Debe ser menor que 65536.

  • callback – invocable llamado como callback(topic, msg) por cada PUBLISH entregado desde el broker. También puede establecerse más tarde con set_callback().

Métodos#

set_callback(f: callable) → None#

Establece la función de retorno (callback) invocada por wait_msg() y check_msg() cuando se recibe un mensaje PUBLISH. La función de retorno se llama como f(topic, msg) con ambos argumentos como bytes.

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

Configura el Last Will and Testament de MQTT. El broker publica msg en topic si el cliente se desconecta de forma anómala. Debe llamarse antes de connect().

Argumentos:

  • topic – tema del last-will (no debe estar vacío).

  • msg – carga útil del last-will.

  • retain – si es True, el broker almacena el mensaje de will como un mensaje retenido.

  • qos – nivel de QoS del last-will. Debe ser 0, 1 o 2.

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

Abre una conexión TCP (y opcionalmente TLS) con el broker y envía un paquete CONNECT.

Argumentos:

  • clean_session – si es True, solicita una sesión limpia; en caso contrario, el broker reanuda cualquier estado de sesión anterior.

  • timeout – tiempo de espera del socket en segundos aplicado al socket subyacente.

Devuelve el indicador session present del broker (0 o 1). Lanza MQTTException si el broker devuelve un código de retorno CONNACK distinto de cero.

disconnect() → None#

Envía un paquete DISCONNECT y cierra el socket subyacente.

ping() → None#

Envía un paquete PINGREQ al broker. Debe llamarse periódicamente si keepalive es distinto de cero para que el broker no cierre la conexión.

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

Publica msg en topic.

Argumentos:

  • topic – nombre del tema en el que publicar.

  • msg – bytes de la carga útil.

  • retain – si es True, indica al broker que retenga el mensaje para los nuevos suscriptores.

  • qos – nivel de calidad de servicio. Se admiten 0 (enviar y olvidar) y 1 (con confirmación). 2 no está implementado y lanzará AssertionError.

Para qos 1, la llamada se bloquea hasta que se recibe el PUBACK correspondiente. El tamaño total del paquete debe ser menor que 2097152 bytes.

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

Se suscribe a topic en el nivel qos indicado. Debe haberse registrado una función de retorno mediante set_callback() o suministrado al constructor; de lo contrario se lanza AssertionError.

Se bloquea hasta que se recibe el SUBACK correspondiente. Lanza MQTTException si el broker rechaza la suscripción (código de retorno 0x80).

wait_msg() → int | None#

Se bloquea esperando un único paquete MQTT entrante y lo procesa. Los paquetes PUBLISH se entregan a la función de retorno registrada. Los paquetes PINGRESP se consumen silenciosamente. Para otros paquetes de control se devuelve el primer byte sin procesar. Devuelve None si no hay datos disponibles o si se procesó un PINGRESP.

check_msg() → int | None#

Variante no bloqueante de wait_msg(). Sondea el socket durante un máximo de ~50 ms usando select.select(); si hay datos pendientes realiza el mismo procesamiento que wait_msg(), de lo contrario devuelve None.