drivers: fuelguage: Add ADI LTC2959 driver #90356

LostinTimeandspaceYT · 2025-05-22T19:57:36Z

The LTC®2959 is an ultra-low power battery gas gauge
that accurately measures charge, voltage, current and
temperature. Its wide input voltage range and its low
operating current make the LTC2959 suitable for many
applications, including duty-cycled systems that operate
over long lifetime.

This driver integrates with Zephyr’s fuel gauge subsystem to provide access to telemetry data such as voltage, current, temperature, and accumulated charge.

Tested on custom hardware with known RSENSE configuration and verified against datasheet behavior.

Signed-off-by: Nathan Winslow natelostintimeandspace@gmail.com

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

github-actions · 2025-05-22T19:58:15Z

Hello @LostinTimeandspaceYT, and thank you very much for your first pull request to the Zephyr project!
Our Continuous Integration pipeline will execute a series of checks on your Pull Request commit messages and code, and you are expected to address any failures by updating the PR. Please take a look at our commit message guidelines to find out how to format your commit messages, and at our contribution workflow to understand how to update your Pull Request. If you haven't already, please make sure to review the project's Contributor Expectations and update (by amending and force-pushing the commits) your pull request if necessary.
If you are stuck or need help please join us on Discord and ask your question there. Additionally, you can escalate the review when applicable. 😊

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

fmoessbauer · 2025-05-22T20:08:40Z

drivers/fuel_gauge/ltc2959/CMakeLists.txt

@@ -0,0 +1,3 @@
+zephyr_library()
+zephyr_include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+zephyr_library_sources(ltc2959.c)


It looks like the driver itself is missing.

My apologies. I was pushing the driver itself in a separate commit.

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

fmoessbauer · 2025-05-22T20:11:01Z

IMHO this should go after #90310 (or at least 12a8422) so things can be tested with the generic example.

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

Signed-off-by: Nathan Winslow <natelostintimeandspace@gmail.com>

sonarqubecloud · 2025-05-27T14:13:56Z

Quality Gate passed

Issues
17 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

ttmut · 2025-07-21T12:28:28Z

Hi @LostinTimeandspaceYT,

Thanks for your contribution. Please refactor your commit title and body so that they adhere to Pull Request Guidelines.

See these examples:

You should also merge your commits into a single commit to retain bisectability as described in PR Requirements

Do not forget to address the compliance failures as well: https://github.com/zephyrproject-rtos/zephyr/actions/runs/15276958086/job/42967094398?pr=90356

ttmut · 2025-07-21T13:16:22Z

drivers/fuel_gauge/ltc2959/Kconfig

+config FUEL_GAUGE_LTC2959_RSENSE_MOHMS
+
+	depends on FUEL_GAUGE_LTC2959
+	int "Sense resistor value in milliohms"
+	default 80
+	help
+	  Set the value of the RSENSE resistor in milliohms.
+	  This is used to calculate the current and charge resolution.


This looks like a hardware parameter, so I suggest converting it into a devicetree property. See https://docs.zephyrproject.org/latest/build/dts/dt-vs-kconfig.html.

Agreed, I will move this into the binding.

ttmut · 2025-07-21T13:17:03Z

drivers/fuel_gauge/ltc2959/Kconfig

+config FUEL_GAUGE_LTC2959
+
+	depends on DT_HAS_ADI_LTC2959_ENABLED
+	bool "LTC2959 Fuel Gauge"
+	default y
+	select I2C
+	help
+	  Enable the LTC2959 fuel gauge driver from Analog Devices.


Suggested change

config FUEL_GAUGE_LTC2959

depends on DT_HAS_ADI_LTC2959_ENABLED

bool "LTC2959 Fuel Gauge"

default y

select I2C

help

Enable the LTC2959 fuel gauge driver from Analog Devices.

config FUEL_GAUGE_LTC2959

depends on DT_HAS_ADI_LTC2959_ENABLED

bool "LTC2959 Fuel Gauge"

default y

select I2C

help

Enable the LTC2959 fuel gauge driver from Analog Devices.

ttmut · 2025-07-21T13:21:45Z

drivers/fuel_gauge/ltc2959/ltc2959.c

+	const struct ltc2959_config *cfg = dev->config;
+	mask &= LTC2959_CC_WRITABLE_MASK;
+	mask |= LTC2959_CC_RESERVED_VALUE;
+	LOG_INF("setting cc to: 0x%02X", mask);


Suggested change

LOG_INF("setting cc to: 0x%02X", mask);

LOG_DBG("setting cc to: 0x%02X", mask);

ttmut · 2025-07-21T13:26:41Z

drivers/fuel_gauge/ltc2959/ltc2959.c

+	int ret = ltc2959_read16(dev, reg, &raw);
+
+	if (ret < 0) {
+		LOG_ERR("ERROR: %i", ret);


Could do with a verbose error message here.

ttmut · 2025-07-21T13:28:25Z

drivers/fuel_gauge/ltc2959/ltc2959.c

+#if 0
+static int ltc2959_get_props(const struct device *dev,
+			     fuel_gauge_prop_t *props,
+			     union fuel_gauge_prop_val *vals,
+			     size_t len)
+{
+
+	int ret;
+	for (size_t i = 0; i < len; ++i) {
+		ret = ltc2959_get_prop(dev, props[i], &vals[i]);
+		if (ret < 0) {
+			return ret;
+		}
+	}
+	return 0;
+
+}
+#endif


Do not introduce dead code.

Suggested change

#if 0

static int ltc2959_get_props(const struct device *dev,

fuel_gauge_prop_t *props,

union fuel_gauge_prop_val *vals,

size_t len)

{

int ret;

for (size_t i = 0; i < len; ++i) {

ret = ltc2959_get_prop(dev, props[i], &vals[i]);

if (ret < 0) {

return ret;

}

}

return 0;

}

#endif

ttmut · 2025-07-21T13:30:33Z

dts/bindings/fuel-gauge/adi,ltc2959.yaml

+  label:
+    required: true


Where do you use this?

It was being used in test code to verify the binding. I will remove this property

ttmut · 2025-07-21T13:31:17Z

dts/bindings/fuel-gauge/adi,ltc2959.yaml

+  alert-gpios:
+    type: phandle-array
+    description: |
+      Optional GPIO used for ALERT output. The LTC2959 pulls this pin low
+      when thresholds are crossed or charge events occur. Typically wired
+      to a host interrupt-capable GPIO pin.


This does not seem to be used anywhere.

@ttmut I will create a custom property to access the state of this pin.

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

sonarqubecloud · 2025-07-21T14:01:48Z

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

LostinTimeandspaceYT · 2025-07-21T16:03:31Z

Thank you @ttmut for reviewing this PR. I will have time later this week to work on the needed changes and consolidate the commits as per the guidelines.

DBS06

First of all, thanks for your contribution and overall it looks well done!
I also looked inside the datasheet and as far as I see you implemented every necessary/interesting feature from the IC. Interestingly, the IC does not provide a relative state of charge in percent, but it is what it is.

Please also add an e.g. ltc2959-emulation, for example emul_lc709203f.c, emul_max17048, or emul_bq27z746.c and also a test (look here), because this helps a lot to avoid possible future breaking changes and further increase the test coverage and quality of Zephyr.

DBS06 · 2025-07-22T06:43:53Z

drivers/fuel_gauge/ltc2959/ltc2959.h

+/* Used when ACR is controlled via firmware */
+#define LTC2959_ACR_CLR (0xFFFFFFFF)
+
+#ifdef CONFIG_FUEL_GAUGE_LTC2959_RSENSE_MOHMS


Should be done via Devicetree as stated here can be removed here

Thank you, these are helpful examples. I will add an emul and ztest.

DBS06 · 2025-07-22T06:51:06Z

drivers/fuel_gauge/ltc2959/ltc2959.h

+/* LTC2959 Register Map — from datasheet (Rev A) */
+
+/* Status and Control */
+#define LTC2959_REG_STATUS                  (0x00)


I would prefer to put all registers in an enum, see here for example.
Furthermore, except the enum ltc2959_custom_props and the registers, everything else (the constant values even including the struct ltc2959_config , etc.) can/should be moved to the ltc2959.c, because there is no need to have it in the public interface.

DBS06 · 2025-07-22T06:54:46Z

drivers/fuel_gauge/ltc2959/ltc2959.c

+
+	int ret = i2c_burst_read_dt(&cfg->i2c, reg, buf, sizeof(buf));
+
+	if (ret < 0) {


Suggested change

if (ret < 0) {

if (ret) {

but both ways are valid

DBS06 · 2025-07-22T07:00:08Z

drivers/fuel_gauge/ltc2959/ltc2959.c

+	case LTC2959_GPIO_MODE_ALERT:
+	case LTC2959_GPIO_MODE_CHGCOMP:


Suggested change

case LTC2959_GPIO_MODE_ALERT:

case LTC2959_GPIO_MODE_CHGCOMP:

If they are doing nothing, the default: branch is enough.

DBS06 · 2025-07-22T07:32:37Z

drivers/fuel_gauge/ltc2959/ltc2959.h

+	FUEL_GAUGE_VOLTAGE_HIGH_THRESHOLD,
+	FUEL_GAUGE_VOLTAGE_LOW_THRESHOLD,
+	FUEL_GAUGE_CURRENT_HIGH_THRESHOLD,
+	FUEL_GAUGE_CURRENT_LOW_THRESHOLD,
+	FUEL_GAUGE_TEMPERATURE_HIGH_THRESHOLD,
+	FUEL_GAUGE_TEMPERATURE_LOW_THRESHOLD,


For FUEL_GAUGE_VOLTAGE_LOW_THRESHOLD the FUEL_GAUGE_LOW_VOLTAGE_ALARM property already exists.
But nevertheless, I think it is valid to add the other 5 properties to the fuel_gauge.h interface, for me it seems legit to add them, because if we already have a low-voltage-alarm why not have a high-voltage-alarm.

I elected not to use FUEL_GAUGE_LOW_VOLTAGE_ALARM as that reports a percentage of charge. The purpose of these properties is for configuring bounds to trigger a fault in the status register. I am not sure how other ICs of this ilk operate, but I agree @DBS06, I think adding them would make sense.

@LostinTimeandspaceYT FUEL_GAUGE_LOW_VOLTAGE_ALARM is described in fuel_gauge.h as /** Low Cell Voltage Alarm (uV)*/ so it does not "reports a percentage of charge", I think you mismatch that with FUEL_GAUGE_STATE_OF_CHARGE_ALARM which is described as /** Remaining state of charge alarm (percent, 0-100) */.

@DBS06 You're right I did, classic off-by-1 😅

I could change the current FUEL_GAUGE_LOW_XXXX_THRESHOLD to FUEL_GAUGE_LOW_XXX_ALARM to have the property names be consistent with the current API.

I could change the current FUEL_GAUGE_LOW_XXXX_THRESHOLD to FUEL_GAUGE_LOW_XXX_ALARM to have the property names be consistent with the current API.

Exactly what I meant! You can keep the register names as it is and just adopt the property names (they are more or less generic names).

I started work on this driver in a project on v4.1.0 and it looks like the FUEL_GAUGE_LOW_VOLTAGE_ALARM property was added after that release. I noticed the discrepancy when attempting to build in that project. I Apologize for the confusion.

You don't need to apologize! That's why code reviews are for.

Yes, I added it after my last PR #90310, which went bigger than originally expected 🤔

Just a minor hint, if you are adding additional properties do that in a separate commit (look at the commits from here #90310) and it should be the first one, as far as I see you can squash all other currently existing commits into one commit. If you add a test for your driver do that in another commit. So basically in the end you have three commits which will be pushed in the main branch.

I hope this helps!

Add dts bindings for ltc2959 fuel_gauge.

6325b2f

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

github-actions bot added platform: ADI Analog Devices, Inc. area: Fuel Gauge labels May 22, 2025

github-actions bot requested review from aaronemassey, galak, MaureenHelm, microbuilder, ozersa, teburd, ttmut and yasinustunerg May 22, 2025 19:58

github-actions bot assigned MaureenHelm May 22, 2025

aaronemassey self-assigned this May 22, 2025

Nathan added 2 commits May 22, 2025 16:04

Added Kconfig settings for LTC2959 driver.

082da4e

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

Added CMakeLists.txt to LTC2959 driver.

7556b22

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

fmoessbauer reviewed May 22, 2025

View reviewed changes

Added Register macros & bitmasks.

febe681

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

Added implementation to Repo.

df906d9

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

kartben requested a review from Copilot May 23, 2025 07:06

This comment was marked as off-topic.

Sign in to view

Format changes to meet compliance.

7214aa5

Signed-off-by: Nathan Winslow <natelostintimeandspace@gmail.com>

LostinTimeandspaceYT changed the title ~~drivers: fuel_guage: Add support for Analog Devices LTC2959~~ drivers: fuelguage: Add ADI LTC2959 driver Jul 21, 2025

ttmut requested changes Jul 21, 2025

View reviewed changes

Merge branch 'zephyrproject-rtos:main' into drivers_ltc2959

9c27f75

zephyrbot requested a review from DBS06 July 21, 2025 13:36

Added dynamic compiling of ltc2959 lib.

3cbcfb9

Signed-off-by: Nathan <natelostintimeandspace@gmail.com>

DBS06 requested changes Jul 22, 2025

View reviewed changes

	LOG_INF("setting cc to: 0x%02X", mask);
	LOG_DBG("setting cc to: 0x%02X", mask);


		int ret = i2c_burst_read_dt(&cfg->i2c, reg, buf, sizeof(buf));

		if (ret < 0) {

		case LTC2959_GPIO_MODE_ALERT:
		case LTC2959_GPIO_MODE_CHGCOMP:

drivers: fuelguage: Add ADI LTC2959 driver #90356

Are you sure you want to change the base?

drivers: fuelguage: Add ADI LTC2959 driver #90356

Conversation

LostinTimeandspaceYT commented May 22, 2025

Uh oh!

github-actions bot commented May 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmoessbauer commented May 22, 2025

Uh oh!

This comment was marked as off-topic.

Uh oh!

sonarqubecloud bot commented May 27, 2025

Quality Gate passed

Uh oh!

ttmut commented Jul 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Jul 21, 2025

Quality Gate passed

Uh oh!

LostinTimeandspaceYT commented Jul 21, 2025

Uh oh!

DBS06 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DBS06 Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DBS06 Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DBS06 left a comment •

edited

Loading

DBS06 Jul 22, 2025 •

edited

Loading

DBS06 Jul 23, 2025 •

edited

Loading