companion_radio: Add optional KEEP_DISPLAY_ON_USB flag to keep display on while powered 🤖🤖

[disq]

Summary

Optional build flag KEEP_DISPLAY_ON_USB that suppresses the companion radio's AUTO_OFF_MILLIS screen-blanking timer only while the board reports isExternalPowered() == true. Default is unchanged — the display still blanks after AUTO_OFF_MILLIS on every existing build. The flag is purely opt-in; LCD-based variants (e.g. heltec_t096) can add -D KEEP_DISPLAY_ON_USB to their env to gain always-on-while-powered behaviour. OLED-based variants stay on the safe default to avoid burn-in.

Why opt-in and not on by default

OLED panels burn in quickly with static content, so unconditionally keeping the screen on while USB-powered would degrade those displays. Thanks to the reviewer for raising this — defaulting to off and exposing it as a flag is the right shape. LCD targets where burn-in isn't a concern can opt in per-env without imposing the risk on every existing board.

Implementation

When KEEP_DISPLAY_ON_USB is defined, each companion UI flavour's loop() refreshes _auto_off every tick that board.isExternalPowered() is true:

#if AUTO_OFF_MILLIS > 0
#ifdef KEEP_DISPLAY_ON_USB
    if (board.isExternalPowered()) {
      _auto_off = millis() + AUTO_OFF_MILLIS;
    }
#endif
    if (millis() > _auto_off) {
      _display->turnOff();
    }
#endif

The refresh-while-powered pattern (rather than just guarding the turnOff() call) means the timer counts a fresh full AUTO_OFF_MILLIS window from the moment USB is unplugged — no instant blank on unplug, no surprise. When the flag is not defined, the block compiles out and the build is byte-identical to upstream.

Applied to all three companion_radio UI flavours: ui-new, ui-tiny, ui-orig.

Safety

• MeshCore.h defines virtual bool isExternalPowered() { return false; } as the base-class default. Boards without an override are unaffected even if a downstream env adds -D KEEP_DISPLAY_ON_USB.
• NRF52Board overrides isExternalPowered() only when NRF52_POWER_MANAGEMENT is defined (RAK3401, RAK4631, etc.).
• Existing battery-only deployments and boards that don't (yet) report external-power state are completely unaffected.

Testing

Verified on RAK3401 + companion_radio_ble (no env change — flag undefined):

• USB-powered, idle: OLED blanks after 15 s — upstream behaviour preserved.
• Battery-only, idle: OLED blanks after 15 s — upstream behaviour preserved.

Same build with -D KEEP_DISPLAY_ON_USB added to the env:

• USB-powered: OLED stays on indefinitely past AUTO_OFF_MILLIS.
• Unplug USB: OLED stays on for a fresh 15 s window from the unplug moment, then blanks.
• Battery-only (no USB ever attached): blanks at 15 s as before.

🤖 Generated with Claude Code

[NickDunklee]

Not a diss to the intent of the PR, but FWIW, OLEDs suffer screen burn-in ridiculously quick. Freedom to choose one's destiny of course, but the default should probably be off but an option. Samsung tried to solve this by rotating pixels around the display on their OLED watches subtly, so burn-in would be more equal, but it's so complicated on finite display life. On the LCD nodes like the Heltec T096 though, bring it on!

[disq]

@NickDunklee Good point :) Updated the PR: the keep-on-while-powered behaviour is now gated behind -D KEEP_DISPLAY_ON_USB, with the default reverting to upstream's blank-after-AUTO_OFF_MILLIS.