Kindle Dashboard

简体中文

A low-power, always-on information board for a jailbroken Kindle. It renders directly to the e-ink framebuffer with FBInk, keeps working without the Kindle Store, shows cached data when Wi-Fi is unavailable, and reliably restores the full board after sleep, cover wake, or USB Drive Mode.

The current layout was designed and physically tested on a Kindle Oasis 3 (10th generation, 1264×1680) running firmware 5.18.2. The shell and rendering approach may be adaptable to other jailbroken Kindles, but the coordinates and lifecycle behavior are not yet guaranteed on other models.

Warning

This project does not jailbreak a Kindle. Jailbreaking and modifying the root filesystem carry real device and support risks. Follow a current guide for your exact model and firmware, keep a recovery path, and proceed only if you understand those risks.

What it does

• Draws a high-contrast dashboard directly to the Kindle framebuffer.
• Uses OpenType CJK fonts instead of coarse fixed-cell bitmap text.
• Shows time, date, weekday, location, temperature, financial summary, three focus items, a three-month trend, team counts, battery, and Wi-Fi state.
• Fetches weather from Open-Meteo with a local last-known-good cache.
• Optionally fetches a strict, read-only dashboard snapshot from a trusted LAN.
• Continues showing the last valid data when the network or server is down.
• Adds KUAL actions for install, start, refresh, diagnostics, stop, and autostart removal.
• Starts after Kindle's framework_ready event through Upstart.
• Avoids drawing while the device is in screensaver or suspend states.
• Restores the whole board after outOfScreenSaver and after USB storage returns.
• Uses periodic full and non-flashing recovery waveforms to balance clarity, ghosting, and visual interruption.

Architecture

flowchart LR
    Weather[Open-Meteo] -->|HTTPS, cached| Daemon
    Data[Optional LAN data endpoint] -->|plain text, max 2 KiB| Daemon
    KUAL[KUAL controls] --> Daemon[BusyBox shell daemon]
    Power[Kindle powerd events] --> Watcher[Wake watcher]
    Watcher --> Daemon
    Daemon --> Render[FBInk + OpenType fonts]
    Render --> Panel[e-ink framebuffer]
    Daemon --> Cache[/mnt/us/kindle-dashboard/state]

Loading

The Kindle never needs database credentials or upstream API secrets. If your real data is protected, run a minimal read-only adapter on a trusted host and send only the fields documented in docs/data-protocol.md.

Requirements

Kindle

• A jailbroken Kindle capable of running KUAL extensions.

• KUAL and MRPI installed according to the current guide for the device.

• A Kindle build of FBInk with OpenType support, available by default at:

  /mnt/us/libkh/bin/fbink
  

• Wi-Fi for weather or live dashboard data.

The project does not bundle FBInk. FBInk is a separate GPL-3.0-or-later project; this repository invokes its command-line binary.

Development computer

• POSIX shell
• jq
• shellcheck
• ripgrep
• zip
• Node.js 18+ only if you want to run the included example data server

Quick start

1. Clone and configure

git clone https://github.com/jefftko/kindle-dashboard.git
cd kindle-dashboard
cp config/dashboard.conf.example config/dashboard.conf

Edit config/dashboard.conf. At minimum, set your weather location if weather is desired:

WEATHER_ENABLED=1
LOCATION_NAME=YOUR CITY
LATITUDE=YOUR_LATITUDE
LONGITUDE=YOUR_LONGITUDE
TIMEZONE=Area/City

config/dashboard.conf is intentionally ignored by Git because it may contain a precise location or private LAN address.

2. Build the device archive

make check
make package

The archive is created at:

dist/kindle-dashboard-0.1.0.zip

Its two top-level directories already match Kindle USB storage:

kindle-dashboard/
extensions/kindle-dashboard/

dist/SHA256SUMS contains the archive checksum.

3. Copy to the Kindle

Connect the Kindle in USB Drive Mode, extract the archive, and copy both top-level directories to the root of the Kindle USB drive—the same level as documents/.

After copying, the device paths must be:

/mnt/us/kindle-dashboard/
/mnt/us/extensions/kindle-dashboard/

Safely eject the Kindle before unplugging it.

4. Install and start

Open KUAL and choose:

Kindle Dashboard → Install / Update & Start

This performs three actions:

1. Copies system/kindle-dashboard.conf to /etc/upstart/.
2. Creates state/enabled and a one-shot refresh marker.
3. Starts the daemon and renders the board.

The first render intentionally waits for the native Kindle framework to finish painting. A delay of roughly 25 seconds is normal.

Configuration reference

All values live in config/dashboard.conf. Keep each value on one line and do not place shell commands in the file.

Key	Default	Description
BOARD_TITLE	OASIS / BOARD	Small header title.
OVERVIEW_TAG	/ OVERVIEW	Label next to the overview heading.
DATA_SOURCE_LABEL	LOCAL API · READ ONLY	Source note near the bottom.
WEATHER_ENABLED	0	Set to 1 after configuring a real location.
LOCATION_NAME	YOUR CITY	Short display name; dynamic CJK is supported.
LATITUDE	0.0000	Open-Meteo latitude.
LONGITUDE	0.0000	Open-Meteo longitude.
TIMEZONE	UTC	IANA timezone, for example Asia/Tokyo.
WEATHER_REFRESH_MINUTES	30	Weather cache interval.
DASHBOARD_URL	empty	Optional read-only LAN snapshot URL.
DASHBOARD_REFRESH_MINUTES	15	Dashboard snapshot interval.
FULL_REFRESH_MINUTES	15	Flashing high-quality GC16 cleanup interval.
RECOVERY_REFRESH_MINUTES	3	Non-flashing full-body recovery interval.
SCREEN_TIMEOUT_SECONDS	7200	Idle timeout; cover-close sleep still works.
STARTUP_SETTLE_SECONDS	25	Delay after framework startup.
WAKE_SETTLE_SECONDS	8	Delay after wake before a full restore.

The renderer targets 1264×1680. Changing the panel geometry currently requires editing the coordinates in bin/render.sh.

Optional live data

Leaving DASHBOARD_URL empty is valid. The board displays placeholders and the three local lines in data/tasks.txt.

For a quick LAN demo:

node examples/data-server/server.mjs
curl http://127.0.0.1:8787/dashboard

Then configure:

DASHBOARD_URL=http://HOST_LAN_ADDRESS:8787/dashboard

Use the host's actual LAN address—not 127.0.0.1, which would refer to the Kindle itself. The Kindle and host must be on the same trusted network, and the host firewall must allow the chosen port.

The example server contains no authentication and must not be exposed directly to the public internet. For a real integration, implement the small protocol documented in docs/data-protocol.md.

Refresh and wake behavior

E-ink is not a normal display: partial updates are fast but can leave ghosting, while full high-quality updates are clearer but visibly flash.

The default policy is:

1. Render the complete board after startup.
2. Update only the 300-pixel header between body refreshes.
3. Perform a high-quality full GC16 refresh every 15 minutes.
4. Perform a non-flashing full GL16 recovery every 3 minutes.
5. Skip all drawing while powerd_test reports a non-active state.
6. Listen for com.lab126.powerd outOfScreenSaver.
7. Wait 8 seconds after wake, then restore the complete board.
8. Detect /mnt/us returning after USB Drive Mode and restore again.

This ordering prevents a clock-only header from being drawn over a native book cover, screensaver, Home page, or Library page.

The project extends the idle screensaver timeout but deliberately does not set preventScreenSaver=1 or disable screen-off. Cover-close sleep remains intact.

KUAL actions

Action	Result
Install / Update & Start	Installs Upstart autostart and starts the board.
Start	Re-enables and restarts the board.
Refresh data + screen	Fetches configured sources and draws a full frame.
Diagnostics	Writes state/diagnostics.txt.
Stop / Return Home	Stops drawing and restarts the native Kindle UI.
Remove autostart	Stops the board and removes /etc/upstart/kindle-dashboard.conf.

Device directory layout

/mnt/us/kindle-dashboard/
├── bin/                       renderer, fetchers, daemon, controls
├── config/dashboard.conf      device-specific configuration
├── data/                      local fallback focus items
├── fonts/                     OFL CJK font subsets
├── state/                     generated cache, logs, and enable marker
└── system/                    Upstart job source

/mnt/us/extensions/kindle-dashboard/
├── bin/                       thin KUAL wrappers
├── config.xml
└── menu.json

Important runtime files:

state/dashboard.log
state/weather.env
state/dashboard.env
state/diagnostics.txt
state/enabled
state/force-refresh

Privacy and security

• The public repository contains synthetic data only.
• Local configuration and runtime state are ignored by Git.
• The Kindle parser rejects unknown response keys and bodies over 2 KiB.
• Valid data is moved into place atomically; a failed fetch keeps the previous cache.
• Do not put database passwords, API tokens, cookies, or authorization headers in dashboard.conf.
• Prefer a minimal, read-only LAN adapter over direct database access.
• Redact diagnostics before opening a public issue.

See SECURITY.md for reporting and deployment guidance.

Development and validation

Run everything:

make check

The checks cover:

• POSIX shell syntax
• KUAL JSON validity
• required release files
• ShellCheck
• full, fast-full, and clock render paths through an FBInk mock
• response fetching and validation
• wake-event signaling
• accidental private paths, RFC1918 addresses, and AppleDouble files

Run tests individually:

sh tests/test-render.sh
sh tests/test-fetch-dashboard.sh
sh tests/test-wake-watcher.sh

Rebuild a release archive:

make package
unzip -l dist/kindle-dashboard-0.1.0.zip
(cd dist && shasum -a 256 -c SHA256SUMS)

Fonts

The bundled fonts are renamed subsets of Noto Sans CJK SC:

• BoardSans-Regular.otf
• BoardSans-Bold.otf
• BoardSans-Data.otf

They are distributed under the SIL Open Font License 1.1; see fonts/OFL.txt and fonts/README.md. Dynamic city, brand, and task text uses the broad data subset. When adding new hard-coded UI strings, update fonts/glyphs.txt and rebuild the compact regular/bold subsets.

Stop, uninstall, and emergency recovery

Normal return to reading:

KUAL → Kindle Dashboard → Stop / Return Home

Remove boot integration:

KUAL → Kindle Dashboard → Remove autostart

If KUAL is unavailable:

1. Connect the Kindle by USB.
2. Delete /mnt/us/kindle-dashboard/state/enabled.
3. Safely eject the drive.
4. Restart the Kindle.

The daemon will no longer start the dashboard. More cases are documented in docs/troubleshooting.md.

Known limitations

• The visual layout is currently fixed for a portrait 1264×1680 framebuffer.
• Upstart, lipc-*, powerd_test, and the wake event are Kindle firmware interfaces and may differ across generations.
• The dashboard intentionally overlays the native UI rather than replacing or stopping the entire Kindle framework.
• There is no touch interaction inside the rendered board; control is through KUAL.
• Jailbreak and firmware compatibility can change. Always use the current Kindle Modding guide for your exact device.

Acknowledgements

• FBInk by NiLuJe for framebuffer rendering.
• Kindle Modding and the MobileRead community for jailbreak, KUAL, and homebrew documentation.
• Open-Meteo for the weather API.
• Noto Sans CJK for the OFL typefaces.

License

Project code is released under the MIT License. Bundled font files are separately licensed under the SIL Open Font License 1.1. FBInk is an external dependency under GPL-3.0-or-later and is not included in this repository.