Bluetooth Page Turner plugin for Kobo KOReader

[lumping-sugar66]

Hello everyone,

I’m pleased to share an exciting update about my KOReader plugin for kobo devices, which now includes proper scripts for turning Bluetooth on and off, along with the necessary modifications and connections to run my selfie clicker as a page turning device. This should be adaptable to various devices and can serve as a useful example for other developers. While I plan to add more functionality in the future and polish it, make it more error prune etc., I wanted to share now and invite the community to collaborate.

Key Features and Insights

Bluetooth On and Off:
This plugin allows you to turn Bluetooth on and off on the fly and connect to your device directly from KOReader. Here’s how it works:

Turning Bluetooth On: Normally bluetooth processes are killed with KOReader on bootup. The plugin enables Bluetooth directly from KOReader and establishes connection to pre-paired bluetooth devices.
Turning Bluetooth Off: Properly shutting down Bluetooth is crucial to prevent excessive battery drain. On a Clara 2E, I observed a battery drain of about 2.8-3% per hour during sleep if Bluetooth isn’t turned off correctly. The plugin ensures Bluetooth is turned off properly. Without a proper shutdown (like pkill only) the drain would still be around 1.5% per hour during sleep. With this plugin, I can turn Bluetooth on and off and leave the device to sleep with 0% drain.

Nickel doesn’t shut down Bluetooth correctly, so relying on Nickel to turn Bluetooth off after exiting KOReader can still result in significant battery drain. It’s better to turn off Bluetooth using this.


New Actions:

Refresh Device Input
Description: This new command allows the device to start listening to input from connected devices again if the connection was lost and then automatically re-established. This is useful in situations where the Kobo device loses connection but reconnects automatically, and input events aren't being recognized.

Connect to Device
Description: Sometimes Kobo devices do not automatically initiate the connection to an available Bluetooth device (e.g., 8bitdo micro). This command sends a connection request from the Kobo to the Bluetooth device. It requires the connect.sh script to be configured with your device’s MAC address, which can be obtained using the bluetoothctl info command.

New Passive Features:

With the current version of the code, there should be no reason to restart KOReader.

Gesture Integration
All commands can now be triggered using taps and gestures. This enhances the user experience by allowing easy access to commands through customizable gestures. Recommendation: Bind the reconnect and relisten events to swipe gestures or similar actions for quick access.

Automatic Listening
Once a device establishes a connection, it will now be automatically listened to without the need to reboot the device. This eliminates the previous requirement of restarting KOReader after enabling Bluetooth.

Dedicated Bluetooth Events:
The following new Bluetooth events have been implemented, allowing for additional functionality within KOReader:

- BTGotoNextChapter: Navigate to the next chapter.
- BTGotoPrevChapter: Navigate to the previous chapter.
- BTDecreaseFontSize: Reduce the font size by 1.
- BTIncreaseFontSize: Increase the font size by 1.
- BTToggleBookmark: Toggle bookmarks on and off.
- BTIterateRotation: Rotate the screen orientation 90 degrees.
- BTBluetoothOff: Turn off Bluetooth.
- BTRight: Go to the next page.
- BTLeft: Go to the previous page.

BTRight and BTLeft is recommended for page turning instead of the default actions as these custom events will work with all screen orientations.

Installation and Usage Instructions

How to Install:

The installation isn't quite hands-free right now. You still need to pair your device once using nickel, and find which /dev/input/eventX it gets mapped to. The initial pairing can also be done using SSH/bluetoothctl.
You also need to add the event code to device.lua listened devices with the action you're expecting. Readme has some examples and more detail on this. My recommendation is to use the dedicated custom events as most events mentioned before this update don't take orientation into account.

Configuring connect.sh:
To use the Connect to Device function, you need to modify the connect.sh script and add your device's MAC address. You can retrieve the MAC address using bluetoothctl info. Once configured, the script will be able to send connection requests from the Kobo device to your Bluetooth device.


Device Specific Modifications:
Clara 2E

By default, all instructions are given for Clara 2E. No further modifications are needed apart from which are documented in this description.

Libra 2

enji provided instructions to adapt this plugin to Libra 2 by using`rtk_hciattach` instead of `hciattach`. (Thanks enji!). There's also previous cases of seeing event4 being used instead of event3. In this case, please replace all instances of event3 to event4 in the scripts.

Replace hciattach with rtk_hciattach instructions
In bluetooth.koplugin/on.sh Change `hciattach -p ttymxc1 any 1500000 flow -t 20` to `/sbin/rtk_hciattach -s 115200 ttymxc1 rtk_h5`.
In bluetooth.koplugin/off.sh, changed `pkill hciattach` to `pkill rtk_hciattach`

How it Works:

This plugin adds a menu under Gear > Network > Bluetooth, which includes:

Bluetooth On: Turns on WiFi (required for Bluetooth) and Bluetooth, then attempts to establish a connection to a previously paired input device. The plugin also includes the uhid.ko kernel patch, which is necessary for certain Bluetooth devices to be recognized.
Bluetooth Off: Properly shuts down Bluetooth to prevent battery drain.

EDIT:After "Bluetooth On", you no longer need to do [Exit > Restart KOReader] now to get the device events registered. There are three options:

1. Your device do not initiate connection at all: Trigger "Connect to Device" (see connect.sh modifications). Wait for the popup to appear. Then trigger "Refresh Device Input". Now you should be properly configured.
2. Your device initiates connection automatically but buttons don't take action: The plugin is modified to start listening at most after 4 seconds of initial connection. In most cases, if your device is connected (usually bluetooth devices indicate their connection status with LEDs), your buttons will start working after 4 seconds.
3. Your device initiates connection automatically but buttons don't take action even after 4 seconds: For some reason if your device is still not behaving, try again "Refresh Device Input". Ensure your device is a keyboard device. You should see under crash.logs if your device is connected properly on the top.

Further Information
For more details or to contribute, please visit the GitHub repository:

---

Tested Devices

Supported

• Clara 2E
• Libra 2 (Requires modifications, see above)

Not Supported
----

https://github.com/onatbas/bluetooth.koplugin
Let me know what you think and I look forward to your feedback and contributions.

[trence]

Originally Posted by lumping-sugar66

Hello everyone,

I’m pleased to share an exciting update about my KOReader plugin for kobo devices, which now includes proper scripts for turning Bluetooth on and off, along with the necessary modifications and connections to run my selfie clicker as a page turning device. This should be adaptable to various devices and can serve as a useful example for other developers. While I plan to add more functionality in the future and polish it, make it more error prune etc., I wanted to share now and invite the community to collaborate.

Key Features and Insights

Bluetooth On and Off:
This plugin allows you to turn Bluetooth on and off on the fly and connect to your device directly from KOReader. Here’s how it works:

Turning Bluetooth On: Normally bluetooth processes are killed with KOReader on bootup. The plugin enables Bluetooth directly from KOReader and establishes connection to pre-paired bluetooth devices.
Turning Bluetooth Off: Properly shutting down Bluetooth is crucial to prevent excessive battery drain. On a Clara 2E, I observed a battery drain of about 2.8-3% per hour during sleep if Bluetooth isn’t turned off correctly. The plugin ensures Bluetooth is turned off properly. Without a proper shutdown (like pkill only) the drain would still be around 1.5% per hour during sleep. With this plugin, I can turn Bluetooth on and off and leave the device to sleep with 0% drain.

Nickel doesn’t shut down Bluetooth correctly, so relying on Nickel to turn Bluetooth off after exiting KOReader can still result in significant battery drain. It’s better to turn off Bluetooth using this.

Installation and Usage Instructions

How to Install:

The installation isn't quite hands-free right now. You still need to pair your device once using nickel, and find which /dev/input/eventX it gets mapped to. The initial pairing can also be done using SSH/bluetoothctl.
You also need to add the event code to device.lua listened devices with the action you're expecting. Readme has some examples and more detail on this.

How it Works:

This plugin adds a menu under Gear > Network > Bluetooth, which includes:

Bluetooth On: Turns on WiFi (required for Bluetooth) and Bluetooth, then attempts to establish a connection to a previously paired input device. The plugin also includes the uhid.ko kernel patch, which is necessary for certain Bluetooth devices to be recognized.
Bluetooth Off: Properly shuts down Bluetooth to prevent battery drain.

EDIT:After "Bluetooth On", you need to do [Exit > Restart KOReader] for now to get the device events registered. I'm planning on fixing this in the near future, but for now the complete operation for page turners is to enable bluetooth, and restart KOreader. No need to go to nickel again, just a KOReader restart is fine.

Further Information
For more details or to contribute, please visit the GitHub repository:

https://github.com/onatbas/bluetooth.koplugin
Let me know what you think and I look forward to your feedback and contributions.

I'm a Kobo developer newbie, so please forgive me for my ignorance on the topic. For step 3 of the guide on your Github it says to be sure the device is mapped to event3, how would I go about doing that on a Kobo? I believe I understand how to go about the rest. Thank you!

[lumping-sugar66]

Originally Posted by trence

I'm a Kobo developer newbie, so please forgive me for my ignorance on the topic. For step 3 of the guide on your Github it says to be sure the device is mapped to event3, how would I go about doing that on a Kobo? I believe I understand how to go about the rest. Thank you!

Check the devices currently available in your system first:

ls /dev/input/

And connect your bluetooth device and do it again, and see the difference.

ls /dev/input/

If you get a /dev/input/event3 that wasn't there before, that's your device. After the device is there, you can do

evtest /dev/input/event3

and press on the bluetooth page turner buttons, see if your event stream detects these events.

If your event list doesn't change after you pair/connect your device, uhid.ko may be required and not have applied. You can cd into the bluetooth.koplugin folder and do

insmod ./uhid/uhid.ko

and retry the connection with the bluetooth clicker again. If you still don't see the event, it's likely that your device is trying to identify itself as a weird device and may not be compatible.

If your event is mapped to a different location, modify main.lua to match yours.

Be sure to check device.lua.patch for what's being done. the

hasKeys = yes

addition needs to go into your devices' configuration. For me that's Clara 2E but yours could be different. device.lua is full of all devices and specific configurations for each.

I also realized a slight mistake in my code. The line at https://github.com/onatbas/bluetooth...5/main.lua#L61
has a hardcoded path and assumes that KOReader is installed under "/mnt/onboard/.adds/koreader/". This may not be the right location for your installation, so change that your path as well.

[trence]

Originally Posted by lumping-sugar66

Check the devices currently available in your system first:

ls /dev/input/

And connect your bluetooth device and do it again, and see the difference.

ls /dev/input/

If you get a /dev/input/event3 that wasn't there before, that's your device. After the device is there, you can do

and press on the bluetooth page turner buttons, see if your event stream detects these events.

If your event list doesn't change after you pair/connect your device, uhid.ko may be required and not have applied. You can cd into the bluetooth.koplugin folder and do

and retry the connection with the bluetooth clicker again. If you still don't see the event, it's likely that your device is trying to identify itself as a weird device and may not be compatible.

If your event is mapped to a different location, modify main.lua to match yours.

Be sure to check device.lua.patch for what's being done. the addition needs to go into your devices' configuration. For me that's Clara 2E but yours could be different. device.lua is full of all devices and specific configurations for each.

I also realized a slight mistake in my code. The line at https://github.com/onatbas/bluetooth...5/main.lua#L61
has a hardcoded path and assumes that KOReader is installed under "/mnt/onboard/.adds/koreader/". This may not be the right location for your installation, so change that your path as well.

I am exposing myself as a rookie even further, but I've not used telnet with the kobo before. I'm familiar with telnet and Linux, but not with Kobo. Is there a specific package from this link that I would launch from NickelMenu

https://www.mobileread.com/forums/sh...d.php?t=254214

[trence]

I believe I have found the answer. Just need to re install NickelMenu, with the telnet parts uncommented. Will update with progress. Thanks again.

[trence]

Hi There,

So I have done all the steps needed, and double checked them all as well.

I needed to change my file to event4 based on the test. I paired multiple times to ensure it was event4 each time. evtest was giving a code of 4

"Event: time 1723677209.973075, type 4 (Misc), code 4 (ScanCode), value 90002
Event: time 1723677209.973075 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723677210.096978, type 4 (Misc), code 4 (ScanCode), value 90002
Event: time 1723677210.096978 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723677254.911169 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
yyy
"

So I changed the event_map lua to reflect [4] = "RPgFwd".

The device in question, a Libra 2, already had the field of HasKeys as set for yes in the lua.

I installed the plugin, rebooted my device, and tried it out. It would search after turning Bluetooth on, but eventually fail connecting.

What's odd is that the device connects with no issue on Nickel, and turns pages. I do have the BTPT plugin installed (https://github.com/tsowell/kobo-btpt), do you believe that could be causing issues?

Edit: Forgot to include the picture of the message that would pop up shortly after turning on Bluetooth. Sorry for the snapshot, Koreader wouldn't let me take a proper screenshot. It would successfully connect to my wifi in Koreader.

2nd Edit: I uninstalled BTPT and re-did the process and all the same results/values from event and evtest. Still did not connect in Koreader

https://imgur.com/a/vz60SJX

[lumping-sugar66]

Hi, it looks like you're making good progress.

That screenshot confirms that the bluetooth is turned on properly, unfortunately it doesn't say anything about connection (it never does).

If your device is getting added to event4, then you need to modify device.lua patch to have it connect to /dev/input/event4.

You need to add

    local success, err = pcall(function()
        self.input.open("/dev/input/event4")
    end)

to device/kobo/device.lua right under

self.input.open("fake_events")

. Currently there's a bug with the plugin auto connecting, so all inputs need to be opened through the koplugin code. This also means you need to "Restart KOreader" after turning on bluetooth via the plugin.

I too have the plugin installed on nickel, it won't break your installation, as nickel isn't working when koreader is working.

Since you say that event code 4 works on Nickel page turner I won't press too much on this but event code 4 seems suspicious. You can cross-check with your .btpt/ config file.

What's your bluetooth device by the way? If the above don't work, please share your device.lua and main.lua files, and let's have a look. When you do that, kindly let me know where is your koreader installation in the device. A good way of letting me know is to cd into bluetooth.koplugin folder and do

pwd

and show me the result.

[trence]

Still no luck after doing the things mentioned. I have attached my files from the Plugin in a zip file. I likely am missing a key step.

I also found the 4 code strange, but that is what the telnet on NickelMenu gave when running evtest.

When pressing the button a couple times:
Event: time 1723756563.085844, type 4 (Misc), code 4 (ScanCode), value 90004
Event: time 1723756563.085844 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723756563.175818, type 4 (Misc), code 4 (ScanCode), value 90004
Event: time 1723756563.175818 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
Event: time 1723756578.323597 ------- Report Sync ------ x: 400 y: 80 p: 0 ------------
yyy


When I did the test a couple years back with evtest on a linux machine, I ended up making this for my btpt config for the page turner. I made all the buttons move a page forward.

nextPage EV_KEY BTN_EAST 0
nextPage EV_KEY BTN_WEST 0
nextPage EV_KEY BTN_GAMEPAD 0
nextPage EV_KEY BTN_NORTH 0

What would the code number be in this case for Kobo, 0? That is one thing I was confused about is where the numeric values for things like RPgFwd are derived from.

Appreciate all the help.

Edit: My koreader is in .adds/koreader. Could the btpt be altering the output of the Kobo Telnet evtest? Or does that run at a level that would be unaffected by something in Nickel like btpt?

[lumping-sugar66]

My pleasure. Thank you for giving it a try.

The code looks good.

By the way, the decimal values of those event codes are as follows. I'm not sure why evtest is skipping through the values. I haven't inspected the code of tsowell/btpt enough to make a call. but it looks like your and my installations are very similar, and I haven't had any issues.

BTN_EAST: 307
BTN_WEST: 308
BTN_GAMEPAD: 304
BTN_NORTH: 305

Please try after mapping functions to these values. If it doesn't work, I can have a look at your device.lua file.

Let me know how it goes.

[trence]

Sorry, I am a bit confused. Do you mean alter the patch file with:

[307] = "BTN_EAST"

etc for the other buttons?

[lumping-sugar66]

No, I suggested a correction for this:

Originally Posted by trence

So I changed the event_map lua to reflect [4] = "RPgFwd".

Those BTN enums correspond to integers in linux input event lists. You mentioned that page turner works with tsowell's plugin and the shared the configuration file. That tells me that your device is issuing BTN_GAMEPAD, BTN_NORTH, BTN_EAST, BTN_WEST events.

Their integer equivalents are 304, 305, 307, 308. (You can literally change the words in the config file to these values and it will work.) For me the event is KEY_VOLUMEUP, so an example for me is as follows.

The following instructions are identical:

nextPage EV_KEY KEY_VOLUMEUP 0
nextPage EV_KEY 115 0

Anyway, coming back to this plugin, instead of

[4] =  "RPgFwd

the following block would give you the identical button configuration with your nickel-based implementation, mapping all buttons to next page.

[304] =  "RPgFwd",
[305] =  "RPgFwd",
[307] =  "RPgFwd",
[308] =  "RPgFwd",

[trence]

Thanks for the explanation. I have added those lines in place of the previous ones, but the clicker still doesn't connect. Instead of the slow blink it does when paired on Nickel/other devices, it continues the fast blink. And I made sure to restart Koreader after enabling bluetooth.

[lumping-sugar66]

OK, sounds like there's something wrong with bluetooth connection, rather than the events being registered.

Try this:

1. SSH into the device.
2. Turn on bluetooth via KOReader.
3. Type in bluetoothctl. (Check 1 - you should see bleuetoothctl prompt. If not, your bluetooth is not running correctly.)
4. See the device name on the bluetooth prompt (if it just says bluetooth, you're not connected).
5. If not connected to the device, check devices using "devices". If your device is in the list, use "trust <MAC_ADDRESS>" and "connect <MAC_ADDRESS>". Once a trust is established, usually devices connect after that automatically.
6. If the device is not on the list at all, then a new pairing must be made. type "scan on" to turn on scan, find your device from that spew of messages coming in, type "pair <MAC_ADDRESS>" and repeat #5. "scan off" after you're done.
7. Try reboot to the device and the workflow again.

[trence]

This was my output, I do not see any devices:

[root@kobo ~]# bluetoothctl
Waiting to connect to bluetoothd...[bluetooth]# Agent registered
[bluetooth]#

I typed in devices:

bluetooth]# devices
No default controller available

I also attempted "scan on" and it said the same about a lack of default controller

[lumping-sugar66]

OK, it sounds like the way I was starting Bluetooth doesn't work properly for Libra 2. I'll modify the descriptions to clearly state it's not tested with anything but Clara 2E. I don't have a Libra 2 device to develop this further for the other devices unfortunately. Thank you for testing this and I'm sorry there isn't a satisfactory resolution.

---

As a side note, this means the missing piece is "turning on bluetooth via KOReader", this means turning it on from Nickel and then running KOReader would have your clicker working.

You can comment out the portion where KOReader kills bluetooth on startup, documented here:
https://github.com/koreader/koreader...ent-1791789778
But this means bluetooth will never be turned off and will drain your battery quickly. You can even delete the folder bluetooth.koplugin as all necessary changes are already in device.lua file already.