DEV Community

Cover image for What Battery Telemetry Can—and Cannot—Tell Developers About Laptop Battery Health
lee
lee

Posted on

What Battery Telemetry Can—and Cannot—Tell Developers About Laptop Battery Health

#hardware #linux #debugging #battery

Battery percentage is useful. Battery health is useful. Neither tells you the whole story.

As developers, we usually meet the laptop battery through software.

On Windows, we may run:

powercfg /batteryreport
Enter fullscreen mode Exit fullscreen mode

On Linux, we might start with:

upower -e
upower -i /org/freedesktop/UPower/devices/battery_BAT0
Enter fullscreen mode Exit fullscreen mode

Or go directly to sysfs:

cat /sys/class/power_supply/BAT0/capacity
cat /sys/class/power_supply/BAT0/status
cat /sys/class/power_supply/BAT0/voltage_now
Enter fullscreen mode Exit fullscreen mode

These tools can expose surprisingly useful battery information. Linux's power-supply class, for example, provides a standard interface through which drivers can expose properties such as voltage, current, charge, energy, capacity, and status when the underlying hardware supports them.

But there is an important limitation:

The operating system is showing you information about the battery system. It is not directly observing the electrochemistry inside the cells.

That distinction matters when you're debugging battery health, unexpected shutdowns, poor runtime, or power-related instability.

Let's look at what battery telemetry can tell us—and where developers need to stop treating software data as ground truth.

First: What Does “Battery Health” Actually Mean?

A typical laptop exposes several battery-related values:

  • state of charge
  • design capacity
  • estimated full-charge capacity
  • voltage
  • charging/discharging state
  • energy or charge remaining
  • current or power draw
  • sometimes cycle information
  • sometimes temperature

The exact properties depend on the laptop, firmware, battery-management hardware, operating system, and driver support.

For Linux systems, UPower provides an abstraction over power devices and can expose battery properties, history, and statistics to applications.

Developers often turn two values into a simple battery-health estimate:

Estimated Health ≈ Full Charge Capacity / Design Capacity × 100%
Enter fullscreen mode Exit fullscreen mode

So if:

Design Capacity      = 60 Wh
Full Charge Capacity = 48 Wh
Enter fullscreen mode Exit fullscreen mode

the rough result is:

48 / 60 × 100% = 80%
Enter fullscreen mode Exit fullscreen mode

Useful?

Yes.

A complete battery diagnosis?

Definitely not.

It tells you how the system currently estimates usable full-charge capacity relative to its original reference value.

It does not explain why that number changed.

Your Battery Percentage Is an Estimate

When your laptop says:

Battery: 63%
Enter fullscreen mode Exit fullscreen mode

there isn't a sensor inside the cell literally measuring “63% lithium remaining.”

A battery fuel gauge estimates state of charge using measurements and models.

Depending on the fuel-gauge architecture, those calculations may use combinations of:

  • voltage
  • current
  • integrated charge
  • temperature
  • cell characteristics
  • internal resistance
  • previous charge/discharge behavior

Texas Instruments, for example, describes fuel-gauge algorithms that use measured battery behavior, impedance, load, temperature, and chemical-capacity estimates to predict state of charge and available capacity.

So think of battery percentage as:

sensor data
    +
battery model
    +
historical data
    ↓
estimated state of charge
Enter fullscreen mode Exit fullscreen mode

not:

direct measurement
    ↓
exact state of charge
Enter fullscreen mode Exit fullscreen mode

That's an important mental model when debugging.

What Telemetry Is Good At

Battery telemetry is extremely useful when you're looking for patterns.

For example, suppose users report:

“The laptop sometimes shuts down even when the battery says 30%.”

One data point isn't very helpful.

A time-series log can be.

Imagine capturing:

Timestamp:        14:32:18
SOC:              31%
Battery voltage:  11.2 V
Battery current:  1.1 A
CPU load:         24%
GPU load:         8%
Temperature:      normal
Enter fullscreen mode Exit fullscreen mode

Then:

Timestamp:        14:32:24
SOC:              30%
Battery voltage:  10.4 V
Battery current:  4.2 A
CPU load:         91%
GPU load:         76%
Event:            application started inference workload
Enter fullscreen mode Exit fullscreen mode

Then:

Timestamp:        14:32:25
System reset
Enter fullscreen mode Exit fullscreen mode

Now you have something interesting.

You haven't proven the battery is defective.

But you've established a correlation:

high system load
→ high battery current
→ voltage drop
→ shutdown
Enter fullscreen mode Exit fullscreen mode

That's far more useful than:

“Battery was at 30% when the computer crashed.”

Telemetry Is Best When Correlated With System Events

If you're building a portable computer, embedded Linux device, edge-AI terminal, or similar battery-powered system, don't log battery data in isolation.

Log battery state together with what the device was doing.

For example:

{
  "timestamp": "2026-08-19T14:32:24",
  "battery_soc": 30,
  "battery_voltage": 10.4,
  "battery_current": 4.2,
  "battery_temperature": 37.5,
  "cpu_load": 91,
  "gpu_load": 76,
  "display_brightness": 80,
  "radio_state": "tx",
  "charger_connected": false,
  "system_event": "ai_inference_started"
}
Enter fullscreen mode Exit fullscreen mode

The exact fields aren't important.

The correlation is.

Useful variables might include:

battery SOC
battery voltage
battery current
battery temperature
charging state
CPU load
GPU load
radio state
display brightness
fan state
application state
suspend/resume events
shutdown/reset events
Enter fullscreen mode Exit fullscreen mode

With that information, “battery issue” becomes a much more testable engineering hypothesis.

Windows: Start With Battery Report

Windows includes a useful built-in command:

powercfg /batteryreport
Enter fullscreen mode Exit fullscreen mode

Microsoft documents /batteryreport as an option that generates a report of battery usage.

You can also specify an output path:

powercfg /batteryreport /output "%USERPROFILE%\Desktop\battery-report.html"
Enter fullscreen mode Exit fullscreen mode

For debugging, don't look at a single number and stop.

Look for trends.

Questions worth asking include:

  • Is estimated capacity declining gradually or suddenly?
  • Did poor runtime start after a software or firmware change?
  • Does abnormal behavior occur only on battery power?
  • Does the issue appear near low state of charge?
  • Is runtime dramatically different under particular workloads?
  • Does the machine fail under bursts of load rather than steady load?

Battery-report data becomes much more valuable when combined with application and system logs.

Linux: You Can Get Closer to the Raw Interface

Linux makes battery debugging especially interesting because the kernel power-supply subsystem can expose battery properties through sysfs.

Start by checking:

ls /sys/class/power_supply/
Enter fullscreen mode Exit fullscreen mode

You may see something like:

AC
BAT0
Enter fullscreen mode Exit fullscreen mode

Then inspect the available battery properties:

ls /sys/class/power_supply/BAT0/
Enter fullscreen mode Exit fullscreen mode

Depending on the hardware and driver, you may find properties such as:

capacity
status
voltage_now
current_now
energy_now
energy_full
energy_full_design
charge_now
charge_full
charge_full_design
technology
Enter fullscreen mode Exit fullscreen mode

Not every battery exposes every property.

That point matters.

Missing telemetry does not necessarily mean missing hardware functionality. It may simply mean that a particular value is not exposed through that driver/interface.

You can quickly inspect available values with something like:

BAT=/sys/class/power_supply/BAT0

for f in \
  status \
  capacity \
  voltage_now \
  current_now \
  energy_now \
  energy_full \
  energy_full_design
do
  if [ -f "$BAT/$f" ]; then
    printf "%-20s " "$f"
    cat "$BAT/$f"
  fi
done
Enter fullscreen mode Exit fullscreen mode

For higher-level access, UPower can also enumerate devices and display available properties:

upower -e
Enter fullscreen mode Exit fullscreen mode

then:

upower -i /org/freedesktop/UPower/devices/battery_BAT0
Enter fullscreen mode Exit fullscreen mode

UPower also supports monitoring power-source changes, making it useful for development and diagnostic workflows.

Now the Important Part: What Telemetry Cannot Tell You

This is where battery debugging often goes wrong.

Suppose your application sees:

SOC = 42%
Voltage = normal
Battery status = discharging
Enter fullscreen mode Exit fullscreen mode

Can you conclude that the battery is physically healthy?

No.

Standard operating-system telemetry generally cannot directly tell you:

1. Whether a pouch cell is physically swelling

Software may eventually show secondary symptoms.

But your API does not visually inspect the battery.

Mechanical swelling is a physical condition.

2. Whether a connector has excessive resistance

A damaged connector, weak crimp, poor contact, cable problem, or other interconnect issue may cause voltage drop under load.

Your logs may reveal the symptom.

They don't automatically identify the connector as the root cause.

3. Whether one cell in a multi-cell pack is behaving differently

Some sophisticated battery systems expose detailed cell-level information.

Many standard OS interfaces do not.

A pack-level voltage can hide useful cell-level detail.

4. Whether the battery protection circuit triggered

You may observe:

power disappeared
Enter fullscreen mode Exit fullscreen mode

but that doesn't automatically tell you:

overcurrent protection triggered
Enter fullscreen mode Exit fullscreen mode

unless your battery-management hardware and firmware explicitly expose that information.

5. Whether a thermal issue is caused by the battery or its environment

Suppose battery temperature rises.

Possible causes include:

high charge current
high discharge current
poor ventilation
nearby CPU/GPU heat
charging circuitry
cell behavior
mechanical enclosure design
Enter fullscreen mode Exit fullscreen mode

Temperature telemetry tells you what happened.

Not necessarily why.

A “Healthy” Capacity Number Doesn't Guarantee Good Power Delivery

Here's another subtle problem.

Imagine two batteries.

Both report:

Full Charge Capacity = 90% of Design Capacity
Enter fullscreen mode Exit fullscreen mode

Would they necessarily perform identically during a heavy workload?

No.

Capacity tells you about stored charge or energy.

A high-power event introduces another question:

Can the battery system deliver the required current while maintaining acceptable voltage?

A battery-powered device might be perfectly stable at:

1 A
Enter fullscreen mode Exit fullscreen mode

but experience a severe voltage drop during a short:

4 A
Enter fullscreen mode Exit fullscreen mode

event.

That becomes especially relevant in modern portable systems where loads can change quickly:

CPU boost
GPU workload
AI inference
wireless transmission
camera activation
display brightness change
USB peripheral startup
Enter fullscreen mode Exit fullscreen mode

This is why developers debugging power failures should care about load profiles, not just battery percentage.

Don't Debug “The Battery.” Debug the Power Path.

Laptop battery power path debugging diagram showing load spike voltage drop and system reset

A portable computer's power architecture is more like:

Battery cells
     ↓
Protection / battery electronics
     ↓
Connector + wiring
     ↓
System power path
     ↓
DC/DC converters
     ↓
CPU / GPU / display / radio / peripherals
Enter fullscreen mode Exit fullscreen mode

A failure anywhere along that chain can look like:

battery problem

from software.

For developers, a better question is:

What changed immediately before the power event?

For example:

Did current spike?
Did voltage fall?
Did temperature rise?
Did the charger disconnect?
Did CPU/GPU load change?
Did wireless transmission begin?
Did the system change power state?
Did a peripheral turn on?
Enter fullscreen mode Exit fullscreen mode

That moves debugging from assumption to evidence.

Laptop Battery Health Is a System-Level Problem

Laptop batteries are particularly interesting because they connect several engineering disciplines:

electrochemistry
        +
battery management
        +
power electronics
        +
embedded firmware
        +
operating system
        +
application workload
Enter fullscreen mode Exit fullscreen mode

That's also why a battery issue can become a developer issue.

A change in software workload can change power consumption.

Power consumption changes battery current.

Battery current changes voltage behavior and heat generation.

Those conditions influence how the overall battery system behaves.

Teams developing portable computers should therefore think about laptop battery design as part of system architecture rather than treating the battery as an isolated component added after the PCB and software are mostly finished.

A Better Battery Debugging Workflow

Here's the workflow I'd use when investigating an unexplained battery-powered shutdown.

Step 1: Reproduce the event

Find a workload that consistently produces the problem.

For example:

Start at ~35% SOC
Unplug charger
Run GPU workload
Enable Wi-Fi transfer
Set display brightness to 100%
Enter fullscreen mode Exit fullscreen mode

Consistency makes debugging dramatically easier.

Step 2: Capture battery telemetry

At minimum:

SOC
voltage
current/power
temperature if available
charging state
Enter fullscreen mode Exit fullscreen mode

Step 3: Capture system telemetry

Add:

CPU usage
GPU usage
radio activity
display state
power mode
application events
Enter fullscreen mode Exit fullscreen mode

Step 4: Put everything on one timeline

You want:

14:32:20  SOC 31%   current 1.1A
14:32:22  inference starts
14:32:23  CPU 95%
14:32:23  GPU 82%
14:32:24  current rises
14:32:24  voltage falls
14:32:25  system resets
Enter fullscreen mode Exit fullscreen mode

Now you have an event sequence.

Step 5: Repeat at different conditions

Try varying:

SOC
temperature
workload
charger state
power profile
Enter fullscreen mode Exit fullscreen mode

If the issue consistently occurs under the same electrical conditions, you've narrowed the search considerably.

Step 6: Move to hardware validation

Eventually software telemetry reaches its limit.

At that point, debugging may require:

  • direct voltage measurement
  • current measurement
  • oscilloscope capture
  • connector inspection
  • thermal measurement
  • battery test equipment
  • pack or cell-level data
  • protection-event analysis

This is the point where software logs should become input to hardware engineering, not a substitute for it.

What Developers Should Send the Battery Engineer

Bad bug report:

Battery sometimes dies at 30%.
Enter fullscreen mode Exit fullscreen mode

Better bug report:

Device shuts down between 28–34% reported SOC.

Occurs only when charger is disconnected.

Reproduced 7/10 times during AI inference + Wi-Fi transmission.

Immediately before shutdown:
- current increases sharply
- battery voltage drops
- CPU load >90%
- battery temperature remains within normal observed range

Does not reproduce above 60% SOC under the same workload.
Enter fullscreen mode Exit fullscreen mode

Now the engineer has somewhere to start.

If you're developing custom hardware, include the battery specification too:

cell/pack configuration
nominal voltage
capacity
continuous current requirement
peak current
peak duration
connector
wire gauge
protection circuit
charging configuration
operating temperature
Enter fullscreen mode Exit fullscreen mode

When troubleshooting crosses from application behavior into pack-level electrical behavior, sharing this data with a lithium battery manufacturer or battery engineer is much more useful than simply reporting that “battery health looks low.”

Telemetry Can Help You Find the Question—Not Always the Answer

This is the biggest takeaway.

Battery telemetry is excellent for answering questions such as:

When does the problem occur?

What was the battery doing immediately before the event?

Is the problem correlated with SOC?

Is voltage changing with workload?

Is runtime getting worse over time?

Does the problem happen only during peak load?

But telemetry alone often cannot answer:

Which physical component is failing?

Is the cell damaged?

Is the connector resistance too high?

Did protection activate?

Is there an internal mechanical problem?

Is the battery thermally compromised?

Those questions require hardware evidence.

The Developer's Mental Model

Battery telemetry data stack from lithium battery sensors and BMS to firmware operating system and developer application

Instead of thinking:

Battery API → Battery Truth
Enter fullscreen mode Exit fullscreen mode

think:

Physical Battery
      ↓
Sensors
      ↓
Fuel Gauge / BMS
      ↓
Firmware / Driver
      ↓
OS Power Interface
      ↓
Your Application
Enter fullscreen mode Exit fullscreen mode

Every layer adds useful information.

Every layer also defines what information you can actually see.

That's why:

Battery = 37%
Enter fullscreen mode Exit fullscreen mode

is useful.

But:

SOC 37%
+ voltage trend
+ current trend
+ temperature
+ workload
+ system events
+ hardware specification
Enter fullscreen mode Exit fullscreen mode

is much closer to an engineering diagnosis.

Final Takeaway

Developers don't need to become battery chemists to debug battery-powered systems effectively.

But they do need to understand one principle:

Software telemetry is an observation layer, not a physical inspection of the battery.

Use it to detect patterns.

Use it to correlate workload with power behavior.

Use it to reproduce failures.

Use it to create better bug reports.

And when the evidence points below the operating-system layer, bring the logs with you when the investigation moves to firmware, power electronics, or battery engineering.

Because the most useful question is rarely:

“Is the battery healthy?”

It's usually:

“What was the complete power system doing when the failure occurred?”

Top comments (0)