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:
1 parent
94a3b7e568
commit
ab6412e73c
108 files changed
+1303
-83
No files matched your search
+49
-3
@@ -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.
|
||||
@@ -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)
|
||||
|
||||
Reference in new issue
Block a user