Bluetooth Page Turner plugin for Kobo KOReader

[lumping-sugar66]

Bluetooth Page Turner for Kobo - v1.0.0

Use a Bluetooth controller (like 8BitDo Micro) to turn pages and control KOReader on your Kobo.

What's New in v1.0.0

Complete overhaul focused on eliminating manual configuration:

• No more editing device.lua
• No more editing shell scripts
• No more hardcoded MAC addresses
• No more figuring out event3 vs event4
• Everything is auto-detected or configurable via UI

Supported Devices

Fully Tested:

• Kobo Clara 2E
• Kobo Libra 2

May Work (auto-detection):

• Other Kobo devices with similar hardware

Not Yet Supported:

• Clara BW, Clara Colour, Libra Colour (MediaTek Bluetooth hardware - different drivers needed)

Installation

Step 1: Copy the Plugin

1. Download from GitHub
2. Rename folder to

   bluetooth.koplugin

3. Copy to

   koreader/plugins/

   on your Kobo
4. Restart KOReader

Step 2: Run Diagnostics & Auto-Fix

Go to Menu > Network > Bluetooth > Diagnostics

Click any item marked with X and choose "Correct Automatically":

• hasKeys flag - Required for button input
• Event map - Default button mappings for 8BitDo

Step 3: Turn On Bluetooth & Pair Your Controller

1. Go to Bluetooth > Bluetooth On
2. Put your controller in pairing mode
3. Go to Bluetooth > Device Management
4. Click "Start scanning (30s)"
5. Click "Select from scanned devices" and choose your controller
6. Done - your controller is saved

Step 4: Connect

Whenever you want to use your controller:

1. Bluetooth > Bluetooth On
2. Device Management > Connect to saved device

That's it.

Features

Auto-Configuration
Everything is automatic:

• Installation path detection
• Device-specific Bluetooth commands (Clara 2E vs Libra 2)
• Input device path (event3/event4)
• Button mappings
• hasKeys override

Device Management
Scan, select, and save Bluetooth devices directly from the UI. No more editing scripts.

Event Map Editor
Bluetooth > Event Map Editor

• View all current mappings (key code to event)
• Add new button mappings
• Change or delete existing mappings
• Changes take effect immediately

Diagnostics
Bluetooth > Diagnostics

• Live Bluetooth status (ON/OFF)
• Pass/fail indicators for each configuration item
• Click for details and auto-fix options
• Debug tools: button press history, raw input monitor

Bank System
Map the same physical buttons to different actions by switching banks. Perfect for controllers with limited buttons.

Edit

bank_config.txt

to customize:

Bank1
BTAction1:BTLeft, A button
BTAction2:BTRight, B button
BTAction3:BTToggleBookmark, Y button

Bank2
BTAction1:BTIncreaseBrightness, A button
BTAction2:BTDecreaseBrightness, B button
BTAction3:BTToggleNightMode, Y button

Switch banks using BTRemoteNextBank / BTRemotePrevBank.

Customizing Button Mappings

The plugin comes pre-configured for 8BitDo Micro in keyboard mode. For other controllers:

Option A: Event Map Editor (recommended)

1. Go to Diagnostics > Monitor raw input (5 sec)
2. Press buttons on your controller
3. Note the key codes shown
4. Go to Event Map Editor > Add new mapping
5. Enter the code and select an event

Option B: Edit bank_config.txt
For power users who want bank switching and full control.

Available Events

Page Navigation

• BTLeft / BTRight - Previous/next page (orientation-aware)
• BTGotoPrevChapter / BTGotoNextChapter

Bookmarks

• BTToggleBookmark, BTPrevBookmark, BTNextBookmark, BTLastBookmark

Display

• BTIncreaseBrightness / BTDecreaseBrightness
• BTIncreaseWarmth / BTDecreaseWarmth
• BTToggleNightMode, BTToggleStatusBar, BTIterateRotation, BTRefreshScreen

Font

• BTIncreaseFontSize / BTDecreaseFontSize
• BTIncreaseFontWeight / BTDecreaseFontWeight
• BTIncreaseLineSpacing / BTDecreaseLineSpacing

System

• BTBluetoothOff, BTBluetoothOffAndSleep, BTSleep

Bank Actions

• BTAction1 through BTAction20 - Configurable via bank_config.txt
• BTRemoteNextBank / BTRemotePrevBank - Switch banks

Troubleshooting

Buttons not working?

1. Check Diagnostics - all items should show pass
2. Use raw input monitor to see if button presses are detected
3. Add missing key codes via Event Map Editor

Controller not connecting?

1. Make sure Bluetooth is ON
2. Use Device Management to scan and select your device

Battery Note

Properly shutting down Bluetooth is crucial. On a Clara 2E, improper shutdown causes ~3% battery drain per hour during sleep. This plugin ensures Bluetooth is turned off correctly - 0% drain when sleeping.

Credits

• Tested on Clara 2E and Libra 2
• Libra 2 support thanks to MobileRead user enji
• 8BitDo Micro controller recommended

Download

https://github.com/onatbas/bluetooth.koplugin

Feedback and contributions welcome.

[trence]

Originally Posted by lumping-sugar66

Hello everyone,

I’m pleased to share an exciting update about my KOReader plugin for kobo devices, which now includes proper scripts for turning Bluetooth on and off, along with the necessary modifications and connections to run my selfie clicker as a page turning device. This should be adaptable to various devices and can serve as a useful example for other developers. While I plan to add more functionality in the future and polish it, make it more error prune etc., I wanted to share now and invite the community to collaborate.

Key Features and Insights

Bluetooth On and Off:
This plugin allows you to turn Bluetooth on and off on the fly and connect to your device directly from KOReader. Here’s how it works:

Turning Bluetooth On: Normally bluetooth processes are killed with KOReader on bootup. The plugin enables Bluetooth directly from KOReader and establishes connection to pre-paired bluetooth devices.
Turning Bluetooth Off: Properly shutting down Bluetooth is crucial to prevent excessive battery drain. On a Clara 2E, I observed a battery drain of about 2.8-3% per hour during sleep if Bluetooth isn’t turned off correctly. The plugin ensures Bluetooth is turned off properly. Without a proper shutdown (like pkill only) the drain would still be around 1.5% per hour during sleep. With this plugin, I can turn Bluetooth on and off and leave the device to sleep with 0% drain.

Nickel doesn’t shut down Bluetooth correctly, so relying on Nickel to turn Bluetooth off after exiting KOReader can still result in significant battery drain. It’s better to turn off Bluetooth using this.

Installation and Usage Instructions

How to Install:

The installation isn't quite hands-free right now. You still need to pair your device once using nickel, and find which /dev/input/eventX it gets mapped to. The initial pairing can also be done using SSH/bluetoothctl.
You also need to add the event code to device.lua listened devices with the action you're expecting. Readme has some examples and more detail on this.

How it Works:

This plugin adds a menu under Gear > Network > Bluetooth, which includes:

Bluetooth On: Turns on WiFi (required for Bluetooth) and Bluetooth, then attempts to establish a connection to a previously paired input device. The plugin also includes the uhid.ko kernel patch, which is necessary for certain Bluetooth devices to be recognized.
Bluetooth Off: Properly shuts down Bluetooth to prevent battery drain.

EDIT:After "Bluetooth On", you need to do [Exit > Restart KOReader] for now to get the device events registered. I'm planning on fixing this in the near future, but for now the complete operation for page turners is to enable bluetooth, and restart KOreader. No need to go to nickel again, just a KOReader restart is fine.

Further Information
For more details or to contribute, please visit the GitHub repository:

https://github.com/onatbas/bluetooth.koplugin
Let me know what you think and I look forward to your feedback and contributions.

I'm a Kobo developer newbie, so please forgive me for my ignorance on the topic. For step 3 of the guide on your Github it says to be sure the device is mapped to event3, how would I go about doing that on a Kobo? I believe I understand how to go about the rest. Thank you!

[lumping-sugar66]

Originally Posted by trence

I'm a Kobo developer newbie, so please forgive me for my ignorance on the topic. For step 3 of the guide on your Github it says to be sure the device is mapped to event3, how would I go about doing that on a Kobo? I believe I understand how to go about the rest. Thank you!

Check the devices currently available in your system first:

ls /dev/input/

And connect your bluetooth device and do it again, and see the difference.

ls /dev/input/

If you get a /dev/input/event3 that wasn't there before, that's your device. After the device is there, you can do

evtest /dev/input/event3

and press on the bluetooth page turner buttons, see if your event stream detects these events.

If your event list doesn't change after you pair/connect your device, uhid.ko may be required and not have applied. You can cd into the bluetooth.koplugin folder and do

insmod ./uhid/uhid.ko

and retry the connection with the bluetooth clicker again. If you still don't see the event, it's likely that your device is trying to identify itself as a weird device and may not be compatible.

If your event is mapped to a different location, modify main.lua to match yours.

Be sure to check device.lua.patch for what's being done. the

hasKeys = yes

addition needs to go into your devices' configuration. For me that's Clara 2E but yours could be different. device.lua is full of all devices and specific configurations for each.

I also realized a slight mistake in my code. The line at https://github.com/onatbas/bluetooth...5/main.lua#L61
has a hardcoded path and assumes that KOReader is installed under "/mnt/onboard/.adds/koreader/". This may not be the right location for your installation, so change that your path as well.

[trence]

Originally Posted by lumping-sugar66

Check the devices currently available in your system first:

ls /dev/input/

And connect your bluetooth device and do it again, and see the difference.

ls /dev/input/

If you get a /dev/input/event3 that wasn't there before, that's your device. After the device is there, you can do

and press on the bluetooth page turner buttons, see if your event stream detects these events.

If your event list doesn't change after you pair/connect your device, uhid.ko may be required and not have applied. You can cd into the bluetooth.koplugin folder and do

and retry the connection with the bluetooth clicker again. If you still don't see the event, it's likely that your device is trying to identify itself as a weird device and may not be compatible.

If your event is mapped to a different location, modify main.lua to match yours.

Be sure to check device.lua.patch for what's being done. the addition needs to go into your devices' configuration. For me that's Clara 2E but yours could be different. device.lua is full of all devices and specific configurations for each.

I also realized a slight mistake in my code. The line at https://github.com/onatbas/bluetooth...5/main.lua#L61
has a hardcoded path and assumes that KOReader is installed under "/mnt/onboard/.adds/koreader/". This may not be the right location for your installation, so change that your path as well.

I am exposing myself as a rookie even further, but I've not used telnet with the kobo before. I'm familiar with telnet and Linux, but not with Kobo. Is there a specific package from this link that I would launch from NickelMenu

https://www.mobileread.com/forums/sh...d.php?t=254214

[trence]

I believe I have found the answer. Just need to re install NickelMenu, with the telnet parts uncommented. Will update with progress. Thanks again.

[trence]

Hi There,

So I have done all the steps needed, and double checked them all as well.

I needed to change my file to event4 based on the test. I paired multiple times to ensure it was event4 each time. evtest was giving a code of 4

"Event: time 1723677209.973075, type 4 (Misc), code 4 (ScanCode), value 90002
Event: time 1723677209.973075 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723677210.096978, type 4 (Misc), code 4 (ScanCode), value 90002
Event: time 1723677210.096978 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723677254.911169 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
yyy
"

So I changed the event_map lua to reflect [4] = "RPgFwd".

The device in question, a Libra 2, already had the field of HasKeys as set for yes in the lua.

I installed the plugin, rebooted my device, and tried it out. It would search after turning Bluetooth on, but eventually fail connecting.

What's odd is that the device connects with no issue on Nickel, and turns pages. I do have the BTPT plugin installed (https://github.com/tsowell/kobo-btpt), do you believe that could be causing issues?

Edit: Forgot to include the picture of the message that would pop up shortly after turning on Bluetooth. Sorry for the snapshot, Koreader wouldn't let me take a proper screenshot. It would successfully connect to my wifi in Koreader.

2nd Edit: I uninstalled BTPT and re-did the process and all the same results/values from event and evtest. Still did not connect in Koreader

https://imgur.com/a/vz60SJX

[lumping-sugar66]

Hi, it looks like you're making good progress.

That screenshot confirms that the bluetooth is turned on properly, unfortunately it doesn't say anything about connection (it never does).

If your device is getting added to event4, then you need to modify device.lua patch to have it connect to /dev/input/event4.

You need to add

    local success, err = pcall(function()
        self.input.open("/dev/input/event4")
    end)

to device/kobo/device.lua right under

self.input.open("fake_events")

. Currently there's a bug with the plugin auto connecting, so all inputs need to be opened through the koplugin code. This also means you need to "Restart KOreader" after turning on bluetooth via the plugin.

I too have the plugin installed on nickel, it won't break your installation, as nickel isn't working when koreader is working.

Since you say that event code 4 works on Nickel page turner I won't press too much on this but event code 4 seems suspicious. You can cross-check with your .btpt/ config file.

What's your bluetooth device by the way? If the above don't work, please share your device.lua and main.lua files, and let's have a look. When you do that, kindly let me know where is your koreader installation in the device. A good way of letting me know is to cd into bluetooth.koplugin folder and do

pwd

and show me the result.

[trence]

Still no luck after doing the things mentioned. I have attached my files from the Plugin in a zip file. I likely am missing a key step.

I also found the 4 code strange, but that is what the telnet on NickelMenu gave when running evtest.

When pressing the button a couple times:
Event: time 1723756563.085844, type 4 (Misc), code 4 (ScanCode), value 90004
Event: time 1723756563.085844 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723756563.175818, type 4 (Misc), code 4 (ScanCode), value 90004
Event: time 1723756563.175818 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723756578.323597 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
yyy


When I did the test a couple years back with evtest on a linux machine, I ended up making this for my btpt config for the page turner. I made all the buttons move a page forward.

nextPage EV_KEY BTN_EAST 0
nextPage EV_KEY BTN_WEST 0
nextPage EV_KEY BTN_GAMEPAD 0
nextPage EV_KEY BTN_NORTH 0

What would the code number be in this case for Kobo, 0? That is one thing I was confused about is where the numeric values for things like RPgFwd are derived from.

Appreciate all the help.

Edit: My koreader is in .adds/koreader. Could the btpt be altering the output of the Kobo Telnet evtest? Or does that run at a level that would be unaffected by something in Nickel like btpt?

[lumping-sugar66]

My pleasure. Thank you for giving it a try.

The code looks good.

By the way, the decimal values of those event codes are as follows. I'm not sure why evtest is skipping through the values. I haven't inspected the code of tsowell/btpt enough to make a call. but it looks like your and my installations are very similar, and I haven't had any issues.

BTN_EAST: 307
BTN_WEST: 308
BTN_GAMEPAD: 304
BTN_NORTH: 305

Please try after mapping functions to these values. If it doesn't work, I can have a look at your device.lua file.

Let me know how it goes.

[trence]

Sorry, I am a bit confused. Do you mean alter the patch file with:

[307] = "BTN_EAST"

etc for the other buttons?

[lumping-sugar66]

No, I suggested a correction for this:

Originally Posted by trence

So I changed the event_map lua to reflect [4] = "RPgFwd".

Those BTN enums correspond to integers in linux input event lists. You mentioned that page turner works with tsowell's plugin and the shared the configuration file. That tells me that your device is issuing BTN_GAMEPAD, BTN_NORTH, BTN_EAST, BTN_WEST events.

Their integer equivalents are 304, 305, 307, 308. (You can literally change the words in the config file to these values and it will work.) For me the event is KEY_VOLUMEUP, so an example for me is as follows.

The following instructions are identical:

nextPage EV_KEY KEY_VOLUMEUP 0
nextPage EV_KEY 115 0

Anyway, coming back to this plugin, instead of

[4] =  "RPgFwd

the following block would give you the identical button configuration with your nickel-based implementation, mapping all buttons to next page.

[304] =  "RPgFwd",
[305] =  "RPgFwd",
[307] =  "RPgFwd",
[308] =  "RPgFwd",

[trence]

Thanks for the explanation. I have added those lines in place of the previous ones, but the clicker still doesn't connect. Instead of the slow blink it does when paired on Nickel/other devices, it continues the fast blink. And I made sure to restart Koreader after enabling bluetooth.

[lumping-sugar66]

OK, sounds like there's something wrong with bluetooth connection, rather than the events being registered.

Try this:

1. SSH into the device.
2. Turn on bluetooth via KOReader.
3. Type in bluetoothctl. (Check 1 - you should see bleuetoothctl prompt. If not, your bluetooth is not running correctly.)
4. See the device name on the bluetooth prompt (if it just says bluetooth, you're not connected).
5. If not connected to the device, check devices using "devices". If your device is in the list, use "trust <MAC_ADDRESS>" and "connect <MAC_ADDRESS>". Once a trust is established, usually devices connect after that automatically.
6. If the device is not on the list at all, then a new pairing must be made. type "scan on" to turn on scan, find your device from that spew of messages coming in, type "pair <MAC_ADDRESS>" and repeat #5. "scan off" after you're done.
7. Try reboot to the device and the workflow again.

[trence]

This was my output, I do not see any devices:

[root@kobo ~]# bluetoothctl
Waiting to connect to bluetoothd...[bluetooth]# Agent registered
[bluetooth]#

I typed in devices:

bluetooth]# devices
No default controller available

I also attempted "scan on" and it said the same about a lack of default controller

[lumping-sugar66]

OK, it sounds like the way I was starting Bluetooth doesn't work properly for Libra 2. I'll modify the descriptions to clearly state it's not tested with anything but Clara 2E. I don't have a Libra 2 device to develop this further for the other devices unfortunately. Thank you for testing this and I'm sorry there isn't a satisfactory resolution.

---

As a side note, this means the missing piece is "turning on bluetooth via KOReader", this means turning it on from Nickel and then running KOReader would have your clicker working.

You can comment out the portion where KOReader kills bluetooth on startup, documented here:
https://github.com/koreader/koreader...ent-1791789778
But this means bluetooth will never be turned off and will drain your battery quickly. You can even delete the folder bluetooth.koplugin as all necessary changes are already in device.lua file already.