Skip to content

feat(battery): opt-in calibrated ADC read on ESP32 (BatterySenseFlags CALIBRATED_MV) - #186

Open
gcormier wants to merge 1 commit into
OpenDisplay:mainfrom
gcormier:greg/battery-calibrated-mv
Open

gcormier wants to merge 1 commit into
OpenDisplay:mainfrom
gcormier:greg/battery-calibrated-mv

Conversation

@gcormier

@gcormier gcormier commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Adds an opt-in calibrated ADC read for battery sensing on ESP32. The flag is defined in OpenDisplay/opendisplay-protocol#16.

The problem

readBatteryVoltageUncached() reads a raw, uncalibrated ADC count and scales it with voltage_scaling_factor (V = raw × factor / 100000). The ESP32's raw transfer curve varies by a few percent between chips, so every board preset's factor has had to be tuned against a meter, and it still carries the error of the unit it was tuned on.

On a RockBase NM-EPD-420 with a fully charged LiPo on USB, the preset's factor of 161 reads 4.02 V. Home Assistant's Li-ion table shows that as 80%, permanently.

The change

When power_option.battery_sense_flags bit1 (OD_BATTERY_SENSE_FLAG_CALIBRATED_MV) is set, ESP32 targets average analogReadMilliVolts(). That applies the chip's eFuse calibration: curve fitting on S3/C3/C6, line fitting on classic ESP32. voltage_scaling_factor then becomes the divider ratio × 1000: V = pin_mV × factor / 1000, so a 2:1 divider is 2000. The ratio depends only on the resistors, so one value is right for every unit of a board.

  • Bit clear: nothing changes. Existing presets keep working.
  • Non-ESP32 targets: the bit is ignored (#ifdef TARGET_ESP32).
  • config_parser.cpp logs CALIBRATED_MV next to ENABLE_INVERTED.
  • include/opendisplay_structs.h is re-vendored with tools/sync_protocol_header.py from the protocol PR, and is byte-identical to it. The only additions compared with main are bit1 and PanelIC 77.

Testing

  • Builds: esp32-s3-N16R8, esp32-wrover-e-N4R8 (classic ESP32, line fitting), esp32-c3-N4, esp32-c6-N4, nrf52840custom (checks the non-ESP32 guard).
  • Hardware, NM-EPD-420 (ESP32-S3), same battery and same session:
Path Config Reading
legacy (2.27.1) factor 161 4.02 V
calibrated (this PR) CALIBRATED_MV, ratio 2000 4.17 V, matches a multimeter

Compatibility note for presets

Firmware without this change ignores bit1, so it would apply a ratio-style factor like 2000 as a raw-count factor (about 51 V). Presets should only switch once the bundled firmware includes this. The NM-EPD-420 preset change is held as a draft for that reason.

Side finding, not changed here

OD_BATTERY_SENSE_FLAG_ENABLE_INVERTED (bit0) is defined and logged, but this function always drives the enable pin HIGH, so active-low enables aren't honoured. I've left that for a separate fix.

Related: Firmware_Unified OpenDisplay/Firmware_Unified#93 · opendisplay.org OpenDisplay/opendisplay.org#210 (docs), OpenDisplay/opendisplay.org#211 (NM-EPD-420 preset, draft)

… CALIBRATED_MV)

The battery-sense path reads a raw, uncalibrated ADC count and scales it
with voltage_scaling_factor (V = raw * factor / 100000). The ESP32 ADC's
raw transfer curve differs by a few percent between chips, so each board
preset's factor has had to be tuned against a meter, and still carries
the error of the unit it was tuned on. On an NM-EPD-420 with a fully
charged cell on USB, the stock factor 161 reads 4.02 V (Home Assistant:
80%); the calibrated read with the 2:1 ratio (2000) reads 4.17 V, which
matches a multimeter on the same battery.

When power_option.battery_sense_flags has CALIBRATED_MV (bit1) set, ESP32
targets average analogReadMilliVolts(), which applies the chip's eFuse
calibration (curve fitting on S3/C3/C6, line fitting on classic ESP32),
and voltage_scaling_factor is the divider ratio x1000:
V = pin_mV * factor / 1000 (a 2:1 divider is 2000). The ratio depends only
on the resistors, so one value is correct for every unit of a board.

With the bit clear nothing changes, so existing presets keep working;
their factors fold each board's ADC error into the number and cannot be
converted without the hardware. Non-ESP32 targets ignore the bit.

Vendors opendisplay_structs.h from opendisplay-protocol (bit1, plus
PanelIC 77 OD_PANEL_IC_EP42R3_400X300), synced with
tools/sync_protocol_header.py.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant