Skip to content

Commit e5b5669

Browse files
dale3hdale3h
authored
Update documentation for Speedtest Sensor (home-assistant#4914)
* Update documentation for Speedtest Sensor * Fixed configuration variables * Fixed automation example * Fixed example format * Fix netlify errors for raw/endraw tags * ✏️ Minor improvements
1 parent a9a26f7 commit e5b5669

File tree

1 file changed

+68
-30
lines changed

1 file changed

+68
-30
lines changed

‎source/_components/sensor.speedtest.markdown

Lines changed: 68 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,13 @@ ha_iot_class: "Cloud Polling"
1616

1717
The `speedtest` sensor component uses the [Speedtest.net](https://speedtest.net/) web service to measure network bandwidth performance.
1818

19-
By default, it will run every hour. The user can change the update frequency in the configuration by defining the minute, hour, and day for a speedtest to run. For the `server_id` check the list of [available servers](https://www.speedtest.net/speedtest-servers.php).
19+
By default, it will run every hour. The user can change the update frequency in the configuration by defining the minute, hour, and day for a speed test to run. For the `server_id` check the list of [available servers](https://www.speedtest.net/speedtest-servers.php).
2020

2121
To add a Speedtest.net sensor to your installation, add the following to your `configuration.yaml` file:
2222

2323
Once per hour, on the hour (default):
2424

25+
{% raw %}
2526
```yaml
2627
# Example configuration.yaml entry
2728
sensor:
@@ -31,32 +32,63 @@ sensor:
3132
- download
3233
- upload
3334
```
34-
35-
Configuration variables:
36-
37-
- **monitored_conditions** array (*Required*): Sensors to display in the frontend.
38-
- **ping**: Reaction time in ms of your connection (how fast you get a response after you've sent out a request).
39-
- **download**: Download speed in Mbps.
40-
- **upload**: Upload speed in Mbps.
41-
- **server_id** (*Optional*): Specify the speedtest server to perform test against.
42-
- **minute** (*Optional*): Specify the minute(s) of the hour to schedule the speedtest. Use a list for multiple entries. Default is 0.
43-
- **hour** (*Optional*): Specify the hour(s) of the day to schedule the speedtest. Use a list for multiple entries. Default is None.
44-
- **day** (*Optional*): Specify the day(s) of the month to schedule the speedtest. Use a list for multiple entries. Default is None.
45-
- **manual** (*Optional*): True or False to turn manual mode on or off. Manual mode will disable scheduled speedtests.
35+
{% endraw %}
36+
37+
{% configuration %}
38+
monitored_conditions:
39+
description: Sensors to display in the frontend.
40+
required: true
41+
type: list
42+
keys:
43+
ping:
44+
description: Reaction time in ms of your connection (how fast you get a response after you've sent out a request).
45+
download:
46+
description: Download speed (Mbit/s)
47+
upload:
48+
description: Upload speed (Mbit/s)
49+
server_id:
50+
description: Specify the speed test server to perform the test against.
51+
required: false
52+
type: int
53+
day:
54+
description: Specify the day(s) of the month to schedule the speed test. Use a list for multiple entries.
55+
required: false
56+
type: [int, list]
57+
hour:
58+
description: Specify the hour(s) of the day to schedule the speed test. Use a list for multiple entries.
59+
required: false
60+
type: [int, list]
61+
minute:
62+
description: Specify the minute(s) of the hour to schedule the speed test. Use a list for multiple entries.
63+
required: false
64+
type: [int, list]
65+
default: 0
66+
second:
67+
description: Specify the second(s) of the minute to schedule the speed test. Use a list for multiple entries.
68+
required: false
69+
type: [int, list]
70+
default: 0
71+
manual:
72+
description: True or False to turn manual mode on or off. Manual mode will disable scheduled speed tests.
73+
required: false
74+
type: bool
75+
default: false
76+
{% endconfiguration %}
4677
4778
This component uses [speedtest-cli](https://github.com/sivel/speedtest-cli) to gather network performance data from Speedtest.net. Please be aware of the potential [inconsistencies](https://github.com/sivel/speedtest-cli#inconsistency) that this component may display.
4879
49-
When Home Assistant first starts up, the values of the speedtest will show as `Unknown`. You can use the service `sensor.update_speedtest` to run a manual speedtest and populate the data or just wait for the next regularly scheduled test. You can turn on manual mode to disable the scheduled speedtests.
80+
When Home Assistant first starts up, the values of the speed test will show as `Unknown`. You can use the service `sensor.update_speedtest` to run a manual speed test and populate the data or just wait for the next regularly scheduled test. You can turn on manual mode to disable the scheduled speed tests.
5081

5182

5283
## {% linkable_title Examples %}
5384

54-
In this section you find some real life examples of how to use this sensor.
85+
In this section, you find some real-life examples of how to use this sensor.
5586

5687
### {% linkable_title Run periodically %}
5788

5889
Every half hour of every day:
5990

91+
{% raw %}
6092
```yaml
6193
# Example configuration.yaml entry
6294
sensor:
@@ -69,11 +101,13 @@ sensor:
69101
- download
70102
- upload
71103
```
104+
{% endraw %}
72105

73106
### {% linkable_title Run at a specific time %}
74107

75108
Everyday at 12:30AM, 6:30AM, 12:30PM, 6:30PM:
76109

110+
{% raw %}
77111
```yaml
78112
# Example configuration.yaml entry
79113
sensor:
@@ -89,29 +123,33 @@ sensor:
89123
- download
90124
- upload
91125
```
126+
{% endraw %}
92127

93128
### {% linkable_title Using as a trigger in an automation %}
94129

130+
{% raw %}
95131
```yaml
96132
# Example configuration.yaml entry
97133
automation:
98-
- alias: 'Internet Speed Glow Connect Great'
99-
trigger:
100-
platform: template
101-
value_template: '{% raw %}{{ states.sensor.speedtest_download.state|float > 10}}{% endraw %}'
102-
action:
103-
service: shell_command.green
104-
- alias: 'Internet Speed Glow Connect Poor'
105-
trigger:
106-
platform: template
107-
value_template: '{% raw %}{{ states.sensor.speedtest_download.state| float < 10 }}{% endraw %}'
108-
action:
109-
service: shell_command.red
134+
- alias: "Internet Speed Glow Connect Great"
135+
trigger:
136+
- platform: template
137+
value_template: "{{ states('sensor.speedtest_download')|float > 10 }}"
138+
action:
139+
- service: shell_command.green
140+
141+
- alias: "Internet Speed Glow Connect Poor"
142+
trigger:
143+
- platform: template
144+
value_template: "{{ states('sensor.speedtest_download')|float < 10 }}"
145+
action:
146+
- service: shell_command.red
110147
```
148+
{% endraw %}
111149

112150
## {% linkable_title Notes %}
113151

114152
- When running on Raspberry Pi, just note that the maximum speed is limited by its 100 Mbit/s LAN adapter.
115-
- Entries under `monitored_conditions` only control what entities are available under home-assistant, it does not disable the condition from running.
116-
- If ran frequently, this component has the capability of using a very large amount of data. Frequent updates should be avoided on bandwidth capped connections.
117-
- While running, network usage is fully utilized. This may have a negative affect on other devices in use the network such as gaming consoles or streaming boxes.
153+
- Entries under `monitored_conditions` only control what entities are available in Home Assistant, it does not disable the condition from running.
154+
- If ran frequently, this component has the ability to use a considerable amount of data. Frequent updates should be avoided on bandwidth-capped connections.
155+
- While running, your network capacity is fully utilized. This may have a negative effect on other devices in use the network such as gaming consoles or streaming boxes.

0 commit comments

Comments
 (0)