From a9145003b13f1416065c2e0b31f58152459fb1b7 Mon Sep 17 00:00:00 2001 From: Lionello Marrelli Date: Sat, 2 Jan 2021 22:19:23 +0100 Subject: [PATCH] [tr064] improve documentation and add textual config example (#9648) * Expanded descriptions and note on textual config Some paragraphs are expanded and some more info on the fritzbox subdevices are given. Channels are grouped by subdevice. Textual description with .items files is briefly described at the end but a clear warning on possible drawbacks is given and it is also clearly stated that it is discouraged. Signed-of-by: Lionello Marrelli --- bundles/org.openhab.binding.tr064/README.md | 144 ++++++++++++++------ 1 file changed, 104 insertions(+), 40 deletions(-) diff --git a/bundles/org.openhab.binding.tr064/README.md b/bundles/org.openhab.binding.tr064/README.md index 79e1c6103b435..2b201805653f7 100644 --- a/bundles/org.openhab.binding.tr064/README.md +++ b/bundles/org.openhab.binding.tr064/README.md @@ -1,15 +1,17 @@ # TR-064 Binding -This binding brings support for internet gateway devices that support the TR-064 protocol. +This binding brings support for internet gateway devices that support the TR-064 protocol (e.g. the AVM FritzBox family of routers). It can be used to gather information from the device and/or re-configure it. +Even though textual configuration is possible, it is strongly recommended to use the Main User Interface for configuration. ## Supported Things -Four thing types are supported: - +Two Bridge things are supported: - `generic`: the internet gateway device itself (generic device) -- `fritzbox`: similar to `generic` with extensions for AVM FritzBox devices -- `subDevice`: a sub-device of a `rootDevice` (e.g. a WAN interface) +- `fritzbox`: similar to `generic` with extensions for AVM FritzBox devices. + +Two kind of Things are supported: +- `subDevice`: a sub-device of the Bridge thing (e.g. a WAN interface) - `subDeviceLan`: a special type of sub-device that supports MAC-detection ## Discovery @@ -35,48 +37,99 @@ For security reasons it is highly recommended to set both, username and password ### `fritzbox` -All additional parameters for `fritzbox` devices (i.e. except those that are shared with `generic`) are advanced parameters. +The `fritzbox` devices can give additional informations in dedicated channels, controlled + by additional parameters (visible if Show Advanced is selected), w.r.t. to `generic` devices. +If the parameters are specified, the corresponding channels will be added to the device. -One or more TAM (telephone answering machines) are supported by most devices. -By setting the `tamIndices` parameter you can instruct the binding to add channels for these devices to the thing. +One or more TAM (telephone answering machines) are supported by most fritzbox devices. +By setting the `tamIndices` parameter you can instruct the binding to add channels for these + devices to the thing. Values start with `0`. -This is an optional parameter and multiple values are allowed. +This is an optional parameter and multiple values are allowed: add one value per line in the Main User Interface. Most devices allow to configure call deflections. If the `callDeflectionIndices` parameter is set, channels for the status of the pre-configured call deflections are added. Values start with `0`, including the number of "Call Blocks" (two configured call-blocks -> first deflection is `2`). -This is an optional parameter and multiple values are allowed. +This is an optional parameter and multiple values are allowed: add one value per line in the Main User Interface. Most devices support call lists. -The binding can analyze these call lists and provide channels for the number of missed calls, inbound calls, outbound calls and rejected (blocked) calls. -The days for which this analysis takes place can be controlled with the `missedCallDays`, `rejectedCallDays`, `inboundCallDays`, `outboundCallDays` and `callListDays`. -This is an optional parameter and multiple values are allowed. +The binding can retrieve these call lists and provide channels for the number of missed calls, inbound calls, outbound calls and rejected (blocked) calls, +for a given number of days. A channel is added to the Thing if such a number is set through the corresponding parameter +in the Main User Interface. +The parameters are: `missedCallDays`, `rejectedCallDays`, `inboundCallDays`, `outboundCallDays` and `callListDays`. Since FritzOS! 7.20 WAN access of local devices can be controlled by their IPs. If the `wanBlockIPs` parameter is set, a channel for each IP is created to block/unblock WAN access for this IP. Values need to be IPv4 addresses in the format `a.b.c.d`. -This is an optional parameter and multiple values are allowed. +This is an optional parameter and multiple values are allowed: add one value per line in the Main User Interface. If the `PHONEBOOK` profile shall be used, it is necessary to retrieve the phonebooks from the FritzBox. -The `phonebookInterval` is uses to set the refresh cycle for phonebooks. +The `phonebookInterval` is uses to set the refresh cycle for phonebooks. It defaults to 600 seconds, +and it can be set to 0 if phoneooks are not to be used. + ### `subdevice`, `subdeviceLan` -Besides the bridge that the thing is attached to, sub-devices have a `uuid` parameter. -This is the UUID/UDN of the device and a mandatory parameter. -Since the value can only be determined by examining the SCPD of the root device, the simplest way to get hold of them is through auto-discovery. +Additional informations (i.e. channels) are available in subdevices of the bridge. +Each subdevice is characterized by a unique `uuid` parameter: this is the UUID/UDN of the device. +This is a mandatory parameter to be set in order to add the subdevice. Since the parameter value can only be determined +by examining the SCPD of the root device, the simplest way to obtain it is through auto-discovery. + +Auto discovery may find several sub-devices, each one holding channels as described in the following. -For `subdeviceLan` devices (type is detected automatically during discovery) the parameter `macOnline` can be defined. -It adds a channel for each MAC (format 11:11:11:11:11:11) that shows the online status of the respective device. -This is an optional parameter and multiple values are allowed. +The LAN sub-device, in particular, is also used for presence detection. +It therefore optionally contains +a channel for each MAC address (in a format 11:11:11:11:11:11, different than the old v1 version of this binding), +defined by the parameter `macOnline`. +This is an optional parameter and multiple values are allowed: add one value per line in the Main User Interface. ## Channels +Channels are grouped according to the subdevice they belong to. + +### fritzbox Bridge channels + +Advanced channels appear only if the corresponding parameters are set in the Thing definition. + | channel | item-type | advanced | description | |----------------------------|---------------------------|:--------:|----------------------------------------------------------------| -| `callDeflectionEnable` | `Switch` | | Enable/Disable the call deflection setup with the given index. | +| `callDeflectionEnable` | `Switch` | x | Enable/Disable the call deflection setup with the given index. | | `callList` | `String` | x | A string containing the call list as JSON (see below) | | `deviceLog` | `String` | x | A string containing the last log messages | +| `missedCalls` | `Number` | | Number of missed calls within the given number of days. | +| `outboundCalls` | `Number` | x | Number of outbound calls within the given number of days. | +| `inboundCalls` | `Number` | x | Number of inbound calls within the given number of days. | +| `reboot` | `Switch` | | Reboot | +| `rejectedCalls` | `Number` | x | Number of rejected calls within the given number of days. | +| `securityPort` | `Number` | x | The port for connecting via HTTPS to the TR-064 service. | +| `tamEnable` | `Switch` | x | Enable/Disable the answering machine with the given index. | +| `tamNewMessages` | `Number` | x | The number of new messages of the given answering machine. | +| `uptime` | `Number:Time` | | Uptime of the device | + +### LAN subdeviceLan channels + +| channel | item-type | advanced | description | +|----------------------------|---------------------------|:--------:|----------------------------------------------------------------| +| `wifi24GHzEnable` | `Switch` | | Enable/Disable the 2.4 GHz WiFi device. | +| `wifi5GHzEnable` | `Switch` | | Enable/Disable the 5.0 GHz WiFi device. | +| `wifiGuestEnable` | `Switch` | | Enable/Disable the guest WiFi. | +| `macOnline` | `Switch` | x | Online status of the device with the given MAC | + +### WANConnection subdevice channels + +| channel | item-type | advanced | description | +|----------------------------|---------------------------|:--------:|----------------------------------------------------------------| +| `Uptime` | `Number:Time` | | Uptime | +| `pppUptime` | `Number:Time` | | Uptime (if using PPP) | +| `wanConnectionStatus` | `String` | | Connection Status | +| `wanPppConnectionStatus` | `String` | | Connection Status (if using PPP) | +| `wanIpAddress` | `String` | x | WAN IP Address | +| `wanPppIpAddress` | `String` | x | WAN IP Address (if using PPP) | + +### WAN subdevice channels + +| channel | item-type | advanced | description | +|----------------------------|---------------------------|:--------:|----------------------------------------------------------------| | `dslCRCErrors` | `Number:Dimensionless` | x | DSL CRC Errors | | `dslDownstreamMaxRate` | `Number:DataTransferRate` | x | DSL Max Downstream Rate | | `dslDownstreamCurrRate` | `Number:DataTransferRate` | x | DSL Curr. Downstream Rate | @@ -90,30 +143,13 @@ This is an optional parameter and multiple values are allowed. | `dslUpstreamCurrRate` | `Number:DataTransferRate` | x | DSL Curr. Upstream Rate | | `dslUpstreamNoiseMargin` | `Number:Dimensionless` | x | DSL Upstream Noise Margin | | `dslUpstreamAttenuation` | `Number:Dimensionless` | x | DSL Upstream Attenuation | -| `inboundCalls` | `Number` | x | Number of inbound calls within the given number of days. | -| `macOnline` | `Switch` | x | Online status of the device with the given MAC | -| `missedCalls` | `Number` | | Number of missed calls within the given number of days. | -| `outboundCalls` | `Number` | x | Number of outbound calls within the given number of days. | -| `reboot` | `Switch` | | Reboot | -| `rejectedCalls` | `Number` | x | Number of rejected calls within the given number of days. | -| `securityPort` | `Number` | x | The port for connecting via HTTPS to the TR-064 service. | -| `tamEnable` | `Switch` | | Enable/Disable the answering machine with the given index. | -| `tamNewMessages` | `Number` | | The number of new messages of the given answering machine. | -| `uptime` | `Number:Time` | | Uptime | -| `pppUptime` | `Number:Time` | | Uptime (if using PPP) | | `wanAccessType` | `String` | x | Access Type | -| `wanConnectionStatus` | `String` | | Connection Status | -| `wanPppConnectionStatus` | `String` | | Connection Status (if using PPP) | -| `wanIpAddress` | `String` | x | WAN IP Address | -| `wanPppIpAddress` | `String` | x | WAN IP Address (if using PPP) | | `wanMaxDownstreamRate` | `Number:DataTransferRate` | x | Max. Downstream Rate | | `wanMaxUpstreamRate` | `Number:DataTransferRate` | x | Max. Upstream Rate | | `wanPhysicalLinkStatus` | `String` | x | Link Status | | `wanTotalBytesReceived` | `Number:DataAmount` | x | Total Bytes Received | | `wanTotalBytesSent` | `Number:DataAmount` | x | Total Bytes Sent | -| `wifi24GHzEnable` | `Switch` | | Enable/Disable the 2.4 GHz WiFi device. | -| `wifi5GHzEnable` | `Switch` | | Enable/Disable the 5.0 GHz WiFi device. | -| `wifiGuestEnable` | `Switch` | | Enable/Disable the guest WiFi. | + ### Channel `callList` @@ -151,3 +187,31 @@ Example (use all phonebooks, match 5 digits from right): val tr064Actions = getActions("tr064","tr064:fritzbox:2a28aee1ee") val result = tr064Actions.phonebookLookup("49157712341234", 5) ``` +## A note on textual configuration + +Textual configuration through a `.things` file is possible but, at present, strongly discouraged because it is significantly more error-prone +than the configuration through Main User Interface. + +If an advanced user is really motivated to define a textual configuration, it is suggested to perform +an automatic scan through the user interface first in order to extract the required parameters (namely the different `uuid` of the +needed subdevices). + +The definition of the bridge and of the subdevices things is the following +``` +Bridge tr064:fritzbox:rootuid "Root label" @ "location" [ host="192.168.1.1", user="user", password="passwd", + phonebookInterval="0"]{ + Thing subdeviceLan LAN "label LAN" [ uuid="uuid:xxxxxxxx-xxxx-xxxx-yyyy-xxxxxxxxxxxx", + macOnline="XX:XX:XX:XX:XX:XX", + "YY:YY:YY:YY:YY:YY"] + Thing subdeviceLan WAN "label WAN" [ uuid="uuid:xxxxxxxx-xxxx-xxxx-zzzz-xxxxxxxxxxxx"] + Thing subdeviceLan WANCon "label WANConnection" [ uuid="uuid:xxxxxxxx-xxxx-xxxx-wwww-xxxxxxxxxxxx"] + } +``` + +The channel are automatically generated and it is simpler to use the Main User Interface to copy the textual definition of the channel + +``` +Switch PresXX "[%s]" {channel="tr064:subdeviceLan:rootuid:LAN:macOnline_XX_3AXX_3AXX_3AXX_3AXX_3AXX"} +Switch PresYY "[%s]" {channel="tr064:subdeviceLan:rootuid:LAN:macOnline_YY_3AYY_3AYY_3AYY_3AYY_3AYY"} + +```