Instructions: Bluetooth control for KOReader on newer Kobo devices

[OG-Booksmith]

I've written a plugin that should make this easier for MTK based kobo ereaders, aka Libra Colour and Clara Colour.

Have a look here: https://ogkevin.github.io/kobo.koplu...bluetooth.html

It esentially allows for registering key bindings via the UI.
The messages/UI needs a bit of polishing tho. But I think the concept works, and can be tested/played around with in the meanwhile if interested.

This might also be of interest: https://ogkevin.github.io/kobo.koplu...bluetooth.html

[potatoball]

Thank you so much for this! How did you find out the event names for the UI manager? I was thinking to add other functionalities like opening the home page / history.

[ciatriad]

Hi all. Thanks in advance, and to the op, thanks for the detailed write-up. I'm on the latest kobo firmware (4.44.23552) on my libra color. For Koreader i'm on 2025.10. Has anyone been able to get the kobo remote working in koreader? I see it as event 4. It looks like ScanCode is the only button identifier when I'm scrolling up to event 4. I don't have any bluetooth plugins installed in Koreader if that matters.
Event type 4 (Misc)
Event code 4 (ScanCode)
When I press the buttons I see:

Event: time 1765391398.834383, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1765391398.834383 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------
Event: time 1765391398.984333, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1765391398.984333 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------
Event: time 1765391401.234164, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1765391401.234164 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------
Event: time 1765391401.384092, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1765391401.384092 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------

For Step 4: [• Scroll down to the section which has the header – set up fake event map (This section has lines that look like Self.event_map[10000] = “IntoSS”)] I didn't find a section with this header or any Self.event_map in my device.lua file. The word map is found 2 times in my file:

self.input = require("device/input"):new{
device = self,
event_map = {
[35] = "SleepCover", -- KEY_H, Elipsa
[59] = "SleepCover",
[90] = "LightButton",
[102] = "Home",
[116] = "Power",
[193] = "RPgBack",
[194] = "RPgFwd",
[331] = "Eraser",
[332] = "Highlighter",

and

event_map_adapter = {
SleepCover = function(ev)
if self.input:isEvKeyPress(ev) then
return "SleepCoverClosed"
elseif self.input:isEvKeyRelease(ev) then
return "SleepCoverOpened"
end
end,

[thegameksk]

Originally Posted by sooeee

Thank you so much for posting these detailed instructions!




I can't seem to get past this stage because the moment I enter KOReader, the bluetooth turns off and the controller disconnects

Would you happen to know if it's something I am doing wrong?

Did you find a fix for this? Im having the same issue

[daBigR--]

Hi. I don't know how the others got it to work. I had this feature working some time ago and I lost my setup when I updated KOReader without pausing to think if the update would overwrite the changes or not. However when I originally set it up and still valid now, I had the same problem you are having. At that time I figured out that The KOReader start script -- koreader.sh -- kills bluetooth with "extreme prejudice" as one of the developers put it. I mean koreader.sh does everything it can to stop bluetooth before launching KOReader. You can find a comment to that effect in the code: # If bluetooth is enabled, kill it. What I did is comment both if statements following said comment and removed blualsa and bluetoothhd from the killall command a few lines below. Of course nickel will crash when exiting KOReader with bluetooth on as others have said but the reboot device workaround works fine. All other pumpkinwhite steps are correct, except that if you use the standard RPageFwd and RPageBack some of the setup is not necessary and if you do include it you may have duplicate events, e.g. forward 2 pages instead of just one.

[daBigR--]

In koreader.sh look for comment : # If bluetooth is enabled, kill it. Then comment both if statements following it. Also remove bluealsa and bluetoothhd from the killall a little below

[Fun4st]

Is there any way to add a Bluetooth remote within koreader? So that if I was my device I do have to exit koreader, connect the remote, and then reopen koreader

[pumpkinwhite]

Originally Posted by daBigR--

In koreader.sh look for comment : # If bluetooth is enabled, kill it. Then comment both if statements following it. Also remove bluealsa and bluetoothhd from the killall a little below

That you for that tip. I happened to update KOReader and the remote stopped working. Luckily your comment was there in this thread itself. I've updated the original instructions to add this as a step, and given you credit for it.

I also added another optional step after that, which reboots the device the when exiting KOReader if bluetooth is ON (instead of simply exiting KOReader which triggers the bug that removes Nickelmenu). Adding that step prevents Nickelmenu from getting removed due to the bug.

[pumpkinwhite]

Originally Posted by ciatriad

Hi all. Thanks in advance, and to the op, thanks for the detailed write-up. I'm on the latest kobo firmware (4.44.23552) on my libra color. For Koreader i'm on 2025.10. Has anyone been able to get the kobo remote working in koreader? I see it as event 4. It looks like ScanCode is the only button identifier when I'm scrolling up to event 4. I don't have any bluetooth plugins installed in Koreader if that matters.
Event type 4 (Misc)
Event code 4 (ScanCode)
When I press the buttons I see:

Event: time 1765391398.834383, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1765391398.834383 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------
Event: time 1765391398.984333, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1765391398.984333 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------
Event: time 1765391401.234164, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1765391401.234164 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------
Event: time 1765391401.384092, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1765391401.384092 ------- Report Sync ------ x: 36808 y: 36728 p: 0 ------------

For Step 4: [• Scroll down to the section which has the header – set up fake event map (This section has lines that look like Self.event_map[10000] = “IntoSS”)] I didn't find a section with this header or any Self.event_map in my device.lua file. The word map is found 2 times in my file:

self.input = require("device/input"):new{
device = self,
event_map = {
[35] = "SleepCover", -- KEY_H, Elipsa
[59] = "SleepCover",
[90] = "LightButton",
[102] = "Home",
[116] = "Power",
[193] = "RPgBack",
[194] = "RPgFwd",
[331] = "Eraser",
[332] = "Highlighter",

and

event_map_adapter = {
SleepCover = function(ev)
if self.input:isEvKeyPress(ev) then
return "SleepCoverClosed"
elseif self.input:isEvKeyRelease(ev) then
return "SleepCoverOpened"
end
end,

The instructions that say you should look for "Self.event_map" are for the input.lua file. You are trying to find them in the device.lua file.

I don't have the original Kobo remote, but I think the instructions should work for any bluetooth device. Maybe the latest KOReader update that turns off bluetooth on launch is impacting. I've updated the instructions with the first step being not letting KOReader turn off bluetooth. Maybe try again with that. Also, be very sure you have identified the correct 'event#' for your remote when it is connected.

[banjax]

Originally Posted by OG-Booksmith

I've written a plugin that should make this easier for MTK based kobo ereaders, aka Libra Colour and Clara Colour.

Have a look here: https://ogkevin.github.io/kobo.koplu...bluetooth.html

Holy wow. You made my day. Worked on the first try and now this Stouchi "Designed for Kobo" ring that warns in the manual "don't use with koreader it might crash your device" works just fine. All except the home button anyway. Seems I can't remap that. Yet

Anyway, thank you!