From ebebc6f202e96c576919b4d838ec4813b301e657 Mon Sep 17 00:00:00 2001 From: Justin Mitchell Date: Sat, 27 Jun 2026 14:22:58 -0400 Subject: [PATCH] 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. --- .gitmodules | 7 ++++--- .skills/SKILL.md | 4 ++-- bin/clang-format-fix.ps1 | 4 ++-- docs/contributing/architecture.md | 6 +++--- freeink-sdk | 1 + open-x4-sdk | 1 - platformio.ini | 14 ++++++++++---- 7 files changed, 22 insertions(+), 15 deletions(-) create mode 160000 freeink-sdk delete mode 160000 open-x4-sdk diff --git a/.gitmodules b/.gitmodules index 80308f05..7c0ed75c 100644 --- a/.gitmodules +++ b/.gitmodules @@ -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 diff --git a/.skills/SKILL.md b/.skills/SKILL.md index 9ebda0a1..55e72d23 100644 --- a/.skills/SKILL.md +++ b/.skills/SKILL.md @@ -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) diff --git a/bin/clang-format-fix.ps1 b/bin/clang-format-fix.ps1 index f90a81b7..28e9394c 100644 --- a/bin/clang-format-fix.ps1 +++ b/bin/clang-format-fix.ps1 @@ -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' diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md index 3e1729a5..b0a85056 100644 --- a/docs/contributing/architecture.md +++ b/docs/contributing/architecture.md @@ -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 diff --git a/freeink-sdk b/freeink-sdk new file mode 160000 index 00000000..8be32366 --- /dev/null +++ b/freeink-sdk @@ -0,0 +1 @@ +Subproject commit 8be32366091e3e0eadeda9b983091166140f816f diff --git a/open-x4-sdk b/open-x4-sdk deleted file mode 160000 index 198ad267..00000000 --- a/open-x4-sdk +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 198ad267219c25c8ab84418b806c66f1fb5216a3 diff --git a/platformio.ini b/platformio.ini index 0fae0516..03a2ece2 100644 --- a/platformio.ini +++ b/platformio.ini @@ -35,6 +35,8 @@ build_flags = # Increase PNG scanline buffer to support up to 2048px wide images # Default is (320*4+1)*2=2562, we need more for larger images -DPNG_MAX_BUFFERED_PIXELS=16416 + -DFREEINK_DEVICE_X4=1 + -DFREEINK_DEVICE_X3=1 -Wno-bidi-chars -Wl,--wrap=panic_print_backtrace,--wrap=panic_abort,--wrap=bootloader_common_check_efuse_blk_validity -fno-exceptions @@ -57,10 +59,14 @@ extra_scripts = ; Libraries lib_deps = - BatteryMonitor=symlink://open-x4-sdk/libs/hardware/BatteryMonitor - InputManager=symlink://open-x4-sdk/libs/hardware/InputManager - EInkDisplay=symlink://open-x4-sdk/libs/display/EInkDisplay - SDCardManager=symlink://open-x4-sdk/libs/hardware/SDCardManager + BatteryMonitor=symlink://freeink-sdk/libs/hardware/BatteryMonitor + InputManager=symlink://freeink-sdk/libs/hardware/InputManager + EInkDisplay=symlink://freeink-sdk/libs/display/FreeInkDisplay + SDCardManager=symlink://freeink-sdk/libs/hardware/SDCardManager + BoardConfig=symlink://freeink-sdk/libs/hardware/BoardConfig + PowerManager=symlink://freeink-sdk/libs/hardware/PowerManager + FreeInkUI=symlink://freeink-sdk/libs/ui/FreeInkUI + Icons=symlink://freeink-sdk/libs/assets/Icons bblanchon/ArduinoJson @ 7.4.2 ricmoo/QRCode @ 0.0.1 bitbank2/PNGdec @ 1.1.6