Repository navigation
Conversation
… 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.
This was referenced Nov 13, 2026
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 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 withvoltage_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_flagsbit1 (OD_BATTERY_SENSE_FLAG_CALIBRATED_MV) is set, ESP32 targets averageanalogReadMilliVolts(). That applies the chip's eFuse calibration: curve fitting on S3/C3/C6, line fitting on classic ESP32.voltage_scaling_factorthen becomes the divider ratio × 1000:V = pin_mV × factor / 1000, so a 2:1 divider is2000. The ratio depends only on the resistors, so one value is right for every unit of a board.#ifdef TARGET_ESP32).config_parser.cpplogsCALIBRATED_MVnext toENABLE_INVERTED.include/opendisplay_structs.his re-vendored withtools/sync_protocol_header.pyfrom the protocol PR, and is byte-identical to it. The only additions compared withmainare bit1 and PanelIC 77.Testing
esp32-s3-N16R8,esp32-wrover-e-N4R8(classic ESP32, line fitting),esp32-c3-N4,esp32-c6-N4,nrf52840custom(checks the non-ESP32 guard).CALIBRATED_MV, ratio 2000Compatibility note for presets
Firmware without this change ignores bit1, so it would apply a ratio-style factor like
2000as 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)