Bluetooth Page Turner plugin for Kobo KOReader

[lumping-sugar66]

Originally Posted by Malletta

after installing the plugin, and enabling WIFi, this is what I see when I try to enable the bluetooth:
any ideas?

Hi, I see similar long messages sometimes, too. It's not really a crash but rather an artifact of the verbose output. I'll try to patch it up on the next push. Bluetooth may actually be turned on despite all that verbosity.

[Malletta]

thank for you reply!
after I got this message, the bluetooth remain still off and I cannot scan for any device..

[lumping-sugar66]

Originally Posted by Malletta

thank for you reply!
after I got this message, the bluetooth remain still off and I cannot scan for any device..

please try 1.0.1 where the messages should be clearer now.

----

Bluetooth Plugin v1.0.1 - Guided Simple Setup & Improvements

Version 1.0.1 is now available with significant usability improvements, focusing on making controller setup accessible to all users.

New Feature: Guided Simple Setup

The biggest addition is an interactive wizard for configuring your Bluetooth controller buttons. Instead of manually editing configuration files or understanding key codes, you can now:

1. Go to Bluetooth → Event Map Editor → Guided Simple Setup
2. Press a button on your controller when prompted
3. Select what that button should do from a list (Next Page, Previous Page, etc.)
4. Repeat for each button you want to configure
5. Review and save your mappings

The wizard automatically detects key codes and saves everything to the correct location. No technical knowledge required.

Dynamic Input Device Detection

Previously, the plugin used hardcoded paths like /dev/input/event3 or event4, which only worked on specific devices. Version 1.0.1 now dynamically matches your Bluetooth controller by name.

When you connect your controller, the plugin searches all available input devices and matches the device name (e.g., "8BitDo Micro") to find the correct event path. This means:

• No more hardcoded event paths that only work on certain Kobo models
• Devices where the Bluetooth receiver appears as event5 or higher now work correctly
• The plugin adapts automatically when input device order changes
• Falls back to known device models or highest event number if name matching fails

You can verify this in Diagnostics → Input device path which will show whether the path was matched by Bluetooth device name, known device model, or fallback.

Other Improvements

• Dynamic driver detection - Auto-detects the correct Bluetooth driver path, supporting i.MX6 devices (Clara 2E, Libra 2) and preparing for MediaTek device support.
  
• Delete Mappings option - In Diagnostics → Event Map, you can now delete existing mappings and start fresh.
  
• Cleaner error handling - Fixed verbose D-Bus output and improved error messages.

Video Tutorial

A video walkthrough demonstrating installation and setup:

[Malletta]

Originally Posted by lumping-sugar66

please try 1.0.1 where the messages should be clearer now.

----

Bluetooth Plugin v1.0.1 - Guided Simple Setup & Improvements

Version 1.0.1 is now available with significant usability improvements, focusing on making controller setup accessible to all users.

New Feature: Guided Simple Setup

The biggest addition is an interactive wizard for configuring your Bluetooth controller buttons. Instead of manually editing configuration files or understanding key codes, you can now:

1. Go to Bluetooth → Event Map Editor → Guided Simple Setup
2. Press a button on your controller when prompted
3. Select what that button should do from a list (Next Page, Previous Page, etc.)
4. Repeat for each button you want to configure
5. Review and save your mappings

The wizard automatically detects key codes and saves everything to the correct location. No technical knowledge required.

Dynamic Input Device Detection

Previously, the plugin used hardcoded paths like /dev/input/event3 or event4, which only worked on specific devices. Version 1.0.1 now dynamically matches your Bluetooth controller by name.

When you connect your controller, the plugin searches all available input devices and matches the device name (e.g., "8BitDo Micro") to find the correct event path. This means:

• No more hardcoded event paths that only work on certain Kobo models
• Devices where the Bluetooth receiver appears as event5 or higher now work correctly
• The plugin adapts automatically when input device order changes
• Falls back to known device models or highest event number if name matching fails

You can verify this in Diagnostics → Input device path which will show whether the path was matched by Bluetooth device name, known device model, or fallback.

Other Improvements

• Dynamic driver detection - Auto-detects the correct Bluetooth driver path, supporting i.MX6 devices (Clara 2E, Libra 2) and preparing for MediaTek device support.
  
• Delete Mappings option - In Diagnostics → Event Map, you can now delete existing mappings and start fresh.
  
• Cleaner error handling - Fixed verbose D-Bus output and improved error messages.

Video Tutorial

A video walkthrough demonstrating installation and setup:

yeees thanks now I can turn bluetooth on! I detect the Kobo Remote and I can connect to it, but it doesn't seems to create any events, no button is working when I try to use the simple guided mapping! (the remote works fine in the stock Kobo reader)
EDIT: Trying again, I just managed to map the buttons, but after a click the remote stopped working again.

[roguexuk]

Hello

Wow you do work fast. Another update already! Thanks for the hard work on this.

I just installed it on my Libra2, I can confirm that the Kobo Remote now works on koreader! Hooray!

At first it wasn't interested when I tried to map keys, but I think that the remote either not connected properly or disconnecting too soon. I think maybe the second one.

In the end I had to connect it, refresh the device input & get to the guided simple setup as soon as possible 😆

Edit: looks like I'm having the same connection issues as the above poster.
The kobo remote only stays connected for 27 seconds (weird number), then I have to refresh device input to get it to work again.

Thanks do much for this 🫰

Sent from my SM-X110 using Tapatalk

[lumping-sugar66]

Originally Posted by roguexuk

I just installed it on my Libra2, I can confirm that the Kobo Remote now works on koreader! Hooray!

I have to refresh device input to get it to work again.

I'm glad it's working for you. All devices are very particular so the behaviours may be different. Things like these are mainly the reason why I didn't conceal "Refresh Device Input" behind a simple connect button. Some devices disconnect and connect within milliseconds and that means the device event listener disappears in the OS.
I recommend that you bind a finger gesture to Restore Device Input and then you can get that triggered easily.

---

Clara BW (MediaTek) - Investigation Results

Thanks to WaveEquation for spending time testing and debugging the plugin on his Clara BW. Here's what we discovered.

The Problem

The Clara BW uses a MediaTek MT8110 processor. Unlike the i.MX6-based Kobos (Libra 2, Clara 2E), Kobo has replaced the standard Linux Bluetooth stack:

- No bluetoothctl involved in managing bluetooth - the standard BlueZ command-line tool is absent
- No bluetoothd daemon running even when bluetooth is working.
- Seems like kobo created their own proprietary "btservice" daemon.
- This btservice has no exposed command-line interface that we could figure out.

This means the plugin cannot turn Bluetooth on/off or manage device pairing on MediaTek devices in it's current stage.

What Works

Partial solution: if you manage Bluetooth through Kobo's native settings, the button mapping still works.

1. Turn on Bluetooth via Kobo settings (not KOReader)
2. Pair and connect your controller via Kobo settings
3. Launch KOReader
4. Use Bluetooth > Refresh Device Input
5. Use Bluetooth > Event Map Editor > Guided Simple Setup to configure buttons

All button actions work correctly once the input device is detected.


The catch is that apparently there's a known KOReader bug where exiting KOReader while Bluetooth is ON can reboot the device and sometimes remove NickelMenu. This could significantly impact the usefulness of any bluetooth integration. We may need help from the wider koreader community. See: https://github.com/koreader/koreader/issues/12739

Because the plugin cannot control Bluetooth on MediaTek, you cannot turn it off before exiting. The workaround is to use "Reboot device" instead of "Exit" when leaving KOReader with Bluetooth active.

Simplified Branch Available

I've pushed a "clarabw" branch to the repository with the Bluetooth management code disabled. This version assumes Bluetooth is handled externally and only provides the event mapping functionality.

Repository: https://github.com/onatbas/bluetooth.koplugin
Branch: clarabw

Future Work

In order for Bluetooth to be fully supported, we need to figure out how to program bluetooth in Clara/Libra BW/Colour without bluetoothd running. One of the benefits of this plugin is easily turning bluetooth functions on/off, and that's the piece new device users are missing here.

It may come to to reverse-engineering how Kobo's btservice works so we can fully integrate with it. If anyone has experience with MediaTek Bluetooth stacks or has one of these devices or wants to help investigate, please feel free to get involved. Remote debugging is quite challenging and I don't want to brick another persons device.

For now, Clara/Libra BW/Colour users will need to manage Bluetooth manually through Kobo's interface.

[lumping-sugar66]

I made some changes in a special branch https://github.com/onatbas/bluetooth.koplugin/tree/mtk

Using @OG-Booksmith's changes from kobo.koreader (mentioned here https://www.mobileread.com/forums/sh...00&postcount=3), I added an MTK backend alternative methods to bluetooth events. This is highly experimental and not tested. But if colour/bw/elipsa users could load this up, can you check Diagnostics > Device Type and see if isMTK flag is being detected correctly?

If so, there’s a chance the other methods may work, too. This is not tested on a real device don’t have the device to test, but if you’re willing to give it a shot, please do and create an issue in the GitHub repository or shoot me an email.

Apart from potentially triggering the kernel issue https://github.com/koreader/koreader/issues/12739, I don’t believe this would cause a lot of long-term trouble.