public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Documentation] Markdown improvements f to m (#13866)

Browse Source 
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
2022-12-08 21:36:05 +01:00
committed by GitHub
parent 3c236b3103
commit 0e68936663
122 changed files with 3490 additions and 3662 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
bundles/org.openhab.binding.knx/README.md
View File

@@ -13,7 +13,7 @@ Since the protocol is identical, the KNX binding can also communicate with it tr
## Supported Things
The KNX binding supports two types of bridges, and one type of things to access the KNX bus.
There is an *ip* bridge to connect to KNX IP Gateways, and a *serial* bridge for connection over a serial port to a host-attached gateway.
There is an _ip_ bridge to connect to KNX IP Gateways, and a _serial_ bridge for connection over a serial port to a host-attached gateway.
## Binding Configuration
@@ -25,7 +25,7 @@ The following two bridge types are supported. Bridges don't have channels on the
### IP Gateway
The IP Gateway is the most commonly used way to connect to the KNX bus. At its base, the *ip* bridge accepts the following configuration parameters:
The IP Gateway is the most commonly used way to connect to the KNX bus. At its base, the _ip_ bridge accepts the following configuration parameters:
| Name | Required | Description | Default value |
|---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
@@ -44,10 +44,9 @@ The IP Gateway is the most commonly used way to connect to the KNX bus. At its b
| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
### Serial Gateway
The *serial* bridge accepts the following configuration parameters:
The _serial_ bridge accepts the following configuration parameters:
| Name | Required | Description | Default value |
|---------------------|----------|--------------------------------------------------------------------------------------------------------------|---------------|
@@ -60,13 +59,13 @@ The *serial* bridge accepts the following configuration parameters:
## Things
### *device* Things
### _device_ Things
*basic* Things are wrappers around arbitrary group addresses on the KNX bus.
They have no specific function in the KNX binding, except that if the *address* is defined, the binding will actively poll the Individual Address on the KNX bus to detect that the KNX actuator is reachable.
_basic_ Things are wrappers around arbitrary group addresses on the KNX bus.
They have no specific function in the KNX binding, except that if the _address_ is defined, the binding will actively poll the Individual Address on the KNX bus to detect that the KNX actuator is reachable.
Under normal real-world circumstances, either all devices on a bus are reachable, or the entire bus is down.
If line couplers are installed, physical device addressing might be filtered; in this case please do not specify the addresses for devices on this line.
When *fetch* is set to true, the binding will read-out the memory of the KNX actuator in order to detect configuration data and so forth.
When _fetch_ is set to true, the binding will read-out the memory of the KNX actuator in order to detect configuration data and so forth.
This is however an experimental feature, very prone to the actual on the KNX bus.
| Name | Required | Description | Default value |
@@ -77,7 +76,7 @@ This is however an experimental feature, very prone to the actual on the KNX bus
| readInterval | N | Interval (in seconds) to actively request reading of values from the bus (0 if they should only be read once at startup) | 0 |
Different kinds of channels are defined and can be used to group together Group Addresses.
All channels of a device share one configuration parameter defined on device level: *readInterval*, an optional parameter which indicates if 'readable' group addresses of that Channel should be read periodically at the given interval, in seconds.
All channels of a device share one configuration parameter defined on device level: _readInterval_, an optional parameter which indicates if 'readable' group addresses of that Channel should be read periodically at the given interval, in seconds.
'Readable' group addresses are marked with an `<` in the group address definition of a Channel, see below.
All readable group addresses are queried by openHAB during startup.
If readInterval is not specified or set to 0, no further periodic reading will be triggered (default: 0).
@@ -95,7 +94,6 @@ Note: After changing the DPT of already existing Channels, openHAB needs to be r
|-----------|-------------------------------------|-------------|
| ga | Group address for the binary switch | 1.001 |
##### Channel Type "dimmer"
| Parameter | Description | Default DPT |
@@ -124,7 +122,6 @@ Note: After changing the DPT of already existing Channels, openHAB needs to be r
|-----------|---------------|-------------|
| ga | Group address | 9.001 |
Note: Using the Units Of Measurement feature of openHAB (Quantitytype) requires that the DPT value is set correctly.
Automatic type conversion will be applied if required.
@@ -140,7 +137,6 @@ Automatic type conversion will be applied if required.
|-----------|---------------|-------------|
| ga | Group address | 19.001 |
#### Control Channel Types
In contrast to the standard channels above, the control channel types are used for cases where the KNX bus does not own the physical state of a device.
@@ -153,7 +149,6 @@ If from the KNX bus a `GroupValueRead` telegram is sent to a *-control Channel,
|-----------|-------------------------------------|-------------|
| ga | Group address for the binary switch | 1.001 |
##### Channel Type "dimmer-control"
| Parameter | Description | Default DPT |
@@ -197,7 +192,7 @@ If from the KNX bus a `GroupValueRead` telegram is sent to a *-control Channel,
#### Group Address Notation
```
```text
<config>="[<dpt>:][<]<mainGA>[[+[<]<listeningGA>][+[<]<listeningGA>..]]"
```
@@ -211,7 +206,6 @@ Each configuration parameter has a `mainGA` where commands are written to and op
The `dpt` element is optional. If omitted, the corresponding default value will be used (see the channel descriptions above).
## KNX Secure
> NOTE: Support for KNX Secure is partly implemented for openHAB and should be considered as experimental.
@@ -221,12 +215,12 @@ The `dpt` element is optional. If omitted, the corresponding default value will
KNX IP Secure protects the traffic between openHAB and your KNX installation.
It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installation **with security features enabled in ETS tool**.
For *Secure routing* mode, the so called `backbone key` needs to be configured in openHAB.
For _Secure routing_ mode, the so called `backbone key` needs to be configured in openHAB.
It is created by the ETS tool and cannot be changed via the ETS user interface.
- The backbone key can be extracted from Security report (ETS, Reports, Security, look for a 32-digit key) and specified in parameter `routerBackboneKey`.
For *Secure tunneling* with a Secure IP Interface (or a router in tunneling mode), more parameters are required.
For _Secure tunneling_ with a Secure IP Interface (or a router in tunneling mode), more parameters are required.
A unique device authentication key, and a specific tunnel identifier and password need to be available.
- All information can be looked up in ETS and provided separately: `tunnelDeviceAuthentication`, `tunnelUserPassword`.
@@ -240,7 +234,6 @@ Data Secure does _not_ necessarily require a KNX Secure Router or a Secure IP In
> NOTE: **openHAB currently ignores messages with secure group addresses.**
## Examples
The following two templates are sufficient for almost all purposes.
@@ -250,7 +243,7 @@ Only add parameters to the Bridge and Thing configuration if you know exactly wh
knx.things:
```xtend
```java
Bridge knx:ip:bridge [
type="ROUTER",
autoReconnectPeriod=60 //optional, do not set <30 sec.
@@ -267,7 +260,7 @@ Bridge knx:ip:bridge [
knx.things:
```xtend
```java
Bridge knx:ip:bridge [
type="TUNNEL",
ipAddress="192.168.0.111",
@@ -283,7 +276,7 @@ Bridge knx:ip:bridge [
### Full Example
```xtend
```java
//TUNNEL
Bridge knx:ip:bridge [
type="TUNNEL",
@@ -328,7 +321,7 @@ Bridge knx:ip:bridge [
knx.items:
```xtend
```java
Switch demoSwitch "Light [%s]" <light> { channel="knx:device:bridge:generic:demoSwitch" }
Dimmer demoDimmer "Dimmer [%d %%]" <light> { channel="knx:device:bridge:generic:demoDimmer" }
Rollershutter demoRollershutter "Shade [%d %%]" <rollershutter> { channel="knx:device:bridge:generic:demoRollershutter" }
@@ -340,7 +333,7 @@ DateTime demoDatetime "Alarm [%1$tH:%1$tM]" { c
knx.sitemap:
```xtend
```perl
sitemap knx label="KNX Demo Sitemap" {
Frame label="Demo Elements" {
Switch item=demoSwitch
@@ -359,7 +352,7 @@ sitemap knx label="KNX Demo Sitemap" {
control.things:
```xtend
```java
Bridge knx:serial:bridge [
serialPort="/dev/ttyAMA0",
readingPause=50,
@@ -387,7 +380,7 @@ Bridge hue:bridge:bridge "Philips Hue Bridge" [
knx.items:
```xtend
```java
Switch demoSwitch "Light [%s]" <light> { channel="hue:0210:bridge:1:color", channel="knx:device:bridge:generic:controlSwitch" }
Dimmer demoDimmer "Dimmer [%d %%]" <light> { channel="hue:0210:bridge:1:color", channel="knx:device:bridge:generic:controlDimmer" }
```