Free-Ink /freeink-sdk

A hardware-independent SDK for building e-paper reader firmware.

★ 300⑂ 216👁 6⑃ 199● 16▤ 0
C++MITCreated 2026-06-03freeink.org
+1
Daily
300
stars
216
forks
6
watchers
199
prs
16
issues
0
releases

README

FreeInk SDK



A hardware-independent SDK for building e-paper reader firmware. FreeInk
abstracts every device-specific detail — display controller, waveforms/LUTs,
GPIOs, bus speeds, input style, touch, frontlight, audio — behind small,
injectable interfaces, so the firmware calls one generic API and gets
device-specific behavior. Adding a new device means adding data (a board
profile + a driver config), not editing the generic code.

It is drop-in compatible with firmware written against the original
EInkDisplay / InputManager / BatteryMonitor / SDCardManager / BoardConfig
API: switching to FreeInk is a matter of repointing the library path.

Start with PlatformIO integration, browse the
documentation index, or run the host tests.

 What's included

- Display facade and panel drivers for SSD1677, UC8179, UC8253, UC8279,
  ED2208, IT8951, and external-library-backed panels.
- Board profiles and capability gates for display, input, touch, SD,
  frontlight, audio, microphone, RTC, sensors, buzzer, LEDs, and TLS networking.
- Device managers that keep firmware code stable across different boards:
  input, battery, SD, frontlight, LEDs, audio, microphone, RTC, sensors, and IMU.
- FreeInkUI, an optional immediate-mode UI layer for e-paper reader screens,
  dialogs, settings, keyboards, library views, and future GUI-builder previews.
- FreeInkBook, a complete EPUB reading engine — streaming parse, CSS,
  UAX 14 layout with hyphenation/justification/ligatures, page caching with
  exact position anchors, TTF fonts with per-codepoint fallback, image
  dithering, links/footnotes — freestanding, arena-allocated, host-tested
  (see docs/freeink-book.md).
- Icon and asset tooling for crisp 1-bpp Lucide-derived icons and generated
  C/C++ assets.

 Credit & lineage

FreeInk is an MIT-licensed re-architecture derived from the
OpenX4 E-Paper Community SDK (open-x4-epaper/community-sdk, MIT) and its
contributors — in particular CidVonHighwind for the original EInkDisplay
driver and the X3/X4 waveform work, and the community device ports (M5Stack
PaperColor, Murphy M3, and the community-sdk-de-link ESP32-S3 port). The
register sequences and waveform LUTs for the SSD1677 and UC8253 panels are
derived from that project — i.e. carried over and adapted, not
reverse-engineered independently — so the community's panel tuning is preserved.
Attribution is in NOTICE. Huge thanks to everyone who reverse-engineered and
tuned those panels.

See display driver reference coverage for
the source hierarchy and the limits of matching GxEPD2 implementations.

What FreeInk changes is the structure, not the panel work: where the upstream
interleaves every device in one monolithic driver, FreeInk splits each controller
into a standalone, compile-time-selectable driver behind a stable facade, with
per-device behavior supplied as injectable config. It is not a fork and has no
build-time or runtime dependency on the upstream repository — its own history and
architecture — but the inheri

Top issues

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON