Skip to content

Add low battery protection - #182

Open
cryptomilk wants to merge 10 commits into
OpenDisplay:mainfrom
cryptomilk:asn-wip
Open

cryptomilk wants to merge 10 commits into
OpenDisplay:mainfrom
cryptomilk:asn-wip

Conversation

@cryptomilk

Copy link
Copy Markdown
Contributor

Currently if the the battery is low, we still accept updates and try to render whatever was sent to us. However it isn't a good idea. We should not keep running till the battery hits 0!

This adds low battery detection, renders a nice low battery screen and turns off wifi/ble and goes to sleep.

e1003_low_bat

If you plug in a charger, it will render the QR screen again.

NULL triggers -Wconversion-null against the uint16_t BLEConnHandle
parameter. main.cpp's LAN call site already uses 0/nullptr; match it.
… getters

Upcoming low-battery detection logic needs to read s_soc, s_gauge_ok
and the charge-pin state from outside this file.
…o at one choke point

Advertising is re-armed from several independent places on each
target. Gating every one of them individually for the upcoming
low-battery mode would be fragile and easy to miss one.
Battery-powered devices drain to zero unattended when the host never
reconnects, with no on-device self-protection. Computing a full
percentage would duplicate py-opendisplay's per-chemistry discharge
curves and risk drifting from them, so a single near-empty cutoff per
chemistry is enough to trigger protective behavior safely.
isBatteryLow() has no way to tell the user yet.
A near-empty battery cannot reliably sustain OTA or a config session.
Neither a cold boot nor a deep-sleep wake leaves a panel session up to reuse.
writeBootScreenWithQr()'s row-streaming core is tightly interleaved with
its QR, swatch, and header/footer painting. Sharing it would mean
touching that path.
…ttonWakeSources()

A near-empty battery must still sleep even when deep_sleep_time_seconds
is configured to 0, since staying awake only drains it further. It also
needs to wake on a charger plug-in without the host seeing a synthetic
button press for it. The upcoming low-battery boot path can also reach
enterDeepSleep() before BLE ever started, so tearing it down
unconditionally would deinit an uninitialized stack.

No caller passes the new arguments yet, so behavior is unchanged.
enterDeepSleep() deinitialized BLE. It left WiFi running. The AP
association, TCP listener, and TLS state stayed live. Only
esp_deep_sleep_start() cut radio power, in hardware, with no software
teardown first.

A low-battery trip with WiFi configured kept the radio fully active
through the screen refresh. AP association, LAN server, and
RSSI-roam logic all kept running.

reboot() already tears WiFi down first, via
esp32_ble_deinit_before_restart(), for the same esp_restart() hazard
class. enterDeepSleep() had no equivalent.

Assisted-By: Claude <noreply@anthropic.com>
A near-empty battery previously had no effect at boot: isBatteryLow()
and the deep-sleep/radio-suppression plumbing existed but nothing
called them. Without this, a device below its chemistry's cutoff keeps
booting normally, draining further with every wake instead of
protecting itself.

A boot-time reading has no radio or panel load skewing it, so it can
be trusted on its own merit rather than needing the debounce the main
loop's poll relies on to reject a single sagged reading.
A device that boots healthy but drains past its chemistry's cutoff
while already awake had no way to notice. isBatteryLow() and its
debounced poll existed. lowBatteryBootCheck() covered the cold-boot
case. Nothing in the main loop called the poll. A device that stayed
connected, or had deep sleep disabled, would run to zero with no
screen, no radio shutdown, and no sleep.

platformIdle() only runs once workInFlight is false, and
ble.isConnected() alone makes workInFlight true. Gating the poll
behind it would let a connected central block the check forever,
which is exactly the case this commit exists to cover.

nRF has no deep-sleep path, so its recovery cannot be checked at the
next wake the way ESP32's can. A software reset is the only way back to
the normal cold-boot path there.
A board with no charger-wake GPIO can only notice a charger plug-in at
its next scheduled wake. The interval was 1-hour which is a bit long.
Lower it to 30 min which should still be fine.
@cryptomilk
cryptomilk marked this pull request as ready for review November 11, 2026 09:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant