Improve developer guidance regarding bandwidth sensors

[Sirs0ri]

Hi there!

I recently had a question regarding the integration for my router (fritz), and why it was using different units for the currently used bandwidth and the max available bandwidth (kilobits/s and kilobytes/s). When talking to the integration's code owner @chemelli74 we came to the conclusion that this issue is probably bigger than just one single integration, and that maybe it would be good to start an architecture discussion to get a general guideline for all integrations.

I've since looked into a couple of the router-related integrations, and found that most of them seem to use different units :

• huawei_lte uses DATA_RATE_BYTES_PER_SECOND
• fritz uses both DATA_RATE_KILOBITS_PER_SECOND and DATA_RATE_KILOBYTES_PER_SECOND
• freebox uses just DATA_RATE_KILOBYTES_PER_SECOND
• bbox and asuswrt use DATA_RATE_MEGABITS_PER_SECOND
• etc...

The relevant documentation for sensors doesn't cover bandwidth at all, since there's no dedicated device class, maybe that would be a place to change it.

There doesn't seem to be any consensus between the different integrations, my idea is that it might be good to have a general guidance about the scale of unit to be used from homeassistant (kilo, mega, etc), while maybe exposing the type of unit (bits/bytes per second) to the user as a toggle similar to the toggle for metric/imperial, or the local currency.

I'm hoping to get some insight into why different units are prepared by different developers, and to hopefully get a bit more consistency into the bandwidth sensors in the future.

[scop]

Speaking for huawei_lte, it exposes bytes per second simply because that's what the routers' API exposes, and because I was not aware of a recommendation to use some particular scale or bits instead of bytes.

I'm all for consistency, although perhaps it'd make sense to have integrations report things as accurately as possible (so maybe make it bits or bytes everywhere, no kilos/megas on that level) and do the conversion in the UI. But then again this might be a bit annoying for automation conditions/triggers, lots of zeros there if they get to deal with the unscaled bits/bytes values. Sub-kilobit accuracy isn't probably that interesting these days, except for if it's really zero or even a bit (pun!) more.

[Jc2k]

I think id prefer the integrations to report their native values rather that doing any conversion within the integration, potentially converting for display within the core. I imagine it won't be as bad as temperature but I've seen us doing F->C->F and it going quite "wrong" from the users perspective.

[chemelli74]

Take care that there are many others usage as well, not only routers.
One example ? synology_dsm has 2 sensors for Download Throughput and Upload Throughput

Simone

[Bre77]

Given that native_unit_of_measurement is required now rather than unit_of_measurement, it would make sense that native_unit_of_measurement is the value reported by the source data, and then HA can convert that to whatever unit_of_measurement the user prefers. Right now I believe that's only done for temperature, but certainly could be done for other units.

[Sirs0ri]

That sounds like it could be a good solution. What can be done to extend the support of native_unit_of_measurement to more types of units than just temperatures?

[Bre77]

Would need to get added in the sensor base class, but a decision would need to be made about what they are converted to.
https://github.com/home-assistant/core/blob/dev/homeassistant/components/sensor/__init__.py#L257
https://github.com/home-assistant/core/blob/dev/homeassistant/components/sensor/__init__.py#L270

If I had to propose something it would to be converted to a value with 3 digits using the same base unit (bits/Bytes/bps/Bps) as the native unit. But I don't know if this is actually good.

1230KB = 1.23MB
0.123Mb = 12.3Kb
1234bps = 1.23kbps