Add mAh, Ah as a new BATTERY_CAPACITY device class

[knyghtryda]

This seems to be a pretty important missing unit. Currently we have support for energy capacity, but not battery capacity, which is useful for a lot of battery based devices (in my case the Ecoflow batteries) which report this value.

[parautenbach]

Ah is actually quite a poor indicator of battery capacity since it's unit isn't Joule, the measure of energy (you thus need the voltage with Ah to get to that).

Wouldn't this value be mostly a constant anyway? Or are you actually talking about remaining capacity here?

[knyghtryda]

Both actually. The Ecoflow delta pro reports full capacity, remaining capacity, and factory spec capacity.

[MartinHjelmare]

Please list the integrations that could leverage the new device class. Integrations that can leverage anything, like template and MQTT aren't interesting.

[frenck]

If there are a handful of integrations in our core codebase that need it, we are definitely open to add it.

At this point, it seems that isn't the case.

[Just-Zuul]

I haven't been using HA for very long, maybe half a year - I'm generally enthusiastic and have decided to use HA instead of IO Broker.

I really don't understand what the problem is with introducing mAh as a unit. MWh (and I think GWh too - of course, if you're a power plant operator) is also possible and I'll say - nobody needs it - normal users probably all use kWh.

Considering that over 1 million people use Ecoflow, most of them don't (yet) know anything about the possibilities with HA, don't know or find this article and all in all it would already make life easier for several thousand people....

But if you think so... OK - HA is your thing - but is that the right decision...?

[frenck]

Home Assistant provides a common interface over multiple devices; it does so by creating an abstraction across things that are common for multiple integrations.

Right now, we do not have multiple integrations in our code codebase that can benefit from these abstractions. If there would be a handful (as pointed out multiple times now), we can reconsider. If we would add it right now, it would be basically dead code or code specifically for a single integration; which is not what we want in our architecture.

../Frenck

[ChristophCaina]

Hi, common to the Statement about MWh:

As already mentioned, Iam using a Rest API to get Sonne information from our Energy supplier about how much renewable Energy is available.
This information comes in MWh.

Beides of that:
My solar Installation does produce 13.000 kWh per year.
At sind Point, it would just good to have the opportunity to Switch to this unit.
That would also apply for the Energy Dashboard, where people already complaining that the large kWh Numbers so not fit into the circles in certain cases.

It's of course not a must have - Just a few usecases where it could already be considered ;)

[frenck]

@ChristophCaina Your comment does not seem to be related to this architectural discussion.

[tiimsvk]

I also use this integration with a device for RPI where the battery capacity is defined in mAh
https://github.com/odya/hass-ina219-ups-hat

[frenck]

Custom integrations are not a factor for us in deciding what we support in Core.

[ChristophCaina]

In my opinion, HA should be capable of handling at least some Standard Units - and Ah / mAh is one.
Regardless of the amount of Integrations that currently exist - or maybe will exist later.

There are other examples of Units that could be integrated - even If they are not that common... MW (Mega Watt) etc. that could be easily added without causing issues If they are not beeing used immediately.

You can Just Setup a Rest API Sensor or create a template that would utilize such a measurement value...
In my opinion, HA should be more flexible for such Units

[frenck]

If there are a handful of integrations in our core codebase that need it, we are definitely open to add it.

At this point, it seems that isn't the case.

[dosmenbsd]

Hello! I was also very surprised that there is no Ah. Ah is a very important indicator for autonomous systems, since modern batteries do not allow you to estimate the remaining charge simply by measuring the voltage. ALL battery controllers simply sum up the charge time multiplied by the charge current (A*h). I use ESPHOME to get data from various BMS - and just ignored the device class error. I thought I didn't read the documentation well enough. Thanks, now I understand - it's not a bug, it's a feature)

[dougiteixeira]

I did a quick search of the codebase, only one integration uses the Ah unit:

• Network UPS Tools (NUT):
  https://github.com/home-assistant/core/blob/db3d3854478086292e98a57af9522f79dc75eede/homeassistant/components/nut/sensor.py#L321-L327

However, I found some interesting cases where calculations are made so that the sensor can have a unit compatible with the energy storage device class:

• MyPermobil:
  https://github.com/home-assistant/core/blob/db3d3854478086292e98a57af9522f79dc75eede/homeassistant/components/permobil/sensor.py#L99-L120

And there are other integrations that implement battery info without informing a unit, which makes one wonder if they are not using units derived from Ah.

I believe that the current behavior of validating the unit as compatible with the device class has caused developers to fail to implement sensors with units and without device classes, which may mask research.

Despite the small number of integrations that currently use units derived from Ah, I believe that after implementation new use cases will appear.

[Eriond]

@frenck Since listing core codebase integration seems pivotal to this enhancement, let me give "Modbus" as an example. I'm adding a configuration yaml for the eFoy fuel cells, which make use of this unit. Right now I have to use device_class 'None', which of course is possible, but don't provide a proper 'unit_of_measurement'.
If this is an enhancement that could be implemented without causing breaking changes, I would much appreciate if could be done.

[asmcc]

@frenck I do not understand your demonstrative protest against AmpereHours as STANDARD UNIT. We are in 21th century and have now the year 2025!
In Germany each home automation amateur buys today a photovoltaic with intergrated battery, or enhances its old installation by a new battery or buy the cells in China an make its own self made battery. And all these systems uses Ah as unit. Most china BMSs (and that are assumed 95...99% of all BMSs) sends this value ONLINE over CAN / ModBus / Serial to the inverter and to other home automation systems. And this value is often not static, but dynamic. It is used often instead or additionaly to of SOC in % for example.
Most users in Germany uses iobroker for it instead of Home Assistant, since this topic (Battery, Photovoltaic, etc.) was better supported under iobrocker the whole time before. But in the last 2-3 years a lot of these old iobroker users migrate to Home Assistant and are wondered, that such elementary things are a big problem under the Home Assistant. Please simple trust us. This unit will come in the future, independed on our wish and your resistance. In contrast to your forecasting, it will not land as "dead code", but it will be used more and more in the next monts. Yes, in the next monts, not years!
I can not refer a concretely intergration, which needs this unit exactly, but that are a lot of MQTT / ModBus and other integrations / implementations, which provide the entities for home assistant with the unit "Ah". And these implementations are not new, but exists already since 3-5 years ago. All modern photovoltaic inverter, all batteries and other things uses "Ah" as unit.
Please simple implement it and do not ask why!
Thanks!

[frenck]

@frenck I do not understand your demonstrative protest against AmpereHours as STANDARD UNIT.

Not sure why you direct this at me, and I'm pretty well aware of the century I'm in. This is not about my personal opinion; this is about how we are extending our code base based on usage. If you read back up this story, you'd notice that is the only think I'm asking for.

I can not refer a concretely integration

Right. Exactly. This was discussed in our architectural core team meeting last week; I'll post an update in a separate reply. As this is a reason for not being able to accept the proposal right now.

[frenck]

Hi everyone! 👋

So, this proposal has been sitting around for a bit now, and there has been some back-and-forth. I scheduled it to be discussed in our architectural core team meeting last week, and so we did.

Unfortunately, we have decided not to accept this proposal in our architecture at this time.

Besides discussion as pointed out in one of the first comments, the bigger issue we have is that the number of integrations we currently have available in our core codebase that can use this is actually quite slim. Although custom integrations may exist, they do not drive our code-base design and decision-making.

For now, we're going to decline this proposal. However, if the potential use in our codebase grows in the future, we may reconsider it.

That said, declining a device class, isn't a blocking factor entities to use the units today. If this unit of measurement fits the sensors you are creating, you use these units.

../Frenck