dfbc931c14
Brings ~55 mod-exclusive files to the upstream-based mod/master-resync branch: Activities (migrated to new ActivityManager pattern): - Clock/Time: SetTimeActivity, SetTimezoneOffsetActivity, NtpSyncActivity - Dictionary: DictionaryDefinitionActivity, DictionarySuggestionsActivity, DictionaryWordSelectActivity, LookedUpWordsActivity - Bookmark: EpubReaderBookmarkSelectionActivity - Book management: BookManageMenuActivity, EndOfBookMenuActivity - OPDS: OpdsServerListActivity, OpdsSettingsActivity - Utility: DirectoryPickerActivity, NumericStepperActivity Utilities (unchanged): - BookManager, BookSettings, BookmarkStore, BootNtpSync - Dictionary, LookupHistory, TimeSync, OpdsServerStore Libraries: PlaceholderCover, TableData, ChapterXPathIndexer Scripts: inject_mod_version, generate_book_icon, preview_placeholder_cover Docs: KOReader sync XPath mapping Migration changes: - ActivityWithSubactivity -> Activity base class - Callback constructors -> finish()/setResult() pattern - enterNewActivity() -> startActivityForResult() - Activity::RenderLock&& -> RenderLock&& These files won't compile yet - they reference mod settings and I18n strings that will be added in subsequent phases. Made-with: Cursor
124 lines
7.1 KiB
Markdown
124 lines
7.1 KiB
Markdown
# Session Context Dump (2026-02-09)
|
|
|
|
> Everything below is a snapshot of the conversation context at the time of writing. It captures what was explored, what was read, what was produced, and what the current state of work is. Use this to resume without re-exploring.
|
|
|
|
## Branch State
|
|
|
|
- **Current branch:** `mod/sleep-screen-tweaks`
|
|
- **Git status:** `.gitignore` modified (unstaged). No other tracked changes. All `mod/docs/` files are new/untracked (the `mod/` directory is gitignored).
|
|
|
|
## What Was Done This Session
|
|
|
|
1. **Explored the entire project structure** using parallel agents. Mapped every directory, identified all source files, read key headers and configs.
|
|
|
|
2. **Created 3 documentation files in `mod/docs/`:**
|
|
- `hardware.md` -- Full hardware capabilities (CPU, flash partitions, display specs with GPIO pins, buttons with indices, SD card, battery, WiFi, USB, power management, SDK libraries)
|
|
- `file-structure.md` -- Complete directory tree with descriptions of every file group (src/ activities, components, network; lib/ HAL, EPUB engine, fonts, supporting libs; scripts, tests, docs, .github CI)
|
|
- `ci-build-and-code-style.md` -- Build system (3 PlatformIO environments), all 4 CI workflows with triggers and steps, release process, clang-format rules table, cppcheck config, PR requirements, contribution guidelines
|
|
|
|
3. **Created `project-summary.md`** -- condensed reference consolidating all three docs plus architecture patterns, caching behavior, and constraints.
|
|
|
|
## Files Read During Exploration
|
|
|
|
The following files were read in full and their contents informed the documentation:
|
|
|
|
**Config/root:**
|
|
- `platformio.ini` -- all build environments, flags, dependencies, SDK symlinks
|
|
- `partitions.csv` -- flash partition table (6 rows)
|
|
- `.clang-format` -- 332 lines of formatting rules
|
|
- `.clangd` -- C++2a standard setting
|
|
- `.gitmodules` -- open-x4-sdk submodule reference
|
|
- `README.md` -- project overview, features checklist, install instructions, internals (caching), contributing
|
|
- `SCOPE.md` -- in-scope/out-of-scope feature boundaries
|
|
- `GOVERNANCE.md` -- community principles, moderation
|
|
|
|
**HAL layer:**
|
|
- `lib/hal/HalDisplay.h` -- display constants (480x800, buffer size 48000), refresh modes enum, grayscale buffer methods
|
|
- `lib/hal/HalGPIO.h` -- GPIO pin defines (EPD_SCLK=8, EPD_MOSI=10, EPD_CS=21, EPD_DC=4, EPD_RST=5, EPD_BUSY=6, SPI_MISO=7, BAT_GPIO0=0, UART0_RXD=20), button indices (0-6), WakeupReason enum
|
|
- `lib/hal/HalStorage.h` -- Storage singleton, file ops API, SDCardManager wrapper
|
|
|
|
**Application:**
|
|
- `src/main.cpp` -- 413 lines: setup/loop, activity routing (onGoHome, onGoToReader, etc.), font initialization (Bookerly 12/14/16/18, NotoSans 12/14/16/18, OpenDyslexic 8/10/12/14, Ubuntu 10/12), power button verification, deep sleep entry, auto-sleep timeout, memory logging
|
|
- `src/MappedInputManager.h` -- Button enum (Back, Confirm, Left, Right, Up, Down, Power, PageBack, PageForward), Labels struct, mapLabels()
|
|
- `src/Battery.h` -- global `BatteryMonitor battery(BAT_GPIO0)` instance
|
|
|
|
**CI/GitHub:**
|
|
- `.github/workflows/ci.yml` -- 4 jobs (clang-format, cppcheck, build, test-status), triggers, steps
|
|
- `.github/workflows/release.yml` -- tag trigger, gh_release env, 5 artifact files
|
|
- `.github/workflows/release_candidate.yml` -- workflow_dispatch, release/* branch gate, SHORT_SHA extraction
|
|
- `.github/workflows/pr-formatting-check.yml` -- semantic PR title check
|
|
- `.github/PULL_REQUEST_TEMPLATE.md` -- summary, context, AI usage disclosure
|
|
|
|
**Scripts:**
|
|
- `bin/clang-format-fix` -- bash script, git ls-files, grep for C/C++ extensions, excludes builtinFonts/, -g flag for modified-only
|
|
|
|
**Directory listings obtained:**
|
|
- Root, `src/`, `src/Activities/` (full recursive), `lib/` (all subdirectories), `lib/Epub/` (full recursive), `docs/`, `scripts/`, `test/`
|
|
|
|
## Current Mod Work Context
|
|
|
|
From `mod/docs/todo.md`, two tasks are planned for the sleep screen on branch `mod/sleep-screen-tweaks`:
|
|
|
|
**Task 1 -- Gradient fill for letterboxed images:**
|
|
When a sleep screen image doesn't match the 480x800 display aspect ratio, void/letterbox areas should be filled with a gradient sampled from the nearest ~20 pixels of the image edge. Relevant files:
|
|
- `src/activities/boot_sleep/SleepActivity.cpp/.h` -- sleep screen rendering logic
|
|
- `lib/GfxRenderer/BitmapHelpers.cpp/.h` -- bitmap manipulation utilities
|
|
- `lib/GfxRenderer/Bitmap.cpp/.h` -- bitmap data structure
|
|
- `lib/hal/HalDisplay.h` -- display dimensions (480x800), buffer operations
|
|
|
|
**Task 2 -- Fix "Fit" mode for small images:**
|
|
In "Fit" mode, images smaller than the display should be scaled UP to fit (maintaining aspect ratio). The current implementation only scales down larger images. Same relevant files as Task 1.
|
|
|
|
Neither task has been started yet -- only documentation/exploration was done this session.
|
|
|
|
## Key Architectural Details Observed in Source
|
|
|
|
**Activity lifecycle (from main.cpp):**
|
|
- `exitActivity()` calls `onExit()` then `delete` on the current activity
|
|
- `enterNewActivity()` sets `currentActivity` and calls `onEnter()`
|
|
- Activities receive `GfxRenderer&` and `MappedInputManager&` in constructors
|
|
- `ReaderActivity` also receives the epub path and callback functions for navigation
|
|
|
|
**Boot sequence (from main.cpp setup()):**
|
|
1. `gpio.begin()` -- init GPIO/SPI
|
|
2. Serial init only if USB connected
|
|
3. `Storage.begin()` -- SD card init (shows error screen on failure)
|
|
4. Load settings, KOReader store, UI theme
|
|
5. Check wakeup reason: PowerButton verifies hold duration, AfterUSBPower goes back to sleep, AfterFlash/Other proceed
|
|
6. Display + font setup
|
|
7. Show BootActivity (splash)
|
|
8. Load app state + recent books
|
|
9. Route to HomeActivity or ReaderActivity based on saved state
|
|
|
|
**Main loop (from main.cpp loop()):**
|
|
1. Poll GPIO
|
|
2. Apply fadingFix setting to renderer
|
|
3. Log memory every 10s (when serial active)
|
|
4. Track activity timer, auto-sleep on configurable timeout
|
|
5. Check power button hold for manual sleep
|
|
6. Run `currentActivity->loop()`
|
|
7. Delay 10ms normally, or `yield()` if activity requests fast response (e.g. web server)
|
|
|
|
**Settings system:**
|
|
- `CrossPointSettings` loaded from SD at boot via `SETTINGS` macro
|
|
- Includes: `shortPwrBtn` behavior, `getPowerButtonDuration()`, `getSleepTimeoutMs()`, `fadingFix`
|
|
- `CrossPointState` (`APP_STATE`) tracks: `openEpubPath`, `lastSleepFromReader`, `readerActivityLoadCount`
|
|
|
|
**Display details (from HalDisplay.h):**
|
|
- `DISPLAY_WIDTH` and `DISPLAY_HEIGHT` are `constexpr` sourced from `EInkDisplay`
|
|
- `DISPLAY_WIDTH_BYTES = DISPLAY_WIDTH / 8` (480/8 = 60)
|
|
- `BUFFER_SIZE = DISPLAY_WIDTH_BYTES * DISPLAY_HEIGHT` (60 * 800 = 48000)
|
|
- Grayscale uses separate LSB/MSB buffers
|
|
- `displayBuffer()` and `refreshDisplay()` take `RefreshMode` and optional `turnOffScreen`
|
|
- `drawImage()` supports PROGMEM source flag
|
|
|
|
## Companion Documentation Files
|
|
|
|
All in `mod/docs/`:
|
|
- `todo.md` -- active mod task list (sleep screen tweaks)
|
|
- `hardware.md` -- full hardware reference (175 lines)
|
|
- `file-structure.md` -- complete file tree with descriptions (307 lines)
|
|
- `ci-build-and-code-style.md` -- build/CI/style reference (281 lines)
|
|
- `project-summary.md` -- condensed project reference (217 lines)
|
|
- `session-summary.md` -- this file
|