Watching this YouTube video, I remembered I had an old Kindle that I barely used. I had soft modded it the past but the hack was overwritten by an automatic update so I had given up… I still had time to experiment with KOReader and I thought it was a really cool project. Watching the video and since my old desk clock died, it gave me the idea to repurpose my old Kindle into a nice looking clock. With the e-ink screen I was confident I could get it to look cool but also last a long time without being plugged to the wall. Given all of that, the project was started.

Running homebrew on the Kindle

The first step was being able to run my own code on the Kindle. Back when I first jailbreak my Kindle, finding how to do it was an absolute mess. You had to look through several outdated forum posts on https://www.mobileread.com/ to find the right one and the instructions were partial and unclear. However this is now history since https://kindlemodding.org/ exist. It’s a comprehensive step by step guide to mod your Kindle and have the jailbreak be persistent. The 2025 exploit helps a lot.

Following the guide I was able to run KOReader once again and run any homebrew I wanted.

Finding the right way to display the clock

We could now run code, but there was absolutely no way I create the clock using only native code. I had to use some kind of “framework” to be able to display what I wanted on the ebook.

Mesquito

My first approach was using “Mesquito” apps. If you follow the guide you’ll see that the exploit is ran through something called “Mesquito”. It’s a software that replaces the Kindle store and allows you to run homebrew. Mesquito homebrew are called “WAF”, they are webapps that run directly onto the Kindle. They are composed mainly from a html, js and css. Contrary to a webpage that you’ll open into the Kindle web browser, you have access to device specific functions from the JavaScript code.

Considering I had a lot of experience in web development from my jobs, I thought this was the faster approach. The first big disappointment was this:

it has the same featureset as Safari 5

I promise you, creating a website without using “flexbox” is a pain! Anyway, I did it. However it didn’t exactly worked as expected. Apart from being a pain to test, the main issue was that I couldn’t get 2 things working:

• Getting the app to display in fullscreen with zero status bar or toolbar
• Getting rid of the screensaver / screen lock

This didn’t seem to be possible using the Mesquito SDK or at least I didn’t find how.

I tried several different approach but they all had those issues. Things I tried:

• Mesquito homebrew
• Native web browser
• WebLaunch (even the forked version)
• SkipStone web browser patched to run in portrait and fullscreen: this is the closest I got but it was a pain to run and I couldn’t quit without rebooting

All of those approaches were inoptimal and had another major flaw: battery usage. Ebooks aren’t meant to run a web browser with a fixed refresh rate like a computer screen. They only refresh when needed and that what makes them efficient.

Considering all that I understood that web development wasn’t the right solution. I had to do it the proper way and write “ebook specific code”.

Creating a KOReader plugin

Since there was still no way I do it in native code, I had to think: who did that before me? The answer was pretty obvious in the end. The biggest homebrew ever made for ebooks is of course KOReader. And luckily it’s open source as well.

KOReader for those who don’t know is basically an open source reader for ebooks. It aims to completely replace the software that runs on your ebook with something completely open source and even offers more features than the OEM software in most cases. It’s a really cool project 👍. The project is written in Lua, runs on Linux and made in a way that it’s easy to port to any ebook reader. For me, it meant that if my clock ran on KOReader, it would also run on many devices and not just the Kindle.

I could edit the code of KOReader to add my own inside of it but luckily, KOReader also supports creating “plugins”. From a plugin, you have access to the whole KOReader dev framework and boy there is a lot to learn here! It’s been years since KOReader exists and they had time to implement pretty much anything you would want to do on an ebook. This also makes a lot of code samples you can take inspiration from.

I knew I could do it but I had barely touch any lua (since my AwesomeWM config) and the framework was huge! Thankfully, looking through the existing plugins I found out someone had a similar idea as mine. He created an analog clock as a plugin. However, I didn’t like the design and it seemed buggy/unfinished. But it was a really good starting point to understand how to code a KOReader plugin.

The learning curve was steep but step by step I understood how the ebook worked and how to use the KOReader framework. With patience and dedication, I was able to complete my project. A thing that helped a lot is that you are able to run KOReader emulator directly on your computer (eg. using Docker) so it’s much faster to test your code.

One of the cool thing I learn during the developing process is how the ebook display things on a screen. On a traditional display you have a set refresh rate so you just create a rendering loop and throw everything you need to render inside of it. On a e-ink screen, if you don’t repaint, what you left on the screen stays forever. You always draw on top of what was previously there; if you want something to refresh you have use “setDirty” and choose a refresh type. Considering this, you can very precisely repaint only what you want on the screen and only when needed. In my case, I repaint the time only once every 60 seconds and the date only once every 24 hours. This saves a lot of battery! The Kindle stays on displaying the clock for about a week without charging.

The problems I had using the web browser approach were gone. Disabling the screensaver can be done with a single line of code and since I control the rendering process, it’s pretty straightforward to display something in fullscreen.

Conclusion

I’m really happy of how this project turned out. It was a long process of trials and errors but I’ve definitely learned a lot to the inner working of an ebook and the result is also pretty cool to look at!

If you’re interested you can find the source code on my GitHub but it’s also “upstream” on the KOReader contrib repo