Area Units

[Xyaren]

Context

There are currently a wide range of units available for implementing sensors.
Those include distance units, temperatures, and flow rates to be a few.

While distance ist currently available in Si and imperial units, area is only.available in square meters.
Also there is only m², and larger or smaller values are not being converted into their respective units like. mm² or km².

I came across this lack of functionality when working with a sensor for a robot vacuum, which exposes it's cleaning area down to mm² precision.
Other applications are possible like robot lawnmowers exposing area cut or cumulative areas which can easily grow past thousands of m².

Proposal

I propose to add area Units similar to the already existing distance units.

Consequences

Area units are handled in a standardized way and represented in the unit of choice for the end users.

[frenck]

When we add things to our global constants file, we will do that only if there is a bigger benefit to doing so.

Which integrations would be able to benefit from this?

And which values would the enum have? Would there be a conversion capability for the end-user?

[Xyaren]

The conversation is dictated by the selected unit system.
The integration I have been in contact with is a relatively new one.
https://github.com/humbertogontijo/homeassistant-roborock/blob/main/custom_components/roborock/sensor.py

In this case it is about cleaning area, which is exposed as mm² by the robot.

This would most likely be used by other robot vacuum integrations as well.

[frenck]

We don't add constants for custom integrations, we need to define the use of Core itself (otherwise, we would be creating dead code).

[Xyaren]

Values could be similar to the distance enum:

# Area units
class UnitOfArea(StrEnum):
    """Area units."""

    SQUARE_MILLIMETERS = "mm²"
    SQUARE_CENTIMETERS = "cm²"
    SQUARE_METERS = "m²"
    SQUARE_KILOMETERS = "km²"
    SQUARE_INCHES = "in²"
    SQUARE_FEET = "ft²"
    SQUARE_YARDS = "yd²"
    SQUARE_MILES = "mi²"

[Xyaren]

https://github.com/home-assistant/core/blob/dev/homeassistant/components/xiaomi_miio/sensor.py

Would use square meters specifically.
Based on the value a conversion up to square km² would be adequate which is not available due to the missing sensor device class for area.

[Xyaren]

Also tuya devices use clean area and total clean area as senso s:

https://github.com/home-assistant/core/blob/fba13dcc907b85f84a2a3d60f3298858439793ca/homeassistant/components/tuya/sensor.py#L820

[frenck]

Tuya doesn't handle units directly.

Instead of dropping some code-refs, please build a solid proposal and case that provides a list of integrations that case leverage the constants and enum you'd like to add; in the OP.

Thanks 👍

[Xyaren]

I'primarily interested in providing a better experience for custom integrations as well as areas displayed in the unit system of choice for the user.
If this is not in your interest and preventing some possibly dead enums is of higher priority consider this closed.

[frenck]

Alright, will consider it closed in that case.

[frenck]

As per #849 (reply in thread)

../Frenck

[lazynoda]

If I may, I'd like to add my 2 cents. I have 2 vacuum robots that, as @Xyaren mentioned, expose the cleaned area. In my case this sensors are in MQTT because of how the robots are integrated into the ecosystem. So any robot through MQTT can benefit.
Because of other reasons, I'm also using this values via RESTful sensors. In my case, I get the values in cm².

Not only core integrations (like the ones for vacuums directly or via mqtt) can benefit from this, but also template sensors created by the user. And as it's part of the SI, I don't see any point against.