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

zephyrproject-rtos / zephyr

Primary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.

https://docs.zephyrproject.org

Apache License 2.0

10.85k stars 6.61k forks source link

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

Closed zephyrbot closed 3 years ago

zephyrbot commented 8 years ago

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 commented 8 years ago

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 commented 6 years ago

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

tbursztyka commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

CC @pizi-nordic @oyvindronningstad

jhedberg commented 6 years ago

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 commented 6 years ago

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

tbursztyka commented 6 years ago

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...)

chris-schra commented 6 years ago

Anyone working on this? I‘ll soon have to interface a BQ24295 (I2C Battery Charger) and it would help if there were others with different hardware

JoeHut commented 6 years ago

The only thing I know of where something is done in this domain is https://github.com/zephyrproject-rtos/zephyr/pull/9735. At least there is a charging state channel for the sensors now. But I don't think anyone has been working on a higher-level API. I have drivers for the BQ24031 charger and the BQ27421 Fuel Gauge lying around that have to be cleaned up and upstreamed if they help you. But the charger is solely GPIO-based so I don't think it would help you a lot.

olsky commented 4 years ago

The only thing I know of where something is done in this domain is #9735. At least there is a charging state channel for the sensors now. But I don't think anyone has been working on a higher-level API. I have drivers for the BQ24031 charger and the BQ27421 Fuel Gauge lying around that have to be cleaned up and upstreamed if they help you. But the charger is solely GPIO-based so I don't think it would help you a lot.

@JoeHut --> could you please share the branch with the BQ27421? I have that sensor on the board, but the drv is missing...

// edit: we are trying, but something is still not working: https://github.com/olsky/zephyr/blob/battery/drivers/sensor/bq274xx/bq274xx.c

martinjaeger commented 4 years ago

Very interesting, just found this issue by chance.

I'm working on a battery management system which I recently ported to Zephyr. It supports TI BQ769x0 and Renesas ISL94202 (preliminary) analog front ends and I thought about whether it could make sense to include the drivers for these ICs into the main Zephyr repository.

A BMS is somewhat more complex than a fuel gauge IC, but it could still make sense to think about a generic battery/energy management API.

pabigot commented 4 years ago

It is true that there is a wide variety of capability in fuel gauge vs battery management vs charging IC. So I think we should have multiple specific drivers available before attempting to guess what a generic API suitable to Zephyr should look like.

I could port my non-Zephyr drivers for XC6804A4E1 (nrf52_pca20020) and XC6802A42 (particle mesh feather) if there was interest.

olsky commented 4 years ago

I agree with @pabigot -- it makes sense to go with specific drivers first, collect experience, gather use-cases and then more to "generalization" and making APIs for a generic battery module.

Standards, rooting from theories -- tend to take time. More pragmatic approach, in my opinion, is required.

carlescufi commented 4 years ago

Current API proposals:

https://github.com/zephyrproject-rtos/zephyr/pull/26974 https://github.com/zephyrproject-rtos/zephyr/pull/26968

carlescufi commented 4 years ago

API meeting 28th July:

@nashif @rkotabag There are currently 2 implementations of this functionality using the sensor API:

General consensus seems to be that right now there is no urgent need for a specific API, since the sensor API seems capable of abstracting this type of functionality. Furthermore, there is currently a battery shell command that uses the sensor API for this purpose.

carlescufi commented 3 years ago

API meeting 2021.02.16:

The current consensus is that the sensor API is sufficient to handle this functionality.