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

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

View File

@@ -21,7 +21,7 @@ This binding uses TCP/IP to access the LCN bus via the software LCN-PCHK (Window
### Thing: LCN Module
Any LCN module that should be controlled or visualized, need to be added to openHAB as a *Thing*.
Any LCN module that should be controlled or visualized, need to be added to openHAB as a _Thing_.
LCN modules with firmware versions 120612 (2008), 170602 (2013) and 1F080A (2021) were tested with this binding.
Modules with older and newer firmware should work, too.
@@ -40,9 +40,9 @@ See [Discover LCN Modules](#discover-lcn-modules).
### Bridge: LCN PCK Gateway
PCK is the protocol spoken over TCP/IP with a PCK gateway to communicate with the LCN bus.
Examples for PCK gateways are the *LCN-PCHK* software running on Windows or Linux and the DIN rail mounting device *LCN-VISU*.
Examples for PCK gateways are the _LCN-PCHK_ software running on Windows or Linux and the DIN rail mounting device _LCN-VISU_.
For each LCN bus, interfaced to openHAB, a PCK gateway needs to be added to openHAB as a *Thing*.
For each LCN bus, interfaced to openHAB, a PCK gateway needs to be added to openHAB as a _Thing_.
Several PCK gateways can be added to openHAB to control multiple LCN busses in distinct locations.
@@ -72,12 +72,12 @@ Please see the following LCN-PRO screenshot to determine the dimmer output resol
### Thing: LCN Group
LCN modules can be assigned to groups with the programming software *LCN-PRO*.
LCN modules can be assigned to groups with the programming software _LCN-PRO_.
To send commands to an LCN group, the group needs to be added to openHAB as a *Thing*.
To send commands to an LCN group, the group needs to be added to openHAB as a _Thing_.
One LCN module within the group is used to represent the status of the whole group.
For example, when a Dimmer Output is controlled via a LCN group *Thing*, openHAB will always visualize the state of the Dimmer Output of the chosen module. The states of the other modules in the group are ignored for visualization.
For example, when a Dimmer Output is controlled via a LCN group _Thing_, openHAB will always visualize the state of the Dimmer Output of the chosen module. The states of the other modules in the group are ignored for visualization.
Thing Type ID: `group`
@@ -87,7 +87,7 @@ Thing Type ID: `group`
| `moduleId` | The module ID of any module in the group. The state of this module is used for visualization of the group as representative for all modules. | Integer | Yes |
| `segmentId` | The segment ID of all modules in this group (0 if no segments are present) | Integer | Yes |
The `groupId` must match the previously configured group number in the programming software *LCN-PRO*.
The `groupId` must match the previously configured group number in the programming software _LCN-PRO_.
## Discovery
@@ -97,7 +97,7 @@ Basic data like the names of all LCN modules in the bus, can be read out by open
If not all LCN modules get listed on the first run, click on the refresh button to start another scan.
When adding a module by discovery, the new *Thing*'s UID will be a combination of segment and module id using the following format:
When adding a module by discovery, the new _Thing_'s UID will be a combination of segment and module id using the following format:
`S<segmentId>M<moduleId>` where `segmentId` and `moduleId` are formatted as three-digit numbers with leading zeros.
### Discover PCK Gateways
@@ -106,8 +106,8 @@ PCK gateways in the LAN can be found automatically by openHAB. This is done by U
The discovery works only if the firewall of the PCK gateway is not configured too strictly.
This means on Windows PCs, that the network must be configured as 'private' and not as 'public'.
Also, some network switches may block multicast packets.
Unfortunately, *LCN-PCHK* listens only on the first network interface of the computer for discovery packets.
If your PCK gateway has multiple network interfaces, *LCN-PCHK* may listen on the wrong interface and fails to respond to the discovery request.
Unfortunately, _LCN-PCHK_ listens only on the first network interface of the computer for discovery packets.
If your PCK gateway has multiple network interfaces, _LCN-PCHK_ may listen on the wrong interface and fails to respond to the discovery request.
Discovery has successfully been tested with LCN-PCHK 3.2.2 running on a Raspberry Pi with Raspbian and openHAB running on Windows 10.
@@ -116,12 +116,12 @@ If discovery fails, you can add a PCK gateway manually. See [Thing: PCK Gateway]
Please be aware that you **have to configure** username, password and the dimmer output resolution also if you use discovery.
See [Thing: PCK Gateway](#bridge-lcn-pck-gateway).
When adding a PCK gateway by discovery, the new *Thing*'s UID is the MAC address of the device, running the PCK gateway.
When adding a PCK gateway by discovery, the new _Thing_'s UID is the MAC address of the device, running the PCK gateway.
## Supported LCN Features and openHAB Channels
The following table lists all features of LCN and their mappings to openHAB Channels.
These Channels are available for the *Thing* LCN module (`module`).
These Channels are available for the _Thing_ LCN module (`module`).
LCN group (`group`) has the same Channels, except status-only Channels like binary sensors or transponders.
The PCK gateway (`pckGateway`) has no Channels.
@@ -162,7 +162,7 @@ If a special command is needed, the [Hit Key](#hit-key) action (German: "Sende T
| Remote Control | Fernbedienung | code#remotecontrolkey | | Trigger | Receive commands from remote control |
| Access Control | Zutrittskontrolle | code#remotecontrolcode | | Trigger | Receive serial numbers from remote control |
| Remote Control Battery Low | Fernbedienung Batterie schwach | code#remotecontrolbatterylow | | Trigger | Triggered when the sending remote control has a low battery |
| Host Command (Send Keys) | Kommando an Host (Sende Tasten) | hostcommand#sendKeys | - | Trigger | Receive *send keys* command from LCN module |
| Host Command (Send Keys) | Kommando an Host (Sende Tasten) | hostcommand#sendKeys | - | Trigger | Receive _send keys_ command from LCN module |
| Operating Hours Counter Outputs | Betriebsstundenzähler Ausgänge | operatinghourscounter | output[1-4] | Number:Time | Visualize Operating Hours Counter for outputs |
| Operating Hours Counter Outputs (rel. Work) | Betriebsstundenzähler Ausgänge (rel. Arbeit) | operatinghourscounter | outputrelativework[1-4] | Number:Time | Visualize Operating Hours Counter for outputs (relative work) |
| Operating Hours Counter Relays | Betriebsstundenzähler Relais | operatinghourscounter | relay[1-8] | Number:Time | Visualize Operating Hours Counter for relays |
@@ -194,9 +194,9 @@ If a special command is needed, the [Hit Key](#hit-key) action (German: "Sende T
| Set S0 Counters | S0-Zähler setzen | - | - | - | Not implemented |
| Status Command | Statuskommandos | - | - | - | Not implemented |
*Notes:*
_Notes:_
- **For some *Channel*s (e.g. temperature) a unit should be configured in the channel configuration.** By default the native LCN value is used.
- **For some _Channel_s (e.g. temperature) a unit should be configured in the channel configuration.** By default the native LCN value is used.
- S0 counter Channels need to be the pulses per kWh configured. If the value is left blank, a default value of 1000 pulses/kWh is set.
- When setting a variable via openHAB, the variable must be configured as counter in LCN-PRO. The variable must be set initially by the module after power up.
- The Rollershutter Channels provide the boolean parameter `invertUpDown`, which can be set to 'true' if the Up/Down wires are interchanged.
@@ -205,11 +205,11 @@ If a special command is needed, the [Hit Key](#hit-key) action (German: "Sende T
### Transponder/Fingerprints
LCN transponder readers or fingerprint readers can be integrated in openHAB e.g. for access control.
The transponder function must be enabled in the module's I-port properties within *LCN-PRO*.
The transponder function must be enabled in the module's I-port properties within _LCN-PRO_.
Example: When the transponder card with the ID "12ABCD" is seen by the reader connected to LCN module "S000M011", the item "M10_Relay7" is switched on:
```
```java
rule "My Transponder"
when
Channel "lcn:module:b827ebfea4bb:S000M011:code#transponder" triggered "12ABCD"
@@ -220,7 +220,7 @@ end
Example: When fingerprint with ID "AFFE12" is seen by reader connected to LCN module "S000M011", the item "M10_Relay7" is switched on:
```
```java
rule "My Fingerprint"
when
Channel "lcn:module:b827ebfea4bb:S000M011:code#fingerprint" triggered "AFFE12"
@@ -233,18 +233,18 @@ end
LCN modules can send commands to openHAB, e.g. by pressing a physical LCN key.
The command must be programmed into the LCN module by the programming software LCN-PRO.
Only the *send keys* command (German: "Sende Tasten") is supported.
Only the _send keys_ command (German: "Sende Tasten") is supported.
Program a command to a key of an LCN module via LCN-PRO.
When LCN-PRO asks you for the target address, don't select any module, but manually enter the PCK host ID, configured within PCHK (default: 4).
Select the *send keys* command and "A-C (former command)", as PCHK 3.2.2 only supports the old command.
Select the _send keys_ command and "A-C (former command)", as PCHK 3.2.2 only supports the old command.
Then, select any key(s) you want to send to openHAB. These can be freely chosen, as they are only evaluated by openHAB.
![Screenshot, showing the send keys command](doc/host_command_send_keys.png)
The following rule can be used to trigger any action:
```
```java
rule "Module 12 sent A1 Hit"
when
Channel "lcn:module:b827ebfea4bb:S000M012:hostcommand#sendKeys" triggered "A1:HIT"
@@ -253,7 +253,7 @@ then
end
```
`A1` is the key of the *send keys* command, programmed by LCN-PRO.
`A1` is the key of the _send keys_ command, programmed by LCN-PRO.
After the colon, the LCN "hit type" follows: HIT, MAKE or BREAK (German: kurz, lang, los)
If multiple keys or key tables are programmed in a single "send keys" command, multiple triggers will be executed.
@@ -264,15 +264,15 @@ Simply press the physical button at the module for testing.
### Remote Control
To evaluate commands from LCN remote controls (e.g. LCN-RT or LCN-RT16), the module's I-port behavior must be configured as "IR access control" within *LCN-PRO*:
To evaluate commands from LCN remote controls (e.g. LCN-RT or LCN-RT16), the module's I-port behavior must be configured as "IR access control" within _LCN-PRO_:
![Screenshot, showing the I-port properties for remote controls](doc/ir.png)
#### Remote Control Keys
The trigger *Channel* `lcn:module:<pckThing>:<moduleThing>:code#remotecontrolkey` can be used to execute commands, when a specific key on a remote control is pressed:
The trigger _Channel_ `lcn:module:<pckThing>:<moduleThing>:code#remotecontrolkey` can be used to execute commands, when a specific key on a remote control is pressed:
```
```java
rule "Remote Control Key 3 on Layer 1 hit"
when
Channel "lcn:module:b827ebfea4bb:S000M012:code#remotecontrolkey" triggered "A3:HIT"
@@ -287,7 +287,7 @@ end
The serial number of a remote control can be used for access control via the channel `lcn:module:<pckThing>:<moduleThing>:code#remotecontrolcode`. See the following example:
```
```java
rule "Remote Control Key 3 on Layer 1 hit (only executed for serial number AB1234)"
when
Channel "lcn:module:b827ebfea4bb:S000M012:code#remotecontrolcode" triggered "AB1234:A3:HIT" or
@@ -301,24 +301,24 @@ The command will be executed when the remote control button A3 is either pressed
## Dimmer Outputs with Ramp and Multiple Outputs
The *output* profile can be used to control multiple dimmer outputs of the *same* module simultaneously or control a dimmer output with a ramp (slowly dimming).
The _output_ profile can be used to control multiple dimmer outputs of the _same_ module simultaneously or control a dimmer output with a ramp (slowly dimming).
The optional *ramp* parameter must be float or integer.
The optional _ramp_ parameter must be float or integer.
The lowest value is 0.25, which corresponds to 0.25s. The highest value is 486s.
When no *ramp* parameter is specified or no profile is configured, the ramp is 0 (behavior like a switch).
The ramp parameter is not available for Color *Item*s.
When no _ramp_ parameter is specified or no profile is configured, the ramp is 0 (behavior like a switch).
The ramp parameter is not available for Color _Item_s.
```
```java
// Dim output 2 in 0.25s
Switch M10_Output2 {channel="lcn:module:b827ebfea4bb:S000M010:output#2"[profile="lcn:output", ramp=0.25]} // with ramp of 0.25s (smallest value)
// Dim output 3 in 486s
Dimmer M10_Output3 {channel="lcn:module:b827ebfea4bb:S000M010:output#3"[profile="lcn:output", ramp=486]} // with ramp of 486s (biggest value)
```
The optional parameters *controlAllOutputs* and *controlOutputs12* can be used to control multiple outputs simultaneously.
Please note that the combination of these parameters with the *ramp* parameter is limited:
The optional parameters _controlAllOutputs_ and _controlOutputs12_ can be used to control multiple outputs simultaneously.
Please note that the combination of these parameters with the _ramp_ parameter is limited:
```
```java
// Control outputs 1+2 simultaneously. Status of Output 1 is visualized. Only ramps of 0s or 0.25s are supported.
Dimmer M10_Outputs12a {channel="lcn:module:b827ebfea4bb:S000M010:output#1"[profile="lcn:output", controlOutputs12=true]}
Dimmer M10_Outputs12b {channel="lcn:module:b827ebfea4bb:S000M010:output#1"[profile="lcn:output", controlOutputs12=true, ramp=0.25]}
@@ -334,20 +334,20 @@ Actions are special commands that can be sent to LCN modules or LCN groups.
### Hit Key
This *Action* virtually hits a key of a key table in an LCN module.
This _Action_ virtually hits a key of a key table in an LCN module.
Simply spoken, openHAB acts as a push button switch connected to an LCN module.
This *Action* can be used to execute commands which are not natively supported by this binding.
The function can be programmed via the software *LCN-PRO* onto a key in a module's key table.
Then, the programmed key can be "hit" by this *Action* and the command will be executed.
This _Action_ can be used to execute commands which are not natively supported by this binding.
The function can be programmed via the software _LCN-PRO_ onto a key in a module's key table.
Then, the programmed key can be "hit" by this _Action_ and the command will be executed.
When programming a "Hit Key" *Action*, the following parameters need to be set:
When programming a "Hit Key" _Action_, the following parameters need to be set:
*table* - The module's key table: A, B, C or D<br />
*key* - The number of the key within the key table: 1-8<br />
*action* - The key's action: HIT (German: "kurz"), MAKE ("lang") or BREAK ("los")
_table_ - The module's key table: A, B, C or D<br />
_key_ - The number of the key within the key table: 1-8<br />
_action_ - The key's action: HIT (German: "kurz"), MAKE ("lang") or BREAK ("los")
```
```java
rule "Hit key C4 hourly"
when
Time cron "0 0 * * * ?"
@@ -359,20 +359,20 @@ end
### Dynamic Text
This *Action* can be used to send custom texts to an LCN-GTxD display.
To make this function work, the row of the display has to be configured to allow dynamic text within *LCN-PRO*:
This _Action_ can be used to send custom texts to an LCN-GTxD display.
To make this function work, the row of the display has to be configured to allow dynamic text within _LCN-PRO_:
![Screenshot of LCN-PRO, showing the dynamic text setting of an LCN-GT10D](doc/dyn_text.png)
When programming a "Dynamic Text" *Action*, the following parameters need to be set:
When programming a "Dynamic Text" _Action_, the following parameters need to be set:
*row* - The number of the row in the display: 1-4<br />
*text* - The text to be displayed (UTF-8)
_row_ - The number of the row in the display: 1-4<br />
_text_ - The text to be displayed (UTF-8)
The length of the text may not exceed 60 bytes of characters.
Bear in mind that unicode characters can take more than one byte (e.g. umlauts (äöü) take two bytes).
```
```java
rule "Send dynamic Text to GT10D hourly"
when
Time cron "0 0 * * * ?"
@@ -384,19 +384,19 @@ end
### Flicker Output
This *Action* realizes the LCN command "Output: Flicker" (German: "Ausgang: Flackern").
This _Action_ realizes the LCN command "Output: Flicker" (German: "Ausgang: Flackern").
The command let a dimmer output flash a given number of times. This feature can be used e.g. for alert signals or visual door bells.
When programming a "Flicker Output" *Action*, the following parameters need to be set:
When programming a "Flicker Output" _Action_, the following parameters need to be set:
*output* - The dimmer output number: 1-4<br />
*depth* - The depth of the flickering: 0-2 (0=25% 1=50% 2=100% Example: When the output is fully on (100%), and 0 is selected, flashes will dim from 100% to 75% and back)<br />
*ramp* - The duration/ramp of one flash: 0-2 (0=2sec 1=1sec 2=0.5sec)<br />
*count* - The number of flashes: 1-15
_output_ - The dimmer output number: 1-4<br />
_depth_ - The depth of the flickering: 0-2 (0=25% 1=50% 2=100% Example: When the output is fully on (100%), and 0 is selected, flashes will dim from 100% to 75% and back)<br />
_ramp_ - The duration/ramp of one flash: 0-2 (0=2sec 1=1sec 2=0.5sec)<br />
_count_ - The number of flashes: 1-15
This action has also effect, if the given output is off. The output will be dimmed from 0% to *depth* and back, then.
This action has also effect, if the given output is off. The output will be dimmed from 0% to _depth_ and back, then.
```
```java
rule "Flicker output 1 when window opens"
when
Item M10_BinarySensor5 changed to OPEN
@@ -409,15 +409,15 @@ end
### Relay Timer
This *Action* realizes the LCN commmand "Relay Timer" (German: "Relais-Timer").
This _Action_ realizes the LCN commmand "Relay Timer" (German: "Relais-Timer").
The command switches the given relay immediately to on and after a given time back to off.
When programming a "Relay Timer" *Action*, the following parameters need to be set:
When programming a "Relay Timer" _Action_, the following parameters need to be set:
*relayNumber* - The relay number: 1-8<br />
*duration* - Timer duration in milliseconds: 30-240.000 ms<br />
_relayNumber_ - The relay number: 1-8<br />
_duration_ - Timer duration in milliseconds: 30-240.000 ms<br />
```
```java
rule "Start relay timer for led driver when dummy switch changed"
when
Item Dummy_Switch changed
@@ -430,14 +430,14 @@ end
### Beep
This *Action* realizes the LCN commmand "audio" (German: "Piepen").
This _Action_ realizes the LCN commmand "audio" (German: "Piepen").
It lets the beeper connected to the LCN module beep.
When programming an "audio" *Action*, the following parameters can be set:
When programming an "audio" _Action_, the following parameters can be set:
*volume* - Sound volume in percent (if null, the previous volume will be used)<br />
*tonality* - The tonality as a String. You need to use quotes. See below.<br />
*count* - Number of beeps (max. 50)
_volume_ - Sound volume in percent (if null, the previous volume will be used)<br />
_tonality_ - The tonality as a String. You need to use quotes. See below.<br />
_count_ - Number of beeps (max. 50)
Tonalities:
@@ -451,7 +451,7 @@ Tonalities:
- "6"=error
- "7"=long
```
```java
rule "Beep when dummy switch changed"
when
Item Dummy_Switch changed
@@ -466,27 +466,27 @@ end
LCN segments are supported by this binding, but could not be tested, due to lack of hardware.
LEDs do not support the *OnOffCommand* and respectively the *Switch* Item type, because they have the additional states *BLINK* and *FLICKER*. They must be configured as *String* Item. When used in rules, the parameter must be of type string. Example: `M10_LED1.sendCommand("ON")`. Note the quotation marks.
LEDs do not support the _OnOffCommand_ and respectively the _Switch_ Item type, because they have the additional states _BLINK_ and _FLICKER_. They must be configured as _String_ Item. When used in rules, the parameter must be of type string. Example: `M10_LED1.sendCommand("ON")`. Note the quotation marks.
## Full Example
Config `.things`
```
```java
Bridge lcn:pckGateway:myPCHK [ hostname="192.168.123.123", port=4114, username="myUser", password="myPassword", mode="native200" ] {
Thing module M99 "M99 MyModule" [ moduleId=99, segmentId=0 ] {
Channels:
Thing module M99 "M99 MyModule" [ moduleId=99, segmentId=0 ] {
Channels:
Rollershutter : rollershutterrelay#1 "My twisted rollershutter relay" [ invertUpDown = true ]
Contact : binarysensor#6 [ invertState=true ]
Number : rvarsetpoint#1 [ unit="temperature" ]
Number : variable#3 [ unit="temperature" ]
}
Contact : binarysensor#6 [ invertState=true ]
Number : rvarsetpoint#1 [ unit="temperature" ]
Number : variable#3 [ unit="temperature" ]
}
}
```
Config `.items`
```
```java
// Dimmer Outputs
Dimmer M10_Output1 {channel="lcn:module:b827ebfea4bb:S000M010:output#1"}
Switch M10_Output2 {channel="lcn:module:b827ebfea4bb:S000M010:output#2"[profile="lcn:output", ramp=0.25]} // with ramp of 0.25s (smallest value)
@@ -560,7 +560,7 @@ Switch M10_KeyLockD5 {channel="lcn:module:b827ebfea4bb:S000M010:keylocktabled#5"
Config `.sitemap`
```
```perl
sitemap lcn label="My home automation" {
Frame label="Demo Items" {
// Dimmer Outputs