Add config flow for Ping (#29786)

Co-authored-by: J. Nick Koston <nick@koston.org>
This commit is contained in:
Jan-Philipp Benecke 2023-11-17 20:43:30 +01:00 committed by GitHub
parent f0801e44ca
commit 65b59bf2e9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -13,6 +13,7 @@ ha_platforms:
- binary_sensor
- device_tracker
ha_integration_type: integration
ha_config_flow: true
ha_codeowners:
- '@jpbede'
---
@ -22,35 +23,12 @@ There is currently support for the following device types within Home Assistant:
- [Binary Sensor](#binary-sensor)
- [Presence Detection](#presence-detection)
{% include integrations/config_flow.md %}
## Binary Sensor
The `ping` binary sensor platform allows you to use `ping` to send ICMP echo requests. This way you can check if a given host is online and determine the round trip times from your Home Assistant instance to that system.
To use this sensor in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: ping
host: 192.168.0.1
```
{% configuration %}
host:
description: The IP address or hostname of the system you want to track.
required: true
type: string
count:
description: Number of packets to be sent up to a maximum of 100.
required: false
type: integer
default: 5
name:
description: Let you overwrite the name of the device.
required: false
type: string
default: Ping [hostname]
{% endconfiguration %}
This sensor is enabled by default. The default polling interval is 5 minutes.
The sensor exposes the different round trip times in milliseconds measured by `ping` as attributes:
@ -59,18 +37,6 @@ The sensor exposes the different round trip times in milliseconds measured by `p
- `round_trip_time_min`
- `round_trip_time_max`
The default polling interval is 5 minutes. As many integrations [based on the entity class](/docs/configuration/platform_options), it is possible to overwrite this scan interval by specifying a `scan_interval` configuration key (value in seconds). In the example below we setup the `ping` binary sensor to poll the device every 30 seconds.
```yaml
# Example configuration.yaml entry to ping host 192.168.0.1 with 2 packets every 30 seconds.
binary_sensor:
- platform: ping
host: 192.168.0.1
name: "device name"
count: 2
scan_interval: 30
```
<div class='note'>
When run on Windows systems, the round trip time attributes are rounded to the nearest millisecond and the mdev value is unavailable.
</div>
@ -79,31 +45,10 @@ When run on Windows systems, the round trip time attributes are rounded to the n
The `ping` device tracker platform offers presence detection by using `ping` to send ICMP echo requests. This can be useful when devices are running a firewall and are blocking UDP or TCP packets but responding to ICMP requests (like Android phones). This tracker doesn't need to know the MAC address since the host can be on a different subnet. This makes this an option to detect hosts on a different subnet when `nmap` or other solutions don't work since `arp` doesn't work.
The device tracker is disabled by default and can be enabled in the UI.
<div class='note'>
Please keep in mind that modern smart phones will usually turn off WiFi when they are idle. Simple trackers like this may not be reliable on their own.
</div>
### Configuration
To use this presence detection in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
device_tracker:
- platform: ping
hosts:
device_name_1: 192.168.2.10
```
{% configuration %}
hosts:
description: Map of device names and their corresponding IP address or hostname. Device names must conform to the standard requirements of lower case, numbers and underscore only - see [entity names](/docs/configuration/troubleshooting/#entity-names).
required: true
type: map
count:
description: Number of packet used for each device (avoid false detection).
required: false
type: integer
{% endconfiguration %}
See the [person integration page](/integrations/person/) for instructions on how to configure the people to be tracked.