Bluetooth Page Turner plugin for Kobo KOReader

[ZuluWraith]

Originally Posted by thegameksk

Anyone have any luck getting this working with the Sage?

Hi, unfortunately I don't own a Sage - but i can confirm that i have managed to get this amazing plugin working on my Elipsa 2E. I'm not sure which cpu the Sage has, but the one in mine isn't fully supported yet so i believe it's more than worth a try - this plugin is truly a game changer!

[glorius]

It doesn't work for me on Sage, unfortunately.

[camifran]

Also not working for me on Sage. After all my tinkering with this and other bluetooth plugins, BT stopped working on my stock reader too!

[Frenzie]

Originally Posted by camifran

Also not working for me on Sage. After all my tinkering with this and other bluetooth plugins, BT stopped working on my stock reader too!

It should recover if you restart the device, shouldn't it?

[signer-ink-beast]

Originally Posted by thegameksk

Anyone have any luck getting this working with the Sage?

Somebody left a comment on the KOReader GitHub saying they got an 8BitDo Micro working here.

[signer-ink-beast]

After using this plugin more consistently on my Libra 2 lately, I have come across an issue. I use KOReader v2025.10-142-g7c33042ae_2026-02-18 (nightly version) and main branch of bluetooth.koplugin (commit 7d4a707).

The event map file (button mappings) are remembered. I can see the file, and settings are loaded within the bluetooth menu when I go view them. However, when I connect my 8BitDo Micro to my Libra 2, these mappings aren't applied. I can't get them to load.

However, there's an easy workaround for now. If I start the simple guided setup and map a single button (I press ‘A’ on the controller and map it to “next page”), and click finish and save, it loads it and the rest of the existing mapping.

I notice this happens consistently. Even if I don't leave KOReader, I have to do the simple guided setup to get it to actually load my keymap properly anytime I want to reconnect and use the controller.

I took a cursory glance at the Lua code, but I am not familiar with Lua or the codebase, both for the plugin and KOReader itself. Haven't gotten around to looking at it more, but wanted to report here for others reading this thread in the meantime. I should probably write a bug report, too.

[daBigR--]

Originally Posted by thegameksk

Anyone have any luck getting this working with the Sage?

Hi, if you mean the plugin published in this thread, no, no luck. But if you mean to get a BT HID device connected and being able to use it to turn pages or trigger other events in Kobo Sage, yes! My current solution is a bit convoluted but I'm working on a new one I've tested on other devices but not on Sage yet. Please reply if you want me to explain my original setup or if you're willing to wait a few days until I test the new solution on my Sage.

[daBigR--]

Originally Posted by camifran

Also not working for me on Sage. After all my tinkering with this and other bluetooth plugins, BT stopped working on my stock reader too!

Hola, I just saw a prior message from somebody's not being able to get it to work in Sage. I got it working, the way I did it originally is quite complex, I'm finishing testing a new way to do it and I'll post this method in a few days. There is still a cumbersome part because KOReader start script for the Sage does try to kill BT with "extreme prejudice" as some developer said. You have to modify this script to eliminate those lines of code and also to wire up the event system. Those changes can't be done in a simpler way that I know of. But the mapping of the device's keys to actions in KOReader will be quite easy enough if my idea works on the Sage - it has worked on other readers so I'm quite optimistic. As I said I'll let you know in a while.

[daBigR--]

Only for Kobo Sage
Tested on KOReader 2026.03

Follow these steps:
- Open .adds/koreader/koreader.sh
- Search for comment # If bluetooth is enabled, kill it
- Comment or delete both ifs below that, one refers to sunxi the other to nxp
e.g.

    # If bluetooth is enabled, kill it.
    # if [ -e "/sys/devices/platform/bt/rfkill/rfkill0/state" ]; then
        # # That's on sunxi, at least
        # IFS= read -r bt_state <"/sys/devices/platform/bt/rfkill/rfkill0/state"
        # if [ "${bt_state}" = "1" ]; then
            # echo "0" >"/sys/devices/platform/bt/rfkill/rfkill0/state"

            # # Power the chip down
            # ./luajit frontend/device/kobo/ntx_io.lua 126 0
        # fi
    # fi
    # if grep -q "^sdio_bt_pwr " "/proc/modules"; then
        # # And that's on NXP SoCs
        # rmmod sdio_bt_pwr
    # fi

A couple of lines further there is a killall line
Again comment or delete both bluetoothd and bluealsa (not 100% sure about this last one but better safe than sorry)
e.g.

    killall -q -TERM nickel hindenburg sickel fickel strickel fontickel adobehost foxitpdf iink dhcpcd-dbus dhcpcd fmon nanoclock.lua # bluealsa bluetoothd

That's it for koreader.sh

- Now open .adds/koreader/frontend/device/kobo/device.lua
- Search for

self.input:open("fake_events")

- After that insert:

local success1, event3res = pcall(function()
    self.input:open("/dev/input/event3")
  end)

AFAIK unless you have more than one bluetooth device paired with Sage it will always be event3.

- Now you will be able to pair and connect your bt device and open KOReader with it enabled.
As many people have said if you open KOReader with bluetooth enabled, when you exit the system will crash. That has to do with the way the drivers are written and there is no way to prevent it. Remember to exit KOReader by rebooting the reader.
- To test and get the keycodes open tools -> more tools -> terminal emulator -> open terminal session
- Inside the terminal type

evtest /dev/input/event3

This command first lists the registered events and then says Testing... if you press a key/button on your BT device (say the key you want to use to go forward one page) you'll see several lines but the important one will be like:

Event: time 1675505630.867333, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70051

That is, a line that says type 4 and a MSC_SCAN value, in the example it is scancode "70051"
- Now the manual decoding part.
+ Part one: 7 means keyboard page and 0051 is the usage id. look that up in https://usb.org/sites/default/files/hut1_21.pdf and you'll see page 0x07 usage id 51 is Keyboard DownArrow
+ Part two: look for down arrow either on evtest's initial listing or in https://github.com/torvalds/linux/bl...-event-codes.h either way you'll find it corresponds to keycode 108.
That last code is what we need for the final config in KOReader, I'll keep using the example but you have to use the value you found.
- Create or modify .adds/koreader/settings/event_map.lua
+ If the file already exists and it already maps 108 to a string you'll have to change the string to "RPgFwd" (or "RPgBack" if you're mapping the "go back" key/button)
+ If the file exists but it doesn't have a line with 108 then you'll have to insert a line like [108] = "RPgFwd",
+ Finally if there is no event_map.lua file in settings, create one and type this inside:

return {
    [108] = "RPgBack",
    [103] = "RPgFwd",
}

The important thing is wou have to replace the example 108 and 103 with the values you decoded earlier.

Not simple but it works. Unfortunatelly the feature that would have made everything easier, at least for finding the keycode, aparently isn't available in KOReader for Kobo

That's it.