battery: Add standard APIs for Battery Charging and Fuel Gauge Handling (Energy Management)

[zephyrbot]

Reported by Souvik Kumar Chakravarty:

Currently Zephyr does not have any standard interface for the applications to interact with the Battery related hardware sub-system. We need to create one so that applications can work independent of hardware variations.

(Imported from Jira ZEP-1037)

[zephyrbot]

by Souvik Kumar Chakravarty:

There is a need for a lightweight API set for applications to talk to Battery Sub-system. This Energy Management API framework should enable the following:

1. Application should be able to get notified on
   Battery threshold breach events
   Charger Events.
2. Application should be able to configure the following battery charge & temperature level thresholds for callback notifications: Warning, Critical, Shutdown
3. Application should be able to enable/disable charging
4. Application should be able to fix the sampling rate for Charge and Battery Temperature measurment to be done by the drivers below
5. Applications should be able to get Battery
   Terminal Voltage
   Temperature
   State Of Charge (SOC) - %

The APIs will be implemented in the FG & Charging drivers below. Default these APIs are stubbed and designed to return an error code.

[JoeHut]

Is anybody working on this Energy Management API? It feels like this is a common problem.

[tbursztyka]

Does not seem so. But I remember replying on the ml about it: this would already all fit within sensor API. Sensor API supports tweaking "attributes" such as threshold, rate, triggers (events), ...

[JoeHut]

Interesting! I didn't think of that. I think a State of Charge channel would be necessary than, but the rest is actually already there. Thanks.

[JoeHut]

@tbursztyka Could you point me in a direction how to enable triggers on charging events? Here we don't have a continuous metric but rather a couple of states (fast charging, normal charging, charging completed, running on battery). I don't see an example of how this could be implemented as part of the sensor API.

[tbursztyka]

I guess you'll need to add trigger types in sensors.h, the power controller driver below would throw these relevantly.
For events like low level, critical level etc.. I guess you'll need to be able to set the threshold you want for each? Then adding relevant attributes in sensors.h

[carlescufi]

CC @pizi-nordic @oyvindronningstad

[jhedberg]

Some use cases that'll be needing this API (from the domain I'm working in):

• Bluetooth GATT battery service
• Bluetooth Mesh battery models
• USB HID peripheral (which could be acting as a proxy for a Bluetooth HID device)

Besides the features that's mentioned here it'd also be nice to be able to get battery health stats if the hardware supports it, such as the number of recharge cycles it has gone through.

[carlescufi]

@Raane do you think you could put together an API proposal?

[tbursztyka]

some of my 2 cents:

• The API should be made on top of sensor API (that will avoid recreating all sorts of things that does exists there)
• If something is missing in sensor API, add stuff there as much as possible which in turn will be used by this Energy API. Unless it's something super specific to battery, like sensing power supply in/off I guess.
• About the health proposed by @jhe, I think it's a good idea. Just be prepared: some controller exposes the number of cycles left, or the one already done + the "upper limit", or the actual power rate out of factory, or all of these, etc... So it would be nice to hide all these possibilities under 1 function that would give the "health" of the battery (could be in percent, or some specific value telling dead/bad/half-life/good/new etc...)