Turn your PocketBook's sleep/lock screen into a reading-stats dashboard. Built and tested on the PocketBook Era, it renders — entirely on-device — a crisp grayscale image in a terminal/dotfiles aesthetic:
- your ASCII signature up top (fully customizable — see the tutorial),
- the book you're now reading with its cover, a progress bar and a time-to-finish estimate,
- your recent books with cover thumbnails, author, read time and whether they're finished,
- a stats tile row: day streak, this month, this year, average session.
┌──────────────────────────────────────┐
│ (ascii signature) │
│ │
│ ── NOW READING ───────────────────── │
│ ┌─────┐ Current Book Title │
│ │cover│ Author Name │
│ │ │ 42% · 137/321 │
│ │ │ [█████████░░░░░░░░░░] │
│ └─────┘ 3h 12m read · ~4h 50m left │
│ │
│ ── RECENT BOOKS ──────────────────── │
│ ┌───┐ ■ Some Finished Book │
│ │cvr│ Ursula K. Le Guin │
│ │cvr│ 6.2h · 9 days · finished │
│ ├───┤ □ Another Book │
│ │cvr│ Neal Stephenson │
│ │cvr│ 2.1h · 4 days · in progress │
│ └───┘ │
│ │
│ ── STATS ─────────────────────────── │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ 12 │ │ 8.4h│ │ 96h │ │ 24m │ │
│ │strk │ │month│ │year │ │sess │ │
│ └─────┘ └─────┘ └─────┘ └─────┘ │
│ generated 2026-07-08 21:30 │
└──────────────────────────────────────┘
Screenshots wanted. Drop real device photos into
docs/screenshots/and link them here — see that folder's README for the how-to.
- Requirements
- Install
- Where to find it in the menu
- Quick start
- How it works (the one thing you must know)
- Output slots
- Menu reference
- Customizing the ASCII signature
- Book covers
- Data notes
- Troubleshooting
- Module layout
- Contributing
- Credits & sources
- License
- A PocketBook e-reader running KOReader (developed on the Era, FW 6.8+). Other PocketBook models with the same lock-screen mechanism should work; other vendors won't (the sleep screen is drawn by PocketBook firmware — see How it works). On non-PocketBook devices the plugin still runs and Preview works, but nothing is written.
- KOReader's built-in Statistics plugin enabled and collecting — this plugin
reads (never writes) its
statistics.sqlite3.
- Grab
chartingsleepscreen.koplugin.zipfrom the latest release. - Unzip it and copy the
chartingsleepscreen.koplugin/folder to your device at/mnt/ext1/applications/koreader/plugins/. - Restart KOReader.
- Connect the PocketBook over USB.
- Copy the
chartingsleepscreen.koplugin/folder from this repo into/mnt/ext1/applications/koreader/plugins/. - Restart KOReader.
Verify it loaded: it appears in Plugin management and in the menu (below).
Open KOReader's top menu (tap the top of the screen), then:
🔧 Tools tab (the wrench) → More tools → Charting sleep screen
That's it — Tools → More tools → Charting sleep screen. The plugin registers
itself with sorting_hint = "more_tools", which is the conventional home for
third-party plugins, so it always lands under More tools regardless of theme.
A gesture action, Write charting sleep screen, is also registered in the Dispatcher — assign it under Taps and gestures → Gesture manager if you want a one-tap refresh.
Using the ZenUI plugin? ZenUI's Zen Mode intentionally hides KOReader's default menu tabs, so Charting sleep screen won't show in the wrench menu while Zen Mode is on. Three ways to reach it: (1) add it via ZenUI's Launcher → Add buttons picker, (2) add it as a Quick settings → Custom button, or (3) toggle Zen Mode off to restore the standard menus. The plugin is fully discoverable by ZenUI's plugin scan either way.
- Make sure the Statistics plugin is enabled and you've read a little (so there's data).
- Tools → More tools → Charting sleep screen → Preview sleep screen now — this renders the image and shows it full-screen (tap to dismiss). Iterate on the look here; no reboot needed.
- Happy with it? Write sleep screen now writes it to the firmware slot(s).
- Leave Write on suspend and Write when a book is opened on (the defaults) so the file stays fresh automatically.
- Reboot once to see it on the actual lock screen (see below for why).
On PocketBook, KOReader never draws its own sleep screen — the firmware does. This plugin therefore renders the stats image and writes it to the file(s) the firmware displays.
The catch: the firmware reads the lock-screen background once, at the first lock after boot, then caches it in RAM. So the lock screen shows "stats as of the last write before this boot's first lock"; a reboot picks up the latest image. The plugin writes eagerly — when a book is opened and on every suspend (debounced, 30 s) — so the file on disk is always as fresh as possible when the firmware next reads it.
Images are 8-bit grayscale uncompressed BMP at the panel's native resolution — the format the firmware accepts. (24-bit BMPs are known not to work.)
Recommended PocketBook power settings for the lock-screen slot: Settings → Saving Power → auto screen lock: on, power off after: off.
Pick which firmware files to write under Output slots in the menu:
| Slot | Path | Behavior |
|---|---|---|
| Lock screen (default) | system/resources/Line/taskmgr_lock_background.bmp |
Read once at the first lock after boot, then cached in RAM. Reboot to refresh. |
| Lock screen (landscape) | system/resources/Line/taskmgr_lock_background_landscape.bmp |
Same caching; under KOReader the firmware usually uses the portrait file anyway. |
| Book-cover logo (experimental) | system/logo/bookcover |
FW 6.9+ with Settings → Personalization → Logos set to "book cover". May refresh without a reboot — worth testing; if it does on your firmware, prefer this slot. |
| Power-off logo | system/logo/offlogo/cover.bmp |
Shown when the device is fully switched off. Same file the built-in Cover image plugin writes — don't enable both. |
| Item | What it does |
|---|---|
| Enable | Master on/off for automatic writes. |
| Preview sleep screen now | Renders and shows the image full-screen (tap to dismiss). No reboot needed — use this to iterate. |
| Write sleep screen now | Renders and writes all enabled slots, then reports the paths. |
| Write on suspend | Auto-write on every suspend (debounced 30 s). |
| Write when a book is opened | Auto-write ~5 s after a book opens. |
| Layout | Signature + books (default) or More books (no signature) — the latter drops the ASCII art and fits two extra recent books in its place. |
| Output slots | Which firmware files to write (see table above). |
| Recent books: N | How many recent books to list (0–6). |
| Show book covers | Toggle cover thumbnails (see Book covers). |
| Dark theme | Invert to light-on-dark. |
| Edit signature | Edit the ASCII art up top (tutorial). |
| Export PNG for inspection | Writes a PNG to your device's home dir so you can eyeball it on a PC. |
The banner at the top is plain text you can change to anything — your name, initials, a glyph, a tiny logo. Edit it on-device via Tools → More tools → Charting sleep screen → Edit signature, or read the full walkthrough (generating ASCII art, sizing, e-ink tips, editing the default in code):
Covers are matched exactly, not fuzzily: the Statistics plugin stores the
same partial_md5_checksum in each book's sidecar (.sdr) and in the stats DB,
so the plugin walks your reading history, reads sidecar checksums, and joins them
to the stats books. Extracted covers are cached as PNGs under
koreader/cache/chartingsleepscreen/ — the first render after enabling covers
opens each matched document once (a few seconds); after that it's instant. Books
whose files were deleted or never opened on this device simply render without a
cover. Toggle with Show book covers.
- Stats come read-only from
koreader/settings/statistics.sqlite3(the built-in Statistics plugin must be enabled and collecting). - "Finished" = ≥ 95 % of pages have been visited. Books with less than 5 minutes of total reading are hidden from the recent list.
- Streak counts consecutive local-time days with any reading; it stays alive if you read today or yesterday. Sessions split on gaps > 5 minutes (30-day window).
- The Statistics plugin flushes its page buffer on the same suspend event this plugin listens to, so a suspend-time write can lag by a few page turns; the next book-open write catches up.
The menu item isn't there. Confirm the folder is at
/mnt/ext1/applications/koreader/plugins/chartingsleepscreen.koplugin/ and
restart KOReader; check Plugin management. If you use ZenUI, see the
Zen Mode note under Where to find it in the menu.
Preview looks right but the lock screen is stale. That's the RAM caching — reboot the device to force the firmware to re-read the background. See How it works.
"Not a PocketBook device — nothing written." Expected on non-PocketBook hardware; Preview and Export PNG still work for development.
Empty / sparse stats. Enable the built-in Statistics plugin and read for a bit; books with < 5 min of reading are intentionally hidden.
No covers. Turn on Show book covers; give the first render a few seconds per book. Books whose files aren't present on the device can't show a cover.
chartingsleepscreen.koplugin/
_meta.lua plugin metadata
main.lua lifecycle, events (onReaderReady/onSuspend), menu, dispatcher
chartstats.lua SQL data layer (read-only, pcall-guarded, never throws)
chartrender.lua pure Blitbuffer renderer (no I/O; returns a BB8 buffer)
chartcovers.lua book-cover lookup + caching, aspect-fitted to a box
charttargets.lua firmware slot paths, dir creation, BMP writes, sync
Issues and PRs welcome — see CONTRIBUTING.md for the dev loop, how to test without a device, and the code conventions.
- Lock-background trick + format: mobileread thread
t=355272, cyfranek's guide (Polish), myvogonpoetry's Touch HD 2 write-up (confirms a KOReader-written grayscale BMP works, and the RAM-caching behavior). - Display model + APIs: KOReader master —
frontend/device/pocketbook/device.lua,plugins/coverimage.koplugin,plugins/statistics.koplugin,ffi/blitbuffer.lua(koreader-base).
Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), matching KOReader's own license. See LICENSE.