Skip to content

Commit

Permalink
[tr064] improve documentation and add textual config example (openhab…
Browse files Browse the repository at this point in the history 
…#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 <[email protected]>
  • Loading branch information
@lionhe1966 @thinkingstone
lionhe1966 authored and thinkingstone committed Nov 7, 2021
1 parent 17e1a8c commit a914500
Showing 1 changed file with 104 additions and 40 deletions.
144 changes: 104 additions & 40 deletions bundles/org.openhab.binding.tr064/README.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 |
Expand All @@ -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`

Expand Down Expand Up @@ -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"}
```

0 comments on commit a914500

Please sign in to comment.