demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/danieldemus/openhab-addons synced 2026-07-31 13:34:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

Fix documentation, grammar, and spelling in bindings N (#19549)

Browse Source 
Signed-off-by: Leo Siepel <leosiepel@gmail.com>
This commit is contained in:
lsiepel
2025-12-25 16:41:53 +01:00
committed by GitHub
parent 67de44c1f9
commit 2fc036812e
43 changed files with 531 additions and 513 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bundles/org.openhab.binding.network/README.md
+18 -20
View File
@@ -13,7 +13,7 @@ The binding has the following configuration options:
- **allowDHCPlisten:** If devices leave and reenter a network, they usually request their last IPv4 address by using DHCP requests. By listening for those messages, the status update can be more "real-time" without having to wait for the next refresh cycle. Default is true.
- **arpPingToolPath:** If the ARP ping tool is not called `arping` and cannot be found in the PATH environment variable, the absolute path can be configured here. Default is `arping`.
- **cacheDeviceStateTimeInMS:** The result of a device presence detection is cached for a small amount of time. Set this time here in milliseconds. Be aware that no new pings will be issued within this time frame, even if explicitly requested. Default is 2000.
- **preferResponseTimeAsLatency:** If enabled, an attempt will be made to extract the latency from the output of the ping command. If no such latency value is found in the ping command output, the time to execute the ping command is used as fallback latency. If disabled, the time to execute the ping command is always used as latency value. This is disabled by default to be backwards-compatible and to not break statistics and monitoring which existed before this feature.
- **preferResponseTimeAsLatency:** If enabled, an attempt will be made to extract the latency from the output of the ping command. If no such latency value is found in the ping command output, the time to execute the ping command is used as a fallback latency. If disabled, the time to execute the ping command is always used as the latency value. This is disabled by default to be backwards-compatible and to not break statistics and monitoring which existed before this feature.
- **numberOfDiscoveryThreads:** Specifies the number of threads to be used during the discovery process. Increasing this value may speed up the discovery of devices on large networks but could also increase the load on the system. Default is `100`.
Create a `<openHAB-conf>/services/network.cfg` file and use the above options like this:
@@ -35,7 +35,7 @@ binding.network:numberOfDiscoveryThreads=100
## Discovery
Auto discovery can be used to scan the local network for **pingdevice** things by sending a ping to every IP on the network.
Some network tools will identify this as a network intruder alarm, therefore automatic background discovery is disabled and a manual scan needs to be issued.
Some network tools will identify this as a network intruder alarm; therefore, automatic background discovery is disabled and a manual scan needs to be issued.
Please note: things discovered by the network binding will be provided with a time to live (TTL) and will automatically disappear from the Inbox after 10 minutes.
@@ -56,10 +56,10 @@ Use the following options for a **network:pingdevice**:
- **timeout:** How long the ping will wait for an answer, in milliseconds. Default: `5000` (5 seconds).
- **refreshInterval:** How often the device will be checked, in milliseconds. Default: `60000` (one minute).
- **useIOSWakeUp:** When set to true, an additional port knock is performed before a ping. Default: `true`.
- **useArpPing:** When set to true if the presence detection is allowed to use arp ping.
- **useArpPing:** When set to true, the presence detection is allowed to use ARP ping.
This can speed up presence detection, but may lead to inaccurate ping latency measurements.
Switch off if you want to use this for ping latency monitoring. Default: `true`.
- **useIcmpPing:** When set to true if the presence detection is allowed to use icmp ping.
- **useIcmpPing:** When set to true, the presence detection is allowed to use ICMP ping.
When also using arp ping, the latency measurements will not be comparable.
Switch off if you rather want to use arp ping latency monitoring. Default: `true`.
- **networkInterfaceNames:** The network interface names used for communicating with the device.
@@ -74,10 +74,9 @@ Use the following options for a **network:speedtest**:
- **refreshInterval:** Interval between each test execution, in minutes. Default: `20`.
- **uploadSize:** Size of the file to be uploaded in bytes. Default: `1000000`.
- **url:** URL of the speed test server.
- **fileName:** Name of the file to download from test server.
- **url:** URL of the speed test server.- **fileName:** Name of the file to download from test server.
- **initialDelay:** Delay (in minutes) before starting the first speed test (can help avoid flooding your server at startup). Default: `5`.
- **maxTimeout:** Number of timeout events that can happend (reset when successful) before setting the thing offline. Default: `3`.
- **maxTimeout:** Number of timeout events that can happen (reset when successful) before setting the Thing offline. Default: `3`.
## Presence detection - Configure target device
@@ -93,14 +92,13 @@ Windows 10 must be configured to allow "Echo Request for ICMPv4" so that it can
Because mobile devices put themselves in a deep sleep mode after some inactivity, they do not react to normal ICMP pings.
Configure ARP ping to realize presence detection for those devices.
This only works if the devices have Wi-Fi enabled, have been configured to use the Wi-Fi network, and have the option "Disable Wi-Fi in standby" disabled (default).
Use DHCP listen for an almost immediate presence detection for phones and tablets when they (re)join the home Wi-Fi network.
This only works if the devices have Wi-Fi enabled, have been configured to use the Wi-Fi network, and have the option "Disable Wi-Fi in standby" disabled (default).Use DHCP listen for an almost immediate presence detection for phones and tablets when they (re)join the home Wi-Fi network.
### iPhones, iPads
Apple iOS devices are usually in a deep sleep mode and do not respond to ARP pings under all conditions, but to Bonjour service discovery messages (UDP port 5353).
Therefore, first a Bonjour message is sent, before the ARP presence detection is performed.
This is default behaviour of the binding, when needed this can be changed with the config parameter `useIOSWakeUp`.
Therefore, first a Bonjour message is sent before the ARP presence detection is performed.
This is default behaviour of the binding; when needed, this can be changed with the config parameter `useIOSWakeUp`.
### Use open TCP ports
@@ -126,7 +124,7 @@ Nmap done: 1 IP address (1 host up) scanned in 106.17 seconds
In this example, there are four suitable ports to use.
The port 554 (Windows network file sharing service) is open on most Windows PCs and Windows compatible Linux systems.
Port 1025 (MS RPC) is open on XBox systems. Port 548 (Apple Filing Protocol (AFP)) is open on macOS systems.
Port 1025 (MS RPC) is open on Xbox systems. Port 548 (Apple Filing Protocol (AFP)) is open on macOS systems.
Please don't forget to open the required ports in the system's firewall setup.
@@ -170,13 +168,13 @@ iptables -A PREROUTING -t mangle -p udp ! -s 127.0.0.1 --dport 67 -j TEE --gatew
iptables -A OUTPUT -t nat -p udp -s 127.0.0.1/32 --dport 67 -j DNAT --to 127.0.0.1:6767
```
Above iptables solutions to check _dhcp_state_ are not working when openHAB is started in Docker. Use another workaround
Above iptables solutions to check _dhcp_state_ are not working when openHAB is started in Docker. Use another workaround:
```shell
iptables -I PREROUTING -t nat -p udp --src 0.0.0.0 --dport 67 -j DNAT --to 0.0.0.0:6767
```
To verify PREROUTING list use below command
To verify PREROUTING list, use the following command:
```shell
iptables -L -n -t nat
@@ -186,11 +184,11 @@ iptables -L -n -t nat
Things support the following channels:
| Channel Type ID | Item Type | Description |
|-----------------|-------------|-------------------------------------------------------------------------------------------|
| online | Switch | This channel indicates whether a device is online |
| lastseen | DateTime | The last seen date/time of the device in question. May be 1. Jan 1970 if no time is known |
| latency | Number:Time | This channel indicates the ping latency. May be 0 if no time is known |
| Channel Type ID | Item Type | Description |
|-----------------|-------------|-----------------------------------------------------------------------------------------------|
| online | Switch | This channel indicates whether a device is online |
| lastseen | DateTime | The last seen date/time of the device in question. May be January 1, 1970 if no time is known |
| latency | Number:Time | This channel indicates the ping latency. May be 0 if no time is known |
## Examples
@@ -260,7 +258,7 @@ sitemap demo label="Main Menu"
## Rule Actions
A Wake-on-LAN action is supported by this binding for the `pingdevice` and `servicedevice` thing types.
A Wake-on-LAN action is supported by this binding for the `pingdevice` and `servicedevice` Thing types.
In classic rules this action is accessible as shown in the example below:
```java
bundles/org.openhab.binding.network/src/main/resources/OH-INF/i18n/network.properties
+15 -15
View File
@@ -40,9 +40,9 @@ thing-type.config.network.pingdevice.networkInterfaceNames.description = The net
thing-type.config.network.pingdevice.refreshInterval.label = Refresh Interval
thing-type.config.network.pingdevice.refreshInterval.description = States how long to wait after a device state update before the next refresh shall occur (in ms)
thing-type.config.network.pingdevice.retry.label = Retry
thing-type.config.network.pingdevice.retry.description = How many refresh interval cycles should a presence detection should take place, before the device is stated as offline
thing-type.config.network.pingdevice.retry.description = How many refresh interval cycles should a presence detection take place before the device is stated as offline.
thing-type.config.network.pingdevice.timeout.label = Timeout
thing-type.config.network.pingdevice.timeout.description = States how long to wait for a response (in ms), before if a device is stated as offline
thing-type.config.network.pingdevice.timeout.description = States how long to wait for a response (in ms) before a device is stated as offline.
thing-type.config.network.pingdevice.useArpPing.label = Use ARP Ping
thing-type.config.network.pingdevice.useArpPing.description = Set to true if the presence detection is allowed to use arp ping. This can speed up presence detection, but may lead to inaccurate ping latency measurements. Switch off if you want to use this for ping latency monitoring.
thing-type.config.network.pingdevice.useIOSWakeUp.label = Use iOS Wake Up
@@ -60,37 +60,37 @@ thing-type.config.network.servicedevice.port.description = The port on which the
thing-type.config.network.servicedevice.refreshInterval.label = Refresh Interval
thing-type.config.network.servicedevice.refreshInterval.description = States how long to wait after a device state update before the next refresh shall occur (in ms)
thing-type.config.network.servicedevice.retry.label = Retry
thing-type.config.network.servicedevice.retry.description = Defines how many times a connection attempt shall occur, before the device is stated as offline
thing-type.config.network.servicedevice.retry.description = Defines how many times a connection attempt shall occur before the device is stated as offline.
thing-type.config.network.servicedevice.timeout.label = Timeout
thing-type.config.network.servicedevice.timeout.description = States how long to wait for a response (in ms), before if a device is stated as offline
thing-type.config.network.servicedevice.timeout.description = States how long to wait for a response (in ms) before a device is stated as offline.
thing-type.config.network.speedtest.fileName.label = File Name
thing-type.config.network.speedtest.fileName.description = Name of the file to download from test server
thing-type.config.network.speedtest.fileName.description = Name of the file to download from test server.
thing-type.config.network.speedtest.initialDelay.label = Initial Delay
thing-type.config.network.speedtest.initialDelay.description = Delay before starting the first speed test (minutes) after initialization of the binding.
thing-type.config.network.speedtest.maxTimeout.label = Timeouts
thing-type.config.network.speedtest.maxTimeout.description = Number of timeout that can happend before the device is stated as offline
thing-type.config.network.speedtest.maxTimeout.description = Number of timeouts that can happen before the device is stated as offline.
thing-type.config.network.speedtest.refreshInterval.label = Refresh Time Interval
thing-type.config.network.speedtest.refreshInterval.description = Refresh time interval in minutes.
thing-type.config.network.speedtest.uploadSize.label = Upload Size
thing-type.config.network.speedtest.uploadSize.description = Size of the file to be uploaded (bytes).
thing-type.config.network.speedtest.url.label = Test Server URL
thing-type.config.network.speedtest.url.description = Url of the speed test server
thing-type.config.network.speedtest.url.description = Url of the speed test server.
# channel types
channel-type.network.Timestamp.label = Timestamp
channel-type.network.Timestamp.description = Status timestamp
channel-type.network.Timestamp.description = Status timestamp.
channel-type.network.isRunning.label = Test Running
channel-type.network.isRunning.description = Indicates if a test is currently ongoing
channel-type.network.isRunning.description = Indicates if a test is currently ongoing.
channel-type.network.lastseen.label = Last Seen
channel-type.network.lastseen.description = States the last seen date/time
channel-type.network.lastseen.description = States the last seen date/time.
channel-type.network.latency.label = Latency
channel-type.network.latency.description = States the latency time
channel-type.network.latency.description = States the latency time.
channel-type.network.online.label = Online
channel-type.network.online.description = States whether a device is online or offline
channel-type.network.online.description = States whether a device is online or offline.
channel-type.network.progress.label = Progress
channel-type.network.progress.description = Current Test progression
channel-type.network.progress.description = Current Test progression.
channel-type.network.rateDown.label = Download Rate
channel-type.network.rateDown.description = Current download rate
channel-type.network.rateDown.description = Current download rate.
channel-type.network.rateUp.label = Upload Rate
channel-type.network.rateUp.description = Current upload rate
channel-type.network.rateUp.description = Current upload rate.
bundles/org.openhab.binding.network/src/main/resources/OH-INF/thing/thing-types.xml
+17 -16
View File
@@ -42,14 +42,15 @@
<parameter name="retry" type="integer">
<label>Retry</label>
<description>How many refresh interval cycles should a presence detection should take place, before the device is
stated as offline</description>
<description>How many refresh interval cycles should a presence detection take place before the device is
stated as
offline.</description>
<default>1</default>
</parameter>
<parameter name="timeout" type="integer" unit="ms">
<label>Timeout</label>
<description>States how long to wait for a response (in ms), before if a device is stated as offline</description>
<description>States how long to wait for a response (in ms) before a device is stated as offline.</description>
<default>5000</default>
<advanced>true</advanced>
</parameter>
@@ -129,13 +130,13 @@
<parameter name="retry" type="integer">
<label>Retry</label>
<description>Defines how many times a connection attempt shall occur, before the device is stated as offline</description>
<description>Defines how many times a connection attempt shall occur before the device is stated as offline.</description>
<default>1</default>
</parameter>
<parameter name="timeout" type="integer">
<label>Timeout</label>
<description>States how long to wait for a response (in ms), before if a device is stated as offline</description>
<description>States how long to wait for a response (in ms) before a device is stated as offline.</description>
<default>5000</default>
</parameter>
@@ -191,15 +192,15 @@
</parameter>
<parameter name="url" type="text" required="true">
<label>Test Server URL</label>
<description>Url of the speed test server</description>
<description>Url of the speed test server.</description>
</parameter>
<parameter name="fileName" type="text" required="true">
<label>File Name</label>
<description>Name of the file to download from test server</description>
<description>Name of the file to download from test server.</description>
</parameter>
<parameter name="maxTimeout" type="integer">
<label>Timeouts</label>
<description>Number of timeout that can happend before the device is stated as offline</description>
<description>Number of timeouts that can happen before the device is stated as offline.</description>
<default>3</default>
<advanced>true</advanced>
</parameter>
@@ -209,35 +210,35 @@
<channel-type id="isRunning">
<item-type>Switch</item-type>
<label>Test Running</label>
<description>Indicates if a test is currently ongoing</description>
<description>Indicates if a test is currently ongoing.</description>
<state readOnly="false"></state>
</channel-type>
<channel-type id="progress">
<item-type>Number:Dimensionless</item-type>
<label>Progress</label>
<description>Current Test progression</description>
<description>Current Test progression.</description>
<state readOnly="true" min="0" max="100" pattern="%.0f %unit%"/>
</channel-type>
<channel-type id="rateUp">
<item-type>Number:DataTransferRate</item-type>
<label>Upload Rate</label>
<description>Current upload rate</description>
<description>Current upload rate.</description>
<state readOnly="true" pattern="%d %unit%"/>
</channel-type>
<channel-type id="rateDown">
<item-type>Number:DataTransferRate</item-type>
<label>Download Rate</label>
<description>Current download rate</description>
<description>Current download rate.</description>
<state readOnly="true" pattern="%d %unit%"/>
</channel-type>
<channel-type id="Timestamp">
<item-type>DateTime</item-type>
<label>Timestamp</label>
<description>Status timestamp</description>
<description>Status timestamp.</description>
<tags>
<tag>Status</tag>
<tag>Timestamp</tag>
@@ -248,7 +249,7 @@
<channel-type id="online">
<item-type>Switch</item-type>
<label>Online</label>
<description>States whether a device is online or offline</description>
<description>States whether a device is online or offline.</description>
<tags>
<tag>Status</tag>
<tag>Mode</tag>
@@ -259,7 +260,7 @@
<channel-type id="latency">
<item-type>Number:Time</item-type>
<label>Latency</label>
<description>States the latency time</description>
<description>States the latency time.</description>
<tags>
<tag>Status</tag>
<tag>Duration</tag>
@@ -270,7 +271,7 @@
<channel-type id="lastseen">
<item-type>DateTime</item-type>
<label>Last Seen</label>
<description>States the last seen date/time</description>
<description>States the last seen date/time.</description>
<category>time</category>
<tags>
<tag>Status</tag>