mqtt — Cliente MQTT simples

O módulo mqtt fornece uma implementação mínima de cliente MQTT v3.1.1 adequada para uso em dispositivos com memória limitada. Suporta ligação a um broker (com TLS opcional), publicação de mensagens, subscrição de tópicos, configuração de last-will e pings de keep-alive.

Exemplo:

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

Exceções

exception mqtt.MQTTException

Lançada quando o broker rejeita o pedido CONNECT ou quando um pedido SUBSCRIBE é recusado. O único argumento é o código de retorno numérico fornecido pelo broker.

Classes

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)

Constrói um cliente MQTT.

Argumentos:

  • client_id – identificador único do cliente enviado ao broker.

  • server – nome do host ou endereço IP do broker (resolvido com socket.getaddrinfo()).

  • port – porta TCP do broker (tipicamente 1883 para ligação simples ou 8883 para TLS).

  • ssl_params – se não for None, o socket é envolvido com ssl.wrap_socket() e ssl_params é passado como argumentos de palavra-chave. Passe {} para ativar TLS com valores padrão.

  • user – nome de utilizador opcional para autenticação no broker. Se fornecido, password também deve ser indicado.

  • password – palavra-passe opcional utilizada em conjunto com user.

  • keepalive – intervalo de keep-alive em segundos (0 desativa). Deve ser inferior a 65536.

  • callback – chamável invocado como callback(topic, msg) para cada PUBLISH entregue pelo broker. Pode também ser definido posteriormente com set_callback().

Métodos

set_callback(f: callable) → None

Define o callback invocado por wait_msg() e check_msg() quando uma mensagem PUBLISH é recebida. O callback é chamado como f(topic, msg) com ambos os argumentos como bytes.

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

Configura o Last Will and Testament do MQTT. O broker publica msg em topic se o cliente se desligar de forma não controlada. Deve ser chamado antes de connect().

Argumentos:

  • topic – tópico do last-will (deve ser não vazio).

  • msg – payload do last-will.

  • retain – se True, o broker armazena a mensagem de will como mensagem retida.

  • qos – nível de QoS do last-will. Deve ser 0, 1 ou 2.

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

Abre uma ligação TCP (e opcionalmente TLS) ao broker e envia um pacote CONNECT.

Argumentos:

  • clean_session – se True, solicita uma sessão limpa; caso contrário, o broker retoma qualquer estado de sessão anterior.

  • timeout – timeout do socket em segundos aplicado ao socket subjacente.

Devolve o sinalizador session present do broker (0 ou 1). Lança MQTTException se o broker devolver um código de retorno CONNACK não zero.

disconnect() → None

Envia um pacote DISCONNECT e fecha o socket subjacente.

ping() → None

Envia um pacote PINGREQ ao broker. Deve ser chamado periodicamente se keepalive for não zero, para que o broker não termine a ligação.

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

Publica msg em topic.

Argumentos:

  • topic – nome do tópico para publicar.

  • msg – bytes do payload.

  • retain – se True, instrui o broker a reter a mensagem para novos subscritores.

  • qos – nível de qualidade de serviço. 0 (disparar e esquecer) e 1 (confirmado) são suportados. 2 não está implementado e lançará AssertionError.

Para qos 1, a chamada bloqueia até o PUBACK correspondente ser recebido. O tamanho total do pacote deve ser inferior a 2097152 bytes.

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

Subscreve topic no nível qos indicado. Um callback deve ter sido registado via set_callback() ou fornecido ao construtor; caso contrário, AssertionError é lançado.

Bloqueia até o SUBACK correspondente ser recebido. Lança MQTTException se o broker recusar a subscrição (código de retorno 0x80).

wait_msg() → int | None

Bloqueia à espera de um único pacote MQTT recebido e processa-o. Os pacotes PUBLISH são entregues ao callback registado. Os pacotes PINGRESP são consumidos silenciosamente. Para outros pacotes de controlo, o primeiro byte bruto é devolvido. Devolve None se não houver dados disponíveis ou se um PINGRESP tiver sido processado.

check_msg() → int | None

Variante não bloqueante de wait_msg(). Faz polling do socket durante no máximo ~50 ms usando select.select(); se houver dados pendentes, realiza o mesmo processamento que wait_msg(), caso contrário devolve None.