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 classinternalMsg
and the mapping classmsgMap
.
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 byapp_properties
to initialise the loggers and handlers;load_config
, used byapp_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
anddummy2mqtt.conf
, the map and configuration file of thedummy
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
andpublish
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 keysession 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
meansMqttGateway
.- 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 theconnect()
method. Overriding them is dangerous. That is why all the homonymous attributes and methods here have anmg_
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 theon_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 toconnected
. 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 variablelag_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 toTrue
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 thetrigger
andreport
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¶