Add persistent battery ADC calibration across boards

Add meter-reference calibration with saved ADC corrections, checked persistence and rollback. Preserve existing board coefficients and nRF52 voltage policy, and merge the Mini Repeater feature gates.

Validation: 69 focused tests, hosted documentation checks, and four firmware builds passed. Mini Repeater retains calibration and its existing filesystem with 376 flash bytes free; earlier Mini Sensor size failures remain documented.
This commit is contained in:
mikecarper committed 2026-10-22 18:56:32 -07:00
1 parent 94a3b7e568
commit ab6412e73c
108 files changed
+1303 -83

No files matched your search

+49 -3
View File
@@ -2526,6 +2526,49 @@ sessions. Setting the password to `off` makes it the literal password `off`.
---
#### Calibrate the battery reading against a meter
**Availability:** Repeater, Room Server, Sensor, Companion and Terminal Chat
firmware on boards with a supported battery ADC. Use an administrative CLI
connection; infrastructure roles also accept authenticated remote commands.
```text
battery calibrate 4.18
get adc.multiplier
battery calibrate reset
```
Measure the battery voltage with a voltmeter and enter that reading in volts.
The firmware calculates `new multiplier = current multiplier * meter voltage /
reported voltage`, applies it and saves it for restart. A reference is required;
the command does not assume a chemistry or a 4.2 V full battery. Enter the voltage
of the battery input the board actually measures, including pack voltage where
that input supports a pack. For example, `battery calibrate 13.2` supplies a
13.200 V reference; it does not change the board's measurement range.
Calibration supports the ESP32, nRF52, RP2040 and STM32 boards with implemented
battery-voltage ADC conversions, including the Wio Tracker L2's external ADS1115.
An unsupported board or unavailable/saturated reading returns an error. Digital
PMU/fuel-gauge and battery-module readings retain their hardware scaling; boards
without a battery-voltage input cannot be calibrated through this command.
The meter reference must be within 50% of the reported voltage. Newly supported
ADCs accept a relative multiplier from `0.500` to `1.500`, where `1.000` retains
their original conversion. Existing board-specific absolute multipliers and
saved values keep their established meaning. The five legacy absolute drivers
are Heltec V4, V4 R8, RC32, Meshnology W12 and ProMicro.
`battery calibrate reset` restores and saves the board's default conversion.
`set adc.multiplier 0` also resets it. A successful numeric calibration reply shows the effective
multiplier, including any rounding by the board. A failed save reports an error
and attempts to restore the previous runtime setting.
Calibration corrects voltage reporting and the battery percentages/protection
that use that reading. On nRF52 boards with voltage policy it also applies to
the boot reading and running cutoff. It does not adjust charger hardware or
create a current measurement. This is a single-point scale correction, not an
ADC offset or nonlinear calibration.
#### Fine-tune the battery reading
**Usage:**
- `get adc.multiplier`
@@ -2536,13 +2579,16 @@ sessions. Setting the password to `off` makes it the literal password `off`.
**Default:** `0.0` (value defined by board)
**Note:** On nRF52 boards with power management and a boot-voltage setting,
**Note:** On newly supported ADC boards this is a relative `0.500`-`1.500`
correction, with `0` restoring the default. Existing absolute-multiplier boards
retain their coefficient units and accept `0` or a positive value up to `10`.
On nRF52 boards with power management and a boot-voltage setting,
this is a saved *relative* calibration: `1.000` keeps the board conversion,
`1.050` raises all reported battery millivolts by 5%, and `0` resets to
`1.000`. The allowed range is `0.500`-`1.500`. This affects boot protection,
running cutoff, telemetry, battery alerts, and percentage. Calibrate against a
voltmeter before enabling a low cutoff. Other boards retain their existing
board-specific multiplier behavior, or return unsupported.
voltmeter before enabling a low cutoff. Boards without a supported ADC return
unsupported.
---
@@ -0,0 +1,119 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/test-results/battery_calibration_2026-10-22/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# Shared battery ADC calibration validation - 2026-10-22
Final integration baseline: `94a3b7e568781533510721670af24c162804a5ca` on
`keymindCascade`, plus the calibration changes. Earlier builds and link
failures below used `af106a0ee9edd8ee0113b7b364290e0944245b86`; the final
integration section supersedes those results for the targets it names.
These checks do not constitute an installed-device or voltmeter acceptance test.
## Behavior and compatibility
- `battery calibrate <measured volts>` calculates the correction from the
effective existing multiplier and the reported battery voltage.
- A reference is mandatory, with millivolt precision and no assumed battery
chemistry or full voltage. A single correction must lie within 50% of the
reported reading. Zero and saturated readings are rejected.
- `battery calibrate reset` saves the board's default conversion.
- Real ADC backends across ESP32, nRF52, RP2040 and STM32 opt into calibration.
The Wio Tracker L2's external ADS1115 is included. Boards requiring an external
divider still require that hardware; software does not add an input.
- Existing absolute coefficients for Heltec V4, V4 R8, RC32, Meshnology W12 and
ProMicro retain their units and saved values. Other supported ADCs use a
relative correction of 0.500-1.500, with zero restoring their factory scale.
- The nRF52 boot-voltage policy remains authoritative where available, and is
applied once. Without that policy, ADC commands use the shared correction.
- Infrastructure roles restore their existing calibration preference centrally,
including Repeater. Companion and Terminal use a checked, versioned
`/battery_cal` record without changing their existing preference layouts.
- Failed saves attempt to restore the runtime multiplier. An uncertain
publication returns an error rather than claiming persistence. Volatile
recovery storage is not used for saving calibration.
- PMU/fuel-gauge readings, UART battery-module readings, raw-count test
placeholders and boards with no battery-voltage measurement remain excluded.
## Host checks
All following checks passed using `TMPDIR=/var/tmp` (the machine's `/tmp` user
quota prevented compiler temporary-file creation):
| Check | Coverage |
| --- | --- |
| `test/test_battery_calibration.py` - 3 tests | Production parsing, meter correction, existing absolute coefficients, pack references, effective multiplier, reset, unsupported/zero/saturated readings, bounds, actual MainBoard scaling and nRF52 policy precedence. |
| `test/test_battery_calibration_store.py` - 1 test across four platform fixtures | ESP32, RP2040, nRF52 and STM32 transaction implementations; reboot restore, every single-bit record corruption, truncation, write failure, uncertain publication, reset, missing persistent storage and backup recovery. |
| `test/test_battery_forwarding.py` - 19 tests | Actual infrastructure setter, failed-save rollback, nRF52 policy fallback, and refreshed battery-based forwarding decisions. |
| `test/test_heltec_r8_external_power.py` - 1 test | Existing R8 power estimate still uses the calibrated voltage. |
| `test/test_stm32_companion_profile.py` - 21 tests | Existing ADC conversion and sampling remain exact at default calibration; memory/profile constraints retained. |
| `test/test_rp2040_application_capabilities.py` - 11 tests | Existing upload artifact and capability validation. |
The production calibration, store and forwarding harnesses use AddressSanitizer
and UndefinedBehaviorSanitizer. `git diff --check` also passed.
## Earlier firmware builds
Before integration, PlatformIO processes were run serially. Successful targets:
- `Heltec_v3_repeater`
- `Heltec_v3_terminal_chat`
- `Heltec_v3_companion_radio_usb`
- `RAK_3401_repeater`
- `RAK_3401_room_server`
- `RAK_3401_sensor`
- `RAK_3401_companion_radio_usb`
- `Xiao_rp2040_companion_radio_usb`
- `wio-e5-mini_companion_radio_usb`
That earlier Mini Companion occupied 228,832 of 229,376 application bytes:
544 bytes remained. This validates the current build recipe, not every possible version
string, optional feature combination or firmware target.
## Earlier STM32 flash blockers
The following targets compile but fail the linker flash limit. Both failures
were reproduced from an isolated, unchanged checkout of the baseline with the
same build recipes and compiler versions:
| Target | Baseline overflow | Calibration build overflow | Additional bytes |
| --- | ---: | ---: | ---: |
| `wio-e5-mini_repeater` | 1,168 | 2,852 | 1,684 |
| `wio-e5-mini_sensor` | 25,584 | 27,368 | 1,784 |
The calibration increase consists of code and constants; it did not introduce
additional floating-point runtime helpers in the Repeater. Filesystem and
application boundaries have not been moved, and no unrelated feature was
removed to conceal these build failures. These results apply to the earlier source baseline above, before the Mini
Repeater feature gates in `94a3b7e56`. The integration checks below supersede
that earlier Repeater result when a newer build succeeds.
## Final integration checks
After merging `94a3b7e56`, 69 distinct focused tests passed: 42 calibration,
platform-storage and related regressions, 19 battery-forwarding tests, and
8 Mini Repeater profile checks. The 23 calibration/store/forwarding tests
were rerun successfully after the final reply compaction. Both new calibration
suites are included in the unit-test workflow.
The first integrated Mini Repeater link exceeded flash by 432 bytes.
Disabling guessed branch probabilities in that target's existing size recipe,
sharing the existing save-failure replies, keeping the command key in constant
storage and shortening calibration replies recovered 808 bytes. Calibration,
routing, logging, 50 neighbours and the existing 16 KiB filesystem are retained.
No extra feature was disabled to make this image fit.
The final merged-source builds passed their flash and runtime-memory checks:
| Target | Application bytes used | Application limit | Free flash bytes |
| --- | ---: | ---: | ---: |
| `Heltec_v3_repeater` | 1,890,881 | 3,342,336 | 1,451,455 |
| `RAK_3401_repeater` | 559,616 | 815,104 | 255,488 |
| `wio-e5-mini_repeater` | 245,384 | 245,760 | 376 |
| `wio-e5-mini_companion_radio_usb` | 228,664 | 229,376 | 712 |
These small Mini margins qualify the stated recipes, not arbitrary optional
features or longer build metadata. The earlier Mini Sensor overflow remains
recorded above; that target was not rebuilt in this final integration campaign.
No physical ADC, voltmeter, charging or installed-device test was performed.
+1
View File
@@ -75,6 +75,7 @@ Completed validation reports, experiments, and test guides are collected here. O
## Build, storage, memory, and checklists
- [Shared battery ADC calibration validation, 2026-10-22](battery_calibration_2026-10-22.md)
- [Heltec V2 BLE RAM reserve repair, 2026-10-22](heltec_v2_ble_memory_2026-10-22.md)
- [ESP32 Bluetooth shutdown and radio2 CPU idle, 2026-10-21](esp32_ble_radio2_sleep_2026-10-21.md)
- [RAK3401 all firmware CPU sleep checks, 2026-10-21](rak3401_all_roles_cpu_sleep_2026-10-21.md)