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. Pasa {} para habilitar TLS con los valores predeterminados.

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