6. mqttgateway package¶

6.1. Warning¶

As of 24 May 2018, most of the docstrings are obsolete. They will be updated gradually as soon as possible.

6.2. Package contents¶

The mqttgateway library helps in building gateways between connected devices and MQTT systems.

This package has 4 groups of files:

the core of the library made of the modules:
- start_gateway.py which contains the script for the application initialisation and main loop;
- mqtt_client.py which defines the child of the MQTT Client class of the paho library, needed to implement a few extra features;
- mqtt_map.py which defines the internal message class internalMsg and the mapping class msgMap.
the utilities used by the core and that are really application agnostic; these are in the modules:
- app_properties.py, a singleton that holds application wide data like name, directories where to look for files, configuration and log information;
- init_logger, used by app_properties to initialise the loggers and handlers;
- load_config, used by app_properties to load the configuration;
- throttled_exception, an exception class that mutes events if they are too frequent, handy for connection problems happening in fast loops.
the dummy interface, an empty interface to test the installation of the library and to be used as a template to write a new interface, and which is made of the modules:
- dummy_start, the launcher script;
- dummy_interface, the actual interface main class.
various data files:
- default.conf, the file containing all the configuration options and their default
  
  values;
- mqtt_map_schema.json, the schema of the mapping files;
- dummy_map.json and dummy2mqtt.conf, the map and configuration file of the dummy interface.

6.3. Modules¶

6.4. mqttgateway.app_properties module¶

6.5. mqttgateway.dummy_interface module¶

6.6. mqttgateway.dummy_start module¶

6.7. mqttgateway.init_logger module¶

6.8. mqttgateway.load_config module¶

6.9. mqttgateway.mqtt_client module¶

This is a child class of the MQTT client class of the PAHO library.

It includes the management of reconnection when using only the loop() method, which is not included natively in the current PAHO library.

Notes on MQTT behaviour:

if not connected, the loop and publish methods will not do anything, but raise no errors either.
the loop method handles always only one message per call.

exception mqttgateway.mqtt_client.connectionError(msg=None)¶

Bases: mqttgateway.throttled_exception.ThrottledException

Base Exception class for this module, inherits from ThrottledException

mqttgateway.mqtt_client.mqttmsg_str(mqttmsg)¶

Returns a string representing the MQTT message object.

As a reminder, the topic is unicode and the payload is binary.

mqttgateway.mqtt_client._on_connect(client, userdata, flags, return_code)¶

The MQTT callback when a connection is established.

It sets to True the connected attribute and subscribes to the topics available in the message map.

As a reminder, the flags argument is a dictionary with at least the key session present (with a space!) which will be 1 if the session is already present.

mqttgateway.mqtt_client._on_subscribe(client, userdata, mid, granted_qos)¶

The MQTT callback when a subscription is completed.

Only implemented for debug purposes.

mqttgateway.mqtt_client._on_disconnect(client, userdata, return_code)¶

The MQTT callback when a disconnection occurs.

It sets to False the mg_connected attribute.

mqttgateway.mqtt_client._on_message(client, userdata, mqtt_msg)¶

The MQTT callback when a message is received from the MQTT broker.

The message (topic and payload) is mapped into its internal representation and then appended to the incoming message list for the gateway interface to execute it later.

class mqttgateway.mqtt_client.mgClient(host='localhost', port=1883, keepalive=60, client_id='', on_msg_func=None, topics=None, userdata=None)¶

Bases: paho.mqtt.client.Client

Class representing the MQTT connection. mg means MqttGateway.

Inheritance issues:: The MQTT paho library sets quite a few attributes in the Client class. They all start with an underscore and have standard names (_host, _port,…). Also, some high level methods are used extensively in the paho library itself, in particular the connect() method. Overriding them is dangerous. That is why all the homonymous attributes and methods here have an mg_ prepended to avoid these problems.

Parameters:

host (string) – a valid host address for the MQTT broker (excluding port)
port (int) – a valid port for the MQTT broker
keepalive (int) – see PAHO documentation
client_id (string) – the name (usually the application name) to send to the MQTT broker
on_msg_func (function) – function to call during on_message()
topics (list of strings) – e.g.[‘home/audiovideo/#’, ‘home/lighting/#’]
userdata (object) – any object that will be passed to the call-backs

lag_end()¶

Method to inhibit the connection test during the lag.

One of the feature added by this class over the standard PAHO class is the possibility to reconnect when disconnected while using only the loop() method. In order to achieve this, the connection is checked regularly. At the very beginning of the connection though, there is the possibility of a race condition when testing the connection state too soon after requesting it. This happens if the on_connect call-back is not called fast enough by the PAHO library and the main loop tests the connection state before that call-back has had the time to set the state to connected. As a consequence the automatic reconnection feature gets triggered while a connection is already under way, and the connection process gets jammed with the broker. That’s why we need to leave a little lag before testing the connection. This is done with the function variable lag_test, which is assigned to this function (lag_end) at connection, and switched to a dummy lambda after the lag has passed.

lag_reset()¶: Resets the lag feature for a new connection request.

mg_connect()¶

Sets up the lag feature on top of the parent connect method.

See lag_end for more information on the lag feature.

mg_reconnect()¶: Sets up the lag feature on top of the parent method.

loop_with_reconnect(timeout)¶

Implements automatic reconnection on top of the parent loop method.

The use of the method/attribute lag_test() is to avoid having to test the lag forever once the connection is established. Once the lag is finished, this method gets replaced by a simple lambda, which hopefully is much faster than calling the time library and doing a comparison.

6.10. mqttgateway.mqtt_map module¶

6.11. mqttgateway.start_gateway module¶

6.12. mqttgateway.throttled_exception module¶

An exception class that throttles events in case an error is triggered too often.

exception mqttgateway.throttled_exception.ThrottledException(msg=None, throttlelag=10, module_name=None)¶

Bases: exceptions.Exception

Exception class base to throttle events

This exception can be used as a base class instead of Exception. It adds a counter and a timer that allow to silence the error for a while if desired. Only after a given period a trigger is set to True to indicate that a number of errors have happened and it is time to report them.

It defines 2 members:

trigger is a boolean set to True after the requested lag;
report is a string giving some more information on top of the latest message.

The code using these exceptions can test the member trigger and decide to silence the error until it is True. At any point one can still decide to use these exceptions as normal ones, ignore the trigger and report members and just raise the exception as normal.

Usage:

try:
    #some statements that might raise your own exception derived from ThrottledException
except YourExceptionError as err:
    if err.trigger:
        log(err.report)

Parameters:	msg (string) – the error message, as for usual exceptions, optional throttlelag (int) – the lag time in seconds while errors should be throttled, defaults to 10 seconds module_name (string) – the calling module to give extra information, optional

_count = 0¶

_timer = 1656078406.21489¶