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 restrita. Ele suporta conexão a um broker (com TLS opcional), publicação de mensagens, inscrição em 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 a requisição CONNECT ou quando uma requisição SUBSCRIBE é recusada. 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 de cliente único enviado ao broker.

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

  • port – porta TCP do broker (tipicamente 1883 em texto puro ou 8883 para TLS).

  • ssl_params – se não for None, o socket é encapsulado com ssl.wrap_socket() e ssl_params é encaminhado como argumentos nomeados. Passe {} para habilitar TLS com os valores padrão.

  • user – nome de usuário opcional para autenticação no broker. Se fornecido, password também deve ser informado.

  • password – senha opcional usada em conjunto com user.

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

  • callback – objeto chamável invocado como callback(topic, msg) para cada PUBLISH entregue pelo broker. Também pode 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 desconectar de forma não graciosa. Deve ser chamado antes de connect().

Argumentos:

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

  • msg – payload do last-will.

  • retain – se True, o broker armazena a mensagem de will como uma 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 conexão TCP (e opcionalmente TLS) com o 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.

Retorna o sinalizador session present do broker (0 ou 1). Lança MQTTException se o broker retornar um código de retorno CONNACK diferente de 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 diferente de zero para que o broker não encerre a conexã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 no qual publicar.

  • msg – bytes do payload.

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

  • qos – nível de qualidade de serviço. 0 (dispara e esquece) e 1 (com confirmação) são suportados. 2 não está implementado e lançará AssertionError.

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

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

Inscreve-se em topic no nível qos fornecido. Um callback deve ter sido registrado via set_callback() ou fornecido ao construtor; caso contrário AssertionError é lançada.

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

wait_msg() → int | None

Bloqueia aguardando um único pacote MQTT recebido e o processa. Pacotes PUBLISH são entregues ao callback registrado. Pacotes PINGRESP são consumidos silenciosamente. Para outros pacotes de controle, o primeiro byte bruto é retornado. Retorna None se nenhum dado estiver disponível ou se um PINGRESP foi processado.

check_msg() → int | None

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