mqtt package

Submodules

mqtt.client module

class mqtt.client.MQTTClient(username: Optional[str] = None, prefix: Optional[str] = None, logger: Optional[mqtt.logger.Logger] = None, *args, **kwargs)

Bases: object

Client base class for MQTT Publisher and Subscriber.

Provides methods required for connecting to a MQTT-Broker.

instances

Static attribute of the class, containing all instances of the class. By using a unique identifier for each instance doubles can be avoided.

Parameters:

  • username – Unique username used as identifier for the client to be created. If None is given, it is created automatically.

  • prefix – Inserted to the beginning of each topic.

  • logger – Logger for creating a log of activities to console/terminal and/or file.

  • *args – Additional optional arguments for initializing the client as of the paho-mqtt package.

  • **kwargs – Additional keyword-arguments for initializing the client as of the paho-mqtt package.

Raises:

IndexError – If there already exists a client with the given uuid.

classmethod client_names() → List[str]

Returns al list of the usernames of all clients.

Returns: List of the usernames of all clients.

connect(broker: str, username: str, password: str, vhost: str = '', port: Union[str, int] = 0, websocket: bool = False, ssl: bool = False, keep_alive: int = 60)

Opens a connection to an MQTT-broker under the given address and post.

Parameters:

  • broker – The address (URL) of the MQTT-broker to connect to.

  • username – The username required for authentication at the broker.

  • password – The password required for authentication at the broker.

  • vhost – Virtual host to connect to at the MQTT-Broker.

  • port – The port behind which the broker is running and accessible.

  • websocket – If true MQTT messages are published/received over WebSockets. If false, the default transportation over raw TCP is used.

  • ssl – If true a secured TLS connection is established.

  • keep_alive – maximum period in seconds allowed between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker.

  • not given explicitly given (If) –

  • port automatically resolved from the values of "websocket" and "ssl". (the) –

property connected

Returns the current connection status of the client

Returns: True, if the client is connected to a broker, false otherwise.

disconnect()

Disconnects the client and closes the connection to the broker.

classmethod get(username: str) → mqtt.client.MQTTClient

Returns the client with given username, if one exists.

Parameters:

username – The unique key identifier of the client to be returned.

Returns: The client identified by the given key.

Raises:

ChildNotFoundError – If no client with the given username could be found.

instances = {}
class mqtt.client.MQTTPublisher(username: Optional[str] = None, prefix: Optional[str] = None, logger: Optional[mqtt.logger.Logger] = None, *args, **kwargs)

Bases: mqtt.client.MQTTClient

Minimal, simple class for publishing MQTT messages.

Parameters:

  • username – Unique username used as identifier for the client to be created. If None is given, it is created automatically.

  • prefix – Inserted to the beginning of each topic.

  • logger – Logger for creating a log of activities to console/terminal and/or file.

  • *args – Additional optional arguments for initializing the client as of the paho-mqtt package.

  • **kwargs – Additional optional keyword-arguments for initializing the client as of the paho-mqtt package.

publish(topic: str, message: str, qos: int = 0, retain: bool = False)

Publish the given message under the given topic.

Parameters:

  • topic – The topic the message is published under.

  • message – The message to be published. Ideally encoded as UTF-8 string.

  • qos – Quality of service level, possible values are 0,1,2.

  • retain – If set to True, the message will be set as the “last known good”/retained message for the topic.

class mqtt.client.MQTTSubscriber(username: Optional[str] = None, prefix: Optional[str] = None, logger: Optional[mqtt.logger.Logger] = None, *args, **kwargs)

Bases: mqtt.client.MQTTClient

Minimal, simple class for subscribing, receiving and processing MQTT messages.

Parameters:

  • username – Unique username used as identifier for the client to be created. If None is given, it is created automatically.

  • prefix – Inserted to the beginning of each topic.

  • logger – Logger for creating a log of activities to console/terminal and/or file.

  • *args – Additional optional arguments of the internally used paho-mqtt client.

  • **kwargs – Additional optional key word arguments of the internally used paho-mqtt client.

remove_callback(key: str)

Removes the callback with the given key identifier.

Parameters:

key – The unique key identifier of the callback.

set_callback(key: str, function: Callable)

Add a callback called at each received message.

Parameters:

  • key – Unique identifier of the callback.

  • function – to be called when a message is received. The function must expect at two arguments. First argument is the topic and the second the received message.

subscribe(topic: str, qos: int = 0)

Subscribes the given topic.

Parameters:

  • topic – The topic to be subscribed given as string.

  • qos – Quality of service. Possible values are 0,1,2.

Raises:

SubscriptionError – If topic could not be subscribed successfully.

unsubscribe(topic: str)

Unsubscribes to updates of the given topic.

Parameters:

topic – The topic which should be unsubscribed given as string.

Raises:

SubscriptionError – If topic could not be unsubscribed successfully.

mqtt.exceptions module

exception mqtt.exceptions.CallbackError(*args, **kwargs)

Bases: mqtt.exceptions.MQTTException

exception mqtt.exceptions.ClientNotFoundError(*args, **kwargs)

Bases: mqtt.exceptions.MQTTException

exception mqtt.exceptions.ConnectionError(*args, **kwargs)

Bases: mqtt.exceptions.MQTTException

exception mqtt.exceptions.MQTTException(*args, **kwargs)

Bases: RuntimeError

exception mqtt.exceptions.PublishError(*args, **kwargs)

Bases: mqtt.exceptions.MQTTException

exception mqtt.exceptions.SubscriptionError(*args, **kwargs)

Bases: mqtt.exceptions.MQTTException

mqtt.logger module

class mqtt.logger.Logger(filename: Optional[str] = None, path: Optional[str] = None, level: Optional[int] = None)

Bases: object

Creates a basic logger for console/terminal and optional file output.

Parameters:

  • filename – Name of the file the output should be logged to, file format can be omitted.

  • timestamp and file format is automatically append to the given filename. (Current) –

  • no (If) –

  • is given (filename) –

  • output is written to console/terminal only. (the) –

  • path – Optional path to the logging file. If omitted, file is created at the current working directory.

  • level – Specifies which information should be logged as specified by the python logging module.

  • not set (If) –

  • console level is INFO and default file level is DEBUG. (default) –

get(name: Optional[str] = None) → logging.Logger

Returns the basic python logging utility.

Parameters:

name – Name to identify the logger. If no name is given, the RootLogger is returned.

Returns: A basic python logger with the given name.

set_logging_level(level: int, target: str = '') → None

Sets the logging level.

Parameters:

  • level – Specifies which information should be logged as specified by the python logging module.

  • target – If specified as “FileHandler” the minimum file output is set to the given level. If specified as “StreamHandler” the minimum console/terminal output is set to the given level. If omitted, the level is set for both handlers.

Module contents