The FritzBoxPlugin can control smart home devices connected to an AVM FRITZ!Box. Supported devices are:
- FRITZ!DECT200 remote controllable power socket, power and energy meter and thermometer
An instance of a FritzBoxPlugin connects to exactly one FRITZ!Box. You have to use a separate plugin node for each FRITZ!Box if you use more than one. One FritzBoxPlugin instance can use an arbitrary number of devices (actors/sensors). Each device in turn defines certain ports that can be used to interact with the device.
Device status is queried in regular intervals. If a device becomes unavailable or a communication error occurs its ports will signal an error. You can expect some delays when changing state or reading values; these devices are not suitable for fast switching or real-time monitoring. Additional delays may be introduced by communication between the FRITZ!Box and devices; obviously, this plugin cannot control these delays. For this reason device control messages are sent asynchronously: Incoming requests for state changes etc. are placed in a queue and processed sequentially. If you fill the queue faster than it can be processed (which may happen, for example, if you connect a Switch to a fast Pulse), it will most likely result in the openhatd process consuming more and more memory until the server stops responding.
This plugin uses the HTTP web service API exposed by FRITZ!Boxes. Interacting with a FRITZ!Box requires logging in with a user that has the proper permissions (set on the FRITZ!Box administration web site). Login is performed using the challenge-response protocol defined by current FRITZ!Box operating systems. This plugin does not support HTTPS, so all communication is unencrypted. It is not recommended to use this over public networks.
Required. The host name or IP address of the FRITZ!Box.
Optional. The web service port. Defaults to 80.
Required. The user name to use for the login.
Required. The password to use for the login.
Optional. Timeout setting for communications in seconds. Defaults to 5 seconds (this assumes a fast response if both devices are in the same local network).
Optional. The default group to use for the device ports. Can be overridden by the device port specification (see below).
Optional. The default log verbosity to use for the device ports. Can be overridden by the device port specification (see below).
Devices are specified in device nodes. Suppose a FritzBoxPlugin instance is defined like this:
[FritzBox1] Type = Plugin Driver = FritzBoxPlugin ... more settings
The plugin assumes that its devices are to be configured in the
Devices sub-node. Devices (actors/sensors) are to be specified with their order of evaluation:
[FritzBox1.Devices] DECT200_1 = 1 DECT200_2 = 2
If the order number is negative the device will not be used.
Each actor/sensor specification requires a node on the same configuration level as the FritzBoxPlugin:
[DECT200_1] Type = FritzDECT200 AIN = ... QueryInterval = 30
Currently, only the type
FritzDECT200 is supported.
The (required) AIN setting specifies the Actor Identification Number of the device. It can be obtained from the FRITZ!Box's administration web site.
The query interval specifies the time between update queries in seconds. This setting affects all ports of the device. The default is 30 seconds.
A node of type FritzDECT200 defines up to four ports: a switch port (Digital), a power port (Dial), an energy port (Dial) and a temperature port. The switch port is defined in the
[DECT200_1_Switch] Type = DigitalPort
The power port is defined in the '_Power' node:
[DECT200_1_Power] Type = DialPort
The energy port is defined in the
[DECT200_1_Energy] Type = DialPort
The temperature port is defined in the
[DECT200_1_Energy] Type = DialPort
Note that these nodes are not configuration sub-sections (separated by a dot). The reason for this is that the names of these nodes will result in port IDs which should not contain special characters.
These ports will only be created if their configuration sections are present and contain a
Type setting. The
Type setting must be correct as specified above.
All ports are initialized with the
LogVerbosity settings inherited from the plugin main node. Individual
LogVerbosity specifications can override these settings. You can only configure the basic port settings for these ports. Other settings like
Minimum are defined by the plugin and cannot be changed.
The switch port reflects the current switch state of the FRITZ!DECT200. It can be used to switch the actor on and off.
Mode = Output Icon = powersocket
The power port contains the current power consumption measurement. It is measured in milliwatts (mW). As the FRITZ!DECT200 is rated for up to 2300 W its max value is 2300000. A power port is readonly by default.
Unit = electricPower_mW Icon = powermeter
The energy port reflects the total energy consumption since starting or resetting the DECT200. It is measured in watt hours (Wh). The max value is 2147483647. An energy port is readonly by default.
Unit = electricEnergy_Wh Icon = energymeter
[General] SlaveName = FritzBoxPlugin Example LogVerbosity = Verbose [Connection] Transport = TCP [Root] FritzBox1 = 1 WebServer = 9999 [FritzBox1] Type = Plugin Driver = FritzBoxPlugin RelativeTo = Config Host = fritz.box User = FritzBoxUser Password = FritzBoxPassword [FritzBox1.Devices] DECT200_1 = 1 [DECT200_1] Type = FritzDECT200 AIN = ... QueryInterval = 10 [DECT200_1_Switch] Type = DigitalPort [DECT200_1_Energy] Type = DialPort [DECT200_1_Power] Type = DialPort ; Not all devices may support the Temperature reading; ; this depends on the firmware version of the FRITZ!Box (>= FRITZ!OS 6.20) [DECT200_1_Temperature]
; Type = DialPort
; This node starts a web server at http://localhost:8080 [WebServer] Type = Plugin Driver = ../plugins/WebServerPlugin/WebServerPlugin Readonly = True