DevelopmentInterfaces

Preface

This is not yet implemented since there has not yet been a proposal that is mostly accepted by the developers. Parts of the implementation can be found around fhem, though. Interfaces serve to purposes:

they document what standardized readings are available
they enable additional functions that rely on the existence of standard readings for a given device that implements interfaces

Are interfaces a must or is it asked to much for the fhem project to rely on the existence of interfaces on all devices?

As a compromise interfaces could be an option but a device that implements interfaces might benefit from addition features, such as:

devices implementing the "switch" interface might have the "toggle" feature in the pgm2 web interface
devices implementing the "humidity" and "temperature" interface might get the "dewpoint" feature for free
devices implementing the "battery" interface might get the "checkstate" feature

etc.

Using Interfaces

An interface documents the readings (meanings and units) and the setters of a device. The objective of the interface concept is to ease the integration of new devices into fhem without the need to make changes to the frontends/GUIs. The frontends/GUIs know how to handle certain interfaces, i.e. how to display readings and how to present setters to the user.

Example: S555TH, HMS100T, HMS100TF, FHT80b, KS300, WS2000, OWTEMP all provide a temperature reading. They announce that they support the temperature reading by adding the temperature interface to the interface internal. S555TH, HMS100TF, KS300, WS2000 also provide a humidity reading and thus add the humidity interface to the interface internal. A frontend that knows how to display temperature but not humidity would still support all of the listed devices and any new device that implements the temperature interface without the need for modification.

Any device that supports interfaces has an internal named Interfaces.

Perl code:

$hash->{fhem}{interfaces}= "temperature";

xmllist:

<INT key="interfaces" value="temperature"/>

list:

Internals: 
    Interfaces temperature

Multiple interfaces are separated by semicolons, e.g. "temperature;humidity".

Interfaces support inheritance. A derived interface supports all readings and setters of its ancestors.

Nevertheless, all parent interface of any given interface must be included in the list of interfaces such that a frontend that does not know about a more specialized interface can still profit from the more general interface: "interface:switch:switch_passive:dimmer". Please note that this is a mere convention and no checks are done. If a dimmer omits the switch interface, a dumb frontend that knows about switches but not about dimmers would not be able to handle the device well.

The list of interfaces for a given device does not need to be exhaustive. Readings that are not covered by the interfaces announced by the device can still be shown by simply enumerating the readings.

Interface definitions

Derived interfaces list only additions to the readings and setters of the parent interface.

interface

The common ancestor of all interfaces.

Readings:

none (later we add here all common internals, i.e. those of the framework like ioDev, def, name, nr, etc.)

Setters:

none

switch

Inherits from interface.

Any device that can be either on or off.

Readings:

onoff: integer, 0..1, the current state of the switch (off or on)

switch_active

Inherits from switch.

Any device that autonomously switches itself on or off.

switch_passive

Inherits from switch.

Any device that can be switched on or off by the user.

Setters:

on: Turns device on.
  off: Turns device off.

dimmer

Inherits from switch_passive.

Any device that change the brightness level, e.g. a lamp dimmer.

Readings:

level: float, 0.0..100.0, indicates the brightness level in percent.

Setters:

dimto x: changes the brightness level to be x%, x float, 0.0..100.0
  dimup x: increases the brightness level by x%, x float, 0.0..100.0
  dimdown x: decreases the brightness level by x%, x float, 0.0..100.0

Notes: (1) switch being an ancestor of dimmer, it is assumed that a dimmer always can be switched on and off. (2) The user cannot assume that off and on are equivalent to brightness levels of 0% or 100% respectively. For example, for FS20 dimmers, brightness level and on/off state are independent settings.

temperature

Inherits from interface.

Any device that measures temperatures.

Readings:

temperature: float, indicates the temperature in centigrades (degrees Celsius)

humidity

Inherits from interface.

Any device that measures humidity.

Readings:

humidity: float, 0.0..100.0, indicates the humidity in percent.

thermostat

Inherits from temperature.

Any device that controls temperatures.

Readings:

desiredTemperature: float, indicates the desired temperature in centigrades (degrees Celsius)

Setters:

desiredTemperature t: set the desired temperature to t, t float, in centigrades (degrees Celsius)

heaterControl

Inherits from thermostat.

Any device that controls a heater. This interface is pretty well tailored to the FHT80b devices.

Readings:

actuator: float, 0.0..100.0, indicates the opening of the heater's valve in percent

brightness

Inherits from interface.

Any device that can measure brightness.

Readings:

brightness: float, >= 0.0, indicates the brightness in lux

volume

Inherits from interface.

Any device that measures volumes, e.g. the volume of water or oil in a tank.

Readings:

volume: float, indicates the measured volume in liters
   level, float, indicates the measured volume in percent of the maximum volume the vessel can contain

power

Inherits from interface.

Any device that measures electric power.

Readings:

currentPower: float, indicates the current power (or average over last time interval) in kW
   maxPower: float, indicates the maximum power measured since startup in kW
   totalEnergy: float, indicates the total energy consumed since startup in kWh
   totalEnergyDay: float, indicates the total energy consumed since midnight in kWh
   totalEnergyWeek: float, indicates the total energy consumed since the beginning of the week in kWh
   totalEnergyMonth: float, indicates the total energy consumed since the beginning of the month in kWh

battery

Inherits from interface.

Any device that sends the battery state.

Readings:

battery: ok, low

Supported interfaces

FHT80b: temperature
HMS100T: temperature
HMS100TF: temperature;humidity
KS300: temperature;humidity
S555TH: temperature;humidity
X10 AM12: switch_passive
X10 LM12: dimmer
X10 LM15: switch_passive
X10 TM13: switch_passive