mqtt — Simple MQTT client

Модуль mqtt надає мінімальну реалізацію клієнта MQTT v3.1.1, придатну для використання на пристроях з обмеженою пам’яттю. Він підтримує підключення до брокера (з необов’язковим TLS), публікацію повідомлень, підписку на теми, налаштування останньої волі та ping-сигнали для підтримки з’єднання.

Приклад:

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

Винятки

exception mqtt.MQTTException

Виникає, коли брокер відхиляє запит CONNECT або коли запит SUBSCRIBE відхиляється. Єдиним аргументом є числовий код повернення від брокера.

Класи

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)

Конструює MQTT-клієнт.

Аргументи:

  • client_id – унікальний ідентифікатор клієнта, що надсилається брокеру.

  • server – ім’я хоста або IP-адреса брокера (вирішується за допомогою socket.getaddrinfo()).

  • port – TCP-порт брокера (зазвичай 1883 для звичайного з’єднання або 8883 для TLS).

  • ssl_params – якщо не None, сокет обгортається за допомогою ssl.wrap_socket(), а ssl_params передається як іменовані аргументи. Передайте {}, щоб увімкнути TLS з параметрами за замовчуванням.

  • user – необов’язкове ім’я користувача для автентифікації на брокері. Якщо вказано, необхідно також надати password.

  • password – необов’язковий пароль, що використовується разом з user.

  • keepalive – інтервал підтримки з’єднання в секундах (0 вимикає). Має бути менше 65536.

  • callback – викликається як callback(topic, msg) для кожного повідомлення PUBLISH, доставленого від брокера. Також може бути встановлений пізніше за допомогою set_callback().

Методи

set_callback(f: callable) → None

Встановлює зворотний виклик, що викликається wait_msg() та check_msg() при отриманні повідомлення PUBLISH. Зворотний виклик викликається як f(topic, msg), де обидва аргументи є bytes.

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

Налаштовує MQTT Last Will and Testament. Брокер публікує msg на topic, якщо клієнт відключається некоректно. Необхідно викликати перед connect().

Аргументи:

  • topic – тема останньої волі (має бути не порожньою).

  • msg – вміст останньої волі.

  • retain – якщо True, брокер зберігає повідомлення останньої волі як збережене повідомлення.

  • qos – рівень QoS останньої волі. Має бути 0, 1 або 2.

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

Відкриває TCP (і, за необхідності, TLS) з’єднання з брокером і надсилає пакет CONNECT.

Аргументи:

  • clean_session – якщо True, запитує чисту сесію; інакше брокер відновлює будь-який попередній стан сесії.

  • timeout – тайм-аут сокета в секундах, що застосовується до базового сокета.

Повертає прапорець session present брокера (0 або 1). Викидає MQTTException, якщо брокер повертає ненульовий код повернення CONNACK.

disconnect() → None

Надсилає пакет DISCONNECT і закриває базовий сокет.

ping() → None

Надсилає пакет PINGREQ брокеру. Слід викликати періодично, якщо keepalive ненульове, щоб брокер не розірвав з’єднання.

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

Публікує msg на topic.

Аргументи:

  • topic – назва теми для публікації.

  • msg – байти вмісту.

  • retain – якщо True, вказує брокеру зберегти повідомлення для нових передплатників.

  • qos – рівень якості обслуговування. Підтримуються 0 (відправив і забув) та 1 (з підтвердженням). 2 не реалізовано та викличе AssertionError.

Для qos 1 виклик блокується до отримання відповідного PUBACK. Загальний розмір пакета повинен бути менше 2097152 байтів.

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

Підписується на topic на заданому рівні qos. Зворотний виклик має бути зареєстрований через set_callback() або переданий конструктору; інакше виникне AssertionError.

Блокується до отримання відповідного SUBACK. Викидає MQTTException, якщо брокер відхиляє підписку (код повернення 0x80).

wait_msg() → int | None

Блокується в очікуванні одного вхідного пакета MQTT та обробляє його. Пакети PUBLISH доставляються до зареєстрованого зворотного виклику. Пакети PINGRESP споживаються без виводу. Для інших керуючих пакетів повертається перший необроблений байт. Повертає None, якщо дані недоступні або якщо PINGRESP був оброблений.

check_msg() → int | None

Неблокуюча варіація wait_msg(). Опитує сокет протягом не більше ~50 мс за допомогою select.select(); якщо є очікуючі дані, виконує таку саму обробку, як wait_msg(), інакше повертає None.