ScreenLockPin: A fast, sophisticated PIN Lock Screen that protects your KOReader content from unauthorized access.

Just what you'd expect from a PIN lock screen…

• 🔒 Lock on wakeup — secures your device after sleep
• 🪝 Lock on boot — secures your device on KOReader boot
• 🛡️ Privacy first — hides everything but your wallpaper from public eyes
• 🔋 Device Info — glimpse the time & battery on the lock screen
• 🚷 Rate Limit — forced delays after repeatedly failed attempts

and more…

• 🪄 Instant unlock — immediate response, no extra confirmation button
• 🪧 Contact notes — people should know how to return a lost device
• 🎯 Customizable layout — can be configured for single-handed use
• 🔆 Frontlight control — easily turn on the screen light in a dark environment
• 🪃 Lightweight design — optimized for performance
• 🗽 PIN length — 3 to 12 digits

This plugin is designed for privacy and casual protection, not cryptographic security.

Please leave a ⭐ if you like the plugin.

1. Download the latest release; either archive is fine — whatever you're familiar with.
2. Extract the archive and copy the extracted folder screenlockpin.koplugin into KOReader’s plugins directory.
3. Restart KOReader. The plugin will appear in the Screen submenu.

1. On your KOReader, open the new Screen › Lock screen submenu.
2. Set your PIN and configure the options to your liking.

Depending on your settings, the Lock Screen will now appear during boot and / or during wakeup from sleep mode.

If you enable lock on boot, make sure to have some way of file access without unlocking the KOReader, in case you forget the PIN (see FAQ below).

Actions for the dispatcher (e.g., Gesture manager) can be found in the Device group.

We do expose an interface to use in foreign plugins. For example, a plugin could use this API to disable the lock screen based on external factors like date or time.

The interface can be accessed like this:

local PluginShare = require("pluginshare")

function yourFunction()
   local lockScreen = PluginShare.screen_lock_pin
   if not lockScreen then return end
   -- safely use lockScreen here
   -- e.g., lockScreen:lock()
end

See publicapi.lua for available methods. Please create an issue or PR if we're missing something that would be of use to you.

If you've built a plugin that integrates with the lock screen, kindly open a PR to list it here for others to find.

Designed for KOReader v2025.08 and newer. Please report any compatibility issues you encounter.

Tested devices:

• ✅ Kindle (10th, 12th gen)
• ✅ Kindle Oasis (10th gen)
• ✅ Kobo Aura (N514)
• ✅ Kobo Clara BW (N365)
• ✅ Kobo Clara Colour (N367)
• ✅ KOReader Desktop

If you tested this plugin on another device type, please add it to the list above.

If you don't have lock on boot enabled, a hard reboot should suffice to get you into the KOReader. Change your PIN from there.

If you do have lock on boot enabled, you'll need access to the devices file system (e.g., USB or SSH). Inside the koreader directory, edit the settings.reader.lua file. Find the screenlockpin_pin option and change, if necessary. Make sure the value adheres the 3–12 digits constraint. Save, and reboot into KOReader.

The lock screen is based on your configured wallpaper: Screen › Sleep screen › Wallpaper.

On disable, we restore the Screen › Sleep screen › Wallpaper › Postpone screen update after wake-up setting that was set before the feature was enabled. You might need to tap the screen, or use your old 'exit sleep screen' gesture to unlock.

Contributions and suggestions are welcome!
Feel free to open an issue or pull request to improve functionality, style, or compatibility.

MIT License — see LICENSE for details.