Iperf3
The iperf3
sensor integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to measure network bandwidth performance against a private or public Iperf3
Enabling this integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] will automatically create the Iperf3 sensors for the monitored conditions (below). By default, it will run every hour. The user can change the update frequency in the configuration by defining the scan_interval
for a Iperf3 test to run.
Setup
This integration requires the iperf3
command to be installed on your OS. Please, refer to the official Iperf3 documentation
Configuration
To add the iperf3
sensor to your installation, add the following to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.
Once per hour, on the hour (default):
# Example configuration.yaml entry
iperf3:
hosts:
- host: iperf.he.net
Configuration Variables
Sensors to display in the frontend.
Minimum time interval between updates. Supported formats: scan_interval: 'HH:MM:SS'
, scan_interval: 'HH:MM'
and Time period dictionary (see example below).
Configuration variables (host):
Configuration Variables
Specify the test duration in seconds. Default is 10 and the valid range is from 5 to 10.
Specify the number of concurrent streams to connect to the server. Default is 1 and the valid range is from 1 to 20.
Specify the protocol to be used on the test. Default is TCP and the valid values are TCP or UDP. If your Iperf3 server is located in the Internet, consider to use TCP instead of UDP. If the protocol is set to use UDP, the sensor may not get updated due to package retransmission issues due to its nature.
Time period dictionary example
scan_interval:
# At least one of these must be specified:
days: 0
hours: 0
minutes: 3
seconds: 30
milliseconds: 0
You can find a list of public Iperf3 servers hereiperf3
command’s man page.
The frequency when the test will be automatically triggered can be adjusted by setting the value scan_interval
in seconds.
Parallel streams can help in some situations. As TCP attempts to be fair and conservative, you may consider increasing the parallel
attribute. Use this value with careful and refer to Iperf3 man page for more information.
You can use the sensor.iperf3_update
action to trigger a manual speed test for all sensors. Iperf3 has its own action that allows performing a speed test on a particular entity.
Action
Once loaded, the iperf3
integration will expose an action (iperf3.speedtest
) that can be called to run a speed test on demand. This can be useful if you have enabled manual mode.
Data attribute | Description |
---|---|
host |
String that point at a configured host from configuration.yaml . Otherwise, tests will be run against all configured hosts. |
Example action data:
{"host": "192.168.0.121"}