Tools kindle-reading-dashboard — view your on-device reading stats, pace & metadata

[zevi svei]

I put together a small offline toolkit that reads and visualizes the reading metadata a Kindle already stores on-device — reading time, pace (WPM), per-book progress, highlights, printed-page mapping, and read/unread status — in a local web dashboard. No cloud account, no Amazon API, no KOReader.

GitHub: https://github.com/zevisvei/kindle-reading-dashboard
License: GPL v3

What it shows

• Library list: title, author, series, % complete, reading time, pace, current page, read/reading/unread — sortable & searchable.
• Per-book detail: timer.model reading-time data, reading-speed distribution, reading timeline, device sessions, highlights/notes, font prefs, all cc.db fields, plus the raw decoded JSON of every source.
• Position → printed page translation via the apnx page map.

Where the data comes from

• cc.db (/var/local) — library: title/author/series/%/legacy read-state.
• *.azw3f / *.azw3r KRDS sidecars — reading time/pace (timer.model), word counts, page history, last/first position, annotations, font prefs.
• fmcache.db (/mnt/us/system/fmcache) — this was the interesting find: the modern "Mark as Read" status is NOT in cc.db.p_readState. The new app keeps read-state in fmcache (schema mar_content_readstate_update_success) and in the cloud (whispersync BookReadStates), so a manual mark can sit there without ever touching p_readState. The dashboard reads fmcache and uses it as an override, and also surfaces the per-book reading_sessions there.

Requirements

• Python 3 + paramiko.
• Full dashboard needs a jailbroken device with USB networking (SSH). Basic sidecar decoding (time/pace/highlights/page map) works on a stock device mounted as a USB drive, via the CLI scripts or --local.

Tested on a Kindle Basic 10th gen (J9G29R), FW 5.18.1.

Credits
The KRDS parser (krds.py) is John Howell's work (GPL v3) from the KRDS thread ( https://www.mobileread.com/forums/sh...d.php?t=322172 ); I patched it for FW 5.18.x (a raw fallback so unknown/new structures don't break decoding). Windows RNDIS usbnet driver by Marco77.

Not affiliated with Amazon. Reads metadata only — no DRM circumvention, read-only against the device. Feedback welcome.

[j.p.s]

Looks very interesting!

Have you considered making a pull request to the KRDS github repository with your changes to krds.py?

[j.p.s]

My kindles are set up to only allow login from private keys whose public keys are listed in authorized_keys for passwordless connection.

reader-dashboard/dashboard.py
doesn't seem to be able to handle that.

[zevi svei]

Originally Posted by j.p.s

Looks very interesting!

Have you considered making a pull request to the KRDS github repository with your changes to krds.py?

done
https://github.com/K-R-D-S/KRDS/pull/3

[zevi svei]

Originally Posted by j.p.s

My kindles are set up to only allow login from private keys whose public keys are listed in authorized_keys for passwordless connection.

reader-dashboard/dashboard.py
doesn't seem to be able to handle that.

Fixed

[j.p.s]

Originally Posted by zevi svei

Fixed

Thanks! Worked great for me. It found my ssh_agent and everything seems to work fine. I didn't have to set any environment variables.

I have more than one kindle, so I changed my clone to allow optional setting of a nickname for the kindle. If the environment variable KINDLE_NAME is set, a subdirectory in cache whose name is the value of KINDLE_NAME will be used to store cc.db and the documents directory, I tried it with three different kindles and it kept them all straight. I only had to add two lines and modify one line.

I've submitted a pull request to your repository.

[j.p.s]

Originally Posted by zevi svei

I put together a small offline toolkit that reads and visualizes the reading metadata a Kindle already stores on-device — reading time, pace (WPM), per-book progress, highlights, printed-page mapping, and read/unread status — in a local web dashboard. No cloud account, no Amazon API, no KOReader.

GitHub: https://github.com/zevisvei/kindle-reading-dashboard
License: GPL v3
...
Feedback welcome.

Do you prefer feedback, bug reports, and discussion here over github?

I think it would be easier to keep things organized at github with significant changes announced here.

Please consider enabling discussions and maybe a wiki in your github repository for kindle-reading-dashboard

[zevi svei]

Originally Posted by j.p.s

Do you prefer feedback, bug reports, and discussion here over github?

I think it would be easier to keep things organized at github with significant changes announced here.

Please consider enabling discussions and maybe a wiki in your github repository for kindle-reading-dashboard

Excellent idea, I enabled discussions.

[j.p.s]

I've filed a new issue on github:
https://github.com/zevisvei/kindle-r...board/issues/3

In the "Reading timeline" section for a book, fpr should be furthest position.

This can be confirmed by syncing, then checking the values for fpr and lpr. Might not be necessary, but I next close reader-dashboard and the browser and disconnect the kindle. Then I open the book on the kindle and page forward around 10 screens, page back around 5 screens, and exit the book.

Re-connect the kindle to the computer and sync again. fpr should have advances by about 10 screens and lpr by about 5 screens.

[zevi svei]

Update — Calibre plugin (v1.0.0)

Following up on the dashboard: there's now a Calibre plugin that pulls the same on-device reading metadata straight into Calibre custom columns — so your reading time, pace, progress and read-status live next to each book in your library.

Download: https://github.com/zevisvei/kindle-r.../plugin-v1.0.0
Install: Calibre → Preferences → Plugins → Load plugin from file → pick kindle_reading_dashboard.zip, then restart.

What it does

• 11 selectable fields, each mapped to a custom column you name: reading hours/minutes, pace (WPM net + incl. breaks), progress %, furthest page, words read, words in book, highlights/notes, read status, last-read date. A "Create missing columns" button sets them up for you.
• Import the whole library, or refresh only the selected book(s).
• Optional auto-import when the Kindle connects.
• Reading stats also show in the Book Details panel (incl. on the device page for matched books).

Source — USB or SSH, auto-detected

• USB mass-storage: reads the .azw3f/.azw3r sidecars (time/pace/progress/furthest page/words/annotations). If the device also exposes cc.db + fmcache.db on the partition, you additionally get reliable title/ASIN matching and read/reading/unread status — no jailbreak needed.
• SSH/usbnet: always provides cc.db + fmcache for the full set.

Auto mode never silently falls back to SSH, so a disconnected device just says so instead of hanging.

Furthest page uses fpr + the apnx page map; decoding reuses the same krds parser as the dashboard. Tested on Calibre 9.9 (Windows). Still read-only, no Amazon account, no DRM circumvention. Feedback welcome.

[j.p.s]

I've opened a Pull Request on your dashboard repository that sets the git filemode for the three CLI scripts to executable so that those files will be executable on operating systems where that matters. There are no changes to any file contents, just the mode, and will have no effect on Windows, etc.