Instructions: Bluetooth control for KOReader on newer Kobo devices

[pumpkinwhite]

Hi all - I'm pleased to share with this community instructions for setting up bluetooth controls on latest Kobo eReaders (definitely works on Libra Colour). This took me quite a while to get it working, and figured I should contribute here. I see many people on this forum struggling to get Bluetooth controls working on KOReader for newer Kobo devices. I hope these instructions help.

For convenience, I'm also attaching a PDF file with these instructions.

Setting up Bluetooth controls for KOReader on Kobo Devices

Notes:
• I only have the Kobo Libra Colour, so I cannot vouch for other devices. As far as I can tell, the steps are pretty generic, so I imagine the instructions should work on other Kobo devices as well.
• The Bluetooth device I’m using is 8BitDo Micro. The instructions for other devices should be similar, and you should be able to follow this guide while making minor changes as needed.
• These instructions assume you already have NickelMenu and KOReader installed. There are plenty of instructions for installing those, and I didn’t want to make the tutorial needlessly long.
• IMPORTANT NOTE: Currently there is a known bug in KOReader where exiting KOReader while Bluetooth is ON, reboots the device and often removes NickelMenu. You then have to transfer the KoboRoot.tgz file into the .kobo folder again to get NickelMenu back. This behavior can be avoided by choosing ‘Reboot the device’ in the exit menu, instead of ‘Exit’. So, while this issue exists, remember to reboot the device to exit KOReader while you have Bluetooth ON

For reference - https://github.com/koreader/koreader/issues/12739

• These instructions do not use any plug-in or different Bluetooth drivers. The default Kobo Bluetooth drivers work just fine.

Features enabled:
• This guide will enable the following features via Bluetooth -

o Go to next page / previous page
o Go to next chapter / previous chapter
o Increase Font size / Decrease Font size
o Increase brightness / Decrease brightness
o Increase warmth / Decrease warmth
o Go to next bookmark / previous bookmark
o Rotate screen
o Toggle Night mode
o Toggle Bookmark
o Toggle Status Bar

• I’ve not mapped every single of the above features to my controller, but this guide will show you how to map whichever features you want.

Step 1 – Set up your Bluetooth controller
• Skip this step if you are not using a controller that allows for custom mapping. Since I use the 8BitDo micro, I’ve included mapping for that device.
• I’ve set up mapping assuming controller usage in vertical orientation, but you may set it up any which way you like.
• 8BitDo micro will be used in keyboard mode. Go ahead and map random keyboard keys to all the buttons using the 8BitDo Ultimate Software. It does not matter which keyboard keys you map here. We will be noting down codes for all those keys later. For reference, this is how I’ve mapped my controller --> (See attached Picture 1)
• Note that I’ve mapped the ‘Keyboard right key’ to the Up D-Pad, and ‘Keyboard left key’ to the Down D-pad. This is on purpose since keyboard left and right arrow keys turn pages on the native Kobo reader without any additional setup. And since I hold the micro vertically, mapping it this way is more intuitive to me.

Step 2 – Pair your device
• Pair the controller using the Bluetooth settings page on the Kobo eReader.
• Side note on 8BitDo micro - Reconnecting the device to Kobo seems to be a bit finicky. I find it best to turn Bluetooth ON on the settings page, and then turning on the controller after a few seconds. The controller then usually connects on first go. Otherwise, it takes three or four tries to connect the controller. I do not use the Nickelmenu option to Turn Bluetooth ON, as that never automatically connects the controller (even though Bluetooth does turn ON, on the Kobo).

Step 3 – Confirm ‘event#’ for your controller and note event keys
• Make sure your controller is connected via Bluetooth. Open KOReader.
• Log into KOReader via SSH

o KOReader --> Gear icon --> Network --> SSH Server
o Tick ‘Login without password (DANGEROUS)’, and then tick ‘SSH server’. (Of course you can choose to set up SSH credentials, but we’ll directly log in for sake of convenience).
o Take note of the device’s internal IP address on the pop-up screen
o On your computer open Terminal if on Mac or Linux, Command Prompt if on Windows
o Enter

ssh -p 2222 root@(ip-address-you-noted above)

o You will be asked if you want to continue, and no password is required (just hit enter)
o Enter

ls /dev/input

o This will show inputs connected to your Kobo, something like –

By-path    event0    event1    event2   event3    event4

o Typically, the last one will be your Bluetooth device if you haven’t connected multiple Bluetooth devices to the Kobo. To check which one is your controller, you can try this step with and without your controller connected. When it’s not connected, that event# will not be there. In my case, ‘event4’ shows up when the 8BitDo controller is connected, and is missing when it’s not. This confirms the 8BitDo controller is ‘event4’.
o Type

evtest /dev/input/event4

(replace ‘event4’ with whichever one you think is your connected controller)
o The terminal window will show a long list of Event codes, and then wait on ‘Testing … (interrupt to exit)’

-- At this point, if you press any key on the controller, you will get an event response. This confirms that your controller is indeed 'event4' (or whichever event# one you are testing).
-- Press Ctrl+C to exit back to the terminal prompt

o Scroll up in the terminal window to see the long list of Event codes. Now make note of whichever keys you mapped on your Bluetooth controller. For example, the line ‘Event code 20 (T)’ means that keyboard key ‘T’ has event code 20.
o In our case, the keys we mapped on the 8BitDo micro have event codes as follows –

Event code 103 (Up) — mapped to Left D-Pad
Event code 105 (Left) — mapped to Down D-Pad
Event code 106 (Right) — mapped to Up D-Pad
Event code 108 (Down) — mapped to Right D-Pad
Event code 104 (PageUp) — mapped to minus
Event code 109 (PageDown) — mapped to plus
Event code 21 (Y) — mapped to Y 
Event code 45 (X) — mapped to X
Event code 48 (B) — mapped to B
Event code 30 (A) — mapped to A
Event code 38 (L) — mapped to Left Trigger L
Event code 22 (U) — mapped to L2
Event code 32 (D) — mapped to R2
Event code 19 (R) — mapped to Right Trigger R
Event code 24 (O) — mapped to Star button

o Turn off the SSH server
o Exit KOReader (remember to use Reboot due to the KOReader bug I mentioned earlier)

Step 4 – Update input.lua file
• Connect your ereader to you computer via USB
• Navigate to KOBOeReader/.adds/koreader/frontend/device
• Take a backup of the input.lua file, so you can place the original back and start over if anything goes wrong.
• Open input.lua
• 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”)
• Add the following lines to this section –

self.event_map[20000] = "GotoNextChapterviaBT"
self.event_map[20001] = "GotoPrevChapterviaBT"
self.event_map[20002] = "DecreaseFontSizeviaBT"
self.event_map[20003] = "IncreaseFontSizeviaBT"
self.event_map[20004] = "ToggleBookmarkviaBT"
self.event_map[20005] = "IterateRotationviaBT"
self.event_map[20007] = "RightviaBT"
self.event_map[20008] = "LeftviaBT"
self.event_map[20009] = "IncreaseBrightnessviaBT"
self.event_map[20010] = "DecreaseBrightnessviaBT"
self.event_map[20011] = "IncreaseWarmthviaBT"
self.event_map[20012] = "DecreaseWarmthviaBT"
self.event_map[20013] = "NextBookmarkviaBT"
self.event_map[20014] = "PrevBookmarkviaBT"
self.event_map[20015] = "LastBookmarkviaBT"
self.event_map[20016] = "ToggleNightModeviaBT"
self.event_map[20017] = "ToggleStatusBarviaBT"

• The numbers in the brackets above are just random numbers I picked. They don’t have any significance here.
• Screenshot for reference --> see attachment Picture 2
• Scroll down further till you reach a function called Input:handleKeyBoardEv(ev). The following lines need to be within this function. I placed them just before a section with the header -- toggle fullscreen on F11.

if self:isEvKeyPress(ev) and keycode == "GotoNextChapterviaBT" then
UIManager:sendEvent(Event:new("GotoNextChapter"))
end

if self:isEvKeyPress(ev) and keycode == "GotoPrevChapterviaBT" then
UIManager:sendEvent(Event:new("GotoPrevChapter"))
end

if self:isEvKeyPress(ev) and keycode == "DecreaseFontSizeviaBT" then
UIManager:sendEvent(Event:new("DecreaseFontSize", 1))
end

if self:isEvKeyPress(ev) and keycode == "IncreaseFontSizeviaBT" then
UIManager:sendEvent(Event:new("IncreaseFontSize", 1))
end

if self:isEvKeyPress(ev) and keycode == "ToggleBookmarkviaBT" then
UIManager:sendEvent(Event:new("ToggleBookmark"))
end

if self:isEvKeyPress(ev) and keycode == "IterateRotationviaBT" then
UIManager:sendEvent(Event:new("IterateRotation"))
end

if self:isEvKeyPress(ev) and keycode == "RightviaBT" then
UIManager:sendEvent(Event:new("GotoViewRel", 1))
end
if self:isEvKeyPress(ev) and keycode == "LeftviaBT" then
UIManager:sendEvent(Event:new("GotoViewRel", -1))
end

if self:isEvKeyPress(ev) and keycode == "IncreaseBrightnessviaBT" then
UIManager:sendEvent(Event:new("IncreaseFlIntensity", 5))
end

if self:isEvKeyPress(ev) and keycode == "DecreaseBrightnessviaBT" then
UIManager:sendEvent(Event:new("DecreaseFlIntensity", 5))
end

if self:isEvKeyPress(ev) and keycode == "IncreaseWarmthviaBT" then
UIManager:sendEvent(Event:new("IncreaseFlWarmth", 1))
end

if self:isEvKeyPress(ev) and keycode == "DecreaseWarmthviaBT" then
UIManager:sendEvent(Event:new("IncreaseFlWarmth", -1))
end

if self:isEvKeyPress(ev) and keycode == "NextBookmarkviaBT" then
UIManager:sendEvent(Event:new("GotoNextBookmarkFromPage"))
end

if self:isEvKeyPress(ev) and keycode == "PrevBookmarkviaBT" then
UIManager:sendEvent(Event:new("GotoPreviousBookmarkFromPage"))
end

if self:isEvKeyPress(ev) and keycode == "LastBookmarkviaBT" then
UIManager:sendEvent(Event:new("GoToLatestBookmark"))
end

if self:isEvKeyPress(ev) and keycode == "ToggleNightModeviaBT" then
UIManager:sendEvent(Event:new("ToggleNightMode"))
end

if self:isEvKeyPress(ev) and keycode == "ToggleStatusBarviaBT" then
UIManager:sendEvent(Event:new("ToggleFooterMode"))
end

• Screenshot for reference --> see attachment Picture 3
• Save and close the file

Step 5 – Update device.lua file
• Navigate to KOBOeReader/.adds/koreader/frontend/device/kobo
• Take a backup of the device.lua file, so you can place the original back and start over if anything goes wrong.
• Navigate to the section that has event maps (Starts with event_map = {)
• Here you will add lines for the features that you want, and map them against the buttons you’ve picked. So, for example, assume we want to map 'increase font size' to the L2 button. On the 8BitDo app we mapped L2 button on the controller to keyboard key ‘U’. And we noted in our event map codes that keyboard key U had event code 22. And so here we will add the event “IncreaseFontSizeviaBT” against code [22]. See format below.
• I’m including below, lines I added for my setup. But you can change these to whichever keys and features you prefer. The “RightviaBT”/“LeftviaBT” are functionally same as “RPgFwd”/ “RPgBack” on Libra eReaders. RPgFwd/RPgBack events are triggered by the physical buttons on that eReader. You can use either set if you using the Libra Colour.

[105] = "LeftviaBT", -- You can also use "RPgBack" on Libra Colour 
[106] = "RightviaBT", -- You can also use "RPgFwd" on Libra Colour
[103] = "GotoNextChapterviaBT", -- D-pad left (Up when held vertically)
[108] = "GotoPrevChapterviaBT", -- D-pad right (Down when held vertically)
[21] = "IncreaseBrightnessviaBT", -- Y-button
[30] = "DecreaseBrightnessviaBT", -- A-button
[45] = "IncreaseWarmthviaBT", -- X-button
[48] = "DecreaseWarmthviaBT", -- B-button
[22] = "IncreaseFontSizeviaBT", -- L2 button
[32] = "DecreaseFontSizeviaBT", -- R2 button
[104] = "IterateRotationviaBT", -- Minus button
[109] = "ToggleNightModeviaBT", -- Plus button
[38] = "RightviaBT", -- Left Trigger L
[19] = "LeftviaBT", -- Right Trigger R

• Screenshot for reference --> see attachment Picture 4
• Scroll down a bit further and place the following lines after self.input: open(“fake_events”). The exact placement shouldn’t matter as long as it’s as long as it’s within the function Kobo:init(), and placed between logic blocks in that function –

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

• Needless to say, if your event# was different you will put that event# here instead.
• Screenshot for reference --> see attachment Picture 5
• Save and close the file

Step 6 – Wrap up
• You are now done. Eject the Kobo ereader from your computer.
• Reboot just to be safe.
• Since this method does not rely on any plug-ins, you will need to connect the controller before opening KOReader. And again, till the KOReader bug mentioned earlier is fixed, remember to reboot the device to exit KOReader.
• The final key mapping used in these instructions is shown in the Picture 6 attachment.

Additional Notes:
• If you don’t care about advanced features, and only care about basic page turn buttons, you can skip the entirety of Step 4. On Step 5, you only need to enter the two lines for mapping “RPgFwd” and “RPgBack” and the “local success1…” lines.
• The Next Chapter/Previous Chapter functionality doesn’t work perfectly if you change the font-size after opening the book. I imagine this is a bug in KOReader, where chapter locations are not updated dynamically after changing the font size. If you close the book and open it again after changing font size, the chapter skips work perfectly again.

Hope this helps! Best of luck!

[WaveEquation]

Mate, I can't thank you enough for figuring BT out. I just tried this with my Kobo Clara BW and can confirm that it works. I too use 8BitDo micro, so maybe it made my job a bit easier.

Also, only Right/Left-viaBT commands worked for me for navigation. Ever since I got Kobo last year, I've been having difficulty setting up BT in KOReader. Not anymore! Thanks again for a clear and detailed write up.

[pumpkinwhite]

Originally Posted by WaveEquation

Mate, I can't thank you enough for figuring BT out. I just tried this with my Kobo Clara BW and can confirm that it works. I too use 8BitDo micro, so maybe it made my job a bit easier.

Also, only Right/Left-viaBT commands worked for me for navigation. Ever since I got Kobo last year, I've been having difficulty setting up BT in KOReader. Not anymore! Thanks again for a clear and detailed write up.

Glad it worked for you. I had a feeling the RPgFwd/RPgBack commands won’t work for other devices since those are mapped to hardware buttons on the Libra Colour.

One problem I’ve been having is that the battery life for the reader takes a huge hit with Bluetooth and koreader running. So much so that I’m wondering whether my new reader has a battery issue.

[WaveEquation]

Originally Posted by pumpkinwhite

One problem I’ve been having is that the battery life for the reader takes a huge hit with Bluetooth and koreader running. So much so that I’m wondering whether my new reader has a battery issue.

In the coming days I'll get some idea about how severe the battery drain is.

Something I forgot to ask, what exactly is the purpose of Nickel menu here? My KOreader rebooted and removed the Nickel but BT just works fine. Am I missing any benefit by not having NM?

[sooeee]

Thank you so much for posting these detailed instructions!

Originally Posted by pumpkinwhite

Step 3 – Confirm ‘event#’ for your controller and note event keys
• Make sure your controller is connected via Bluetooth. Open KOReader.
• Log into KOReader via SSH

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?

[pumpkinwhite]

Originally Posted by WaveEquation

In the coming days I'll get some idea about how severe the battery drain is.

Something I forgot to ask, what exactly is the purpose of Nickel menu here? My KOreader rebooted and removed the Nickel but BT just works fine. Am I missing any benefit by not having NM?

Regarding the battery drain - I did some basic testing on my end. I think you have to make sure the wifi and bluetooth are off before putting the reader to sleep. After I started doing that, the battery drain was only about 2% a day, which is not bad. Reading around in forums, it seems bluetooth being ON continuously is a big battery drain, with multiple posts reporting 2 to 3% drain per hour, even when the reader is on sleep. Seemingly the implementation is a bit buggy and often bluetooth remains ON in the background, even when the reader is on sleep and drains the battery continuously. So best to make sure it's actually off in Settings before putting the reader to sleep. Not sure how much drain wifi being ON causes, but no harm in keeping that off as well.

Regarding your query about Nickelmenu - It's a convenience menu that gives some options on the main screen itself -- like Reboot, Shutdown, Sleep, Dark Mode etc. You can set up options to force connect the USB (so you don't have to unplug and plug the cable to the computer again if you are charging using a computer and then want to transfer stuff). There are some options to some games like solitaire, sudoku, word scramble etc.

Nickelmenu is indeed nice to have, but it's not essential by any means. You are not missing anything if just need KOReader. Getting it back is easy -- just transfer the TGZ file into .kobo folder again. You can play around with it to see if you like any options. But don't sweat it too much if you find getting it back to be a chore. You are not missing out on anything major. End of the day, the core utility of the eReader is to read books. We spend hours reading a book, and barely a few a few seconds on the device's main menu to just open the book.

[pumpkinwhite]

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?

That does seem strange. I have no clue what might be causing it. Do you have any KOReader plugin installed by any chance? Maybe something is causing some interference. If all else fails, no harm deleting KOReader and starting afresh. Before I posted this tutorial, and wiped my Kobo clean, restored to factory settings just to make sure the instructions work as is. I'm not saying you need to restore everything to factory settings, but deleting KOReader and starting with a fresh KOReader install might not be a bad idea.

[Lonenso]

Hi, thanks for your detailed instructions very much. I finally can use my device.

however, after using a few minutes, koreader is not responding to my keypress. I don't know if you have the same issue.

and I checked, `evtest /dev/input/event3` still respond to my keypress.

another question: do i need to worry about reconnecting after kobo sleeps? (enable bluetooth natively again and relaunch koreader)

[Lonenso]

Originally Posted by Lonenso

Hi, thanks for your detailed instructions very much. I finally can use my device.

however, after using a few minutes, koreader is not responding to my keypress. I don't know if you have the same issue.

and I checked, `evtest /dev/input/event3` still respond to my keypress.

another question: do i need to worry about reconnecting after kobo sleeps? (enable bluetooth natively again and relaunch koreader)

btw, a workaround is to `restart koreader`

[lGrahaml]

Thanks for the tutorial, it worked perfectly! Just wondering, do you have to go into nickel to connect to your page turner everytime a disconnection occurs or is there another way?

[duylinh241]

I followed the instructions, but when I press 'test,' it only shows the scancode format, not EVKEY:
Event: time 1762417947.302802, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1762417947.302802 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.392968, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1762417947.392968 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.910197, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1762417947.910197 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.961686, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1762417947.961686 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------

[duylinh241]

Originally Posted by pumpkinwhite

Hi all - I'm pleased to share with this community instructions for setting up bluetooth controls on latest Kobo eReaders (definitely works on Libra Colour). This took me quite a while to get it working, and figured I should contribute here. I see many people on this forum struggling to get Bluetooth controls working on KOReader for newer Kobo devices. I hope these instructions help.

For convenience, I'm also attaching a PDF file with these instructions.

Setting up Bluetooth controls for KOReader on Kobo Devices

Notes:
• I only have the Kobo Libra Colour, so I cannot vouch for other devices. As far as I can tell, the steps are pretty generic, so I imagine the instructions should work on other Kobo devices as well.
• The Bluetooth device I’m using is 8BitDo Micro. The instructions for other devices should be similar, and you should be able to follow this guide while making minor changes as needed.
• These instructions assume you already have NickelMenu and KOReader installed. There are plenty of instructions for installing those, and I didn’t want to make the tutorial needlessly long.
• IMPORTANT NOTE: Currently there is a known bug in KOReader where exiting KOReader while Bluetooth is ON, reboots the device and often removes NickelMenu. You then have to transfer the KoboRoot.tgz file into the .kobo folder again to get NickelMenu back. This behavior can be avoided by choosing ‘Reboot the device’ in the exit menu, instead of ‘Exit’. So, while this issue exists, remember to reboot the device to exit KOReader while you have Bluetooth ON

For reference - https://github.com/koreader/koreader/issues/12739

• These instructions do not use any plug-in or different Bluetooth drivers. The default Kobo Bluetooth drivers work just fine.

Features enabled:
• This guide will enable the following features via Bluetooth -

o Go to next page / previous page
o Go to next chapter / previous chapter
o Increase Font size / Decrease Font size
o Increase brightness / Decrease brightness
o Increase warmth / Decrease warmth
o Go to next bookmark / previous bookmark
o Rotate screen
o Toggle Night mode
o Toggle Bookmark
o Toggle Status Bar

• I’ve not mapped every single of the above features to my controller, but this guide will show you how to map whichever features you want.

Step 1 – Set up your Bluetooth controller
• Skip this step if you are not using a controller that allows for custom mapping. Since I use the 8BitDo micro, I’ve included mapping for that device.
• I’ve set up mapping assuming controller usage in vertical orientation, but you may set it up any which way you like.
• 8BitDo micro will be used in keyboard mode. Go ahead and map random keyboard keys to all the buttons using the 8BitDo Ultimate Software. It does not matter which keyboard keys you map here. We will be noting down codes for all those keys later. For reference, this is how I’ve mapped my controller --> (See attached Picture 1)
• Note that I’ve mapped the ‘Keyboard right key’ to the Up D-Pad, and ‘Keyboard left key’ to the Down D-pad. This is on purpose since keyboard left and right arrow keys turn pages on the native Kobo reader without any additional setup. And since I hold the micro vertically, mapping it this way is more intuitive to me.

Step 2 – Pair your device
• Pair the controller using the Bluetooth settings page on the Kobo eReader.
• Side note on 8BitDo micro - Reconnecting the device to Kobo seems to be a bit finicky. I find it best to turn Bluetooth ON on the settings page, and then turning on the controller after a few seconds. The controller then usually connects on first go. Otherwise, it takes three or four tries to connect the controller. I do not use the Nickelmenu option to Turn Bluetooth ON, as that never automatically connects the controller (even though Bluetooth does turn ON, on the Kobo).

Step 3 – Confirm ‘event#’ for your controller and note event keys
• Make sure your controller is connected via Bluetooth. Open KOReader.
• Log into KOReader via SSH

o KOReader --> Gear icon --> Network --> SSH Server
o Tick ‘Login without password (DANGEROUS)’, and then tick ‘SSH server’. (Of course you can choose to set up SSH credentials, but we’ll directly log in for sake of convenience).
o Take note of the device’s internal IP address on the pop-up screen
o On your computer open Terminal if on Mac or Linux, Command Prompt if on Windows
o Enter

ssh -p 2222 root@(ip-address-you-noted above)

o You will be asked if you want to continue, and no password is required (just hit enter)
o Enter

ls /dev/input

o This will show inputs connected to your Kobo, something like –

By-path    event0    event1    event2   event3    event4

o Typically, the last one will be your Bluetooth device if you haven’t connected multiple Bluetooth devices to the Kobo. To check which one is your controller, you can try this step with and without your controller connected. When it’s not connected, that event# will not be there. In my case, ‘event4’ shows up when the 8BitDo controller is connected, and is missing when it’s not. This confirms the 8BitDo controller is ‘event4’.
o Type

evtest /dev/input/event4

(replace ‘event4’ with whichever one you think is your connected controller)
o The terminal window will show a long list of Event codes, and then wait on ‘Testing … (interrupt to exit)’

-- At this point, if you press any key on the controller, you will get an event response. This confirms that your controller is indeed 'event4' (or whichever event# one you are testing).
-- Press Ctrl+C to exit back to the terminal prompt

o Scroll up in the terminal window to see the long list of Event codes. Now make note of whichever keys you mapped on your Bluetooth controller. For example, the line ‘Event code 20 (T)’ means that keyboard key ‘T’ has event code 20.
o In our case, the keys we mapped on the 8BitDo micro have event codes as follows –

Event code 103 (Up) — mapped to Left D-Pad
Event code 105 (Left) — mapped to Down D-Pad
Event code 106 (Right) — mapped to Up D-Pad
Event code 108 (Down) — mapped to Right D-Pad
Event code 104 (PageUp) — mapped to minus
Event code 109 (PageDown) — mapped to plus
Event code 21 (Y) — mapped to Y 
Event code 45 (X) — mapped to X
Event code 48 (B) — mapped to B
Event code 30 (A) — mapped to A
Event code 38 (L) — mapped to Left Trigger L
Event code 22 (U) — mapped to L2
Event code 32 (D) — mapped to R2
Event code 19 (R) — mapped to Right Trigger R
Event code 24 (O) — mapped to Star button

o Turn off the SSH server
o Exit KOReader (remember to use Reboot due to the KOReader bug I mentioned earlier)

Step 4 – Update input.lua file
• Connect your ereader to you computer via USB
• Navigate to KOBOeReader/.adds/koreader/frontend/device
• Take a backup of the input.lua file, so you can place the original back and start over if anything goes wrong.
• Open input.lua
• 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”)
• Add the following lines to this section –

self.event_map[20000] = "GotoNextChapterviaBT"
self.event_map[20001] = "GotoPrevChapterviaBT"
self.event_map[20002] = "DecreaseFontSizeviaBT"
self.event_map[20003] = "IncreaseFontSizeviaBT"
self.event_map[20004] = "ToggleBookmarkviaBT"
self.event_map[20005] = "IterateRotationviaBT"
self.event_map[20007] = "RightviaBT"
self.event_map[20008] = "LeftviaBT"
self.event_map[20009] = "IncreaseBrightnessviaBT"
self.event_map[20010] = "DecreaseBrightnessviaBT"
self.event_map[20011] = "IncreaseWarmthviaBT"
self.event_map[20012] = "DecreaseWarmthviaBT"
self.event_map[20013] = "NextBookmarkviaBT"
self.event_map[20014] = "PrevBookmarkviaBT"
self.event_map[20015] = "LastBookmarkviaBT"
self.event_map[20016] = "ToggleNightModeviaBT"
self.event_map[20017] = "ToggleStatusBarviaBT"

• The numbers in the brackets above are just random numbers I picked. They don’t have any significance here.
• Screenshot for reference --> see attachment Picture 2
• Scroll down further till you reach a function called Input:handleKeyBoardEv(ev). The following lines need to be within this function. I placed them just before a section with the header -- toggle fullscreen on F11.

if self:isEvKeyPress(ev) and keycode == "GotoNextChapterviaBT" then
UIManager:sendEvent(Event:new("GotoNextChapter"))
end

if self:isEvKeyPress(ev) and keycode == "GotoPrevChapterviaBT" then
UIManager:sendEvent(Event:new("GotoPrevChapter"))
end

if self:isEvKeyPress(ev) and keycode == "DecreaseFontSizeviaBT" then
UIManager:sendEvent(Event:new("DecreaseFontSize", 1))
end

if self:isEvKeyPress(ev) and keycode == "IncreaseFontSizeviaBT" then
UIManager:sendEvent(Event:new("IncreaseFontSize", 1))
end

if self:isEvKeyPress(ev) and keycode == "ToggleBookmarkviaBT" then
UIManager:sendEvent(Event:new("ToggleBookmark"))
end

if self:isEvKeyPress(ev) and keycode == "IterateRotationviaBT" then
UIManager:sendEvent(Event:new("IterateRotation"))
end

if self:isEvKeyPress(ev) and keycode == "RightviaBT" then
UIManager:sendEvent(Event:new("GotoViewRel", 1))
end
if self:isEvKeyPress(ev) and keycode == "LeftviaBT" then
UIManager:sendEvent(Event:new("GotoViewRel", -1))
end

if self:isEvKeyPress(ev) and keycode == "IncreaseBrightnessviaBT" then
UIManager:sendEvent(Event:new("IncreaseFlIntensity", 5))
end

if self:isEvKeyPress(ev) and keycode == "DecreaseBrightnessviaBT" then
UIManager:sendEvent(Event:new("DecreaseFlIntensity", 5))
end

if self:isEvKeyPress(ev) and keycode == "IncreaseWarmthviaBT" then
UIManager:sendEvent(Event:new("IncreaseFlWarmth", 1))
end

if self:isEvKeyPress(ev) and keycode == "DecreaseWarmthviaBT" then
UIManager:sendEvent(Event:new("IncreaseFlWarmth", -1))
end

if self:isEvKeyPress(ev) and keycode == "NextBookmarkviaBT" then
UIManager:sendEvent(Event:new("GotoNextBookmarkFromPage"))
end

if self:isEvKeyPress(ev) and keycode == "PrevBookmarkviaBT" then
UIManager:sendEvent(Event:new("GotoPreviousBookmarkFromPage"))
end

if self:isEvKeyPress(ev) and keycode == "LastBookmarkviaBT" then
UIManager:sendEvent(Event:new("GoToLatestBookmark"))
end

if self:isEvKeyPress(ev) and keycode == "ToggleNightModeviaBT" then
UIManager:sendEvent(Event:new("ToggleNightMode"))
end

if self:isEvKeyPress(ev) and keycode == "ToggleStatusBarviaBT" then
UIManager:sendEvent(Event:new("ToggleFooterMode"))
end

• Screenshot for reference --> see attachment Picture 3
• Save and close the file

Step 5 – Update device.lua file
• Navigate to KOBOeReader/.adds/koreader/frontend/device/kobo
• Take a backup of the device.lua file, so you can place the original back and start over if anything goes wrong.
• Navigate to the section that has event maps (Starts with event_map = {)
• Here you will add lines for the features that you want, and map them against the buttons you’ve picked. So, for example, assume we want to map 'increase font size' to the L2 button. On the 8BitDo app we mapped L2 button on the controller to keyboard key ‘U’. And we noted in our event map codes that keyboard key U had event code 22. And so here we will add the event “IncreaseFontSizeviaBT” against code [22]. See format below.
• I’m including below, lines I added for my setup. But you can change these to whichever keys and features you prefer. The “RightviaBT”/“LeftviaBT” are functionally same as “RPgFwd”/ “RPgBack” on Libra eReaders. RPgFwd/RPgBack events are triggered by the physical buttons on that eReader. You can use either set if you using the Libra Colour.

[105] = "LeftviaBT", -- You can also use "RPgBack" on Libra Colour 
[106] = "RightviaBT", -- You can also use "RPgFwd" on Libra Colour
[103] = "GotoNextChapterviaBT", -- D-pad left (Up when held vertically)
[108] = "GotoPrevChapterviaBT", -- D-pad right (Down when held vertically)
[21] = "IncreaseBrightnessviaBT", -- Y-button
[30] = "DecreaseBrightnessviaBT", -- A-button
[45] = "IncreaseWarmthviaBT", -- X-button
[48] = "DecreaseWarmthviaBT", -- B-button
[22] = "IncreaseFontSizeviaBT", -- L2 button
[32] = "DecreaseFontSizeviaBT", -- R2 button
[104] = "IterateRotationviaBT", -- Minus button
[109] = "ToggleNightModeviaBT", -- Plus button
[38] = "RightviaBT", -- Left Trigger L
[19] = "LeftviaBT", -- Right Trigger R

• Screenshot for reference --> see attachment Picture 4
• Scroll down a bit further and place the following lines after self.input: open(“fake_events”). The exact placement shouldn’t matter as long as it’s as long as it’s within the function Kobo:init(), and placed between logic blocks in that function –

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

• Needless to say, if your event# was different you will put that event# here instead.
• Screenshot for reference --> see attachment Picture 5
• Save and close the file

Step 6 – Wrap up
• You are now done. Eject the Kobo ereader from your computer.
• Reboot just to be safe.
• Since this method does not rely on any plug-ins, you will need to connect the controller before opening KOReader. And again, till the KOReader bug mentioned earlier is fixed, remember to reboot the device to exit KOReader.
• The final key mapping used in these instructions is shown in the Picture 6 attachment.

Additional Notes:
• If you don’t care about advanced features, and only care about basic page turn buttons, you can skip the entirety of Step 4. On Step 5, you only need to enter the two lines for mapping “RPgFwd” and “RPgBack” and the “local success1…” lines.
• The Next Chapter/Previous Chapter functionality doesn’t work perfectly if you change the font-size after opening the book. I imagine this is a bug in KOReader, where chapter locations are not updated dynamically after changing the font size. If you close the book and open it again after changing font size, the chapter skips work perfectly again.

Hope this helps! Best of luck!

I followed the instructions, but when I press 'test,' it only shows the scancode format, not EVKEY:
Event: time 1762417947.302802, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1762417947.302802 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.392968, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1762417947.392968 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.910197, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1762417947.910197 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.961686, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1762417947.961686 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------

[pumpkinwhite]

Scroll all the way up in the terminal window. The keys are not shown on every press. They are shown in the beginning. But it’s a long wall of text so you miss it. The key press response is just to check that the presses are being recognized. The codes themselves are listed earlier. Like I said scroll back up .

Best of luck!

[pumpkinwhite]

Originally Posted by duylinh241

I followed the instructions, but when I press 'test,' it only shows the scancode format, not EVKEY:
Event: time 1762417947.302802, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1762417947.302802 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.392968, type 4 (Misc), code 4 (ScanCode), value 70052
Event: time 1762417947.392968 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.910197, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1762417947.910197 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1762417947.961686, type 4 (Misc), code 4 (ScanCode), value 70051
Event: time 1762417947.961686 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------

Scroll all the way up in the terminal window. The keys are not shown on every press. They are shown in the beginning. But it’s a long wall of text so you miss it. The key press response is just to check that the presses are being recognized. The codes themselves are listed earlier. Like I said, scroll back up .

Best of luck!