Bluetooth Page Turner plugin for Kobo KOReader

[edojan]

I wonder if anyone can confirm this works with Kobo Sage? Anything needs to be changed / done differently after installation of the plugin? Thanks!

[lucasz]

I'm wondering if this will work with the new official Kobo Remote...
I myself am still on the original Clara HD. So I can't really test it out. But it would be great if I eventually upgrade.

[Malletta]

Any ideas on how to pair the Official Kobo Remote with Libra 2?

[lumping-sugar66]

Originally Posted by edojan

I wonder if anyone can confirm this works with Kobo Sage? Anything needs to be changed / done differently after installation of the plugin? Thanks!

I don't possess a Sage but I bet the drivers exists. We could likely figure out the instructions the standard nickel issues by looking at the logs if they're different. Please check if it's compatible using Libra 2 instructions, and let us know otherwise.

[lumping-sugar66]

Originally Posted by lucasz

I'm wondering if this will work with the new official Kobo Remote...
I myself am still on the original Clara HD. So I can't really test it out. But it would be great if I eventually upgrade.

I'm not familiar with the workings of the official Kobo Remote but if purpose-built remotes are any indication of future performance, they may have locked in support for standard nickel. This is purely anecdotal, though. If they make the Kobo Remote act just like any sender, there's nothing prevents nickel users or us from using it.

[lumping-sugar66]

Bluetooth Plugin Update 1.0.0 - Major Overhaul: Auto-Configuration & Diagnostics

Hello everyone! I've made a major overhaul on the Bluetooth plugin based on your feedback with the goals of eliminating manual configuration wherever possible and make troubleshooting easy when things don't work.

Hopefully now most of the issues we've seen so far will be resolved as there's less room for errors.

What's New

No More Manual File Editing

The biggest pain point was having to manually edit multiple files. That's gone now:

• No more KOReader code editing for button mappings → No need to edit device.lua or anything. Now auto-configured via Diagnostics → "Correct Automatically"
• device.lua hasKeys patch → Now auto-configured via Diagnostics → "Correct Automatically"
• main.lua installation path → Now auto-detected using KOReader's DataStorage API
• UI-based via Device Management menu → No need to figure out MAC addresses, there's a menu for that.
• Scripts for Libra 2 vs Clara 2E → Now auto-detected by checking which binaries exist in /sbin
• Smart Device Detection → Now auto-detected based on device model, No more event3 vs event4 confusion.
• No shell scripts → Now have been replaced with native Lua code. This means no need for editing scripts.

Device Management UI

New menu: Bluetooth → Device Management

�� Bluetooth is ON
Current device: 8BitDo Micro (E4:17:D8:7D:3D:69)
Connect to saved device
───────────────
Start scanning (30s)
Stop scanning
Select from scanned devices
Select from paired devices

• Scan for devices directly from the UI
• Select and save your controller
• No more editing MAC addresses in scripts

Comprehensive Diagnostics

New menu: Bluetooth → Diagnostics

�� Bluetooth is ON
─── Configuration Checks ───
ℹ  KOReader installation path
✓  Device type
✓  hasKeys flag
✓  Input device path
ℹ  Bluetooth commands
✓  Event map (BT events)
✓  Bank configuration
✓  Saved Bluetooth device
─── Debug Tools ───
�� Button press history (0)
��  Clear button history
�� Monitor raw input (5 sec)

Each diagnostic check:

• Shows ✓ (pass), ✗ (fail), ⚠ (warning), or ℹ (info)
• Click to see detailed information
• Offers "Correct Automatically" button where applicable

Debug Tools

• Button press history - Shows the last 10 button presses with timestamps, event names, key codes, and which action was triggered
• Monitor raw input - Captures 5 seconds of raw input from the event device, showing actual key codes your controller sends

�� Addressing Previous Issues

✅ FIXED - These issues are now resolved:

Originally Posted by roguexuk

Through my many koreader crashes, I've discovered that adding the changes from your patch file seem to break the loading of koreader...
I'm also using a Kobo Libra 2, so I made the adjustments suggested in yours and enji's posts

→ FIXED: The hasKeys patch now uses KOReader's official user patch system (

koreader/patches/

). The Diagnostics page offers "Correct Automatically" which creates a proper patch file that won't crash KOReader. Libra 2 commands are now auto-detected.

Originally Posted by roguexuk

Error: No result from the Bluetooth script

→ FIXED: All shell scripts have been eliminated. Bluetooth control is now 100% Lua code with proper error handling.

Originally Posted by roguexuk

I'm wondering if it the location of the plug-in entry in the main.lua file...
local command = "/mnt/onboard/.adds/koreader/plugins/bluetooth.koplugin"

→ FIXED: The plugin now uses

DataStorage:getFullDataDir()

to dynamically detect KOReader's installation path. No more hardcoded paths.

Originally Posted by lkws1

1. The path to the plugin folder is set on an absolute basis - my folder directory was different
2. The on.sh script doesn't return the right variables

→ FIXED: Both issues resolved. Dynamic path detection and shell scripts eliminated.

Originally Posted by RootNinja

I also get this "no result from script error". Could you explain more about changing the folder?

→ FIXED: No more script errors. No folder changes needed - it's all automatic now.

Originally Posted by lumping-sugar66 about Libra 2

Using rtk_hciattach instead of hciattach

→ FIXED: The plugin now checks

/sbin

for which binary exists and uses the appropriate one automatically. Diagnostics shows which config was detected.

�� DIAGNOSABLE - These can now be investigated:

Originally Posted by pumpkinwhite

I connected a regular game controller to the Kobo Libra Colour, just to see what event codes it provides. I got the following output - Event code 304 (BtnA), Event code 305 (BtnB)...

→ DIAGNOSABLE: Use Diagnostics → Monitor raw input (5 sec) to capture the exact key codes your controller sends. The button press history also shows codes. Gamepad codes (304-318) are different from keyboard codes - you'd need to add these to the event mappings.

Originally Posted by Frenzie

Out of curiosity, do you recall if the KOReader logs showed any kind of keycodes for the gamepad?

→ DIAGNOSABLE: The new Button press history shows every BT event with its integer key code. The Raw input monitor shows codes directly from the input device.

⚠️ NOT SUPPORTED - Hardware limitations:

Originally Posted by billie on Clara BW

insmod: can't insert '/drivers/mx6sll-ntx/wifi/sdio_bt_pwr.ko': No such file or directory
When I check /drivers/ there's only /drivers/mt8113t-ntx/mt66xx/

Originally Posted by Sofo

I get the same error. Trying this on the KCL (Kobo Libra Colour).

Originally Posted by lambic

I'm on a Kobo Libra Color and seeing pretty much the same symptoms. I'm guessing koreader just plain doesn't support the MTK (MediaTek) bluetooth hardware.

Originally Posted by carloslmar on Clara Colour

It gives me an error "Error: No result from the Bluetooth script" even after changing the path

Originally Posted by WaveEquation on Clara BW

If anyone has managed to get this work on a Clara with 8bitdo micro, can you please share the plugin code?

→ NOT SUPPORTED (yet): The Clara BW, Clara Colour, and Libra Colour use MediaTek (MTK) Bluetooth hardware with completely different drivers:

• They have

  /drivers/mt8113t-ntx/mt66xx/

  instead of

  /drivers/mx6sll-ntx/

• The kernel modules and attach commands are different
• This requires someone with these devices to figure out the correct commands

The Diagnostics page will now clearly show:

• ⚠ Warning if your device model is unsupported
• ⚠ Warning if no known Bluetooth binaries are found in /sbin
• The exact error details when you click the diagnostic

If you have a Clara BW/Colour or Libra Colour and want to help, please:
1. SSH into your device
2. Run

ls -la /drivers/

and

ls -la /sbin/*hci*

3. Share the output so we can add support for MTK devices

�� Installation

1. Download the plugin from GitHub
2. Rename folder to

bluetooth.koplugin

(remove the "-main" suffix)
3. Copy to

koreader/plugins/

4. Restart KOReader
5. Go to Bluetooth → Diagnostics and click any ✗ items to auto-fix

That's it! No more editing device.lua, no more patching files, no more script modifications.

�� Supported Devices

Fully Tested:

• Kobo Clara 2E (Kobo_goldfinch)
• Kobo Libra 2 (Kobo_io)

Should Work (auto-detection will try):

• Other Kobo devices with similar Bluetooth hardware

Still Not Yet Supported:

• Kobo Clara BW (MediaTek hardware)
• Kobo Clara Colour (MediaTek hardware)
• Kobo Libra Colour (MediaTek hardware)

Feedback welcome.

[lumping-sugar66]

Building on yesterdays post, I’ve recorded two video tutorials to help with installation and to give a general feature overview, as I know the setup and configuration process has caused some pain.

With version 1.0.0, most of the manual steps are now handled automatically by the software. With these improvements and the videos, I’m hoping it’ll be much easier to get up and running.

Installation tutorial:


Feature overview tutorial:

[roguexuk]

Wow, you've been hard at work :-) Thanks for this.

I've tried it out on my Libra 2:
- The 8bitdo connects and works fine.
- The kobo remote says that it's connected but the flashing pairing light on the back of the remote is on - so I don't think that it's actually connecting.

I was curious about the raw data codes that I would get, but when I tried it with the 8bitdo, it didn't register any key presses at all, and history for those had nothing either.
But the 8bitDo was connected and working, so I don't mind that too much ;-)

It was so much easier to install. And I really like the Full Setup Option, means I don't forget to turn off wi-fi.

To sum up the 8bitdo does work with this plug-in.
The Kobo remote doesn't, but from previous comments inthis thread, I wasn't really expecting it to.

[JSWolf]

Originally Posted by lumping-sugar66

Building on yesterdays post, I’ve recorded two video tutorials to help with installation and to give a general feature overview, as I know the setup and configuration process has caused some pain.

With version 1.0.0, most of the manual steps are now handled automatically by the software. With these improvements and the videos, I’m hoping it’ll be much easier to get up and running.

Can you do away with the login so we can see the videos?

[lumping-sugar66]

Originally Posted by JSWolf

Can you do away with the login so we can see the videos?

Is that something I have control over on YouTube? These are public videos and I can see them even if I'm logged out or in an incognito window.

[WaveEquation]

@lumping-sugar66 Thanks so much for the update. I have a Clara BW and ran the commands you requested. Hope this helps:

[root@kobo ~]# ls -la /drivers/
total 12
drwxrwxr-x    3 3018     3018          4096 Aug 19 08:48 .
drwxr-xr-x   20 root     root          4096 Apr 27  2024 ..
drwxrwxr-x    3 3018     3018          4096 Dec 12  2024 mt8113t-ntx

[root@kobo ~]# ls -la /sbin/*hci*
-rwxr-xr-x    1 root     root        182684 Mar  2  2022 /sbin/hciattach
-rwxr-xr-x    1 root     root         59860 Aug 19  2021 /sbin/rtk_hciattach

Let me know if you need any assistance from me.

[lumping-sugar66]

Originally Posted by WaveEquation

@lumping-sugar66 Thanks so much for the update. I have a Clara BW and ran the commands you requested. Hope this helps:

Let me know if you need any assistance from me.

Thanks for the results. It's interesting that both hciattach and rtk_hciattach are there. Would you be open to a TeamViewer session? I feel like an SSH session will help tremendously, and we may be able to figure out a way to get it working on the BW kernel. If you're interested, shoot me an email, you can find my email here.

[lumping-sugar66]

New Diagnostic Tools

Pushed an update with additional diagnostic tools to help troubleshoot more Bluetooth controllers and help identify the events generated by them.

After connecting your Bluetooth device, navigate to Diagnostics > Debug Tools. The following tools are now available:

List all input devices
Displays all input devices on your Kobo along with their names. This identifies which /dev/input/eventX your controller is assigned to.

Test specific device
Allows you to select and test any input device directly. Useful if your controller is mapped to a different event device than the default.

Live capture (15 sec)
Hooks into KOReader's input system and captures all key events for 15 seconds. Press buttons on your controller during the capture window to see which key codes are being generated.

Output includes:
- Key codes received by KOReader
- Human-readable names for known keys
- Summary of unique codes detected

=== KEY CODES DETECTED ===

  Code 109 = PAGEDOWN
  Code 104 = PAGEUP
  Code 115 (unknown - add to event_map!)

=== ALL PRESS EVENTS ===
  [14:32:15] Code 109 (PAGEDOWN)
  [14:32:16] Code 104 (PAGEUP)

If you are experiencing difficulties ensuring the device is sending the correct event codes after your button presses, or want to ensure the event listeners are created at the right places, you can use these new diagnostics tools.