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

+18 -2
View File
@@ -5,6 +5,7 @@
#include <math.h>
#include "helpers/UsbLogging.h"
#include "helpers/BatteryChargeSupport.h"
#include "helpers/BatteryCalibration.h"
#include "helpers/RegulatorMode.h"
#include "helpers/PowerSavingDiagnostics.h"
#include "helpers/LedPolicy.h"
@@ -137,13 +138,28 @@ namespace mesh {
class MainBoard {
bool _radio_test_active = false;
float _battery_calibration_factor = 1.0f;
protected:
uint16_t calibrateBatteryMillivolts(uint16_t raw_mv) const {
return mesh::power::scaleBatteryMillivolts(raw_mv, _battery_calibration_factor);
}
public:
void setRadioTestActive(bool active) { _radio_test_active = active; }
bool isRadioTestActive() const { return _radio_test_active; }
virtual uint16_t getBattMilliVolts() = 0;
virtual float getMCUTemperature() { return NAN; }
virtual bool setAdcMultiplier(float multiplier) { return false; };
virtual float getAdcMultiplier() const { return 0.0f; }
virtual bool supportsBatteryCalibration() const { return false; }
// Relative to the board's built-in ADC conversion; zero restores its scale.
// Boards with an existing absolute ADC coefficient retain their overrides.
virtual bool setAdcMultiplier(float multiplier) {
if (!supportsBatteryCalibration()
|| !mesh::power::validRelativeBatteryMultiplier(multiplier)) return false;
_battery_calibration_factor = multiplier == 0.0f ? 1.0f : multiplier;
return true;
}
virtual float getAdcMultiplier() const {
return supportsBatteryCalibration() ? _battery_calibration_factor : 0.0f;
}
virtual const char* getManufacturerName() const = 0;
virtual void onBeforeTransmit() { }
virtual void onAfterTransmit() { }
+118
View File
@@ -0,0 +1,118 @@
#pragma once
#include <math.h>
#include <stdint.h>
#include <stddef.h>
#include <stdio.h>
#include <string.h>
namespace mesh { namespace power {
// New ADC backends use a correction relative to their original conversion.
// Existing board-specific absolute multipliers retain their own units.
inline bool validRelativeBatteryMultiplier(float multiplier) {
return isfinite(multiplier) && (multiplier == 0.0f
|| (multiplier >= 0.5f && multiplier <= 1.5f));
}
inline uint16_t scaleBatteryMillivolts(uint16_t millivolts, float multiplier) {
if (millivolts == 0 || !isfinite(multiplier) || multiplier <= 0.0f)
return millivolts;
const float scaled = millivolts * multiplier;
if (scaled >= 65535.0f) return UINT16_MAX;
return static_cast<uint16_t>(scaled + 0.5f);
}
// Volts with millivolt precision. Require a measured value; neither chemistry
// nor charger regulation voltage supplies a calibration reference.
inline bool parseBatteryReferenceMillivolts(const char* text, uint16_t& result) {
if (!text || *text < '0' || *text > '9') return false;
uint32_t whole = 0, fraction = 0;
while (*text >= '0' && *text <= '9') {
whole = whole * 10 + static_cast<unsigned>(*text++ - '0');
if (whole > 65) return false;
}
unsigned digits = 0;
if (*text == '.') {
++text;
while (*text >= '0' && *text <= '9') {
if (++digits > 3) return false;
fraction = fraction * 10 + static_cast<unsigned>(*text++ - '0');
}
if (digits == 0) return false;
}
while (*text == ' ' || *text == '\t') ++text;
if (*text) return false;
while (digits++ < 3) fraction *= 10;
const uint32_t millivolts = whole * 1000 + fraction;
if (millivolts == 0 || millivolts > UINT16_MAX) return false;
result = static_cast<uint16_t>(millivolts);
return true;
}
// Setter owns application, checked persistence and rollback. It leaves a
// useful error in reply when it fails. This keeps nRF52 boot-voltage policy
// and legacy absolute multiplier storage authoritative in their own roles.
template <typename Board, typename Setter>
bool handleBatteryCalibrationCommand(Board& board, const char* command,
char* reply, size_t capacity,
Setter set_multiplier) {
if (!command || !reply || capacity == 0) return false;
while (*command == ' ' || *command == '\t') ++command;
static const char key[] = "battery calibrate";
const size_t length = sizeof(key) - 1;
if (strncmp(command, key, length) != 0
|| (command[length] && command[length] != ' ' && command[length] != '\t'))
return false;
const char* value = command + length;
while (*value == ' ' || *value == '\t') ++value;
const float previous = board.getAdcMultiplier();
if (!isfinite(previous) || previous <= 0.0f) {
snprintf(reply, capacity, "Error: battery ADC unsupported");
return true;
}
const char* reset_end = value;
if (strncmp(value, "reset", 5) == 0) {
reset_end = value + 5;
while (*reset_end == ' ' || *reset_end == '\t') ++reset_end;
if (*reset_end == 0) {
*reply = 0;
if (set_multiplier(0.0f, reply, capacity))
snprintf(reply, capacity, "OK - ADC defaults restored (saved)");
else if (*reply == 0)
snprintf(reply, capacity, "Error: calibration save failed");
return true;
}
}
uint16_t reference = 0;
if (!parseBatteryReferenceMillivolts(value, reference)) {
snprintf(reply, capacity, "Error: use battery calibrate <volts>|reset");
return true;
}
const uint16_t reported = board.getBattMilliVolts();
if (reported == 0 || reported == UINT16_MAX) {
snprintf(reply, capacity, "Error: battery voltage unavailable");
return true;
}
const float correction = static_cast<float>(reference) / reported;
if (!validRelativeBatteryMultiplier(correction)) {
snprintf(reply, capacity, "Error: reference must be 50%%-150%% of reading");
return true;
}
const float multiplier = previous * correction;
if (!isfinite(multiplier) || multiplier <= 0.0f) {
snprintf(reply, capacity, "Error: invalid calibration correction");
return true;
}
*reply = 0;
if (set_multiplier(multiplier, reply, capacity)) {
snprintf(reply, capacity, "OK - %u.%03u V; multiplier %.6f (saved)",
static_cast<unsigned>(reference / 1000),
static_cast<unsigned>(reference % 1000), board.getAdcMultiplier());
} else if (*reply == 0) {
snprintf(reply, capacity, "Error: calibration save failed");
}
return true;
}
}} // namespace mesh::power
+152
View File
@@ -0,0 +1,152 @@
#include "BatteryCalibrationStore.h"
#include "BatteryCalibration.h"
#include "CheckedSettingsFile.h"
#include "CLICommandUtils.h"
#include "PersistentStoreFormat.h"
#if defined(NRF52_PLATFORM) || defined(STM32_PLATFORM)
#include "AtomicFileWriter.h"
#else
#include "ContactFileTransaction.h"
#endif
#if defined(NRF52_POWER_MANAGEMENT)
#include "NRF52VoltagePolicy.h"
#endif
#include <math.h>
#include <stdio.h>
#include <string.h>
namespace mesh { namespace power {
namespace {
FILESYSTEM* calibration_fs = nullptr;
const char* const calibration_path = "/battery_cal";
bool usesVoltagePolicy() {
#if defined(NRF52_POWER_MANAGEMENT)
return voltagePolicySupported();
#else
return false;
#endif
}
void encode(float multiplier, uint8_t (&data)[12]) {
memcpy(data, "ADC1", 4);
static_assert(sizeof(multiplier) == sizeof(uint32_t), "ADC record needs 32-bit float");
uint32_t bits;
memcpy(&bits, &multiplier, sizeof(bits));
storage::writeLE32(data + 4, bits);
storage::writeLE32(data + 8, storage::updateCRC32(0xffffffffUL, data, 8));
}
bool readMultiplier(float& multiplier) {
uint8_t data[12];
if (!storage::readFixedSettingsFile(calibration_fs, calibration_path, data, sizeof(data))
|| memcmp(data, "ADC1", 4) != 0
|| storage::readLE32(data + 8) != storage::updateCRC32(0xffffffffUL, data, 8)) return false;
const uint32_t bits = storage::readLE32(data + 4);
memcpy(&multiplier, &bits, sizeof(bits));
return isfinite(multiplier) && multiplier >= 0.0f && multiplier <= 10.0f;
}
bool saveMultiplier(float multiplier) {
if (!calibration_fs) return false;
uint8_t data[12], verified[12];
encode(multiplier, data);
#if defined(NRF52_PLATFORM) || defined(STM32_PLATFORM)
AtomicFileWriter file(calibration_fs, calibration_path);
#else
ContactFileTransaction file(calibration_fs, calibration_path);
#endif
if (!file || file.write(data, sizeof(data)) != sizeof(data) || !file.commit()) return false;
return storage::readFixedSettingsFile(calibration_fs, calibration_path,
verified, sizeof(verified))
&& memcmp(data, verified, sizeof(data)) == 0;
}
} // namespace
bool beginBatteryCalibrationStore(MainBoard& board, FILESYSTEM* fs) {
calibration_fs = fs;
if (usesVoltagePolicy() || board.getAdcMultiplier() <= 0.0f) return true;
#if defined(ESP32_PLATFORM) || defined(RP2040_PLATFORM)
if (!fs || !ContactFileTransaction::recover(fs, calibration_path)) return false;
#endif
if (!fs) return false;
if (!fs->exists(calibration_path)) return true;
float multiplier;
return readMultiplier(multiplier) && board.setAdcMultiplier(multiplier);
}
bool setStoredAdcMultiplier(MainBoard& board, float multiplier,
char* reply, size_t capacity) {
if (!isfinite(multiplier) || multiplier < 0.0f || multiplier > 10.0f) {
snprintf(reply, capacity, "Error: multiplier must be 0-10");
return false;
}
if (board.getAdcMultiplier() <= 0.0f) {
snprintf(reply, capacity, "Error: ADC calibration unsupported");
return false;
}
#if defined(NRF52_POWER_MANAGEMENT)
if (usesVoltagePolicy()) {
char command[48];
snprintf(command, sizeof(command), "set adc.multiplier %.3f", multiplier);
return handleVoltagePolicyCommand(command, reply, capacity)
&& strncmp(reply, "OK", 2) == 0;
}
#endif
const float previous = board.getAdcMultiplier();
if (!board.setAdcMultiplier(multiplier)) {
snprintf(reply, capacity, "Error: multiplier rejected by board");
return false;
}
if (!saveMultiplier(multiplier)) {
const bool restored = board.setAdcMultiplier(previous);
snprintf(reply, capacity, "%s", restored
? "Error: save unconfirmed; reboot may differ"
: "Error: save unconfirmed; runtime restore failed; reboot may differ");
return false;
}
if (multiplier == 0.0f) snprintf(reply, capacity, "OK - using default board multiplier");
else snprintf(reply, capacity, "OK - multiplier set to %.3f (saved)", multiplier);
return true;
}
bool handleStoredAdcMultiplierCommand(MainBoard& board, const char* command,
char* reply, size_t capacity) {
if (!command || !reply || !capacity) return false;
const bool get = strncmp(command, "get ", 4) == 0;
const bool set = strncmp(command, "set ", 4) == 0;
if (!get && !set) return false;
const char* key = command + 4;
if (strncmp(key, "adc.multiplier", 14) != 0
|| (key[14] && key[14] != ' ' && key[14] != '\t')) return false;
if (board.getAdcMultiplier() <= 0.0f) {
snprintf(reply, capacity, "Error: ADC calibration unsupported");
return true;
}
#if defined(NRF52_POWER_MANAGEMENT)
if (usesVoltagePolicy()) return handleVoltagePolicyCommand(command, reply, capacity);
#endif
const char* value = key + 14;
while (*value == ' ' || *value == '\t') ++value;
if (get) {
if (*value) snprintf(reply, capacity, "Error: usage get adc.multiplier");
else if (board.getAdcMultiplier() <= 0.0f) snprintf(reply, capacity, "Error: ADC calibration unsupported");
else snprintf(reply, capacity, "> %.3f", board.getAdcMultiplier());
} else {
float multiplier;
if (!cli::parseDecimalStrict(value, multiplier))
snprintf(reply, capacity, "Error: invalid multiplier");
else setStoredAdcMultiplier(board, multiplier, reply, capacity);
}
return true;
}
bool handleStoredBatteryCalibrationCommand(MainBoard& board, const char* command,
char* reply, size_t capacity) {
if (handleBatteryCalibrationCommand(board, command, reply, capacity,
[&board](float multiplier, char* result, size_t result_capacity) {
return setStoredAdcMultiplier(board, multiplier, result, result_capacity);
})) return true;
return handleStoredAdcMultiplierCommand(board, command, reply, capacity);
}
}} // namespace mesh::power
+18
View File
@@ -0,0 +1,18 @@
#pragma once
#include <MeshCore.h>
#include <helpers/IdentityStore.h>
namespace mesh { namespace power {
// Companion and Terminal Chat keep calibration outside their published
// preference layouts. Infrastructure roles retain their existing ADC field.
bool beginBatteryCalibrationStore(MainBoard& board, FILESYSTEM* fs);
bool setStoredAdcMultiplier(MainBoard& board, float multiplier,
char* reply, size_t capacity);
bool handleStoredAdcMultiplierCommand(MainBoard& board, const char* command,
char* reply, size_t capacity);
bool handleStoredBatteryCalibrationCommand(MainBoard& board, const char* command,
char* reply, size_t capacity);
}} // namespace mesh::power
+72 -17
View File
@@ -22,6 +22,7 @@
#include <helpers/ui/DisplayRotationSettings.h>
#endif
#include <helpers/BatteryChargeCLI.h>
#include <helpers/BatteryCalibration.h>
#if MESH_ENABLE_CARRIER_TOOLS || MESH_ENABLE_MORSE_RX
#include <helpers/MorseCLI.h>
#endif
@@ -1069,6 +1070,12 @@ void CommonCLI::loadPrefs(FILESYSTEM* fs) {
if (loaded) syncOtaConfigFromPrefs(); // persisted OTA policy/keys -> OtaContext (else keep safe defaults)
#endif
mesh::hilStartupTrace("prefs_apply_begin");
#if defined(NRF52_POWER_MANAGEMENT)
// The startup voltage policy owns the relative calibration on these boards.
// Its checked record must not be replaced by the legacy infrastructure field.
if (!mesh::power::voltagePolicySupported())
#endif
_board->setAdcMultiplier(_prefs->adc_multiplier);
#if defined(RAK_4631)
// Boot-time only. Later CLI saves must not cut a live peripheral/flash rail.
_sensors->configureSharedPeripheralMode(_prefs->peripherals_shared != 0);
@@ -3018,6 +3025,47 @@ bool CommonCLI::saveCommonPrefs() {
return _common_save_result_known && _common_save_succeeded;
}
bool CommonCLI::applyAndSaveAdcMultiplier(float multiplier, char* reply,
size_t capacity) {
if (!isfinite(multiplier) || multiplier < 0.0f || multiplier > 10.0f) {
snprintf(reply, capacity, "Error: multiplier must be 0-10");
return false;
}
if (_board->getAdcMultiplier() <= 0.0f) {
snprintf(reply, capacity, "Error: unsupported");
return false;
}
#if defined(NRF52_POWER_MANAGEMENT)
if (mesh::power::voltagePolicySupported()) {
char command[48];
snprintf(command, sizeof(command), "set adc.multiplier %.3f", multiplier);
const bool saved = mesh::power::handleVoltagePolicyCommand(command, reply, capacity)
&& strncmp(reply, "OK", 2) == 0;
if (saved) loopBatteryForwarding(true);
return saved;
}
#endif
const float previous = _board->getAdcMultiplier();
const float previous_pref = _prefs->adc_multiplier;
if (!_board->setAdcMultiplier(multiplier)) {
snprintf(reply, capacity, "Error: multiplier rejected by board");
return false;
}
_prefs->adc_multiplier = multiplier;
if (!trySavePrefs()) {
_prefs->adc_multiplier = previous_pref;
const bool restored = _board->setAdcMultiplier(previous);
snprintf(reply, capacity, "%s", restored
? "Error: save unconfirmed; reboot may differ"
: "Error: save unconfirmed; runtime restore failed; reboot may differ");
return false;
}
loopBatteryForwarding(true);
if (multiplier == 0.0f) snprintf(reply, capacity, "OK - using default board multiplier");
else snprintf(reply, capacity, "OK - multiplier set to %.3f", multiplier);
return true;
}
bool CommonCLI::savePrimaryRadioParams(float freq, float bw, uint8_t sf,
uint8_t cr, uint16_t preamble) {
if (!isfinite(freq) || !isfinite(bw) || freq < 150.0f || freq > 2500.0f
@@ -3264,6 +3312,10 @@ bool CommonCLI::handleUDPBridgeCommand(uint32_t sender_timestamp,
void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* reply) {
PrefsSaveReplyGuard save_reply(_prefs_save_failures, reply);
mesh::cli::normalizeCommandVerb(command);
if (mesh::power::handleBatteryCalibrationCommand(*_board, command, reply, 160,
[this](float multiplier, char* result, size_t capacity) {
return applyAndSaveAdcMultiplier(multiplier, result, capacity);
})) return;
#if MESH_ENABLE_BATTERY_FORWARDING
if (handleBatteryForwardingCommand(command, reply)) return;
#endif
@@ -4229,12 +4281,18 @@ void CommonCLI::handleSetCmd(uint32_t sender_timestamp, char* command, char* rep
return;
}
#if defined(NRF52_POWER_MANAGEMENT)
if (mesh::power::handleVoltagePolicyCommand(command, reply, 160)) {
#if MESH_ENABLE_BATTERY_FORWARDING
if (strncmp(reply, "OK", 2) == 0) loopBatteryForwarding(true);
#endif
const bool adc_multiplier_command = strncmp(config, "adc.multiplier", 14) == 0
&& (config[14] == 0 || config[14] == ' ' || config[14] == '\t');
if (adc_multiplier_command && _board->getAdcMultiplier() <= 0.0f) {
strcpy(reply, "Error: unsupported");
return;
}
if (!adc_multiplier_command || mesh::power::voltagePolicySupported()) {
if (mesh::power::handleVoltagePolicyCommand(command, reply, 160)) {
if (strncmp(reply, "OK", 2) == 0) loopBatteryForwarding(true);
return;
}
}
#endif
// Infrastructure roles dispatch here rather than through CommonRadioPrefs.
if (strncmp(config, "path.hash.mode", 14) == 0
@@ -5721,19 +5779,8 @@ void CommonCLI::handleSetCmd(uint32_t sender_timestamp, char* command, char* rep
float multiplier = 0.0f;
if (!mesh::cli::parseDecimalStrict(&config[15], multiplier)) {
strcpy(reply, "Error: invalid multiplier");
} else if (_board->setAdcMultiplier(multiplier)) {
_prefs->adc_multiplier = multiplier;
savePrefs();
#if MESH_ENABLE_BATTERY_FORWARDING
loopBatteryForwarding(true);
#endif
if (_prefs->adc_multiplier == 0.0f) {
strcpy(reply, "OK - using default board multiplier");
} else {
sprintf(reply, "OK - multiplier set to %.3f", _prefs->adc_multiplier);
}
} else {
strcpy(reply, "Error: unsupported");
applyAndSaveAdcMultiplier(multiplier, reply, 160);
};
} else if (memcmp(config, "reboot.interval ", 16) == 0) {
int hours = _atoi(&config[16]);
@@ -5804,7 +5851,15 @@ void CommonCLI::handleGetCmd(uint32_t sender_timestamp, char* command, char* rep
return;
}
#if defined(NRF52_POWER_MANAGEMENT)
if (mesh::power::handleVoltagePolicyCommand(command, reply, 160)) return;
const bool adc_multiplier_command = strncmp(config, "adc.multiplier", 14) == 0
&& (config[14] == 0 || config[14] == ' ' || config[14] == '\t');
if (adc_multiplier_command && _board->getAdcMultiplier() <= 0.0f) {
strcpy(reply, "Error: unsupported");
return;
}
if (!adc_multiplier_command || mesh::power::voltagePolicySupported()) {
if (mesh::power::handleVoltagePolicyCommand(command, reply, 160)) return;
}
#endif
if (strcmp(config, "password") == 0) {
if (sender_timestamp == 0) {
+1
View File
@@ -945,6 +945,7 @@ class CommonCLI {
PrefsSaveRouting::Scope scope = PrefsSaveRouting::Scope::Common);
bool trySavePrefs(
PrefsSaveRouting::Scope scope = PrefsSaveRouting::Scope::Common);
bool applyAndSaveAdcMultiplier(float multiplier, char* reply, size_t capacity);
bool saveObserverPrefs();
void loadPrefsInt(FILESYSTEM* _fs, const char* filename);
#ifdef WITH_MQTT_BRIDGE
+9 -1
View File
@@ -518,6 +518,14 @@ public:
}
#endif
bool supportsBatteryCalibration() const override {
#ifdef PIN_VBAT_READ
return true;
#else
return false;
#endif
}
uint16_t getBattMilliVolts() override {
#ifdef PIN_VBAT_READ
analogReadResolution(12);
@@ -528,7 +536,7 @@ public:
}
raw = raw / 4;
return (2 * raw);
return calibrateBatteryMillivolts(2 * raw);
#else
return 0; // not supported
#endif
+16 -4
View File
@@ -293,12 +293,24 @@ void NRF52Board::loop() {
#endif
}
#ifdef NRF52_POWER_MANAGEMENT
uint16_t NRF52Board::calibrateBatteryMillivolts(uint16_t raw_mv) const {
return mesh::power::calibratedMillivolts(
raw_mv, mesh::power::configuredAdcPermille());
}
#ifdef NRF52_POWER_MANAGEMENT
if (supportsBatteryCalibration() && mesh::power::voltagePolicySupported()) {
return mesh::power::calibratedMillivolts(
raw_mv, mesh::power::configuredAdcPermille());
}
#endif
return mesh::MainBoard::calibrateBatteryMillivolts(raw_mv);
}
float NRF52Board::getAdcMultiplier() const {
#ifdef NRF52_POWER_MANAGEMENT
if (supportsBatteryCalibration() && mesh::power::voltagePolicySupported()) {
return mesh::power::configuredAdcPermille() / 1000.0f;
}
#endif
return mesh::MainBoard::getAdcMultiplier();
}
#if NRF52_WATCHDOG_TIMEOUT_SECONDS > 0
static void reloadWatchdogChannels() {
+3 -3
View File
@@ -102,10 +102,10 @@ public:
bool isUsbDataConnected() override;
bool isUsbHostConnected() override;
#ifdef NRF52_POWER_MANAGEMENT
// Relative to each board's built-in ADC conversion; 1.000 is unchanged.
// Power-managed boards use the early-boot voltage policy; other ADC boards
// use the shared relative multiplier persisted with their role settings.
uint16_t calibrateBatteryMillivolts(uint16_t raw_mv) const;
#endif
float getAdcMultiplier() const override;
void attachDynamicPrefs(KeyValueStore* prefs) { (void)prefs; } // no-op
+2
View File
@@ -162,6 +162,8 @@ public:
}
#endif
bool supportsBatteryCalibration() const override { return false; }
uint16_t getBattMilliVolts(){
if (!charge_pmu_ready) return 0;
#if defined(PORTABLE_MQTT_OBSERVER) && !defined(TBEAM_SUPREME_SX1262)