mqtt_gateways.gateway package¶

Module contents¶

The package representing the core of the application.

There are 4 modules:

mqtt_client.py defines the child class of the official MQTT Client class of the paho library;
mqtt_map.py defines the classes internalMsg and msgMap;
start_gateway.py which contains the script for the application initialisation and main loop.
configuration.py which contains the default configuration as a string.

Submodules¶

mqtt_gateways.gateway.mqtt_map module¶

This module represents the bridge between the internal representation of messages and the MQTT representation.

It defines 2 classes:

internalMsg is the internal representation of a message
msgMap is the conversion engine between the internal representation and the MQTT one.

As a reminder, we define the MQTT syntax as follows:

topic: root/function/gateway/location/device/sender/type-{C or S}
payload: action or status, in plain text or in query string, e.g. key1=value1&key2=value2&...

class mqtt_gateways.gateway.mqtt_map.internalMsg(iscmd=False, function=None, gateway=None, location=None, device=None, sender=None, action=None, arguments=None)¶

Bases: object

Defines all the characteristics of an internal message.

Parameters:

iscmd (bool) – Indicates if the message is a command (True) or a status (False), optional
function (string) – internal representation of function, optional
gateway (string) – internal representation of gateway, optional
location (string) – internal representation of location, optional
device (string) – internal representation of device, optional
sender (string) – internal representation of sender, optional
action (string) – internal representation of action, optional
arguments (dictionary of strings) – all values should be assumed to be strings, optional

copy()¶: docstring

str()¶: Helper function to stringify the class attributes.

reply(response, reason)¶

Formats the message to be sent as a reply to an existing command

This method is supposed to be used with an existing message that has been received by the interface

class mqtt_gateways.gateway.mqtt_map.MsgList¶

Bases: Queue.Queue, object

docstring

push(item)¶: Equivalent to self._list.append(item)

pull()¶: Equivalent to self._list.pop(0)

class mqtt_gateways.gateway.mqtt_map.mappedFields(function, gateway, location, device, sender, action, argkey, argvalue)¶

Bases: tuple

action¶: Alias for field number 5

argkey¶: Alias for field number 6

argvalue¶: Alias for field number 7

device¶: Alias for field number 3

function¶: Alias for field number 0

gateway¶: Alias for field number 1

location¶: Alias for field number 2

sender¶: Alias for field number 4

class mqtt_gateways.gateway.mqtt_map.msgMap(jsondict)¶

Bases: object

Contains the mapping data and the conversion methods.

Initialises the 5 maps from the argument mapdata, which is an object that must be readable line by line with a simple iterator. The syntax for mapdata is that each line has to start with one of 6 possible labels (topic, function, gateway, location, device, action) followed by : and then the actual data. If the label is topic then the data should be a valid MQTT topic string, otherwise the data should be a pair of keywords separated by a ,, the first being the MQTT representation of the element and the second being its internal equivalent.

To access the maps use: mqtt_token = maps.*field*.m2i(internal_token) Example: mqtt_token = maps.gateway.m2i(internal_token)

Parameters:	jsondata (dictionary) – contains the map data in the agreed format; if None, the NO_MAP structure is used.

class tokenMap(maptype, mapdict=None)¶

Bases: object

Represents the mapping for a given token or characteristic.

Each instantiation of this class represent the mapping for a given token, and contains the type of mapping, the mapping dictionary if available, and the methods to convert the keywords back and forth between MQTT and internal representation.

m2i(mqtt_token)¶: docstring

i2m(internal_token)¶: docstring

sender()¶: docstring

mqtt2internal(mqtt_msg)¶

Converts the MQTT message into an internal one.

Parameters:	mqtt_msg (mqtt.MQTTMessage) – a MQTT message.
Returns:	the conversion of the MQTT message
Return type:	internalMsg object
Raises:	`ValueError` – in case of bad MQTT syntax or unrecognised map elements

internal2mqtt(internal_msg)¶

Converts an internal message into a MQTT one.

Parameters:	internal_msg (an internalMsg object) – the message to convert
Returns:	a full MQTT message where topic syntax is `root/function/gateway/location/device/sender/{C or S}` and payload syntax is either a plain action or a query string.
Return type:	a MQTTMessage object
Raises:	`ValueError` – in case a token conversion fails

mqtt_gateways.gateway.mqtt_map.test()¶: docstring

mqtt_gateways.gateway.start_gateway module¶

Defines the function that starts the gateway and the 3 MQTT callbacks.

This module exposes the main entry points for the framework: the gateway interface class, which is received as an argument by the main function startgateway(), and is instantiated after all the initialisations are done. Note that at the moment of instantiation, the configuration file should be loaded, so anything that is written inside the [INTERFACE] section will be passed on to the class constructor. This way custom configuration settings can be passed on to the gateway interface.

mqtt_gateways.gateway.start_gateway.startgateway(gateway_interface)¶

Initialisation and main loop.

Initialises the configuration and the logger, starts the interface, starts the MQTT communication then starts the main loop. The loop calls the MQTT loop method to process any message from the broker, then calls the gateway interface loop, and finally publishes all MQTT messages queued.

Notes on MQTT behaviour:

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

Notes on the loading of data: the configuration file is the only file that needs to be either passed as argument through the command line, or the default settings will be used (and probably fail as one needs at least a valid MQTT broker for the application to start). All other filenames will be in the configuration file itself. The configuration file name can be passed as the first argument in the command line. If the argument is a directory (i.err. ends with a slash) then it is appended with the default file name. If it is a path it is checked to see if it is absolute, and if it is not it will be prepended with the path of the calling script. The default file name is the name of the calling script with the .conf extension. The default directory is the directory of the calling script.

Parameters:

gateway_interface (class (not an instance of it!)) – the interface The only requirement is that it should have an appropriate constructor and a loop method.

Raises:

OSError – if any of the necessary files are not found.

The necessary files are the configuration file (which is necessary to define the MQTT broker, at the very least) and the map (for which there can not be any default). It tries to catch most other ‘possible’ exceptions. KeyboardInterrupt should work as there are a few pauses around. Finally, only errors thrown by the provided interface class will not be caught and could terminate the application.

mqtt_gateways.gateway.configuration module¶

The default configuration settings in a single string constant.

Given how the configuration loader works, only the sections and options declared already here will be considered in any external configuration file. If an external configuration file is read and contains sections and options not included in here, they will be ignored, except for the [INTERFACE] section. The section [INTERFACE] is reserved to the configuration parameters that might be needed by the interface being implemented.

Use this declaration as a template configuration file.