Add configurable default home screen action

Themes can now specify an initialAction in home screen config to set the default selected action when entering home normally. Falls back to this theme setting when no explicit action is requested, but explicit firmware navigation still takes precedence.
Add SD theme system
2026-08-13 14:21:57 -07:00 · 2026-06-28 02:38:53 -04:00 · 2026-06-28 01:44:38 -04:00 · 2026-06-27 22:40:21 +03:00 · 2026-06-27 21:22:58 +03:00
76 changed files with 6401 additions and 372 deletions
@@ -1,3 +1,4 @@
-[submodule "open-x4-sdk"]
-	path = open-x4-sdk
-	url = https://github.com/crosspoint-reader/community-sdk.git
+[submodule "freeink-sdk"]
+	path = freeink-sdk
+	url = https://github.com/Free-Ink/freeink-sdk.git
+	branch = main
@@ -7,7 +7,7 @@ Mission: Provide a lightweight, high-performance reading experience focused on E
 * Role: Senior Embedded Systems Engineer (ESP-IDF/Arduino-ESP32 specialized).
 * Primary Constraint: 380KB RAM is the hard ceiling. Stability is non-negotiable.
 * Evidence-Based Reasoning: Before proposing a change, you MUST cite the specific file path and line numbers that justify the modification.
-* Anti-Hallucination: Do not assume the existence of libraries or ESP-IDF functions. If you are unsure of an API's availability for the ESP32-C3 RISC-V target, check the open-x4-sdk or official docs first.
+* Anti-Hallucination: Do not assume the existence of libraries or ESP-IDF functions. If you are unsure of an API's availability for the ESP32-C3 RISC-V target, check the freeink-sdk source or the FreeInk SDK docs (https://freeink.org/llms.txt for an LLM-readable index) first.
 * No Unfounded Claims: Do not claim performance gains or memory savings without explaining the technical mechanism (e.g., DRAM vs IRAM usage).
 * Resource Justification: You must justify any new heap allocation (new, malloc, std::vector) or explain why a stack/static alternative was rejected.
 * Verification: After suggesting a fix, instruct the user on how to verify it (e.g., monitoring heap via Serial or checking a specific cache file).
@@ -127,7 +127,7 @@ These flags in `platformio.ini` fundamentally affect firmware behavior:
  * lib/hal/: Hardware Abstraction Layer (HalDisplay, HalGPIO, HalStorage)
  * lib/I18n/: Internationalization (translations in `translations/*.yaml`, generated string tables)
 * src/activities/: UI logic using the Activity Lifecycle (onEnter, loop, onExit)
-* open-x4-sdk/: Low-level SDK (EInkDisplay, InputManager, BatteryMonitor, SDCardManager)
+* freeink-sdk/: Low-level SDK (EInkDisplay, InputManager, BatteryMonitor, SDCardManager)
 * .crosspoint/: SD-based binary cache for EPUB metadata and pre-rendered layout sections

 ### Hardware Abstraction Layer (HAL)
@@ -131,6 +131,23 @@ Convert your own TTF/OTF files into `.cpfont` files that load from the SD card.

 Conversion runs the firmware repo's `lib/EpdFont/scripts/fontconvert_sdcard.py` script unmodified, so output matches a local host build.

+## Custom SD-card themes
+
+Downloadable themes are packaged in the tools repo under `../crosspoint-tools/public/themes/<theme-id>/`. Each theme folder must contain a `theme.json`; optional assets such as generated BMP icons live beside it, usually under `icons/`.
+
+See [SD-card theme creation](./docs/theme-creation.md) for the full JSON format, device-specific overrides, icon generation, CrossInk extension fields, and packaging rules.
+
+After adding or changing a hosted theme, regenerate the download manifest:
+
+```bash
+python3 scripts/generate-theme-manifest.py \
+  --root ../crosspoint-tools/public/themes \
+  --base-url http://crosspointreader.com/themes \
+  --output ../crosspoint-tools/public/themes/themes.json
+```
+
+The script scans every theme folder, includes every file in each package, and writes size and CRC32 values used by the device downloader. Commit changed theme package files and the regenerated `themes.json` in `crosspoint-tools`.
+
 ---

 ## Documentation
@@ -138,6 +155,7 @@ Conversion runs the firmware repo's `lib/EpdFont/scripts/fontconvert_sdcard.py`
 - [User Guide](./USER_GUIDE.md)
 - [Web server usage](./docs/webserver.md)
 - [Web server endpoints](./docs/webserver-endpoints.md)
+- [SD-card theme creation](./docs/theme-creation.md)
 - [Project scope](./SCOPE.md)
 - [Contributing docs](./docs/contributing/README.md)

@@ -174,6 +174,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
  - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
  - "None" - A blank screen
  - "Cover + Custom" - The book cover image while actively reading, falls back to "Custom" behavior otherwise
+  - "Quick resume" - The text of the last page read will be displayed on the sleep screen and a moon icon is shown on the edge of the screen. Waking up the device will return to the same page of the opened book. This is useful for quickly resuming reading without waiting for the device to fully wake up and load the book.

 - **Sleep Screen Cover Mode**: How to display the book cover when "Cover" sleep screen is selected:
  
@@ -186,6 +187,8 @@ The Settings screen allows you to configure the device's behavior. There are a f
  - "Contrast" - The image will be displayed as a black & white image without grayscale conversion
  - "Inverted" - The image will be inverted as in white & black and will be displayed without grayscale conversion

+- **Quick Resume on Timeout**: Whether to enable the "Quick Resume" sleep screen when the device goes to sleep due to inactivity (System > Time to Sleep). This is useful for quickly resuming reading without waiting for the device to fully wake up and load the book. This overwrites the Sleep Screen Cover Mode when enabled.
+
 - **Status Bar**: Configure the status bar displayed while reading:
  
  - "None" - No status bar
@@ -4,7 +4,7 @@

 .DESCRIPTION
    Formats all C/C++ source and header files in the repository, excluding
-    generated, vendored, and build directories (open-x4-sdk, builtinFonts,
+    generated, vendored, and build directories (freeink-sdk, builtinFonts,
    hyphenation tries, uzlib, .pio, *.generated.h).

    The clang-format binary path is resolved once and cached in
@@ -92,7 +92,7 @@ function Resolve-ClangFormat {
 $clangFormat = Resolve-ClangFormat

 $exclude = @(
-    'open-x4-sdk'
+    'freeink-sdk'
    'lib\EpdFont\builtinFonts'
    'lib\Epub\Epub\hyphenation\generated'
    'lib\uzlib'
@@ -8,7 +8,7 @@ At a high level, it is firmware that uses an activity-driven application archite

 ```mermaid
 graph TD
-    A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[open-x4-sdk]
+    A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[freeink-sdk]
    B --> C[lib/hal wrappers]
    C --> D[src/main.cpp runtime loop]
    D --> E[Activities layer]
@@ -195,10 +195,10 @@ When editing related source assets, regenerate via normal build steps/scripts.
 - `src/`: app orchestration, settings/state, and activity implementations
 - `src/network/`: web server and OTA/update networking
 - `src/components/`: theming and shared UI components
- `lib/hal/`: hardware abstraction wrappers around open-x4-sdk
+- `lib/hal/`: hardware abstraction wrappers around freeink-sdk
 - `lib/Epub/`: EPUB parser, layout, CSS handling, and hyphenation
 - `lib/`: supporting libraries (fonts, text, filesystem helpers, etc.)
- `open-x4-sdk/`: hardware SDK submodule (display, input, storage, battery)
+- `freeink-sdk/`: hardware SDK submodule (display, input, storage, battery). Docs: https://freeink.org/docs
 - `docs/`: user and technical documentation

 ## Embedded constraints that shape design
@@ -8,6 +8,7 @@
 #include <Utf8.h>

 #include <algorithm>
+#include <cassert>

 #include "FontCacheManager.h"

@@ -1055,7 +1056,19 @@ void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, co
 }

 void GfxRenderer::drawIcon(const uint8_t bitmap[], const int x, const int y, const int width, const int height) const {
-  display.drawImageTransparent(bitmap, y, getScreenWidth() - width - x, height, width);
+  if (bitmap == nullptr || width <= 0 || height <= 0) return;
+  assert(width == height);
+
+  const int bytesPerRow = (width + 7) / 8;
+  for (int sourceY = 0; sourceY < height; ++sourceY) {
+    for (int sourceX = 0; sourceX < width; ++sourceX) {
+      const uint8_t rowByte = bitmap[sourceY * bytesPerRow + sourceX / 8];
+      const bool background = (rowByte >> (7 - (sourceX % 8))) & 0x01;
+      if (background) continue;
+
+      drawPixel(x + height - 1 - sourceY, y + sourceX, true);
+    }
+  }
 }

 void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, const int maxWidth, const int maxHeight,
@@ -300,3 +300,4 @@ STR_SLEEP_TIMER_STEP_HINT: "Улева/Управа: 1 хв  Уверх/Уніз
 STR_AUTO_TURN_ENABLED: "Аўтаперагортванне: "
 STR_AUTO_TURN_PAGES_PER_MIN: "Аўтаперагортванне (старонак за хвіліну)"
 STR_TILT_PAGE_TURN: "Перагортванне нахілам"
+STR_MANAGE_THEMES: "Кіраванне тэмамі"
@@ -383,3 +383,4 @@ STR_FIRMWARE_WRITE_FAILED: "Ha fallat l'escriptura del firmware"
 STR_FIRMWARE_UPDATE_DO_NOT_POWER_OFF: "No apagueu el dispositiu!"
 STR_RECOVERY_MODE: "Mode de recuperació"
 STR_RECOVERY_MODE_HINT: "Poseu firmware.bin a l'arrel de la targeta SD i seleccioneu-lo"
+STR_MANAGE_THEMES: "Gestiona els temes"
@@ -275,3 +275,4 @@ STR_SLEEP_TIMER_VALUE_FORMAT: "%u min"
 STR_SLEEP_NEVER: "Nikdy"
 STR_SLEEP_TIMER_STEP_HINT: "Vlevo/Vpravo: 1 min  Nahoru/Dolů: 5 min"
 STR_TILT_PAGE_TURN: "Otáčení stránek nakloněním"
+STR_MANAGE_THEMES: "Spravovat motivy"
@@ -303,3 +303,4 @@ STR_SCREENSHOT_BUTTON: "Tag skærmbillede"
 STR_AUTO_TURN_ENABLED: "Automatisk sidevendning aktiveret: "
 STR_AUTO_TURN_PAGES_PER_MIN: "Automatisk vending (sider per minut)"
 STR_TILT_PAGE_TURN: "Vip for at vende side"
+STR_MANAGE_THEMES: "Administrer temaer"
@@ -303,3 +303,4 @@ STR_SCREENSHOT_BUTTON: "Screenshot maken"
 STR_AUTO_TURN_ENABLED: "Automatisch omslaan ingeschakeld: "
 STR_AUTO_TURN_PAGES_PER_MIN: "Autom. omslaan (pagina's per minuut)"
 STR_TILT_PAGE_TURN: "Kantel om te bladeren"
+STR_MANAGE_THEMES: "Thema's beheren"
@@ -350,6 +350,7 @@ STR_INSTALLED: "Installed"
 STR_DOWNLOAD_ALL: "Download All"
 STR_UPDATE_ALL: "Update All"
 STR_UPDATE_AVAILABLE: "Update"
+STR_MANAGE_THEMES: "Manage Themes"
 STR_CRASH_TITLE: "System Crash"
 STR_CRASH_DESCRIPTION: "A detailed report was saved to crash_report.txt. Please include this file in your bug report."
 STR_CRASH_REASON: "Crash reason:"
@@ -273,3 +273,4 @@ STR_SLEEP_TIMER_VALUE_FORMAT: "%u min"
 STR_SLEEP_NEVER: "Ei koskaan"
 STR_SLEEP_TIMER_STEP_HINT: "Vasen/Oikea: 1 min  Ylös/Alas: 5 min"
 STR_TILT_PAGE_TURN: "Sivunkääntö kallistamalla"
+STR_MANAGE_THEMES: "Hallinnoi teemoja"
@@ -304,3 +304,4 @@ STR_SCREENSHOT_BUTTON: "Capture d'écran"
 STR_AUTO_TURN_ENABLED: "Tourne-page auto : "
 STR_AUTO_TURN_PAGES_PER_MIN: "Tourne-page auto (pages par minute)"
 STR_TILT_PAGE_TURN: "Tourner par inclinaison"
+STR_MANAGE_THEMES: "Gérer les thèmes"
@@ -380,3 +380,4 @@ STR_FIRMWARE_WRITE_FAILED: "Schreiben der Firmware-Datei ist fehlgeschlagen"
 STR_FIRMWARE_UPDATE_DO_NOT_POWER_OFF: "Nicht ausschalten!"
 STR_RECOVERY_MODE: "Wiederherstellungsmodus"
 STR_RECOVERY_MODE_HINT: "Lege firmware.bin im SD-Kartenwurzelverzeichnis ab und wähle es aus"
+STR_MANAGE_THEMES: "Designs verwalten"
@@ -384,6 +384,7 @@ STR_BOOKMARK_REMOVED: "הסימנייה הוסרה"
 STR_QUICK_RESUME: "חזרה מהירה"
 STR_REMOVE_FROM_RECENTS: "להסיר מרשימת הספרים האחרונים?"
 STR_CONFIRM_DELETE_BOOKMARK: "למחוק סימנייה זו?"
+STR_MANAGE_THEMES: "ניהול ערכות נושא"
 STR_LONG_PRESS_MENU: "לחיצה ארוכה על אישור"
 STR_KOSYNC: "KOSync"
 STR_BOOKMARK_OPTION: "סימנייה"
@@ -300,3 +300,4 @@ STR_SCREENSHOT_BUTTON: "Képernyőkép készítése"
 STR_AUTO_TURN_ENABLED: "Automatikus lapozás bekapcsolva: "
 STR_AUTO_TURN_PAGES_PER_MIN: "Automatikus lapozás (oldal/perc)"
 STR_TILT_PAGE_TURN: "Döntéses lapozás"
+STR_MANAGE_THEMES: "Témák kezelése"
Author	SHA1	Message	Date
Justin Mitchell	79f5657fb2	Add configurable default home screen action Themes can now specify an initialAction in home screen config to set the default selected action when entering home normally. Falls back to this theme setting when no explicit action is requested, but explicit firmware navigation still takes precedence.	2026-06-28 02:38:53 -04:00
Justin Mitchell	48aa3c8e02	Add SD theme system Adds installable SD-card themes with manifest downloads, theme registry parsing, themed home/chrome/settings/file browser support, FreeInk layout integration, theme documentation, and layout tests.	2026-06-28 01:44:38 -04:00
Bastian	cbaa498ccc	docs: adding quick resume option and quick resume on timeout to userguide (#2425 )	2026-06-27 22:40:21 +03:00
Justin Mitchell	ebebc6f202	chore: migrate from open-x4-sdk to freeink-sdk (#2449 ) This PR moves us from the xteink openx4 SDK to the freeink sdk from https://freeink.org. Out of the box there are NO changes needed in the firmware to support this swap, it all magically works as is. However as we support more than just the x3/x4 devices, this sdk allows us to pass env vars into the build commands to include support for other devices. As support for new hardware such as touch screens and bluetooth are added the xteink builds decide at compile time if the libraries are used or not. For example right now the freeinkui and icons libraries are in the platform.io file but as they are not used anywhere, they won't be included in the final build. Once the touch branch and sd themes branch are merged in this sdk is required for them to function correctly. All the docs for freeink are available at freeink.org/docs. x4/x3 is a single binary build unlike other devices that will build unique binaries for each device. Eventually we will want to remove a lot of the manual isx3 type stuff from our firmware and go through the boardsupport api the sdk provides as it will generalize everything into one common system that any device can support. The upcoming touch branch does a lot of this for us but this initial PR is JUST to get the sdk swapped over without any code changes to show seamless integration without any regressions.	2026-06-27 21:22:58 +03:00