Connecting to Bluetooth classic keyboards

[clint32]

After much trial and error, false starts and...so much log reading, I managed to get a keyboard over Bluetooth classic (not BLE) working on my PW5/PW6 running jailbroken 5.18. (Older versions may also work, I just don't have any devices to test on.)

This definitely requires a jailbroken device and some kinda dangerous operations.

Enabling Bluetooth HID devices
This requires a small udev rule to keep things working after reboots, reconnects, or btmanagerd crashes

The Kindle comes with a version of the X server (v1.8.2, from 2010) that requires udev 148 or newer to support "hot plugged" input devices, because the X server looks for certain properties on the devices that older versions don't set. Unfortunately, the Kindle firmware ships udev 146, so we have to do that part manually. Since Bluetooth keyboards will basically always be hot plugged (you don't want to restart the X server every time it connects), this is an important step.

Create a small shell script (e.g. /usr/local/bin/dev_is_keyboard.sh, and don't forget to chmod +x) that detects whether an attached device is capable of keyboard input.

#!/bin/sh
DEVICE=$1
if evtest info $DEVICE | grep -q 'Event type 1 (Key)'; then
  if evtest info $DEVICE | grep -q 'Event code 16 (Q)'; then
    # Don't set these just because Key is supported -- that will
    # detect the touchscreen as a keyboard which breaks the UI
    echo ID_INPUT=1
    echo ID_INPUT_KEY=1
    echo ID_INPUT_KEYBOARD=1
  fi
fi

Now, we need a file to run this as part of a udev rule, and fix up some file permissions. Create one, like /etc/udev/rules.d/99-bt-keyboard.rules:

KERNEL=="uhid", MODE="0660", GROUP="bluetooth"

ACTION=="add", SUBSYSTEM=="input", IMPORT+="/usr/local/bin/dev_is_keyboard.sh %N"

The first rule is necessary as restarts of btmanagerd seem to reset it to being owned by root. The second one runs the script and adds its output to the properties of the device.

Run udevadm control --reload-rules once this is in place.

Pairing a device

The ace_bt_cli tool can be used to manipulate the Bluetooth (classic and BLE) system.

ACEBTCLI BT Client :: start
p_data (size:27) = 1B 00 00 00 00 00 00 00 00 00 00 61 63 65 5F 62
                   74 5F 63 6C 69 00 00 00 00 00 00
ACEBTCLI BT Client :: opened session with 0x19b9550

>:

Check if bluetooth is enabled
Run radiostate; you should see ACEBTCLI getRadioState() state:1 status:0.
If it's not enabled, run enable.

Run help to see all the options, but we're mostly just interested in pair here.

Finding your Bluetooth address
You can try classic scan here, but it also filters out non-audio devices. You'll need to know the Bluetooth address of your keyboard. (On macOS, you can find it in the Bluetooth settings: option-click on the icon for your keyboard in the device list. Alternately, install blueutil and run blueutil inquiry. I'm not sure how to do this on Windows or Linux, sorry.)

Pairing
Once you have the address, pair it -- the address must be colon separated (or no separator at all):

>: pair 19:18:17:16:15:14

At this point, if everything went correctly, you should have a connected keyboard that can type in applications like kterm, the built-in browser, etc.

If it didn't work, you'll have some debugging to do.

Debugging

Spoiler:

Check if the device is connected:

# ace_bt_cli
>: connectedlist
ACEBTCLI Got 1 devices for getConnectedDevices
ACEBTCLI xx:15:14
ACEBTCLI aceBT_freeDeviceList with status 0

Check that /dev/uhid is accessible to the Bluetooth software:

[root@kindle us]# ls -l /dev/uhid
crw-rw----    1 root     bluetoot   10, 239 Aug 30 22:44 /dev/uhid

Check that your device exists:

[root@kindle us]# cat /proc/bus/input/devices
...
I: Bus=0005 Vendor=0abc Product=0123 Version=0001
N: Name="BT keyboard"
P: Phys=
S: Sysfs=/devices/virtual/misc/uhid/0005:0ABC:0123.0003/input/input4
U: Uniq=19:18:17:16:15:14
H: Handlers=leds event2 perfmgr
...

Note the event# here; check your Kindle is receiving keypresses (but may not be making it to the X server):

[root@kindle us]# evtest /dev/input/event2
...
Testing ... (interrupt to exit)
Event: time 1756676427.351791, type 4 (Misc), code 4 (ScanCode), value 7002c
Event: time 1756676427.351791, type 1 (Key), code 57 (Space), value 1
Event: time 1756676427.351791, -------------- Report Sync ------------

If that works, then the Bluetooth parts are all fine and it's the X server device detection that is not working.

Check /tmp/x.err for any relevant logs.

Check /var/log/messages for any logs related to ace or mention the redacted address of your device (a device address "19:18:17:16:15:14" may be logged as "xx:15:14").

Run udevadm monitor while connecting your device. Confirm that udevadm info --query=property --name /dev/input/event2 shows IS_INPUT=1 and IS_INPUT_KEY=1.

While this is probably a bit more invasive than most would hope, I thought I'd share what I found and document the debugging steps for any future determined souls

[mergen3107]

This is awesome, Thank you! Have you shared this over Kindle Modding on Discord?
People will be ecstatic

I will try this later on 5.17.x

[Frogm4n]

Nice sleuthing! I haven't set it up yet, but I've noticed one annoyance: rotation events show up as ESC codes when running ace_bt_cli and mangle your input.

[kbarni]

Wow, great project! Trying to make it work...
- created the 2 files and ran udevadm control --reload-rules
- started ace_bt_cli:

[root@kindle btkeyboard]# ace_bt_cli 
ACEBTCLI BT Client :: start
p_data (size:27) = 1B 00 00 00 00 00 00 00 00 00 00 61 63 65 5F 62 
                   74 5F 63 6C 69 00 00 00 00 00 00 
ACEBTCLI BT Client :: opened session with 0x1599540

>: radiostate
ACEBTCLI getRadioState() state:1 status:0

>: pair B0:45:19:EC:A6:F1
ACEBTCLI str: B04519ECA6F1
ACEBTCLI ACEBT_DISCOVERY_STATE_STOPPED
ACEBTCLI Initiate Pairing Success

>: ACEBTCLI CLI callback : bond state changed() status: 0 addr: B0:45:19:EC:A6:F1 state: BONDING
ACEBTCLI CLI callback : bond state changed() status: 0 addr: B0:45:19:EC:A6:F1 state: BONDING
ACEBTCLI CLI callback : bond state changed() status: -206 addr: B0:45:19:EC:A6:F1 state: NONE
ACEBTCLI CLI callback : bond state changed() status: -206 addr: B0:45:19:EC:A6:F1 state: NONE

>: connectedlist
ACEBTCLI Got 0 devices for getConnectedDevices
ACEBTCLI aceBT_freeDeviceList with status 0

...so it's not connected.

The file /dev/uhid is still owned by root:root.

Can you guide me from here?

[Frogm4n]

Check the MAC address of your BT keyboard. That output shows it started trying to pair, but it's not finding it.

I was able to get a BT keyboard working. I had to troubleshoot my own typo of a single missing character from the shell script, but other than that it went off ok. Input worked in most places I'd expect. Kindle UI text boxes, kterm, Leafpad. However, it did not work in KOReader at all. Not in textboxes, the texteditor, or the terminal. I'm assuming that's a KOReader issue and nothing to do with the input method itself. I'm guessing there are input checks and since Kindles haven't been able to use BT keyboards before, they don't expect input from one. I'm sure if they get BT input working then BT page turners to use keycodes would work as-is inside of KOReader.

The Kindle even shows the connected keyboard name under the BT icon in the Kindle pull-down quick menu. Interestingly, it also shows/hides the volume slider depending on if it's connected or not. They must have that tied to having any BT device connected.

There doesn't seem to be any native Kindle book reader UI reaction to arrows/PgDn/PgUp. That's going to rule out BT page turners that send keycodes. I know there was a lot of hope about getting those working on a Kindle. I don't know how other types work, but if udev rules could be written for them and a custom script watches the /dev/input/eventX file and can route event messages to the UI...

[kbarni]

We tried to debug my issue with Clint and Sighery, it's a problem with the authentication using the pairing process. The keyboard asks for a pairing confirmation that doesn't show up in the ace_bt_cli interface.

I tried to pair another BT keyboard, and it works!
Now I can play with Textadept on my Kindle!

Another question: how can I change the disposition of the keyboard? I need to set it to French (azerty).

Update: Solved. See below

[kbarni]

Important: Read below to set a custom layout to your external keyboard!

If your external keyboard has a custom layout (french, german, dvorak or anything else), you can choose it with the attached script.
Copy the file to the root of your kindle and remove the .txt from the filename (the forum doesn't accept sh file attachments).

Then, run the script from kterm, with the keyboard language as parameter.

Example:

./setlayout.sh fr

You can also add a keyboard variant:

./setlayout.sh 'fr(bepo)'

(note the apostrophes)

This is not a persistent change, so you need to run the script after each reboot!

(you can check the /usr/share/x11/xkb/symbols folder for available languages and variants)

[Frogm4n]

I've discovered unexpected functionality on my Scribe running 5.18.1: Pressing F1 - Force screen rotation normal, F2 - Force screen rotation inverted. Will be over-ridden by sensor when the Scribe is moved. Seems to work in all situations in the Kindle UI, but still no response at all in KOReader. If I do get this updated to 5.18.5, I'll see how the new rotation lock responds vs this current behavior.