Splash, // cold boot, flash, panic, or plain reboot

Silent, // heap-defrag ESP.restart() (RTC flag; lost on power loss)

SplashlessWake, // wake from deep sleep with the splash suppressed by the SD flag

if (deepSleepInProgress) return; // sleeping supersedes the heap-defrag reboot

silentRebootTarget = SILENT_REBOOT_TARGET_HOME;

silentRebootMagic = SILENT_REBOOT_MAGIC;

LOG_DBG("MAIN", "Silent restart (target=home)");

// E-ink retains the previous frame until Home's first paint lands (~2-3s).

// Without an overlay, users don't see the reboot and fire input through to

// Home. Select on the default selectorIndex=0 then opens the most-recent

// book, looking like a trampoline back to the reader they just exited.

GUI.drawPopup(renderer, tr(STR_LOADING_POPUP));

delay(50);

ESP.restart();

if (deepSleepInProgress) return; // sleeping supersedes the heap-defrag reboot

silentRebootTarget = SILENT_REBOOT_TARGET_READER;

silentRebootMagic = SILENT_REBOOT_MAGIC;

LOG_DBG("MAIN", "Silent restart (target=reader)");

GUI.drawPopup(renderer, tr(STR_LOADING_POPUP));

delay(50);

ESP.restart();

HalFile file;

if (!Storage.openFileForWrite("SLP", SLEEP_FRAME_FILE, file)) return;

file.write(renderer.getFrameBuffer(), renderer.getBufferSize());

file.close();

HalFile file;

if (!Storage.openFileForRead("SLP", SLEEP_FRAME_FILE, file)) return false;

const size_t bufferSize = display.getBufferSize();

const size_t bytesRead = file.read(display.getFrameBuffer(), bufferSize);

file.close();

if (bytesRead != bufferSize) {

Storage.remove(SLEEP_FRAME_FILE);

return false;

}

Storage.remove(SLEEP_FRAME_FILE);

return true;

HalPowerManager::Lock powerLock; // Ensure we are at normal CPU frequency for sleep preparation

APP_STATE.lastSleepFromReader = activityManager.isReaderActivity();

const bool isQuickResumeSleep =

SETTINGS.sleepScreen == CrossPointSettings::SLEEP_SCREEN_MODE::QUICK_RESUME ||

(fromTimeout &&

SETTINGS.quickResumeSleepScreen == CrossPointSettings::QUICK_RESUME_SLEEP_SCREEN::QUICK_RESUME_AFTER_TIMEOUT);

// Every sleep mode leaves a complete retained frame on the e-ink panel. Keep

// it visible until the first useful reader or home paint replaces it.

APP_STATE.showBootScreen = false;

APP_STATE.saveToFile();

// Commit to sleeping before goToSleep() runs the outgoing activity's onExit():

// a WiFi activity would otherwise silentRestart() here and reboot instead.

deepSleepInProgress = true;

activityManager.goToSleep(fromTimeout);

if (isQuickResumeSleep) {

saveSleepFrameBuffer();

} else if (Storage.exists(SLEEP_FRAME_FILE)) {

// A stale Quick Resume frame must not replace the selected sleep screen during wake.

Storage.remove(SLEEP_FRAME_FILE);

}

// Tear down WiFi so the modem power domain isn't held alive across deep sleep.

// Wake from deep sleep is effectively a chip reset, so no state needs to survive.

if (WiFi.getMode() != WIFI_MODE_NULL) {

WiFi.disconnect(true);

WiFi.mode(WIFI_OFF);

}

halTiltSensor.deepSleep();

display.deepSleep();

LOG_DBG("MAIN", "Entering deep sleep");

powerManager.startDeepSleep(gpio);

display.begin(seamless);

renderer.begin();

activityManager.begin();

LOG_DBG("MAIN", "Display initialized");

// Initialize font decompressor for compressed reader fonts

if (!fontDecompressor.init()) {

LOG_ERR("MAIN", "Font decompressor init failed");

}

fontCacheManager.setFontDecompressor(&fontDecompressor);

renderer.setFontCacheManager(&fontCacheManager);

renderer.insertFont(NOTOSERIF_14_FONT_ID, notoserif14FontFamily);

#ifndef OMIT_FONTS

renderer.insertFont(NOTOSERIF_12_FONT_ID, notoserif12FontFamily);

renderer.insertFont(NOTOSERIF_16_FONT_ID, notoserif16FontFamily);

renderer.insertFont(NOTOSERIF_18_FONT_ID, notoserif18FontFamily);

renderer.insertFont(NOTOSANS_12_FONT_ID, notosans12FontFamily);

renderer.insertFont(NOTOSANS_14_FONT_ID, notosans14FontFamily);

renderer.insertFont(NOTOSANS_16_FONT_ID, notosans16FontFamily);

renderer.insertFont(NOTOSANS_18_FONT_ID, notosans18FontFamily);

#endif // OMIT_FONTS

renderer.insertFont(UI_10_FONT_ID, ui10FontFamily);

renderer.insertFont(UI_12_FONT_ID, ui12FontFamily);

renderer.insertFont(SMALL_FONT_ID, smallFontFamily);

// Discover and load SD card fonts

sdFontSystem.begin(renderer);

LOG_DBG("MAIN", "Fonts setup");

BoardConfig::holdPowerRails();

t1 = millis();

#ifdef ENABLE_SERIAL_LOG

// Earliest possible Serial setup. The 250 ms stall before begin() lets the

// USB Serial/JTAG peripheral finish power-on and lets the host complete USB

// enumeration before we touch the CDC state — otherwise cold boot races

// and the host has to be physically replugged for logs to flow. Warm reboot

// worked without the delay because USB was already enumerated.

delay(250);

Serial.begin(115200);

#if LOG_SERIAL_HAS_TX_TIMEOUT

logSerial.setTxTimeoutMs(1); // This is a load-bearing 1. Do not modify.

#endif

#endif

HalSystem::begin();

// checkPanic() clears the watchdog capture marker after a successful SD

// dump, so retain the boot classification for the later activity route.

const bool rebootedFromPanic = HalSystem::isRebootFromPanic();

// Read-and-clear so a panic later in setup() doesn't loop into silent reboot.

// Bound the target range too — RTC_NOINIT memory is uninitialized on cold boot.

const bool isSilentReboot = (silentRebootMagic == SILENT_REBOOT_MAGIC);

const uint32_t snapshotTarget =

(isSilentReboot && silentRebootTarget <= SILENT_REBOOT_TARGET_READER) ? silentRebootTarget : 0;

silentRebootMagic = 0;

silentRebootTarget = 0;

gpio.begin();

powerManager.begin();

halTiltSensor.begin();

halClock.begin();

// First of two USB samples (second below, before display bring-up): the SOF

// verdict needs two samples a frame apart, and it must be settled before the

// first refresh — the boot paint's light-sleep slices would otherwise kill a

// live CDC link whenever the charge-based check reads false (full battery,

// data-only cable). See HalGPIO::pollUsbState().

gpio.pollUsbState();

// Light-sleep through the render task's e-ink BUSY wait (0.3-2 s of pure pin

// polling) in short slices, waking exactly on the BUSY pin's completion level

// (falls back to plain polling when WiFi/USB blocks light sleep)

display.setBusyWaitSliceHook(

[](int8_t busyPin, uint8_t busyLevel) { return powerManager.onEinkBusyWaitSlice(busyPin, busyLevel); });

LOG_INF("MAIN", "Hardware detect: %s", gpio.deviceIsX3() ? "X3" : "X4");

// SD Card Initialization

// We need 6 open files concurrently when parsing a new chapter

if (!Storage.begin()) {

LOG_ERR("MAIN", "SD card initialization failed");

gpio.pollUsbState(); // settle the USB verdict before the error paint (see above)

setupDisplayAndFonts(isSilentReboot);

activityManager.goToFullScreenMessage("SD card error", EpdFontFamily::BOLD);

return;

}

HalSystem::checkPanic();

SETTINGS.loadFromFile();

APP_STATE.loadFromFile();

RECENT_BOOKS.loadFromFile();

I18N.setLanguage(static_cast<Language>(SETTINGS.language));

KOREADER_STORE.loadFromFile();

OPDS_STORE.loadFromFile();

UITheme::getInstance().reload();

ButtonNavigator::setMappedInputManager(mappedInputManager);

const auto wakeupReason = gpio.getWakeupReason();

switch (wakeupReason) {

case HalGPIO::WakeupReason::PowerButton:

LOG_DBG("MAIN", "Verifying power button press duration");

if (!gpio.verifyPowerButtonWakeup(SETTINGS.getPowerButtonDuration(),

SETTINGS.shortPwrBtn == CrossPointSettings::SHORT_PWRBTN::SLEEP)) {

powerManager.startDeepSleep(gpio);

}

wakePowerReleasePending = true;

break;

case HalGPIO::WakeupReason::AfterUSBPower:

// If USB power caused a cold boot, go back to sleep

LOG_DBG("MAIN", "Wakeup reason: After USB Power");

powerManager.startDeepSleep(gpio);

break;

case HalGPIO::WakeupReason::AfterFlash:

// After flashing, just proceed to boot

case HalGPIO::WakeupReason::Other:

default:

break;

}

// Recovery firmware mode: hold left side button (BTN_UP) together with the power button at

// boot to skip directly to the SD-card firmware update screen. Useful on devices where USB

// flashing has been locked down (e.g. recent X3 firmware).

bool recoveryFirmwareMode = false;

if (wakeupReason == HalGPIO::WakeupReason::PowerButton) {

// Refresh the cached button state a few times — isPressed() needs ~half a second to settle

// after boot per the HalGPIO contract. Use a millis-based deadline so we always wait the full

// settle window even if the loop body takes longer than expected on slow boots.

const unsigned long settleStart = millis();

while (millis() - settleStart < 500) {

gpio.update();

delay(10);

}

if (gpio.isPressed(HalGPIO::BTN_UP)) {

recoveryFirmwareMode = true;

LOG_INF("MAIN", "Recovery firmware mode (UP + POWER held at boot)");

}

}

// First serial output only here to avoid timing inconsistencies for power button press duration verification

LOG_DBG("MAIN", "Starting CrossPoint version " CROSSPOINT_VERSION);

// Resolve the single boot-presentation decision. Skipping the splash also

// skips the panel-clearing pass and the X3 initial-full-sync arming (see

// HalDisplay::begin), so the first paint is FAST_REFRESH (~500ms) over the

// retained frame and input dispatches against a visible UI.

// Only a verified deep-sleep wake may use the one-shot persisted flag.

// Otherwise a stale flag could suppress the splash on a cold boot.

const bool isSleepWake = wakeupReason == HalGPIO::WakeupReason::PowerButton;

const BootResume resume = isSilentReboot ? BootResume::Silent

: isSleepWake && !APP_STATE.showBootScreen ? BootResume::SplashlessWake

: BootResume::Splash;

bool allowFastInitialReaderRefresh = false;

// Second USB sample (first one right after powerManager.begin()): settles the

// SOF host-link verdict before the first refresh can slice-sleep.

gpio.pollUsbState();

setupDisplayAndFonts(resume != BootResume::Splash);

switch (resume) {

case BootResume::Silent:

// Splash skipped: the routing block below picks the target activity; the

// panel keeps showing the pre-reboot popup until that first paint lands.

break;

case BootResume::SplashlessWake:

// One-shot flag: re-arm the splash for the next ordinary boot. Save

// before any painting so a hang in the blocking paint path can't strand

// us in a splashless-with-no-frame loop on the next boot.

APP_STATE.showBootScreen = true;

APP_STATE.saveToFile();

if (Storage.exists(SLEEP_FRAME_FILE) && loadSleepFrameBuffer()) {

const bool useDifferentialRefresh = gpio.deviceIsX3();

if (useDifferentialRefresh) {

// begin() clears the X3 controller RAM, so restore the saved frame as

// the baseline before replacing the moon with the loading icon.

renderer.cleanupGrayscaleWithFrameBuffer();

}

const auto pageHeight = renderer.getScreenHeight();

renderer.drawImage(LoadingIcon, 0, pageHeight - LOADINGICON_HEIGHT, LOADINGICON_WIDTH, LOADINGICON_HEIGHT);

if (useDifferentialRefresh) {

renderer.displayGrayscaleBase(HalDisplay::FAST_REFRESH);

allowFastInitialReaderRefresh = true;

} else {

renderer.displayBuffer(HalDisplay::HALF_REFRESH);

}

}

break;

case BootResume::Splash:

activityManager.goToBoot();

break;

}

// Output polarity is resolved per render by ActivityManager (night mode

// inverts only the reading surfaces), so nothing to restore here.

if (recoveryFirmwareMode) {

// Skip normal home/reader routing: jump straight into the SD firmware picker.

activityManager.replaceActivity(

std::make_unique<SdFirmwareUpdateActivity>(renderer, mappedInputManager, /*recoveryMode=*/true));

} else if (rebootedFromPanic) {

// If we rebooted from a panic, go to crash report screen to show the panic info

activityManager.goToCrashReport();

} else if (resume == BootResume::Silent && snapshotTarget == SILENT_REBOOT_TARGET_READER &&

!APP_STATE.openEpubPath.empty()) {

activityManager.goToReader(APP_STATE.openEpubPath);

} else if (resume == BootResume::Silent) {

// target == home (or reader with no open book): land on home — don't fall

// through to the sleep-wake "resume reader" logic, which fires on stale

// openEpubPath + lastSleepFromReader from a prior session.

activityManager.goHome();

} else if (APP_STATE.openEpubPath.empty() || !APP_STATE.lastSleepFromReader ||

mappedInputManager.isPressed(MappedInputManager::Button::Back) || APP_STATE.readerActivityLoadCount > 0) {

// Boot to home screen if no book is open, last sleep was not from reader, back button is held, or reader activity

// crashed (indicated by readerActivityLoadCount > 0)

activityManager.goHome();

} else {

// Clear app state to avoid getting into a boot loop if the epub doesn't load

const auto path = APP_STATE.openEpubPath;

APP_STATE.openEpubPath = "";

APP_STATE.readerActivityLoadCount++;

APP_STATE.saveToFile();

activityManager.goToReader(path, allowFastInitialReaderRefresh);

}

if (resume == BootResume::Silent) {

// Block until the first paint physically completes. refreshDisplay()

// waits on the panel BUSY pin so when this returns the user can see the

// new activity. Without the wait, an edge captured by gpio.update()

// during boot dispatches against an invisible Home and the default

// selectorIndex=0 opens the most-recent book.

activityManager.requestUpdateAndWait();

// Absorb any button held at this point into currentState as a non-edge:

// two gpio.update() calls separated by > InputManager's 5ms debounce

// transition the held bit through lastDebounceTime into currentState

// without setting pressedEvents, so the first loop()'s own gpio.update()

// sees state == currentState and emits nothing.

gpio.update();

delay(10);

gpio.update();

}

allowSleepAt = millis() + 2000;

const unsigned long deadline = millis() + ms;

while (static_cast<long>(millis() - deadline) < 0) {

vTaskDelay(1);

}

static unsigned long maxLoopDuration = 0;

const unsigned long loopStartTime = millis();

static unsigned long lastMemPrint = 0;

gpio.setSharedConfirmPowerShortPressEmitsPower(SETTINGS.shortPwrBtn == CrossPointSettings::SHORT_PWRBTN::SLEEP);

gpio.update();

halTiltSensor.update(SETTINGS.tiltPageTurn, SETTINGS.orientation, activityManager.isReaderActivity());

renderer.setFadingFix(SETTINGS.fadingFix);

if (Serial && millis() - lastMemPrint >= 10000) {

LOG_INF("MEM", "Free: %d bytes, Total: %d bytes, Min Free: %d bytes, MaxAlloc: %d bytes", ESP.getFreeHeap(),

ESP.getHeapSize(), ESP.getMinFreeHeap(), ESP.getMaxAllocHeap());

lastMemPrint = millis();

}

// Handle incoming serial commands,

// nb: we use logSerial from logging to avoid deprecation warnings

if (logSerial.available() > 0) {

String line = logSerial.readStringUntil('\n');

if (line.startsWith("CMD:")) {

String cmd = line.substring(4);

cmd.trim();

bool handled = true;

if (cmd == "SCREENSHOT") {

const uint32_t bufferSize = display.getBufferSize();

logSerial.printf("SCREENSHOT_START:%d\n", bufferSize);

uint8_t* buf = display.getFrameBuffer();

logSerial.write(buf, bufferSize);

logSerial.printf("SCREENSHOT_END\n");

} else {

handled = false;

}

// Raw print, not LOG_*: debugging_monitor.py keys on this ack to report

// command success, so it must survive LOG_LEVEL=0 builds. Commands

// compiled out of this build report unknown.

logSerial.printf(handled ? "CMDACK:%s\n" : "CMDERR:unknown:%s\n", cmd.c_str());

}

}

// Check for any user activity (button press or release) or active background work

static unsigned long lastActivityTime = millis();

if (gpio.wasAnyPressed() || gpio.wasAnyReleased() || gpio.wasTouchActivity() || halTiltSensor.hadActivity() ||

activityManager.preventAutoSleep()) {

lastActivityTime = millis(); // Reset inactivity timer

powerManager.setPowerSaving(false); // Restore normal CPU frequency on user activity

}

// Let wake continue as soon as its hold has been verified. The release can

// arrive after setup, so consume that one input frame rather than making it

// a page turn, refresh, or other short power-button action.

if (wakePowerReleasePending && !gpio.isPressed(HalGPIO::BTN_POWER)) {

wakePowerReleasePending = false;

return;

}

static bool screenshotButtonsReleased = true;

static bool screenshotComboActive = false;

if (gpio.isPressed(HalGPIO::BTN_POWER) && gpio.isPressed(HalGPIO::BTN_DOWN)) {

screenshotComboActive = true;

if (screenshotButtonsReleased) {

screenshotButtonsReleased = false;

{

RenderLock lock;

ScreenshotUtil::takeScreenshot(renderer);

}

}

return;

}

if (screenshotComboActive) {

if (gpio.isPressed(HalGPIO::BTN_POWER)) return;

if (gpio.wasReleased(HalGPIO::BTN_POWER)) {

screenshotButtonsReleased = true;

screenshotComboActive = false;

return;

}

screenshotButtonsReleased = true;

screenshotComboActive = false;

}

const unsigned long sleepTimeoutMs = SETTINGS.getSleepTimeoutMs();

if (sleepTimeoutMs > 0 && millis() - lastActivityTime >= sleepTimeoutMs) {

LOG_DBG("SLP", "Auto-sleep triggered after %lu ms of inactivity", sleepTimeoutMs);

enterDeepSleep(true);

// This should never be hit as `enterDeepSleep` calls esp_deep_sleep_start

return;

}

// A hold that woke the device must be released before it can count as a new

// in-app long press. Otherwise a user who keeps holding after wake would put

// the device straight back to sleep once allowSleepAt expires.

static bool powerReleasedSinceWake = false;

if (!gpio.isPressed(HalGPIO::BTN_POWER)) powerReleasedSinceWake = true;

if (powerReleasedSinceWake && millis() >= allowSleepAt && gpio.isPressed(HalGPIO::BTN_POWER) &&

gpio.getPowerButtonHeldTime() > SETTINGS.getPowerButtonDuration()) {

// If the screenshot combination is potentially being pressed, don't sleep

if (gpio.isPressed(HalGPIO::BTN_DOWN)) {

return;

}

enterDeepSleep();

// This should never be hit as `enterDeepSleep` calls esp_deep_sleep_start

return;

}

// Refresh screen when power button is short-pressed with FORCE_REFRESH setting.

if (SETTINGS.shortPwrBtn == CrossPointSettings::SHORT_PWRBTN::FORCE_REFRESH &&

mappedInputManager.wasReleased(MappedInputManager::Button::Power)) {

LOG_DBG("MAIN", "Manual screen refresh triggered");

if (!activityManager.handleForcedRefresh()) {

RenderLock lock;

renderer.displayBuffer(HalDisplay::HALF_REFRESH);

}

}

// Refresh the battery icon when USB is plugged or unplugged.

// Placed after sleep guards so we never queue a render that won't be processed.

if (gpio.wasUsbStateChanged()) {

activityManager.requestUpdate();

}

const unsigned long activityStartTime = millis();

activityManager.loop();

const unsigned long activityDuration = millis() - activityStartTime;

// Body complete: releases the slice hook's yield (see onEinkBusyWaitSlice).

powerManager.noteMainLoopIteration();

const unsigned long loopDuration = millis() - loopStartTime;

if (loopDuration > maxLoopDuration) {

maxLoopDuration = loopDuration;

if (maxLoopDuration > 50) {

LOG_DBG("LOOP", "New max loop duration: %lu ms (activity: %lu ms)", maxLoopDuration, activityDuration);

}

}

// Add delay at the end of the loop to prevent tight spinning

// When an activity requests skip loop delay (e.g., webserver running), use yield() for faster response

// Otherwise, use longer delay to save power

if (activityManager.skipLoopDelay()) {

powerManager.setPowerSaving(false); // Make sure we're at full performance when skipLoopDelay is requested

yield(); // Give FreeRTOS a chance to run tasks, but return immediately

} else {

const unsigned long idleMs = millis() - lastActivityTime;

if (idleMs >= HalPowerManager::IDLE_LIGHT_SLEEP_MS) {

// Idle: light-sleep between input polls instead of busy-delaying (same poll cadence).

// Race-to-sleep: run the brief wake windows at normal clock, not LOW_POWER_FREQ.

// The board's sleep-floor current is paid per-millisecond regardless of CPU

// speed, so finishing the per-wake work ~16x faster and returning to sleep

// costs less charge than stretching the window at 10 MHz (measured at 10 MHz:

// 8.8 mA for 4.5 ms per wake). The downclock below only serves the pre-sleep

// 100 Hz delay-poll phase. The lightSleep()-rejected fallback delay() then

// also runs at normal clock, but that only happens when USB (externally

// powered), WiFi, or a render Lock (full speed wanted anyway) is active.

powerManager.setPowerSaving(false);

if (gpio.isDebouncePending()) {

// A raw button-state change is mid-debounce: commitment needs a second

// matching sample, so poll again quickly instead of sleeping a slice —

// a tap shorter than the 50 ms cadence would otherwise land in a single

// sample and be dropped, and every press would commit a slice late.

delayWallClock(10);

} else if (!powerManager.lightSleep(gpio)) {

// Light sleep declined = a render Lock, USB, or WiFi is active — the

// chip is at full clock anyway, so poll at 100 Hz. A 50 ms cadence

// here dropped sub-slice power taps (a press needs two samples >=5 ms

// apart to commit), which made short-press sleep flaky during renders

// — exactly when a render Lock forces this fallback.

delayWallClock(10);

}

} else {

// Response window after recent input: keep 100 Hz polling for snappy interaction,

// but downclock once rapid-input bursts have settled — renders re-raise the clock

// via HalPowerManager::Lock, so full speed only serves loop bookkeeping here

if (idleMs >= HalPowerManager::IDLE_DOWNCLOCK_MS) {

powerManager.setPowerSaving(true);

}

delayWallClock(10);

}

}