Skip to content

feat(battery): opt-in eFuse-calibrated ADC read for ESP32 battery sense - #184

Open
gcormier wants to merge 3 commits into
OpenDisplay:mainfrom
gcormier:feat/esp32-adc-calibrated-battery
Open

gcormier wants to merge 3 commits into
OpenDisplay:mainfrom
gcormier:feat/esp32-adc-calibrated-battery

Conversation

@gcormier

@gcormier gcormier commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Adds an opt-in way for ESP32 boards to read the battery-sense pin with the chip's eFuse ADC calibration (analogReadMilliVolts()), so one voltage_scaling_factor fits every board of a model.

Today the battery voltage is raw_count * voltage_scaling_factor / 100000. Raw ESP32 ADC counts vary a few percent from chip to chip, so a factor tuned on one board reads off on the next. Two original M5Papers with the same preset (factor 174) read 4.20 V and 4.10 V for full cells.

Changes

  • include/opendisplay_structs.h: new OD_BATTERY_SENSE_FLAG_CALIBRATED_MV (bit 1 of PowerOption.battery_sense_flags, carved from reserved; no layout change). With the bit set, voltage_scaling_factor is the divider ratio x1000 and V = calibrated_pin_mV * factor / 1e6 (2000 = 2:1). With the bit clear, the formula is unchanged. Changelog entry under Unreleased. This still needs to land in opendisplay-protocol.
  • src/display_service.cpp (readBatteryVoltageUncached()): with the bit set on ESP32, the 10 samples use analogReadMilliVolts(). Same sample count, delays and 30 s cache. On non-ESP32 targets the bit makes the voltage "unknown" (-1) with a one-time warning, rather than applying a x1000 ratio to a raw count. A zero factor now returns -1 before pulsing the enable pin; same result as before.
  • src/config_parser.cpp: the config dump prints the new bit.
  • tools/od-device-cli.py: comments only (the field is a plain u8).
  • docs/FINDINGS_ESP32_ADC_CALIBRATED_2026-11-11.md: the hardware A/B below. Drop it if you'd rather not keep it in the repo.

Why a flag instead of changing what the factor means: every deployed config and every toolbox preset holds a factor tuned for raw counts. The firmware cannot tell which unit a stored factor is in, so a silent switch would break the battery reading of every ESP32 board (174 under the new formula is ~0.4 V).

Order of rollout: firmware that predates this ignores the bit, so a calibrated config on old firmware reads ~48 V. The toolbox preset change (M5Paper: battery_sense_flags 0x2, voltage_scaling_factor 1999) should only ship after a release that contains this.

Testing

Hardware: one original M5Paper (ESP32-D0WDQ6-V3, GPIO35 through a 2:1 divider), A/B by switching the config over BLE.

  • On battery, charger out of the loop, cell 3-27 min off the charger: calibrated (factor 1999) 4.20, 4.19, 4.20 V; legacy (factor 174) 4.11, 4.10, 4.11, 4.10 V; calibrated again 4.19 V. The bracket rules out cell drift.
  • On USB after charging: calibrated 4.23-4.24 V, legacy 4.13 V.
  • Factor 1999 comes from a second M5Paper: 2101 mV at the pin (calibrated read) for a 4.20 V cell.
  • All 12 CI targets build.

Not tested:

  • Against a multimeter.
  • Lower in the discharge curve (3.3-3.8 V).
  • ESP32-S3/C3/C6 (different calibration schemes) and any board other than the M5Paper.
  • The first reading after a boot is sometimes high (seen with both paths, clears at the next 30 s refresh); not investigated.

Found while doing this, not fixed here: OD_BATTERY_SENSE_FLAG_ENABLE_INVERTED (bit 0) is only logged. readBatteryVoltageUncached() always drives the enable pin HIGH then LOW, so active-low enables (e.g. XIAO ~READ_BAT) are not honoured.

Toolbox preset (draft until this ships in a release): OpenDisplay/opendisplay.org#207

Raw ESP32 ADC counts vary several percent chip to chip, so one
voltage_scaling_factor cannot fit every board of a model (two M5Papers on
the same factor read 4.20 V vs up to 4.33 V on USB).

Add BatterySenseFlags bit1 OD_BATTERY_SENSE_FLAG_CALIBRATED_MV. When set,
ESP32 reads the sense pin with analogReadMilliVolts() (core eFuse
calibration) and voltage_scaling_factor is the divider ratio x1000:
V = mV * factor / 1e6 (2000 = 2:1). When clear, the legacy meaning
V = raw_count * factor / 1e5 is unchanged, so every deployed config reads
exactly as before. Non-ESP32 targets report the voltage as unknown (-1)
with a one-time warning if the bit is set. Sample count, delays and the
30 s cache are unchanged.

Also documents the bit in opendisplay_structs.h (Unreleased changelog,
field @doc), logs it in the config dump, and notes the two meanings in
tools/od-device-cli.py.

Builds clean on all 12 envs in .github/firmware-targets.json.
NOT verified on hardware: no device was flashed or measured.
Checked on one M5Paper (the bathroom board) on USB, comparing the calibrated and legacy paths via the advertised voltage: calibrated 4.23-4.24 V, legacy 4.13 V. NOT checked against a multimeter, so absolute accuracy is unverified.
With the charger out of the loop the calibrated path read 4.19-4.20 V and the legacy path 4.10-4.11 V on the same M5Paper, bracketed by switching methods over BLE. No multimeter reading.
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