MQTT

class nirahmq.mqtt.MQTTClient

Bases: object

NirahMQ MQTT client class

This class is responsible for establishing a connection to the MQTT broker, handles authentication, callback registration and subscription, as well as publishing arbitrary payloads to any MQTT topic.

__init__(hostname: str, port: int = 1883, username: str | None = None, password: str | None = None, client_id: str = 'nirahmq')

Initialize the MQTT client.

Caution

Currently there is no TLS support! Authentication details and messages are sent on plaintext!

Parameters:

• hostname (str) – The MQTT broker hostname

• port (int) – The MQTT broker port

• username (str) – The MQTT broker username

• password (str) – The MQTT broker password

• client_id (str) – The MQTT broker client ID

add_callback(topic: str, callback: Callable[[bytes | bytearray], None]) → None

Register a callback to an MQTT topic.

Subscribes to the specified MQTT topic and registers a user supplied callback to it. See remove_callback() for how to remove a callback.

Parameters:

• topic (str) – The MQTT topic to register the callback to

• callback (Callable[[bytes | bytearray], None]) – The callback to register

connect() → bool

Connect to the MQTT broker.

Attempt to connect to the MQTT broker with the configured settings. If the connection was successful, returns True. If the connection failed or the instance is already connected, returns False.

Returns:

True if the connection was successful

Return type:

bool

Raises:

RuntimeError – If the connection was not successful

disconnect() → None

Disconnect from the MQTT broker.

Disconnect from the connected MQTT broker. Does nothing if the instance is already disconnected.

Raises:

RuntimeError – If the connection was not successfully terminated

publish(topic: str, payload: str | bytes | bytearray | int | float | None, qos: QoS = QoS.MOST, retain: bool = True) → None

Publish an arbitrary payload to the specified MQTT topic.

Publish an arbitrary payload to the specified MQTT topic. Optionally, set the Quality of Service (QoS) and retain flag for the message.

Does nothing if the instance is not connected to an MQTT broker.

Parameters:

• topic (str) – The MQTT topic to publish the payload to

• payload (str | bytes | bytearray | int | float | None) – The payload to publish

• qos (QoS) – The QoS to use

• retain (bool) – Retain flag

remove_callback(topic: str) → None

Unregister a callback to an MQTT topic.

Removes a previously registered callback with add_callback() and unsubscribes from the associated MQTT topic. See add_callback() for how to add a callback.

Note

The instance must be connected to take effect. Does nothing otherwise.

Parameters:

topic (str) – The topic to remove the callback from

set_will(topic: str, payload: str) → None

Set the MQTT Last Will and Testament (LWT) payload and topic.

Set the MQTT topic and payload that the MQTT broker will publish to when the client disconnects unexpectedly.

Note

Must be called before connection. Does nothing otherwise.

Parameters:

• topic (str) – The LWT topic

• payload (str) – The LWT payload

property client_id: str

The configured MQTT client ID (read-only).

Returns:

The configured client ID

Return type:

str

property hostname: str

The configured MQTT broker hostname (read-only).

Returns:

The configured hostname

Return type:

str

property port: int

The configured MQTT broker port (read-only).

Returns:

The configured port

Return type:

int

class nirahmq.mqtt.QoS

Bases: IntEnum

MQTT Quality of Service (QoS) enumeration class.

EXACTLY = 2

Message is delivered exactly once.

LEAST = 1

Message is delivered at least once.

MOST = 0

Message is delivered at most once.

mqtt.Topic = Topic

A custom type alias used by nirahmq to validate a string is a valid MQTT topic.