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] = "RPgFwd",
    [103] = "RPgBack",
}

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.

[glorius]

Originally Posted by 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.

It's working!!! Thanx a lot!

[tharavol]

NOTE: I did all of this with the assistance of Claude. I don't generally work with LUA, so this is what I came up with today with its assistance. It's working for me, if a little clunky. The Realtek chip seems to lock itself up frequently, so I have to us the repair option often. I hope this helps!

Getting the official Kobo Remote (BLE page-turner) working with bluetooth.koplugin (CarloDePieri fork) on a Kobo Sage

The Sage uses a Realtek RTL8821CS Wi-Fi/Bluetooth combo chip, not Broadcom. This fork's scripts (and the upstream onatbas plugin) assume hciattach ... bcm43xx, which will never work on this hardware ("Initialization timed out"). Confirmed via dmesg (rtl8821c_fillh2ccmd driver lines) and by comparing against what stock Nickel actually runs for Bluetooth (rtk_hciattach).

1. Plugin installation gotcha
If installing via GitHub's "Download ZIP," the extracted folder is named bluetooth.koplugin-main, not bluetooth.koplugin. KOReader's plugin loader only scans folders literally named *.koplugin, so this needs renaming manually or the plugin silently never appears - no error, nothing in crash.log.

2. on.sh/off.sh need a full rewrite for this chip
Final, hardened version - this always tears down and rebuilds the whole stack rather than assuming any prior state is clean, since the adapter frequently ends up "attached but DOWN" or otherwise wedged after periods of Remote inactivity:

#!/bin/sh
cd "$(dirname "$0")"

killall rtk_hciattach 2>/dev/null
killall bluetoothd 2>/dev/null
hciconfig hci0 down 2>/dev/null

echo 0 > /sys/devices/platform/bt/rfkill/rfkill0/state
sleep 1
echo 1 > /sys/devices/platform/bt/rfkill/rfkill0/state

/sbin/rtk_hciattach -n -s 115200 /dev/ttyS1 rtk_h5 > /var/log/rtk_hciattach.log 2>&1 &
sleep 2
hciconfig hci0 up

setsid /libexec/bluetooth/bluetoothd -n -d > /var/log/bluetoothd.log 2>&1 &
sleep 2

echo "complete"

#!/bin/sh
cd "$(dirname "$0")"
hciconfig hci0 down
killall rtk_hciattach
killall bluetoothd
echo 0 > /sys/devices/platform/bt/rfkill/rfkill0/state

Non-obvious details baked into this:

• rtk_hciattach is a resident process (Realtek's H5/three-wire UART transport needs something servicing the link continuously, unlike a typical fire-and-forget hciattach), so it must run backgrounded - but its stdout/stderr must be redirected to a log file, never left attached to the invoking script's own stdout. If it isn't, and the plugin invokes on.sh via a pipe it reads to completion, the pipe never closes and the entire KOReader UI thread hangs forever (pipe_wait) - this looked exactly like a crash until traced via /proc/<pid>/wchan.
• bluetoothd isn't started automatically in this environment and needs setsid to fully detach it from the invoking process/session so it doesn't die when that session ends.
• The rfkill power-cycle (off -> sleep -> on) before every attach, not just on first setup, turned out necessary - hciconfig hci0 up alone repeatedly failed with "Connection timed out" once the chip got into a stuck state, and only a full rfkill cycle reliably recovered it.

3. main.lua fixes

• Device.input.open(...) must be Device.input:open(...) - colon, not dot. The dot-call passes the path string in as self, causing a hard crash (attempt to index field 'input' (a nil value)) inside KOReader's own Input:open.
• The Remote is a BLE peripheral (HID-over-GATT), not classic Bluetooth HID - confirmed via bluetoothctl info showing UUID 1812 (HOGP).
• Pairing must fully complete (Paired: yes), not just connect. An unbonded connection lets GAP/GATT/Device-Info resolve fine, but the actual HID report characteristics stay inaccessible without a completed bond, so no input device ever gets created even though Connected: yes.
• The Remote's button presses arrive as EV_MSC/MSC_SCAN only - no EV_KEY is ever generated, despite the underlying codes (163/164, standard NextSong/PlayPause) appearing in the device's own advertised capability bitmap via evtest. This is a known Linux HID quirk where the kernel's default usage-to-keycode table doesn't confidently map this device/usage combination. The normal fix (a udev hwdb rule) isn't available on stock Kobo firmware - udevadm here has no hwdb subcommand at all. Workaround: a registerEventAdjustHook in main.lua that watches for the specific raw ev.value and calls UIManager:sendEvent(Event:new("GotoViewRel", ...)) directly, bypassing event_map.lua/named-key dispatch entirely (remapping into a synthetic EV_KEY + event_map.lua string didn't work reliably - likely an ordering issue between the adjust-hook and KOReader's type-based event dispatch).
• The same physical press sometimes fires two MSC_SCAN notifications a few hundred ms apart, causing double page-turns - fixed with a simple software debounce gating on ev.time.sec/ev.time.usec (~400ms window).
• The raw scancode values evtest reports don't necessarily match what KOReader's own input pipeline sees for the same event (70051 decimal vs 458833 in our case) - worth confirming the actual values via a debug popup inside the real hook rather than trusting evtest numbers directly when writing the match conditions.

4. Other things worth knowing if you attempt this

• hci0 periodically ends up attached-but-DOWN after periods of inactivity or repeated pair/remove cycling - the hardened on.sh above handles this automatically by always doing a full teardown/rebuild rather than trying to detect when it's needed.
• The BLE bond/connection doesn't reliably survive the Remote sitting idle, and /dev/input/eventN's number isn't stable across reconnects - a hardcoded event path in main.lua will periodically need updating. A name-based lookup at runtime (checking /proc/bus/input/devices for the known device name) would be a more durable long-term fix than a fixed path, but wasn't implemented here. (However, as others have noted, it's always going to be event3.)

Hope this saves someone else the multi-hour rabbit hole this turned into.

[tharavol]

I've worked through some additional issues and this is working pretty well now, including a fix for having to manually repair every time (yay!). Note that this is not generic for any page turner - this is for the Kobo Remote only on the Kobo Sage using the Realtek chipset. Your mileage may vary.

My version is published at:
https://github.com/Tharavol/bluetooth.koplugin

Originally Posted by tharavol

NOTE: I did all of this with the assistance of Claude. I don't generally work with LUA, so this is what I came up with today with its assistance. It's working for me, if a little clunky. The Realtek chip seems to lock itself up frequently, so I have to us the repair option often. I hope this helps!

Getting the official Kobo Remote (BLE page-turner) working with bluetooth.koplugin (CarloDePieri fork) on a Kobo Sage

The Sage uses a Realtek RTL8821CS Wi-Fi/Bluetooth combo chip, not Broadcom. This fork's scripts (and the upstream onatbas plugin) assume hciattach ... bcm43xx, which will never work on this hardware ("Initialization timed out"). Confirmed via dmesg (rtl8821c_fillh2ccmd driver lines) and by comparing against what stock Nickel actually runs for Bluetooth (rtk_hciattach).

1. Plugin installation gotcha
If installing via GitHub's "Download ZIP," the extracted folder is named bluetooth.koplugin-main, not bluetooth.koplugin. KOReader's plugin loader only scans folders literally named *.koplugin, so this needs renaming manually or the plugin silently never appears - no error, nothing in crash.log.

2. on.sh/off.sh need a full rewrite for this chip
Final, hardened version - this always tears down and rebuilds the whole stack rather than assuming any prior state is clean, since the adapter frequently ends up "attached but DOWN" or otherwise wedged after periods of Remote inactivity:

#!/bin/sh
cd "$(dirname "$0")"

killall rtk_hciattach 2>/dev/null
killall bluetoothd 2>/dev/null
hciconfig hci0 down 2>/dev/null

echo 0 > /sys/devices/platform/bt/rfkill/rfkill0/state
sleep 1
echo 1 > /sys/devices/platform/bt/rfkill/rfkill0/state

/sbin/rtk_hciattach -n -s 115200 /dev/ttyS1 rtk_h5 > /var/log/rtk_hciattach.log 2>&1 &
sleep 2
hciconfig hci0 up

setsid /libexec/bluetooth/bluetoothd -n -d > /var/log/bluetoothd.log 2>&1 &
sleep 2

echo "complete"

#!/bin/sh
cd "$(dirname "$0")"
hciconfig hci0 down
killall rtk_hciattach
killall bluetoothd
echo 0 > /sys/devices/platform/bt/rfkill/rfkill0/state

Non-obvious details baked into this:

• rtk_hciattach is a resident process (Realtek's H5/three-wire UART transport needs something servicing the link continuously, unlike a typical fire-and-forget hciattach), so it must run backgrounded - but its stdout/stderr must be redirected to a log file, never left attached to the invoking script's own stdout. If it isn't, and the plugin invokes on.sh via a pipe it reads to completion, the pipe never closes and the entire KOReader UI thread hangs forever (pipe_wait) - this looked exactly like a crash until traced via /proc/<pid>/wchan.
• bluetoothd isn't started automatically in this environment and needs setsid to fully detach it from the invoking process/session so it doesn't die when that session ends.
• The rfkill power-cycle (off -> sleep -> on) before every attach, not just on first setup, turned out necessary - hciconfig hci0 up alone repeatedly failed with "Connection timed out" once the chip got into a stuck state, and only a full rfkill cycle reliably recovered it.

3. main.lua fixes

• Device.input.open(...) must be Device.input:open(...) - colon, not dot. The dot-call passes the path string in as self, causing a hard crash (attempt to index field 'input' (a nil value)) inside KOReader's own Input:open.
• The Remote is a BLE peripheral (HID-over-GATT), not classic Bluetooth HID - confirmed via bluetoothctl info showing UUID 1812 (HOGP).
• Pairing must fully complete (Paired: yes), not just connect. An unbonded connection lets GAP/GATT/Device-Info resolve fine, but the actual HID report characteristics stay inaccessible without a completed bond, so no input device ever gets created even though Connected: yes.
• The Remote's button presses arrive as EV_MSC/MSC_SCAN only - no EV_KEY is ever generated, despite the underlying codes (163/164, standard NextSong/PlayPause) appearing in the device's own advertised capability bitmap via evtest. This is a known Linux HID quirk where the kernel's default usage-to-keycode table doesn't confidently map this device/usage combination. The normal fix (a udev hwdb rule) isn't available on stock Kobo firmware - udevadm here has no hwdb subcommand at all. Workaround: a registerEventAdjustHook in main.lua that watches for the specific raw ev.value and calls UIManager:sendEvent(Event:new("GotoViewRel", ...)) directly, bypassing event_map.lua/named-key dispatch entirely (remapping into a synthetic EV_KEY + event_map.lua string didn't work reliably - likely an ordering issue between the adjust-hook and KOReader's type-based event dispatch).
• The same physical press sometimes fires two MSC_SCAN notifications a few hundred ms apart, causing double page-turns - fixed with a simple software debounce gating on ev.time.sec/ev.time.usec (~400ms window).
• The raw scancode values evtest reports don't necessarily match what KOReader's own input pipeline sees for the same event (70051 decimal vs 458833 in our case) - worth confirming the actual values via a debug popup inside the real hook rather than trusting evtest numbers directly when writing the match conditions.

4. Other things worth knowing if you attempt this

• hci0 periodically ends up attached-but-DOWN after periods of inactivity or repeated pair/remove cycling - the hardened on.sh above handles this automatically by always doing a full teardown/rebuild rather than trying to detect when it's needed.
• The BLE bond/connection doesn't reliably survive the Remote sitting idle, and /dev/input/eventN's number isn't stable across reconnects - a hardcoded event path in main.lua will periodically need updating. A name-based lookup at runtime (checking /proc/bus/input/devices for the known device name) would be a more durable long-term fix than a fixed path, but wasn't implemented here. (However, as others have noted, it's always going to be event3.)

Hope this saves someone else the multi-hour rabbit hole this turned into.