Controlling Home Assistant with a Kindle

bogdan.sv · September 4, 2026, 11:53am

Hi everyone. This guide turns a cheap Kindle into an interactive Home Assistant dashboard. E-Ink sips power and the devices go for next to nothing second-hand — mine is a Kindle 7th generation (firmware 5.12.2.2) that cost about $12 on OLX, Ukraine’s classifieds site for used goods.

Up front: the dashboard doesn’t need a jailbreak, the screensaver does. Both newer and older firmware can be jailbroken — check your model and serial number on kindlemodding.org before buying.

Jailbreaking the Kindle

Pick the right jailbreak using the wizard. In my case it turned out to be WinterBreak2.

Fill up the device storage so it can’t update itself. This is where I hit a snag — the script wouldn’t accept my answers in the browser. So I downloaded it first and ran it locally instead.

Download the latest WinterBreak2 release. I’m deliberately not linking a specific file, because by the time you read this the latest release will probably be a different one. Just follow the official instructions.
Unpack wb2.zip and move the winterbreak2 folder to the root of the Kindle.

Safely eject the device from the computer and connect it to Wi-Fi.
Open the Experimental Browser and go to https://penguins184.xyz/wb2

Press the Jailbreak button in the middle of the screen.

Jailbreak button1151×1112 137 KB
The process starts and a strange-looking window appears. Don’t panic. After a moment a not-very-obvious Close button shows up in the bottom right corner — tap it. To check whether the jailbreak worked, type ;log into the search bar. In my case a new text file named JAILBROKEN appeared. That means you’re in.

Reboot the Kindle: three dots → Settings → Device Options → Restart. Wait for the reboot to finish completely.

restarting the Kindle600×800 13.1 KB
Remove the blocking files — either with the same script, or by hand.

Building the Home Assistant dashboard

For the interactive dashboard I used the Kindle-Home-Assistant-Remote project by derekmcauley7 as a starting point.

In short: you create an HTML file with the controls in it, put it inside the Home Assistant file system, and open that file in the Kindle browser.

Get a long-lived access token in Home Assistant. Sidebar → your user profile → Security tab → Long-lived access tokens → Create token. Give it any name and copy the token.

Using the File Editor add-on, create a folder called www. It must sit at the same level as configuration.yaml. If you don’t have File Editor, install it from the add-on store.

Inside www, create an .html file with any name — for example kindle-dashboard.html — and paste in the code. Here’s my own variation of the same dashboard: I translated the comments and the interface into Ukrainian, and added tiles, behaviour and domains for a TV and an air conditioner.

At first glance the file looks big and complicated, but once the structure clicks it’s much simpler. Roughly, it breaks down into a few parts:

Settings — three variables at the top of <script>:

HA_TOKEN — paste your long-lived token here
HA_URL — the address of Home Assistant; you can leave it empty if the file lives in Home Assistant’s own wwwfolder
AUTO_REFRESH_MS — how often the page refreshes automatically

GROUPS — the list of entities and the sections they appear in. This is the part you’ll edit most often: the entity id from Home Assistant and name, the label on the tile.

DOMAIN_META — the behaviour of each domain: which icon to use, which state counts as “on”, which labels to show, and which services to call when a domain doesn’t support a plain toggle. This is exactly where climate and media_player were added.

ICONS — icons as simple inline SVG, no external files, so they’re guaranteed to render on e-ink.

Rendering and logic — the rest of the code, which you don’t need to touch: it builds the tiles from GROUPS, pulls states through the Home Assistant API and toggles devices.

A note on state updates. States only refresh while the page is open. The Refresh button at the bottom updates every tile at once. AUTO_REFRESH_MS controls how often that happens automatically — 30 seconds by default. When the Kindle goes to sleep, refreshing stops. Set it to 0 and states will only ever update when you press the button.

Home Assistant online screensaver

This part does need the jailbreak. When the Kindle sleeps or locks, it loads nice pictures from device storage. The hass-lovelace-kindle-screensaver project takes advantage of that: it screenshots a Home Assistant dashboard, converts it into a format the Kindle understands, and shows it on the lock screen. The fun part is that Home Assistant is extremely flexible, so you can put anything you like on that dashboard, styled however you want. You’ll need both a Home Assistant add-on and a Kindle extension.

In Home Assistant go to Settings → Add-ons → Add-on Store, click the three dots in the top right → Repositories → Add, and paste: https://github.com/sibbl/hass-lovelace-kindle-screensaver

Find and install Lovelace Kindle Screensaver in the add-on store. To configure it you’ll need a dashboard path and a token:

Pick an existing dashboard or create a new one and copy its address. For example, the URL I see in my browser is http://192.168.31.172:8123/dashboard-kindle/0, so my dashboard path is dashboard-kindle/0
Create a long-lived access token

In the Lovelace Kindle Screensaver Configuration tab, enter your Home Assistant address, the dashboard path and the access token. Everything else can stay as it is. Don’t share your access token publicly. Start the add-on.

HA_BASE_URL: http://192.168.31.172:8123 
HA_SCREENSHOT_URL: /dashboard-kindle/0
HA_ACCESS_TOKEN: >- 'TOKEN'
HTTP_AUTH_USER: ''
HTTP_AUTH_PASSWORD: ''
LANGUAGE: uk
CRON_JOB: '* * * * *'
RENDERING_TIMEOUT: 60000
RENDERING_DELAY: 0
RENDERING_SCREEN_HEIGHT: 600
RENDERING_SCREEN_WIDTH: 800
BROWSER_LAUNCH_TIMEOUT: 30000
BROWSER_CACHE_TTL_SECONDS: 86400
ROTATION: 90
SCALING: 1.3
GRAYSCALE_DEPTH: 8
IMAGE_FORMAT: png
COLOR_MODE: GrayScale
REMOVE_GAMMA: true
PREFERS_COLOR_SCHEME: light
HA_BATTERY_WEBHOOK: ''
SATURATION: 1
CONTRAST: 1
ADDITIONAL_ENV_VARS: []

If it started correctly, clicking Open Web UI shows a black-and-white image. The same image should be available at your Home Assistant address on port 5000 — in my case http://192.168.31.172:5000

Now install the software on the Kindle itself. First you need KUAL — the Kindle Unified Application Launcher. It’s a menu for third-party applications that the Kindle doesn’t ship with. There’s a separate guide for it on the Kindle Modding wiki.

For my Kindle the first option, PEKI, is the right one, so that’s what I downloaded. Next I downloaded MRPI (MobileRead Package Installer) for Modern Devices.

Unpack kual-mrinstaller-khf, copy the extensions and mrpackages folders and move them to the root of the Kindle.

Unpack PEKI.
Copy KUAL.sh and KUAL.jar into the documents folder on the Kindle.
Eject the Kindle. The KUAL icon will appear on the screen.

You also need two hacks (.bin files that modify the Kindle system itself) from NiLuJe’s thread on MobileRead:

linkss — lets you replace the stock screensaver with your own image. It creates the folder that Online Screensaver drops the downloaded picture into. Nothing works without it.
USBNetwork — gives you SSH access to the Kindle. Optional, but a lifesaver when you need to look at logs.

For my Kindle, in the section titled Packages targeting the Kindle 5, I needed kindle-linkss-0.25.N-r18981.tar.xzandkindle-usbnet-0.22.N-r19297.tar.xz. Unpack both, find Update_linkss_0.25.N_install_pw2_and_up.bin in the first and Update_usbnet_0.22.N_install_pw2_and_up.bin in the second, and copy them into the mrpackages folder. Nothing else from those archives is needed.

Then eject the Kindle, open KUAL → Helper → Install MR Packages. Both packages installed in a single pass for me, and a new Screen Savers entry appeared in KUAL.

To check whether image replacement works, just lock the screen — you should see a little penguin.

After installation, a linkss/screensavers folder with bg_ss00.png appears in the Kindle root — that file is now what drives the lock screen. Replace it with your own picture: a grayscale PNG, 600×800, with the same filename. There are good ready-made images out there, and it’s easy enough to prepare your own in an image editor.

Next, download Online Screensaver and copy it in full into the extensions folder, so you end up with extensions/onlinescreensaver/bin/.... This extension downloads an image from a given address on a schedule and drops it into the linkss folder — in other words, it automates the screensaver replacement.
Now edit three settings in bin/config.sh:

IMAGE_URI — where to fetch the picture from. This is your Home Assistant address with the add-on’s port 5000, e.g. 192.168.31.172:5000
SCREENSAVERFILE — where to put it. The config ships with bg_medium_ss00.png; I changed it to bg_ss00.png, since that’s the name of the penguin image.
The rest can stay as-is. There’s also SCHEDULE — the update schedule — but the defaults work fine.

#############################################################################
### ONLINE-SCREENSAVER CONFIGURATION SETTINGS
#############################################################################

# Interval in MINUTES in which to update the screensaver by default. This
# setting will only be used if no schedule (see below) fits. Note that if the
# update fails, the script is not updating again until INTERVAL minutes have
# passed again. So chose a good compromise between updating often (to make
# sure you always have the latest image) and rarely (to not waste battery).
DEFAULTINTERVAL=300

# Schedule for updating the screensaver. Use checkschedule.sh to check whether
# the format is correctly understood. 
#
# The format is a space separated list of settings for different times of day:
#       SCHEDULE="setting1 setting2 setting3 etc"
# where each setting is of the format
#       STARTHOUR:STARTMINUTE-ENDHOUR:ENDMINUTE=INTERVAL
# where
#       STARTHOUR:STARTMINUTE is the time this setting starts taking effect
#       ENDHOUR:ENDMINUTE is the time this setting stops being active
#       INTERVAL is the interval in MINUTES in which to update the screensaver
#
# Time values must be in 24 hour format and not wrap over midnight.
# EXAMPLE: "00:00-06:00=480 06:00-18:00=15 18:00-24:00=30"
#          -> Between midnight and 6am, update every 4 hours
#          -> Between 6am and 6pm (18 o'clock), update every 15 minutes
#          -> Between 6pm and midnight, update every 30 minutes
#
# Use the checkschedule.sh script to verify that the setting is correct and
# which would be the active interval.
SCHEDULE="00:00-06:00=240 06:00-22:00=120 22:00-24:00=240"

# URL of screensaver image. This really must be in the EXACT resolution of
# your Kindle's screen (e.g. 600x800 or 758x1024) and really must be PNG.
#IMAGE_URI="http://enter.the.domain/here/and/the/path/to/the/image.png"
IMAGE_URI="http://192.168.31.172:5000/"

# folder that holds the screensavers
SCREENSAVERFOLDER=/mnt/us/linkss/screensavers/

# In which file to store the downloaded image. Make sure this is a valid
# screensaver file. E.g. check the current screensaver folder to see what
# the first filename is, then just use this. THIS FILE WILL BE OVERWRITTEN!
SCREENSAVERFILE=$SCREENSAVERFOLDER/bg_ss00.png

# Whether to create log output (1) or not (0).
LOGGING=1

# Where to log to - either /dev/stderr for console output, or an absolute
# file path (beware that this may grow large over time!)
#LOGFILE=/dev/stderr
LOGFILE=/tmp/onlinescreensaver.log

# whether to disable WiFi after the script has finished (if WiFi was off
# when the script started, it will always turn it off)
DISABLE_WIFI=0

# Domain to ping to test network connectivity. Default should work, but in
# case some firewall blocks access, try a popular local website.
TEST_DOMAIN="www.google.com"

# How long (in seconds) to wait for an internet connection to be established
# (if you experience frequent timeouts when waking up from sleep, try to
# increase this value)
NETWORK_TIMEOUT=30



#############################################################################
# Advanced
#############################################################################

# the real-time clock to use (0, 1 or 2)
RTC=0

# the temporary file to download the screensaver image to
TMPFILE=/tmp/tmp.onlinescreensaver.png

Time to test. A new Online-Screensaver entry has appeared in KUAL. Start with Update now for a one-off download, then put the Kindle to sleep with the power button — instead of the penguin you should see your dashboard. If that worked, choose Enable auto-download; from then on the image updates itself on schedule and survives reboots.

Bonus: the KPM package manager

KPM (Kindle Package Manager) is a package manager for jailbroken Kindles. It lets you install and update third-party apps and modifications directly from the device — think of it as apt for the Kindle.

For example:

;kpm update — refresh the package list
;kpm install koreader — install KOReader. I also installed the SimpleUi and App Store plugins.
;kpm install kterm — install the Kterm terminal emulator. The virtual keyboard didn’t come up for me; the fix is to change the kb_conf_path line in kterm.conf.
;kpm upgrade — update already-installed packages

There are plenty of other third-party applications out there too, though I haven’t figured out how to install those yet.

How KPM actually works wasn’t obvious to me at first. You type the command into the search bar. And then the second non-obvious step: move the cursor to the end of the line and press Enter.