How to setup iperf integration?

I try to setup the iperf integration: Iperf3 - Home Assistant My yaml is:

# iperf speedtest
  scan_interval: '00:15:00'
    - host:
      port: 5201

This doesn’t work and creates sensors with unknown state. The documentation gives the hint that iperf3 needs to be installed on the OS. Using the SSH and Web Terminal add-on of my supervised setup, I can confirm that iperf3 is not installed. But shouldn’t this be something the integration takes care of? I never installed anything by hand with my 20+ integrations so far.

Is this standard behaviour for a core integration?

1 Like

I have the same problem. Is there solution or workaround?

Edit: Nvm, the servers I choose didn’t react to iperf3, only to iperf.

I’d advice you to test with your personal computer to make sure the server is responding.
I tested a couple servers listed here iPerf - Public iPerf3 servers, but they where not working. The server at was.

Just download the bin and do a test run. On Windows the command looks like:
.\iperf3.exe -4 -c -p 5201

If you are sure about the server, the mentioned config should work like a charm. In my config I didn’t use the port option.

Can anybody help with this?
I’d like to use iperf3 on Homeassistant running on Home Assistant OS 9.4 in a Virtualbox VM.

How do I install iperf3 in the Home Assistant OS?

Don’t know what you mean with ‘install’, but if you want to add it to HA, it’s explained in the link of the opening post: Iperf3 - Home Assistant

Add it to the configuration.yaml and reboot, that’s it.

The problem is that Home Assistant OS does not come with iperf. So adding to Home Assistant as explained in the link will not help. Or am I missing something?

My current setup looks like:

    - download
    - upload
  scan_interval: '01:00:00'
    - host:
      port: 5202
      parallel: 2

This works on a HASSIO installation. When I SSH to the machine, iperf isn’t installed. So I think it has the iperf binary installed inside the ha container.

Only the upload doesn’t work really well.


1 Like

I used the Speedtest integration for a (long) while and it always under performed. Last night it had only 15% of the upload and 60% of the download speed. So I decided to give Iperf3 another go and found this list of public servers: GitHub - R0GGER/public-iperf3-servers: A list of public iPerf3 servers...

Picked a random one that had -R as option listed and it works like a charm. The config:

    - download
    - upload
    - host: <the server I picked>
      port: <port it supports>
      parallel: 2
  manual: true

Hope this helps anyone who’s struggling with this integration.

Do you not get server connection refused from time to time ?

One of the two servers I use does respond with being busy from time to time. Do you think it’s caused by the parallel setting?

No i think its just to many people use it. I wish one could provide a range of ports.The problem i see is that it only reports up to a 100Mbps when i have a 1Gbps connection (which is what also reports i.e. nperf).

I agree that it would be nice to have an array/list of ports where the integration would just use the last known good and if that fails, walk trough the list of other ports. Unfortunately it doesn’t.
I currently use two servers in my config. The one performs better on the upload, where the other is better on the download.

Any way 100Mbps isn’t what you expect from a 1Gbps connection. But just a couple things to check:

  1. I assume your device is wired and not WiFi connected, right?
    WiFi is far from reliable since it’s shared and can have a lot of interference from neighbor networks and (in case of 2.4ghz) noise in the spectrum caused by i.e. Zigbee, Smoke alarms and more.

  2. I assume you have tested your speed in different ways, like a regular speedtest or for example a Linux ISO download from a fast source, with a better result than iPerf. So it’s not your provider throttling your connection.

  3. What is the max network speed of your HA device and the switch/router/modem is connected on. In case of a Pi3, it has a 100Mbps Ethernet connection, so it won’t ever go faster than that.

  4. Is your HA device heavily used on CPU %/Load 1m at the moment of the test?
    If it’s multi core (like a Raspberry Pi) anything lower than 1 on the load and 20% CPU or so, should be fine to exceed the speeds you are talking about.

  5. Finaly, if all should be capable of running more than 100Mbps, I’d suggest try a couple other France servers. Perhaps -p 9202 is a nice one, with 40Gbps.
    You could of course start with step 5 :sunglasses:

FYI, my bests on a Pi4 are 934Mbps up and 933Mbps down using iPerf. But 9 out of 10 the score is between 870 and 920. If it performs below 85% of it’s best, it will do a rerun. So the integration (on it self) is perfectly capable of 1Gbps-ish speeds.

  1. Yeah, wired on a 1Gbps port. Virtualized in VMware though, so there might be some overhead there. I recently moved from the e1000 driver to the vmxnet3 driver, which theoretically should be able to do up to 40Gbps.
  2. Yeah, on the laptop itself using i get 940Mbps or so.
  3. 1Gbps connection, see above.
  4. Mmm, around 20% i suppose.
  5. Yeah i tried a few different ones, but i’m a bit put off that i keep getting connection refused and stuff like that. I guess they are just very popular.

That’s a pretty good result for a Pi4! I suspect in my case it’s the virtualisation overhead, as the iperf results i did get previously were also around the speedtest (with the add-on that’s out there that aims to improve speeds) reports.

If you put the configure to manual though, does the service call still use the port and parallel arguments that are in the configuration.yaml ? As one can’t these in the developer tool service call. I’m thinking i will just use manual and call it myself several times per day rather then use the scan_interval option. But for that obviously the service call does need to take those arguments in consideration.

As i keep getting operation timed out. I did read something interesting though:

| Service data attribute | Description | | `host` | String that point at a configured `host` from `configuration.yaml` . Otherwise, tests will be run against all configured hosts.

It seems i can have different entries in configuration.yaml, and then i could call the service call without host arguments and it should start iperf client sessions on all configured hosts.

Edit: Forget that, that doesn’t work like it’s described.

Should this work for multiple hosts?

    - download
    - upload
  scan_interval: '00:30:00'
    - host:
      port: 9202
      parallel: 2
    - host:
      port: 5201
      parallel: 2
  manual: false

As i get this error upon startup, i don’t know if this is because it can’t reach them or ?

Error adding entities for domain sensor with platform iperf3
Error while setting up iperf3 platform for sensor
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/sensor/", line 590, in state
    numerical_value = int(value)
ValueError: invalid literal for int() with base 10: 'unknown'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/helpers/", line 504, in async_add_entities
    await asyncio.gather(*tasks)
  File "/usr/src/homeassistant/homeassistant/helpers/", line 788, in _async_add_entity
    await entity.add_to_platform_finish()
  File "/usr/src/homeassistant/homeassistant/helpers/", line 1006, in add_to_platform_finish
  File "/usr/src/homeassistant/homeassistant/helpers/", line 742, in async_write_ha_state
  File "/usr/src/homeassistant/homeassistant/helpers/", line 810, in _async_write_ha_state
    state = self._stringify_state(available)
  File "/usr/src/homeassistant/homeassistant/helpers/", line 748, in _stringify_state
    if (state := self.state) is None:
  File "/usr/src/homeassistant/homeassistant/components/sensor/", line 594, in state
    raise ValueError(
ValueError: Sensor sensor.download_iperf_par2_as49434_net has device class 'data_rate', state class 'measurement' unit 'Mbit/s' and suggested precision 'None' thus indicating it has a numeric value; however, it has the non-numeric value: 'unknown' (<class 'str'>)

I configured it to manual and trigger the run with a time based automation.
You basically select the host you want to test your speed with. I don’t know what happens if you add more than 1 host and run it automatically. I hope they don’t run at the same time :wink:

Anyway, what you could perhaps try is to run a local test to your laptop. Just to see what speed your HA VM reaches.

You can run iPerf using the Dev tools, you just have to know the host name of your config

I am not familiar with the errors, but can have a look in my config later. went up to 921Mbps, so we’re making progress.

Could you show me your config? Are you running tests around more then one host? Trying to figure how to run tests to different hosts but at different times. Seems i can only set the scan interval for the entire iperf platform.

Apparently the hosts argument does allow for multiple hosts, but i don’t know, surely it can’t test them at the same time? Must be doing it in succession or something?

I had 2 hosts setup previously so that would obviously have affected bandwidth, i’m going to do just one know with upload and download, see what happens.

My configuration is exactly like shared in post 8, above and what you posted as your config above. The difference only is that I do not use scan_interval: '00:30:00' and have set manual: true.

Next I run the speedtest using an action in my automation. Your action should be:

service: iperf3.speedtest

The second action:

service: iperf3.speedtest

I run them directly after each-other. I believe the default test time is 10s.

If you want to use two different moments in time, just set two triggers in your automation. Give them for example an ID and use a ‘Choose’ to decide which speedtest will be run.

Btw, I can imagine that your scheduled scan (every 30 minutes) results in refused connections. I, as a speedtest service, would not be happy if the same IP consumed my bandwidth 48 times a day. A speedtest is basically a waste of money for them and you are most likely not the only one.

Thanks. It’s just very inconsistent for me, one time i get 910Mbps and the other 61Mbps. I don’t understand where this is coming from. I think i will install or run the iperf3 client from the homeassistant container myself and check what’s going on.

As a speedtest service, i imagine they are well equipped to handle speed tests. You can’t have a service like that and then wonder why people use it :wink:

The integration clearly allows for every 30 minutes, even seconds, so if that’s not possible there should be a warning on the integration there. Anyway, i can go the to website and run it every mouse click, it’s not a problem. They are more then capable (and that doesn’t cause me low bandwidth or say connection refused.

There’s a problem with the VM or overhead somewhere.

True, but every 30 minutes can be considered excessive.
It’s a free service, don’t make them stop. It’s of no value to test your internet connection every day, every 30 minutes. So I can imagine they block you if you don’t know how to behave :wink:

The high frequent testing can be useful for a short period of time, for example trouble shooting, especially in combination with a local server. So the fact that the integration supports it, doesn’t mean your speedtest service provider is happy with you doing it. How would you feel if someone rang your doorbell 24/4 every 5 minutes? The doorbell allows it, so…

Anyway, just respect the providers giving you the opportunity to have you check your speed and don’t abuse it.

Good points. Yeah, i’m not going to run it that much, that time was just for testing. Probably few times per day will be more then enough.

So you are running these manually, i understand.

But you can’t add things like port to the service call from an automation, does it read it from the configuration.yaml somehow? That doesn’t seem to work in my case. For example works fine from a service call (as it uses the default iperf port) but doesn’t as it uses 5202. I can work around it of course by just using servers that use the default iperf port.