I Turned a 2011 Kindle into an E-Ink Display for My Front Door
DEV Community

I Turned a 2011 Kindle into an E-Ink Display for My Front Door

According to a Calibre file still on it, my Kindle 4 last talked to a computer on 15 December 2016. It's the 2011 model with buttons, no touch screen and no backlight, and after an afternoon on the charger the battery still showed 100%.

I wanted to put it by the front door and show something useful there. For a screen you pass on your way out, the useful question is whether you need an umbrella or a warmer coat. I also asked for the Bitcoin price, which takes up less space than you'd expect.

The project is called Doorstep, and it's on GitHub. I built it in an afternoon with Claude Code, and nearly every hour went to five small assumptions that turned out to be wrong.

The Kindle by the front door.

The Kindle should not run anything clever

I had the Kindle and an old laptop. Before Claude Code wrote anything, I asked it to decide what each machine should do. I collected the six prompts in the Doorstep README so you can work through the same decisions with your own hardware.

Prompt 1: The idea and the hardware

I have an old non-touch Kindle (the version with buttons) and an old laptop. I want to turn the Kindle into an always-on display for the entrance of my apartment. It should show useful things for when I leave home, such as the weather and the Bitcoin price, and refresh by itself every 4 hours. Choose what's best for an entrance and explain the architecture before you build it.

The obvious first idea is to open a web page in the Kindle's experimental browser and let it reload itself. On a non-touch Kindle, that idea fails. The screensaver takes over after a few minutes, and nothing on the device can keep the page awake.

Hardly anything runs on the Kindle at all. A server draws a 600ร—800 grayscale PNG, and the Kindle downloads it, draws it with eips, and suspends until the next update. kindle-dash by pascalw does exactly this. Its README says it was tested on the Kindle 4 non-touch, which is what I have.

That split moves every hard part off the device. I write Node.js on a normal machine, and the Kindle only needs a working Wi-Fi connection and a clock.

That gave me something I could build and check before touching the firmware: a single image. The renderer prompt spells out what I want to see on my way out and gives Claude Code the exact file format the Kindle expects.

Prompt 2: The renderer

Build a Node.js renderer that draws a 600x800 portrait dashboard and saves it as an 8-bit grayscale PNG with no alpha channel, because that's what the Kindle's eips tool needs. Use free APIs that need no key: Open-Meteo for weather and CoinGecko for Bitcoin. Show the date, current weather with a big temperature, a black banner with advice on what to bring for the next 12 hours (umbrella, coat, gloves...), a forecast in 3-hour steps plus tomorrow, and the Bitcoin price with its 24h change and a 7-day chart. Use large type, thick lines and hard black and white, since it's e-ink. Don't show a live clock. Show "Updated HH:MM ยท Next HH:MM" instead.

The live image, rendered by GitHub Actions. This is exactly what the Kindle downloads.

The renderer uses @napi-rs/canvas, keyless APIs from Open-Meteo for weather and CoinGecko for Bitcoin, and a hand-written grayscale PNG encoder. I wrote my own encoder because canvas libraries output RGBA, and kindle-dash's own tips ask for "grayscale PNG images, without any alpha layers". The whole encoder is a zlib call and three PNG chunks.

Then I checked the header bytes, because "it opened in my image viewer" proves nothing about what eips will accept:

IHDR 600x800 depth 8 type 0

Two design decisions that came from the door

No clock. A screen that refreshes every 4 hours shows the wrong time for most of the day. The header says "Updated 15:51 ยท Next 19:00" instead, so the screen is honest about how old it is.

One banner that answers the question. The black bar is the only part of the screen you can read from two metres away. It summarises the next 12 hours into something I can act on: "Take an umbrella + light jacket", "Snow boots + hat & gloves", or "Bring water" in July.

The same question about stale time applies to the forecast. What happens if an API goes down overnight and the Kindle still has yesterday's image on it when I reach for my coat?

Prompt 3: Make it robust

Make the image always render, even when an API is down: cache the last good data on disk, use it, and mark it as offline in the footer. Then add a small HTTP server that serves /dashboard.png with a 200 status, plus a preview page. Verify the PNG header yourself: 600x800, bit depth 8, colour type 0.

kindle-dash doesn't update the screen if the fetch fails, so an HTTP error can leave yesterday's forecast on screen with no warning. A valid image can carry the warning itself. Doorstep uses the last good data if it has any, and the footer says Offline: weather from 12:44. On the first run there might be no cache at all, so the renderer has to draw that case too.

Five assumptions that cost me time

I could check the PNG on my laptop. Getting the Kindle to fetch it, display it and go back to sleep took the rest of the work. The fourth prompt asks Claude Code to read the original scripts and find the instructions for my model and firmware.

Prompt 4: The Kindle side

Set up the Kindle with kindle-dash (github.com/pascalw/kindle-dash). Write local/env.sh and local/fetch-dashboard.sh for a refresh every 4 hours that includes 07:00, my timezone, and a full e-ink refresh on every update. Check kindle-dash's source for settings that would break a 4-hour schedule, such as SLEEP_SCREEN_INTERVAL. Write setup steps that point to the MobileRead jailbreak thread for my model and firmware instead of guessing them.

Reading the source caught one trap before I started. The other clues came from plugging in the cable, opening the release tarball and watching what the Kindle actually did.

  1. "It charges, so the cable works"

The Kindle charged and stayed on its home screen. Windows saw nothing: no drive, no Amazon USB device (vendor ID 1949), and no device in the PnP history at all. Replugging it changed nothing. The cable had no data wires.

With a different micro-USB cable, a "Kindle" drive showed up as D: straight away. A Kindle on its home screen with the cable plugged in is the clue: if data were flowing, it would switch to "USB Drive Mode" by itself. There's no button to force that.

  1. "The default config is fine for my schedule"

kindle-dash ships with SLEEP_SCREEN_INTERVAL=3600. If the next wake-up is more than an hour away, it shows a "sleeping" picture instead of your dashboard. With a 4-hour schedule, the next wake-up is always more than an hour away, so I would never have seen the dashboard once. We caught it by reading dash.sh before running anything, not by testing.

The fixed env.sh:

export REFRESH_SCHEDULE="0 3,7,11,15,19,23 * * *"
export TIMEZONE="Europe/Zurich"
export FULL_DISPLAY_REFRESH_RATE=1
export SLEEP_SCREEN_INTERVAL=20000

FULL_DISPLAY_REFRESH_RATE=1 has a similar trap. With the counter logic in dash.sh, 0 gives one full refresh and then partial refreshes forever, so e-ink ghosting builds up. At six updates a day, a full flash every time costs nothing. The 07:00 slot is deliberate. That refresh is the one I actually read on my way out.

  1. "I'll need KUAL to start it"

kindle-dash's README mentions KUAL, the Kindle app launcher, as an optional way to start it, and the first README Claude Code wrote for Doorstep relied on it. When we opened the kindle-dash release tarball, it had no KUAL folder at all. The tested path is shorter: jailbreak, USBNetwork for SSH, then start kindle-dash from a terminal.

The jailbreak is NiLuJe's kindle-k4-jailbreak-1.8.N.zip from the MobileRead thread. The thread title says 4.0.x to 4.1.2, while the MobileRead wiki and a forum report cover 4.1.4. Mine is 4.1.4, and it worked. After copying three files and choosing three items in the diagnostics menu, a book called "You are Jailbroken" showed up in the library.

I didn't want a root password typed anywhere, in a terminal or in the conversation. USBNetwork reads OpenSSH keys from usbnet/etc/authorized_keys, so I put an RSA key there. The bundled dropbear is from 2015 and doesn't accept ed25519.

Then I switched it to SSH over Wi-Fi only, in usbnet/etc/config:

K3_WIFI="true"
K3_WIFI_SSHD_ONLY="true"

That kept the Kindle a normal USB drive, so files could still be copied over the cable, and it skipped setting up a USB network adapter on Windows.

To turn it on, you type three searches on the Kindle's home screen: ;debugOn, ~usbNetwork, ;debugOff. Then a quick port-22 scan found three SSH servers on my network. Two were Debian machines. The third answered SSH-2.0-dropbear_2015.68, and that was the Kindle.

Modern OpenSSH has to be told to accept the old algorithms:

ssh -i ~/.ssh/doorstep_kindle_rsa \
  -o HostKeyAlgorithms=+ssh-rsa \
  -o PubkeyAcceptedAlgorithms=+ssh-rsa \
  root@<kindle-ip>
  1. "The download hangs because the Kindle is slow"

The first real fetch never finished. DNS resolved kasuken.github.io, and ping 1.1.1.1 came back in 22 ms. xh just sat there. The first guess was entropy, because a TLS library on a 2013 kernel can stall waiting for randomness. The Kindle had 167 bits available, which ruled that out.

/proc/<pid>/wchan said pipe_wait, and file descriptor 0 was a pipe. xh, like HTTPie, reads a request body from standard input whenever that input isn't a terminal. Over a non-interactive SSH command, it was waiting for a body that would never arrive.

The fix is one flag:

"$(dirname "$0")/../xh" -d -q --ignore-stdin --check-status --timeout 30 \
  -o "$1" get "$DASHBOARD_URL?t=$(date +%s)"

The ?t= cache-buster is there because GitHub Pages sits behind a CDN. Without it, the Kindle can download the previous cycle's image.

  1. "nohup exists"

It doesn't. The Kindle runs BusyBox 1.7.2, which has no nohup and no setsid, and its grep doesn't support -E. If kindle-dash is started over SSH, it dies when the session closes. A subshell that ignores the hangup signal does the job:

cd /mnt/us/dashboard && ( trap '' HUP ; ./start.sh ) < /dev/null > /dev/null 2>&1 &

The log showed Wi-Fi connected, then Partial screen refresh, and shortly after that the Kindle stopped answering on the network. That's the suspend working as intended.

The dashboard on the Kindle after the first refresh.

No computer at home

The GitHub Pages URL in the fetch command came from asking Claude Code to sketch both ways to host the same image. I already had the laptop, so I started by looking at what it would take to leave it running.

Prompt 5: Hosting

Give me two hosting options: (a) the old laptop, with the Windows firewall rule, power settings and auto-start, and (b) a GitHub Actions workflow that renders the image shortly before each Kindle wake-up and publishes it to GitHub Pages, so no computer at home has to stay on.

The laptop would need to stay awake, keep a reserved IP, and have a firewall rule, all to serve one image six times a day. Once I saw that list, I dropped it. A GitHub Actions workflow renders the PNG and publishes it on GitHub Pages instead. The schedule runs 20 minutes before each Kindle wake-up. GitHub cron runs in UTC and Zurich switches between UTC+1 and UTC+2, so the hours are listed for both:

  • cron: "40 0,1,4,5,8,9,12,13,16,17,20,21 * * *"

The Kindle then fetches https://kasuken.github.io/Doorstep/dashboard.png. The xh binary in the kindle-dash release handles modern TLS, which the Kindle's own curl and wget can't.

A forecast I can change without waiting for snow

The screen in the photos is set to Zurich and CHF. The last prompt pulls those choices into configuration and asks for examples I can render any day.

Prompt 6: Personalise

Set the city to <your city>, the timezone to <your timezone> and the currency to <your currency>. Add a demo script that renders example screens (rainy, snow, summer, offline) from made-up data for the README, plus a mockup of the display in an e-reader frame.

With npm run demo, I can check if a longer recommendation like "Snow boots + hat & gloves" fits in the banner while it's 11 degrees outside. The offline image above comes from the same demo. I can see what the screen says when both APIs fail and there's nothing in the cache.

The snow-day fixture from npm run demo, rendered with made-up data.

What it costs you

The jailbreak puts a community developer key on the device. Amazon firmware updates should stay off from now on, and there is a small risk of making the Kindle unusable. That risk is acceptable for a device nobody had used since 2016. I would think twice about it on a Kindle someone still reads on.

The setup is also not "plug it in and forget it". After a hard restart, the Kindle boots back to its normal home screen and kindle-dash has to be started again over SSH. GitHub also pauses scheduled workflows in repositories without activity for 60 days, so the image can quietly stop updating in January.

Using Claude Code changed where my time went, not how much thinking the project needed. It wrote the renderer, the PNG encoder, and the workflow quickly, and it read dash.sh closely enough to catch the SLEEP_SCREEN_INTERVAL trap. It also asked before downloading the jailbreak files from MobileRead, and it set up key login so no password ever went into the conversation.

Swapping the cable, pressing through the diagnostics menu, and reading what the Kindle's screen said were still my job. So was knowing that the agent's first README describes how a project like this usually goes, not how this Kindle actually went.

If you have one in a drawer

Check the model and firmware first, under Menu โ†’ Settings at the bottom of the page. For a Kindle 4 non-touch up to firmware 4.1.4, the Doorstep README has the tested steps. Expect to spend more time on the cable and the diagnostics menu than on the code.

Start with the image, not the device. Get a 600ร—800 grayscale PNG you would actually read at your door, verify its head

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.