[knx] Improve labels and documentation for parameter readInterval (#12992)

Clarify handling of initial read and readInterval in documentation.
Updated labels to distinguish readInterval and pollInterval.
Fixes #12921.

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

bundles/org.openhab.binding.knx/README.md

@@ -61,6 +61,7 @@ The *serial* bridge accepts the following configuration parameters:
 *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.
 This is however an experimental feature, very prone to the actual on the KNX bus.
 
@@ -72,8 +73,10 @@ 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 channel types share two configuration parameters: *read*, an optional parameter to indicate if the 'readable' group addresses of that Channel should be read at startup (default: false), and *interval*, an optional parameter that defines an interval between attempts to read the status group address on the bus, in seconds.
-When defined and set to 0, the interval is ignored (default: 0)
+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).
 
 #### Standard Channel Types
 
@@ -197,6 +200,7 @@ If from the KNX bus a `GroupValueRead` telegram is sent to a *-control Channel,
 where parts in brackets `[]` denote optional information.
 
 The optional `<` sign tells whether the group address of the datapoint accepts read requests on the KNX bus (it does, if the sign is there).
+All group addresses marked with `<` are read by openHAB during startup.
 With `*-control` channels, the state is not owned by any device on the KNX bus, therefore no read requests will be sent by the binding, i.e. `<` signs will be ignored for them.
 
 Each configuration parameter has a `mainGA` where commands are written to and optionally several `listeningGA`s.

bundles/org.openhab.binding.knx/src/main/resources/OH-INF/i18n/knx.properties

@@ -18,9 +18,9 @@ thing-type.config.knx.device.address.label = Address
 thing-type.config.knx.device.address.description = The individual address in x.y.z notation
 thing-type.config.knx.device.fetch.label = Fetch
 thing-type.config.knx.device.fetch.description = Read out the device parameters and address/communication object tables
-thing-type.config.knx.device.pingInterval.label = Interval
+thing-type.config.knx.device.pingInterval.label = Ping Interval
 thing-type.config.knx.device.pingInterval.description = Interval (in seconds) between attempts to poll the device status
-thing-type.config.knx.device.readInterval.label = Interval
+thing-type.config.knx.device.readInterval.label = Read Interval
 thing-type.config.knx.device.readInterval.description = Interval (in seconds) between attempts to read the status group addresses on the bus
 thing-type.config.knx.ip.autoReconnectPeriod.label = Auto Reconnect Period
 thing-type.config.knx.ip.autoReconnectPeriod.description = Seconds between connection retries when KNX link has been lost, 0 means never retry, minimum 30s

bundles/org.openhab.binding.knx/src/main/resources/OH-INF/thing/device.xml

@@ -24,12 +24,12 @@
 				<default>false</default>
 			</parameter>
 			<parameter name="pingInterval" type="integer">
-				<label>Interval</label>
+				<label>Ping Interval</label>
 				<description>Interval (in seconds) between attempts to poll the device status</description>
 				<default>600</default>
 			</parameter>
 			<parameter name="readInterval" type="integer">
-				<label>Interval</label>
+				<label>Read Interval</label>
 				<description>Interval (in seconds) between attempts to read the status group addresses on the bus</description>
 				<default>0</default>
 			</parameter>