Heltec T1 battery readings jump between two voltage bands, inaccurate battery levels

[benaltair]

Summary

On my Heltec Mesh Node T1, the reported battery voltage jumps between two distinct bands. I first noticed this manually in MeshCore clients. I then ran a read-only BLE test that reproduced the behaviour while charging and after unplugging the charger.

The data shows changes of hundreds of millivolts within a few seconds. I don't believe these changes can represent physical cell-voltage movement. An AI-assisted source review reported that the switched battery divider presents about 79.59 kΩ to the nRF52840 SAADC while the currently pinned Arduino core defaults to a 3 µs acquisition time, specified for sources up to 10 kΩ. This is a plausible explanation to test, but I have not yet confirmed it with patched firmware or a multimeter - don't want to ruin the water resistance on my T1 with a teardown.

Hardware and software

• Device: Heltec Mesh Node T1
• Firmware-reported model: Heltec T1
• Firmware: v1.16.0-07a3ca9
• Data client: meshcore Python package 2.3.7, revision 5bac3573b51c4298062881885b6d15a994109076
• T1 battery path reviewed: variants/heltec_t1/T1Board.cpp:69-80
• MeshCore source reviewed at commit: a3a1aa5e3be34b42d8ac8c2cc244d30af6cdd71e

Reproduction and data collection

I kept the node on its normal charger, marked the full-on-charger point, unplugged it, and marked the unplug event. I then used a simple python logger that queried the existing battery command over BLE:

• five readings per batch, about two seconds apart;
• one batch every 120 seconds;
• 1,605 raw readings in 321 complete batches;
• over 8 hours represented in the charging phase and 3 hours after unplugging;
• every stored batch summary recomputes exactly from the raw readings.

A minimal manual reproduction you could do would be to connect to a T1 over BLE and issue five battery queries about two seconds apart, then repeat the group periodically. I observed the incompatible bands both while charging and after unplugging.

Observed result

The thresholds below only describe the two visible clusters; they are not assumed to identify the true cell voltage.

• While charging, the upper cluster has a median of 4201 mV and the lower excursions have a median of 3935 mV.
• After unplugging, the lower cluster has a median of 3352 mV and the upper excursions have a median of 3831 mV.
• There are 30 post-unplug pairs in which both bands occur in the same five-reading batch. Their median separation is 479 mV (443–504 mV), with the paired readings only about 2.16 seconds apart.

Because the raw voltage is not trustworthy, I didn't get the battery-percentage curve from this run for the T1 that I'd hopped to get.

Source-level hypothesis — not yet hardware-confirmed, AI assisted

I used Codex with GPT-5.6 Sol on Max reasoning to carry out several analysis tasks on the schematic and source code.

The Heltec schematic shows R11 = 390 kΩ and R16 = 100 kΩ on BAT_ADC. Their Thevenin resistance is about 79.59 kΩ.

The current T1 implementation enables the divider, waits 10 ms, takes one analogRead(), and disables the divider. The MeshCore-pinned Adafruit nRF52 core documents and implements a 3 µs default SAADC acquisition time. Nordic's nRF52840 SAADC specification lists:

• 3 µs for source resistance up to 10 kΩ;
• 10 µs for source resistance up to 100 kΩ.

The external 10 ms delay can settle the switched divider, but it does not lengthen the SAADC's internal sample-and-hold acquisition window. The approximately 79.6 kΩ source is therefore outside the 3 µs acquisition-time specification. This mismatch is confirmed in the source and datasheets; whether it causes the observed bimodality still needs a device-side A/B test.

The fixed multiplier does not explain the jumps: 4.916 versus the schematic divider ratio of 4.900 differs by about 0.327%.

Proposed next test

Before proposing a production fix, it could be helpful to test a narrowly scoped diagnostic build that:

1. uses an acquisition time suitable for this divider (10 µs minimum; 40 µs for the initial diagnostic A/B);
2. keeps the divider enabled across the conversion set;
3. discards the first conversion;
4. takes a small odd sample set and uses a robust aggregate such as the median;
5. restores any global ADC setting changed by the function;
6. leaves ADC_MULTIPLIER unchanged.

I would compare the current and diagnostic builds on USB and battery-only power and check both against a multimeter before opening a firmware PR.

Current testing limits

• No firmware patch has been built or flashed.
• No current-versus-diagnostic A/B test has been performed.
• No independent multimeter measurement has been taken.
• No second T1 has been tested.
• The exact collection script was not included in the run bundle transferred for analysis. I have prepared a redacted evidence bundle containing the raw measurements, event metadata, and a standalone script that deterministically validates the reported statistics, and can provide it if useful.
• This issue reports reproducible measurement behaviour and a source-backed hypothesis, not a confirmed root cause or completed fix.

AI assistance and provenance

• The physical observations, charge/unplug actions, and phase markers were mine. I supplied the initial observations and test instructions in my own words, including voice-dictated notes.
• The read-only logger and collection workflow were created with assistance from OpenAI Codex using GPT 5.6 Sol on Max reasoning effort.
• Post-run integrity checking, source/specification review, hypothesis development, deterministic analysis scripting, and drafting were assisted by Hermes Agent, also using GPT 5.6 Sol on Max reasoning effort.
• The numerical results are reproducible from the attached raw data with a standalone Python script; they do not depend on an LLM summary.
• I reviewed the resulting evidence and am responsible for the report's scope, limitations, and decision to submit it. This started because of data I was seeing in the telemetry on the client applications. I wanted to better understand why the battery level seemed to be inaccurate for this model.

References

• T1 battery implementation:

  MeshCore/variants/heltec_t1/T1Board.cpp

  Lines 69 to 80 in a3a1aa5

  	uint16_t T1Board::getBattMilliVolts() {
  	analogReadResolution(12);
  	analogReference(VBAT_AR_INTERNAL);
  	pinMode(PIN_VBAT_READ, INPUT);
  	pinMode(PIN_BAT_CTL, OUTPUT);
  	digitalWrite(PIN_BAT_CTL, ADC_CTRL_ENABLED);
  	delay(10);
  	int adcvalue = analogRead(PIN_VBAT_READ);
  	digitalWrite(PIN_BAT_CTL, !ADC_CTRL_ENABLED);
  	return (uint16_t)((float)adcvalue * MV_LSB * ADC_MULTIPLIER);

• T1 battery constants:

  MeshCore/variants/heltec_t1/variant.h

  Lines 150 to 165 in a3a1aa5

  	////////////////////////////////////////////////////////////////////////////////
  	// Battery
  	#define ADC_CTRL (0 + 11)
  	#define PIN_BAT_CTL ADC_CTRL
  	#define ADC_CTRL_ENABLED HIGH
  	#define BATTERY_PIN (0 + 5)
  	#define PIN_VBAT_READ BATTERY_PIN
  	#define ADC_RESOLUTION (14)
  	#define AREF_VOLTAGE (3.0)
  	#define VBAT_AR_INTERNAL AR_INTERNAL_3_0
  	#define ADC_MULTIPLIER (4.916F)
  	#define MV_LSB (3000.0F / 4096.0F)
  	#define PWRMGT_VOLTAGE_BOOTLOCK 3100

• MeshCore-pinned nRF52 core sample-time API: https://github.com/meshcore-dev/Adafruit_nRF52_Arduino/blob/d541301665b40959682252911e57b11df3ee651a/cores/nRF5/wiring_analog.h#L118-L125
• MeshCore-pinned nRF52 core 3 µs default: https://github.com/meshcore-dev/Adafruit_nRF52_Arduino/blob/d541301665b40959682252911e57b11df3ee651a/cores/nRF5/wiring_analog_nRF52.c#L144-L163
• Heltec schematic: https://resource.heltec.cn/download/Mesh_Node_T1/schematic/Mesh_Node_T1_V1.0.pdf
• Nordic nRF52840 Product Specification: https://docs.nordicsemi.com/bundle/nRF52840_PS_v1.10
• MeshCore team statement on AI-generated code and disclosure: https://blog.meshcore.io/2026/04/23/the-split
• Redacted raw measurements and deterministic reproduction script are available in a prepared evidence bundle on request.

[benaltair]

Reported this to the Heltec team over email too. In my testing my unit has read around 10% battery for over 60 hours now. Firmware likely needs some tweaking.

[Quency-D]

https://resource.heltec.cn/download/Mesh_Node_T1/firmware/Heltec_t1_companion_radio_ble-Voltage-filtering(1).uf2 This version includes a battery voltage filtering algorithm designed to prevent excessive voltage fluctuations caused by RF transmissions. Please give it a try to see if the issue persists. Also, feel free to send us the data you've read so we can analyze it as well. Thank you very much.

[benaltair]

Thanks @Quency-D - I’ve flashed the test firmware and am testing it now.

The MeshCore flasher would not accept the raw UF2 because it expects a Nordic DFU ZIP. I couldn’t find an official DFU ZIP for this specific test build, so to flash it with the online flasher I had to package the same UF2 application payload in the DFU ZIP format used by the official T1 releases. Here's the ZIP I flashed:

Heltec_t1_companion_radio_ble-Voltage-filtering-DFU.zip

Please let me know if there's another way you'd like me to test it - otherwise I'll get some test data to you soon.

[Quency-D]

As long as the firmware is flashed correctly, it works. For UF2 files, you can simply double-click the board to reset it—creating a virtual flash drive—and then copy the file directly over; that is very convenient.

[benaltair]

My testing shows that using the firmware you sent reduces the spikes as expected with the changes (filtering outliers and averaging several samples) but there are still oddities. For example, after charging overnight the battery level reads 10% as it did before. I'll try some of my own firmware modifications and see if I can get stable and accurate readings. It seems now we've increased precision but not accuracy. It may be that a combination of changing the reading mechanism as described in the proposal above and a change in how the measurements are sampled and calculated could produce the reading needed.