Turn a cheap, jailbroken Kindle Oasis into a wall/desk Home Assistant dashboard — weather + 5-day forecast, tappable controls, a sensor tile, an optional calendar and live sensor graphs — fully touch-interactive, on e-ink, sipping battery. Plus a quick-jump that bounces you between your book, a terminal, and an SSH session on your homelab with a single tap in the library.
This repo is the field notes: how we jailbroke it, what we learned about the Kindle's
internals, and how we built the panel — including all the quirks that cost hours
(the fbink image gotcha, dbclient vs ssh, busybox arithmetic, framework-pause for
touch, the crash that froze the device, RTC-wake sleep, and more).
It doubles as a general Kindle-hacking primer — the ecosystem overview (KUAL, MRPI, hotfix, KOReader, the DRM reality, OTA persistence) and the SSH guide stand on their own, whether or not you ever build the panel.
ℹ️ This is a generic, non-functional template. The only live integration is weather (yr/met.no); the light/sensor tiles are placeholder examples — swap the entity IDs in
ha-panel.sh's CONFIG block for your own. Nothing here contains real tokens, keys, IPs, or entity/device names. The techniques are the point — bring your own Home Assistant setup.
🤖 How this repo was made. It documents a real, working panel on my own jailbroken Oasis — everything here was actually run and debugged on-device. The write-up itself was authored with an AI assistant (Claude Code) from those experiments, then the panel's specifics — real entities, tokens, IPs, device/homelab names — were deliberately stripped and genericized. So: the lessons are battle-tested, but treat the prose and scripts as a reference to verify against your own device, not gospel. Firmware differs, details drift, and AI can be confidently wrong — when in doubt, trust kindlemodding.org and the MobileRead forums. No warranty; you jailbreak and wire up controls at your own risk.
┌───────────────────────────────────────────────────────────┐
│ HOME Kindle 86% 10:19 EXIT │
├───────────────────────────────────────────────────────────┤
│ WEATHER │
│ 14.6°C ⛅ partlycloudy │
│ 54% RH · wind 6 km/h │
│ Mon Tue Wed Thu Fri │
│ ⛅ ☀ ⛅ 🌧 ⛅ (5-day forecast, yr) │
│ 23/14 25/8 24/14 21/13 23/12 │
├───────────────────────────────────────────────────────────┤
│ SENSOR (example) 21.4 │
├───────────────────────────────────────────────────────────┤
│ LIGHTS (example) [Room 1 ●] [Room 2 ○] [Room 3 ●] │
├───────────────────────────────────────────────────────────┤
│ CALENDAR (optional) Mon | Tue | Wed | Thu | Fri │
└───────────────────────────────────────────────────────────┘
▲ everything but WEATHER is a placeholder — bring your own entities
Because that's the trap everyone hits. The Kindle's "experimental" browser is a ~2009-era WebKit with tiny RAM/GPU: no websockets, no CSS grid, no CORS, and nowhere near enough horsepower for the modern Lovelace UI. You get JS slowness, half-rendered dashboards, and eventual breakdown. It's a dead end for anything interactive.
The community has three real ways to do it — this repo is the third:
| Approach | How | Interactive? | Trade-off |
|---|---|---|---|
| Experimental browser → Lovelace | aim the Kindle browser at HA | the failure mode above — old WebKit, no websockets, JS grinds to a halt | |
| PNG/screenshot server | a server renders the dashboard to an image; Kindle displays + refreshes on a timer | ❌ glance-only | dead simple & low-power, but no touch control and interval lag (petterhj, kindle_infoscreen) |
This repo — native fbink + REST |
shell draws with fbink, luajit grabs touch, talks HA REST directly — no browser at all |
✅ full touch control | needs a jailbreak + scripting, but it's fast, spot-refreshes single tiles, and actuates devices |
So: if you only want to glance, a PNG server is less work. If you want to tap a tile and have a light/lock/thermostat actually respond on e-ink, you skip the browser entirely and draw the UI yourself — which is what this guide is about. (See also KFloorP for a jailbroken-Kindle floorplan take.)
flowchart LR
subgraph Kindle["Kindle Oasis (jailbroken)"]
panel["ha-panel.sh<br/>fbink draw + touch loop"]
grab["grab.lua<br/>EVIOCGRAB touchscreen"]
panel <--> grab
end
subgraph Homelab["Homelab (Docker)"]
ha["Home Assistant"]
cal["cal-helper<br/>:8899 calendar"]
gsvc["graph-svc<br/>:8900 matplotlib PNG"]
end
gcal["Google Calendar<br/>(secret iCal URL)"]
panel -- "REST /api (token)" --> ha
panel -- "GET plain-text" --> cal
panel -- "GET graph.png" --> gsvc
cal -- "fetch .ics" --> gcal
gsvc -- "REST history + forecast" --> ha
| # | Guide | What's in it |
|---|---|---|
| 0 | Ecosystem primer | Start here — KUAL/MRPI/hotfix/KOReader glossary, how it fits, DRM reality, OTA persistence |
| 1 | Jailbreak | Getting root: hotfix, KUAL, scriptlets |
| 2 | SSH client & server | usbnetlite, dropbear, the dbclient vs ssh key trap |
| 3 | System internals | lipc, mounts, the framework, fbink, input devices |
| 4 | The HA panel | Drawing on e-ink, touch, framework-pause, the 3 run modes |
| 5 | Homelab backend | Calendar + graph microservices in Docker |
| 6 | Gotchas & lessons | Every quirk that cost us time — read this one |
| 7 | Quick-jump | One-tap library ⇄ terminal ⇄ homelab, and the foreground-launch lesson |
# 1. put your token + HA url on the Kindle
echo 'HA_URL=http://homelab:8123' > /mnt/us/.ha_env # (see config.example.sh)
echo '<HA_LONG_LIVED_TOKEN>' > /mnt/us/.ha_token && chmod 600 /mnt/us/.ha_token
# 2. copy scripts to /mnt/us and edit the entity IDs at the top of ha-panel.sh
# 3. run it
sh /mnt/us/ha-panel.sh # interactive
sh /mnt/us/ha-panel.sh kiosk # low-power, wake-to-touch- Kindle Oasis 3 (10th gen), firmware 5.18.2 (KPP)
- Jailbreak via KindleModding (hotfix + KUAL)
fbink,luajit, fonts from KOReader- A homelab running Docker (we co-located with Home Assistant)
This repo is field notes. For anything about your device, the source of truth is KindleModding:
- Jailbreaking (find your jailbreak) — the oracle
- Kindle models — identify your device first
- Set up a hotfix — make it persist
- Scriptlets — run
.shfrom the library - Awesome window manager — the proper way to draw fullscreen
- Kindle SDK / toolchain — compile native helpers
- FBInk · KOReader · Dropbear
Built with the excellent work of KindleModding, NiLuJe's FBInk, KOReader, and Dropbear.
MIT — see LICENSE.