Kindle Display

This article shows how to configure an Amazon Kindle eBook-Reader as a information display for Fhem. Since such eBook-Readers use eInk displays which keep their display even when the device is completely switched off, this offers a nice method to visualize Fhem devices and readings on a battery powered device which is mainly in deep sleep mode and only powers up to fetch new data from Fhem and update the display e.g. every 10 minutes.

Use this manual at your own risk. Jailbreaking a Kindle is quite easy but there is no guarantee for breaking the system.
I will show how to configure it with the FileReplacer.pm from Stefan. The "old" method with the special function in MyUtils is not part of this article.

All of the information shown below is collected from the Fhem-forum fhem-Forum. Many thanks to everybody who participated on the development of this information to get it done. Special thanks to "alex" and "Stefan" from the board. Further information is from the mobileread board.

Hardware requirements

Kindle Touch / Paperwhite / Paperwhite 2

You can use Kindle Touch / Paperwhite / Paperwhite 2 without any limitations.

Kindle 4 or Kindle 5

For setting this up on the Kindle 4 (graphite color and with the 5-way button) or Kindle 5 (black and with the 5-way button) you need some more configuration but it's also working. Addidional tasks for this version are shown down below.

Prerequisites

fhem and server configuration

Server configuration

The Fhem side that provides the image to display an a Kindle device typically creates this image by replacing placeholders in an SVG-file and the converting the result into a suitable PNG-file. For this conversion you need imagemagick or some other command line utility to convert SVG into PNG in the right format.

apt-get install imagemagick

fhem configuration

First you need an SVG-template. You can draw one e.g. with inkscape or you can find one in the first posting on the fhem-Forum thread. In the template just replace the data with some placeholder you like. Later this placeholder is found via a regular expression and replaced with your data. For example, you can set XYZ at the place where the first temperature should be shown and ABC for the first humidity value. If you want to edit the template you can use the free software [www.inkscape.org/de/ Inkscape] for example. For more information about generating SVGs for Fhem please refer to this article Icons. The most important information is to save the SVG as a "normal SVG" and not as an inkscape SVG. For the Kindle Paperwhite the resolution of the SVG must be 758 x 1024 for the Kindle 4 and 5 version use 600x800. This is mandatory. Wrong scaled images won't be displayed on the Kindle.
Copy the Kindle_Template.svg to /opt/fhem/www/images/.

All we're doing now is using the FReplacer module which is part of Fhem to read the SVG template, replace a search pattern with our data and save it.

define kindledisplay FReplacer /opt/fhem/www/images/template1.svg /opt/fhem/www/images/status1.svg 60

attr kindledisplay PostCommand convert /opt/fhem/www/images/status.svg -type GrayScale -depth 8 /opt/fhem/www/images/status.png 2>/dev/null &

attr kindledisplay ReplacementEncode UTF-8

attr kindledisplay room Display

PostCommand defines that the external command will be issued after the replacement to convert the resulting SVG to a PNG in 8 bit GreyScale mode. UTF8-Encode might be needed to support special characters.

Now just create your mappings:

attr kindledisplay Rep01Regex XYZ

attr kindledisplay Rep01Reading Sensor1:Temp1

attr kindledisplay Rep01Format %.1f

attr kindledisplay Rep02Regex ABC

attr kindledisplay Rep02Reading Sensor1:Hum1

attr kindledisplay Rep01Format %.1f

And so on... :) The FReplacer module will replace the pattern XYZ with the ReadingsVal from Sensor1.

More and up to date details about the configuration of the FReplacer module can be found in the Fhem command reference [1]

Now check if the PNG is created http://your-fhem-ip:8083/fhem/www/images/KindleDisplay.png. If so, be happy, the first part is done!

If you want to use more complex Perl expressions to compute the replacement string, you can use the RepExpr attribute instead of RepReading and do someting like this:

attr kindledisplay Rep11Expr (ReadingsVal("XY", "Reading", "off") eq "on" ? "An" : "Aus")

If you want to add a "last modified" timestamp to the dispaly, create a placeholder for it in your SVG template (like "last modified lmtime123") and then define a Regex / Reading attribute pair to replace it with the Reading "LastUpdate" from your FReplacer device:

attr kindledisplay Rep14Regex lmtime123

attr kindledisplay Rep14Reading kindledisplay:LastUpdate:never

Templates

You can find my templates here: fhem Forum. Feel free to use and modify.

Modifying the Kindle

To prevent from error messages like "your Kindle is no longer registered as a test Kindle..." please make sure your Kindle is connected to a valid Amazon Account.
We need to download some software to install it on the Kindle.
Please download it from Mobileread Forums

• Kindle Jailbreak Mobileread Forums
• MKK Mobileread Kindlet Kit Mobileread Forums
• KUAL Mobileread Forums
• Screensavers Hack Mobileread Forums
• OnlineScreenSaver Mobileread Forums

• for Kindle 4 or 5 only: USBNETWORK also Mobileread Forums

Always use the newest version and look for one who fits to your Kindle (e.G. K4 or K5).

Jailbreaking the Kindle

Don't worry. This sounds more hard and dangerous than it is in fact. It's just a few steps to have full access to your Kindle.

Kindle Touch/Paperwhite

• Download the kindle-jailbreak-0.12.N.zip file, and unpack it. In there, you'll find some .bin files, and a src directory.Leave the directory alone, and upload the correct Update_*_install.bin file for your kindle & FW version to the root directory of your Kindle.

• Now, eject & unplug your Kindle, and go to [HOME] -> [MENU] > Settings -> [MENU] > Update Your Kindle. It should be quick.
  (And, on FW 2.x only, it should FAIL (With a U006 error, in the bottom left corner of the screen). It's completely normal, intended, and harmless).

And that's it, your Kindle is now ready to install custom hacks!
(Quoted from http://www.mobileread.com/forums/showthread.php?t=88004)

Kindle 4 or 5 / Universal method

• Download and unzip the jailbreak.
• Plug in the Kindle and copy the data.tar.gz & ENABLE_DIAGS files plus the diagnostic_logs folder to the Kindle's USB drive's root
• Safely remove the USB cable and restart the Kindle (Menu -> Settings -> Menu -> Restart)
• Once the device restarts into diagnostics mode, select "D) Exit, Reboot or Disable Diags" (using the 5-way keypad)
• Select "R) Reboot System" and "Q) To continue" (following on-screen instructions, when it tells you to use 'FW Left' to select an option, it means left on the 5-way keypad)
• Wait about 20 seconds: you should see the Jailbreak screen for a while, and the device should then restart normally
• After the Kindle restarts, you should see a new book titled "You are Jailbroken", if you see this, the jailbreak has been successful.

Installing additional software

MKK

The Mobileread Kindlet Kit (MKK) is used to execute custom Kindlets (programs) on the Kindle.
Download the software from here: MKK
Unzip the folder and copy the .bin file to the root directory of your kindle. Please note that you need to install the Kindle matching version (e.g. K4 = Kindle 4 with 5-way-button).
On the Kindle goto Menu -> Settings -> Menu -> Update your Kindle.
After the update it is installed.

KUAL

The Kindle Unified Application Launcher (KUAL) running applications on the Kindle.
Download it from here: KUAL
Unzip the folder and copy the matching .azw2 file to the documents directory of your kindle.

(K2, DX, K3, K4, K5)
Put KUAL-KDK-1.0.azw2 in documents folder.
Run it by clicking new kindlet (book) document in your list.

(Touch, PaperWhite)
Put KUAL-KDK-2.0.azw2 in documents folder.
Run it by clicking icon.

Backdoorlock

This is used to prevent from getting automated updates which could remove the JailBreak.
Download from here: Backdoorlock
Unzip the folder and copy the .bin file to the root directory of your kindle. Please note that you need to install the Kindle matching version (e.g. K4 = Kindle 4 with 5-way-button). On the Kindle goto Menu -> Settings -> Menu -> Update your Kindle. After the update it is installed.

ScreenSavers Hack

The ScreenSavers Hack let you show custom screen savers on the kindle.
Download the file: ScreenSaver Hack
Install the corresponding .bin file as the others before and use the "update your kindle" function to install it.
After the installation you will find a directory called "linkss" in the Kindle root. Here open the screensavers dir and delete all images.

Online ScreenSaver

This application copies the PNG image file created on the Fhem side to the ScreenSavers hack so it is displayed when the Kindle start sleeping. Just take the modified version for Kindle 4 and 5 from [2] or download the original application for later Kindles from here, extract the file and copy the folder into the extensions directory. Now you have to edit the config.sh file up to your need.
NOTE Use a linux/unix compatible editor (like notepad++) only!
You need to enter the image URL, the update interval and the schedule for the updates.

The onlinescreensaver contains a script called enable.sh in its bin subdirectory. This should be invoked manually if you are logged into the kindle via ssh or via KUAL from the Kindles menue. enable.sh takes care that the scheduler of onlinescreensaver is started (also after reboot).

Kindle 4 and 5 differences compared to later models

A Kindle 4 and 5 differs in a few ways from the later models. It doesn't use upstart but old start up scripts. The enable.sh script takes care that the appropriate startup skript is copied in the right place.

Another difference is the power management. The original online screensave was created for a kindle paperwhite which has a real time clock with alarm functions that can be controlled through the sysfs. Utils.sh in the online screensavers bin directory puts the next wake up time in /sys/class/rtc/rtc$RTC/wakealarm to achieve this. So the Paperwhite can sleep most of the time and only wake up to retrieve the latest PNG, display it and go back to sleep.

The modified version of onlinescreensaver for Kindle 4 and 5 that can be downloaded from the Fhem forum [3] therefore contains an rtcwake binary that puts the Kindle into deep sleep and wakes it up again with the built in real time clock after a defined time.

As your Kindle 4 or 5 needs some more attention to get it done, please find the steps here:

USB Network Hack

This hack is used to get SSH/Telnet Access to your Kindle. We need this on Kindle 4 to change some settings on the system.
Download and install the kindle-usbnetwork file from here: USBNETWORK
I'm sure you know what to do in the meantime ;-)
After that, activate the USBNetwork via KUAL and connect the Kindle via USB.

Connecting to the Kindle

Before you can connect you need to install the RNDIS driver. Here you can find a very good "HowTo" to do this. Note that the IP-Addresses you need to configure are different then addresses used in the example. Your RNDIS Interface needs to have 192.168.15.201 configured, the Kindle uses 192.168.15.244 on this interface.
Don't wonder you cannot ping the Kindle!
Now you can use a ssh-client like putty to connect to the Kindle. Telnet is also an option but only when WiFI mode is disabled. So better forget about it. Success? Great job!

Changing the "sleep settings" to keep the Kindle awake

The modified version of onlinescreensaver for K4 and K5 does this automatically when the above mentioned enable-sh script is run. For the original onlinescreensaver however this is a manual task:

After you connected to the Kindle you will be asked for a password. Login with root and blank password. Should work.
Now we need to make the filesystem writeable:

mntroot rw

Changing the root password:

passwd

Changing the timeouts:

cd /etc/kdb.src/yoshi/system/daemon/powerd/

Edit the t1_timeout (time before the secreensaver gets displayed) with the editor "vi" and change the last line to 200.
Same for the t2_timeout but here we enter 200000 in the last line to keep the Kindle awake for at least 2 days.
These values are setting the "sleep" counters on the Kindle. Unfortunately this will lower the battery faster then normal so I recommend to have the display in a docking station.

Cron setting (optional)

In some cases that all didn't really work. In such cases the onlinescreensaver update script can also be called via cron:

vi /etc/crontab/root

Add the following line at the bottom. */5 means every 5 minutes.

*/5 * * * * /mnt/us/extensions/onlinescreensaver/bin/update.sh

/etc/init.d/cron restart

Setting back filesystem in read-only mode

mntroot ro

That's it for me. Not working? Ask and look here for help: FHEM Forum

Examples and Pictures

Kindle Display Example on Kindle 4

---