Repository navigation
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an opt-in way for ESP32 boards to read the battery-sense pin with the chip's eFuse ADC calibration (
analogReadMilliVolts()), so onevoltage_scaling_factorfits 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: newOD_BATTERY_SENSE_FLAG_CALIBRATED_MV(bit 1 ofPowerOption.battery_sense_flags, carved from reserved; no layout change). With the bit set,voltage_scaling_factoris the divider ratio x1000 andV = 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 useanalogReadMilliVolts(). 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_flags0x2,voltage_scaling_factor1999) 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.
Not tested:
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