Models

Information

class models.Information(name, description, info_range)

Class used to wrap an information made available by a device.

set(args)

Method enabling the user to change the name, the description and the location of the device. The args must follow the format given in device_infos[‘arguments’].

Action

class models.Action(name, description, method, arguments_format)

Class used to wrap an action made available by a device.

set(args)

Method enabling the user to change the name, the description and the location of the device. The args must follow the format given in device_infos[‘arguments’].

Device

class models.Device(protocol)

Base class for any Device.

Implementation examples

Interface

class models.Interface

Base class for any Interface. This class will be documented later, once an Interface actually behaving like a plugin would have been developed.

Implementation examples

Protocol

class models.Protocol

In the model used to design the box, a class deriving from models.Protocol implements all the functions that are necessary to make the box compatible with a new home automation protocol. For instance, it is the protocol class of a given home automation protocol that should implement the methods necessary to the process of adding of a new device to the box.

The class models.Protocol defines the minimal public interface that any protocol class should implement, in order to allow other entities to use it.

It should not be directly instantiated.

Any protocol plugin should derive from it. To see what the actual implementation of a protocol looks like, you may for instance refer to the classes protocols.nexa.Nexa and protocols.oregon.Oregon.

get_handled_devices()

Presents the different types of devices handled by this protocol.

It does not mean that the user can instantiate them himself: some may not need interventiion of the user on the software part to be added to the system. Still, this function lets the user know what kinds of devices this protocol added support for.

Returns:A list of python dictionaries describing every type of device handled by this protocol

The format of each python dictionary returned is the following:

• name
• description
• user_instantiable
• (device_code)
• (settings)

The user_instantiable parameter is a boolean. It specified whether or not the user can instantiate himself the device. For instance, if we take into consideration the protocols.nexa.Nexa protocol, the NexaRemote cannot be instantied by the user; they are automatically detected by the system when the user presses one of the button of the actual remote. On the other side, a NexaDevice can be instantiated by the user himself and he will then sync/pair it to an actual Nexa actuator.

The two last keys of the dictionary only exist if the device can be instantiated by the user, that is when the user_instantiable value is True.

• :param:`device_code` is an integer which characterizes a type of device.

It must be given as first argument at the call of the models.Protocol.add_device() function. This function creates a new device whose :param:`device_code` is the one given using the initial settings given as argument. * :param:`settings`

get_settings()

Presents the available settings for this protocol and their respectives types. For instance, the modem used to get radio messages has to be manually set by the user when he initializes the protocol for the first time.

Returns:a dictionary describing the available settings and their type Return type:dict

set(settings)

Applies the settings given as argument to the protocol.

The settings given as argument at function call must be a python dictionary following the format described in the python dict returned by the models.Protocol.get_settings() function.

If the settings given are not valid, they are ignored and the function returns a dictionary containing the faulty keys. For instance, settings may not be valid if you try giving a dictionary having a key which was not specified in the result of models.Protocol.get_settings() or if the value of a setting does not tally with the type requested in models.Protocol.get_settings().

The settings dictionary given as argument may not contain every key specified in the format dictionary. In this case, all the specified settings will me modified (on the condition they are valid) and the others will be left unchanged.

Parameters:settings (python dict) – The python dictionary containing the settings to apply. Returns:True if the settings were correctly applied. A python dictionary containing the faulty settings otherwise. Return type:boolean or python dict

Implementation examples

Example of implementation can be found here: protocols.nexa.Nexa or protocols.oregon.Oregon.

Driver

class models.Driver

In the model used to design the box, a class deriving from models.Driver implements the way the box communicates with an external hardware part. Hardware parts may for instance be radio modems, as it is the case with the drivers.arduino_radio.ArduinoRadio driver.

In the case of the hardware being a modem, this class has then two main features to implement: the process of receiving a message and the process of sending one. In the first case, the driver must implement the way it communicates with hardware parts. For the example of the drivers.arduino_radio.ArduinoRadio, the mini communication protocol used is described in the arduino section

Then, once the message has been recovered from the hardware part, it must be transmitted to the protocols that use this hardware as a communication medium in order to get the actual content of the message. This is implemented through a ‘subscription’ process: protocols subscribe to the driver they want to get their messages from when they are initialized.

The class models.Driver defines the minimal public interface that any driver class should implement, in order to allow other entities to use it.

It should not be directly instantiated.

Any driver plugin should derive from it. To see what the actual implementation of a drivers looks like, you may for instance refer to the class drivers.arduino_radio.ArduinoRadio.

Implementation examples

An example of implementation can be found here: :class:drivers.arduino_radio.ArduinoRadio.

Custom exceptions

class models.AttributeNotSet

Raised when an object tries to use an object whose an attribute essential to its working has not yet been set. E.g. when you try sending a message with a modem whose COM port has not been set.