MobileRead Forums - View Single Post - Bluetooth Page Turner plugin for Kobo KOReader

lumping-sugar66 · 08-09-2024, 12:54 AM

Bluetooth Plugin for KOReader - v1.0.1

Use a Bluetooth controller (like 8BitDo Micro) to turn pages and control other reader settings of KOReader on your Kobo.

What's New in v1.0.1
• Guided Simple Setup - configure buttons without editing files
• Dynamic device detection - works on more Kobo models
• Built-in diagnostics and troubleshooting

What's New in v1.0.0

Complete overhaul focused on eliminating manual configuration:

No more editing device.lua
No more editing shell scripts
No more hardcoded MAC addresses
No more figuring out event3 vs event4
Everything is auto-detected or configurable via UI

Supported Devices

Fully Tested:

Kobo Clara 2E
Kobo Libra 2

May Work (auto-detection):

Other Kobo devices with similar hardware

Not Yet Supported:

Clara BW, Clara Colour, Libra Colour (MediaTek Bluetooth hardware - different drivers needed)

Installation

Step 1: Copy the Plugin

Download from GitHub
Rename folder to
Code:
```
bluetooth.koplugin
```
Copy to
Code:
```
koreader/plugins/
```
on your Kobo
Restart KOReader

Step 2: Run Diagnostics & Auto-Fix

Go to Menu > Network > Bluetooth > Diagnostics

Click any item marked with X and choose "Correct Automatically":

hasKeys flag - Required for button input
Event map - Default button mappings for 8BitDo

Step 3: Turn On Bluetooth & Pair Your Controller

Go to Bluetooth > Bluetooth On
Put your controller in pairing mode
Go to Bluetooth > Device Management
Click "Start scanning (30s)"
Click "Select from scanned devices" and choose your controller
Done - your controller is saved

Step 4: Connect

Whenever you want to use your controller:

Bluetooth > Bluetooth On
Device Management > Connect to saved device

That's it.

Features

Auto-Configuration
Everything is automatic:

Installation path detection
Device-specific Bluetooth commands (Clara 2E vs Libra 2)
Input device path (event3/event4)
Button mappings
hasKeys override

Device Management
Scan, select, and save Bluetooth devices directly from the UI. No more editing scripts.

Event Map Editor
Bluetooth > Event Map Editor

View all current mappings (key code to event)
Add new button mappings
Change or delete existing mappings
Changes take effect immediately

Diagnostics
Bluetooth > Diagnostics

Live Bluetooth status (ON/OFF)
Pass/fail indicators for each configuration item
Click for details and auto-fix options
Debug tools: button press history, raw input monitor

Bank System
Map the same physical buttons to different actions by switching banks. Perfect for controllers with limited buttons.

Edit

Code:

bank_config.txt

to customize:

Code:

Bank1
BTAction1:BTLeft, A button
BTAction2:BTRight, B button
BTAction3:BTToggleBookmark, Y button

Bank2
BTAction1:BTIncreaseBrightness, A button
BTAction2:BTDecreaseBrightness, B button
BTAction3:BTToggleNightMode, Y button

Switch banks using BTRemoteNextBank / BTRemotePrevBank.

Customizing Button Mappings

The plugin comes pre-configured for 8BitDo Micro in keyboard mode. For other controllers:

Option A: Event Map Editor (recommended)

Go to Diagnostics > Monitor raw input (5 sec)
Press buttons on your controller
Note the key codes shown
Go to Event Map Editor > Add new mapping
Enter the code and select an event

Option B: Edit bank_config.txt
For power users who want bank switching and full control.

Available Events

Page Navigation

BTLeft / BTRight - Previous/next page (orientation-aware)
BTGotoPrevChapter / BTGotoNextChapter

Bookmarks

BTToggleBookmark, BTPrevBookmark, BTNextBookmark, BTLastBookmark

Display

BTIncreaseBrightness / BTDecreaseBrightness
BTIncreaseWarmth / BTDecreaseWarmth
BTToggleNightMode, BTToggleStatusBar, BTIterateRotation, BTRefreshScreen

Font

BTIncreaseFontSize / BTDecreaseFontSize
BTIncreaseFontWeight / BTDecreaseFontWeight
BTIncreaseLineSpacing / BTDecreaseLineSpacing

System

BTBluetoothOff, BTBluetoothOffAndSleep, BTSleep

Bank Actions

BTAction1 through BTAction20 - Configurable via bank_config.txt
BTRemoteNextBank / BTRemotePrevBank - Switch banks

Troubleshooting

Buttons not working?

Check Diagnostics - all items should show pass
Use raw input monitor to see if button presses are detected
Add missing key codes via Event Map Editor

Controller not connecting?

Make sure Bluetooth is ON
Use Device Management to scan and select your device

Battery Note

Properly shutting down Bluetooth is crucial. On a Clara 2E, improper shutdown causes ~3% battery drain per hour during sleep. This plugin ensures Bluetooth is turned off correctly - 0% drain when sleeping.

Credits

Tested on Clara 2E and Libra 2
Libra 2 support thanks to MobileRead user enji
8BitDo Micro controller recommended

Download

https://github.com/onatbas/bluetooth.koplugin

Feedback and contributions welcome.

08-09-2024, 12:54 AM	#1
lumping-sugar66 Groupie Posts: 152 Karma: 87635 Join Date: Oct 2023 Location: Ontario, Canada Device: Kobo Aura Edition 2, Kobo Clara 2E, Kobo Libra 2	Bluetooth Plugin for Kobo KOReader Bluetooth Plugin for KOReader - v1.0.1 Use a Bluetooth controller (like 8BitDo Micro) to turn pages and control other reader settings of KOReader on your Kobo. What's New in v1.0.1 • Guided Simple Setup - configure buttons without editing files • Dynamic device detection - works on more Kobo models • Built-in diagnostics and troubleshooting What's New in v1.0.0 Complete overhaul focused on eliminating manual configuration: No more editing device.lua No more editing shell scripts No more hardcoded MAC addresses No more figuring out event3 vs event4 Everything is auto-detected or configurable via UI Supported Devices Fully Tested: Kobo Clara 2E Kobo Libra 2 May Work (auto-detection): Other Kobo devices with similar hardware Not Yet Supported: Clara BW, Clara Colour, Libra Colour (MediaTek Bluetooth hardware - different drivers needed) Installation Step 1: Copy the Plugin Download from GitHub Rename folder to Code: bluetooth.koplugin Copy to Code: koreader/plugins/ on your Kobo Restart KOReader Step 2: Run Diagnostics & Auto-Fix Go to Menu > Network > Bluetooth > Diagnostics Click any item marked with X and choose "Correct Automatically": hasKeys flag - Required for button input Event map - Default button mappings for 8BitDo Step 3: Turn On Bluetooth & Pair Your Controller Go to Bluetooth > Bluetooth On Put your controller in pairing mode Go to Bluetooth > Device Management Click "Start scanning (30s)" Click "Select from scanned devices" and choose your controller Done - your controller is saved Step 4: Connect Whenever you want to use your controller: Bluetooth > Bluetooth On Device Management > Connect to saved device That's it. Features Auto-Configuration Everything is automatic: Installation path detection Device-specific Bluetooth commands (Clara 2E vs Libra 2) Input device path (event3/event4) Button mappings hasKeys override Device Management Scan, select, and save Bluetooth devices directly from the UI. No more editing scripts. Event Map Editor Bluetooth > Event Map Editor View all current mappings (key code to event) Add new button mappings Change or delete existing mappings Changes take effect immediately Diagnostics Bluetooth > Diagnostics Live Bluetooth status (ON/OFF) Pass/fail indicators for each configuration item Click for details and auto-fix options Debug tools: button press history, raw input monitor Bank System Map the same physical buttons to different actions by switching banks. Perfect for controllers with limited buttons. Edit Code: bank_config.txt to customize: Code: Bank1 BTAction1:BTLeft, A button BTAction2:BTRight, B button BTAction3:BTToggleBookmark, Y button Bank2 BTAction1:BTIncreaseBrightness, A button BTAction2:BTDecreaseBrightness, B button BTAction3:BTToggleNightMode, Y button Switch banks using BTRemoteNextBank / BTRemotePrevBank. Customizing Button Mappings The plugin comes pre-configured for 8BitDo Micro in keyboard mode. For other controllers: Option A: Event Map Editor (recommended) Go to Diagnostics > Monitor raw input (5 sec) Press buttons on your controller Note the key codes shown Go to Event Map Editor > Add new mapping Enter the code and select an event Option B: Edit bank_config.txt For power users who want bank switching and full control. Available Events Page Navigation BTLeft / BTRight - Previous/next page (orientation-aware) BTGotoPrevChapter / BTGotoNextChapter Bookmarks BTToggleBookmark, BTPrevBookmark, BTNextBookmark, BTLastBookmark Display BTIncreaseBrightness / BTDecreaseBrightness BTIncreaseWarmth / BTDecreaseWarmth BTToggleNightMode, BTToggleStatusBar, BTIterateRotation, BTRefreshScreen Font BTIncreaseFontSize / BTDecreaseFontSize BTIncreaseFontWeight / BTDecreaseFontWeight BTIncreaseLineSpacing / BTDecreaseLineSpacing System BTBluetoothOff, BTBluetoothOffAndSleep, BTSleep Bank Actions BTAction1 through BTAction20 - Configurable via bank_config.txt BTRemoteNextBank / BTRemotePrevBank - Switch banks Troubleshooting Buttons not working? Check Diagnostics - all items should show pass Use raw input monitor to see if button presses are detected Add missing key codes via Event Map Editor Controller not connecting? Make sure Bluetooth is ON Use Device Management to scan and select your device Battery Note Properly shutting down Bluetooth is crucial. On a Clara 2E, improper shutdown causes ~3% battery drain per hour during sleep. This plugin ensures Bluetooth is turned off correctly - 0% drain when sleeping. Credits Tested on Clara 2E and Libra 2 Libra 2 support thanks to MobileRead user enji 8BitDo Micro controller recommended Download https://github.com/onatbas/bluetooth.koplugin Feedback and contributions welcome. Attached Thumbnails Last edited by lumping-sugar66; 12-28-2025 at 03:09 PM.