Workaround for external keyboards to make special characters in KOReader
+published: 2023-09-01
++
For a while, I've fantasized about turning my little Kobo Libra H2O, an e-reader that runs an embedded and bare-bones version of Linux, into a more general-purpose computing device. You know, in case the apocalypse hits and somehow all my other devices eventually go to shit. For a while I've been most of the way there: KOReader, a third-party reading application for the Kobo, has an embedded terminal emulator that hands root access to the device to you, no questions asked. You just drop whatever command-line binaries you want in /mnt/onboard/.adds/koreader/plugins/terminal.koplugin/, and as long as they're compiled for Linux armv7l they're good to go. For a while, the terminal emulator had problems with ncurses, so you couldn't use any TUI programs and had to stick exclusively to the command line with its one-off commands... but somewhere along the way that got fixed, so now you can use your fancy Gemini browsers and the built-in vi and anything else that requires an actual text-based interface.
The only problem with this setup is that the Kobo Libra H2O doesn't support USB OTG out-of-the-box. That means, even if you have a special adapter, you can't use an external keyboard. You're stuck with the virtual keyboard on-screen, which is okay for small operations but highly uncomfortable for long typing sessions like writing, which is mainly what I'd use the extra functionality for. It's also a pain in the ass to use the virtual keyboard to type any special characters like the pipe symbol or an exclamation mark.
+Well, apparently almost a year ago KOReader added external keyboard support for Kobo devices. You need a powered USB OTG adapter as the Kobo won't supply enough power to recognize that there's a device connected, but once you have the keyboard and the power source (I use one of those cheap portable battery packs, because if I have to be tethered to an outlet, I'd rather just use an actual computer) connected, KOReader recognizes that there's a keyboard plugged in and enables keyboard shortcuts in the interface and keyboard input for the text editor and terminal.
+...Except that the shift button doesn't work properly.
+On a standard US QWERTY keyboard, pressing Shift and one of the number keys on top makes a special character. Shift and 1, for example, make an exclamation mark. Shift and 2 make an @ symbol. Shift and 3 make a hash. Shift and 4 make a dollar sign. Et cetera. However, the Kobo doesn't seem to recognize when the Shift key is being held down for any key other than the twenty-six alphabetic keys. I can TYPE IN ALL CAPS WITH THE SHIFT BUTTON HELD DOWN, but I can't make any underscores or question marks or double quotation marks. "Who cares?" you might ask, in which case I would respond, "Well, when writing, the characters often speak, and they accentuate their sentences! Which creates a problem: if I have to constantly capitulate to the keyboard on the screen to make special characters, then I will always be losing my rhythm (and possibly my train of thought as well)."
How keyboards work in Linux is pretty complicated, but the gist is this: when you press a key on your keyboard, it doesn't send that key specifically; it sends a "keycode" to the kernel, which decides what key that corresponds to. So when I press the A key on my laptop keyboard, it doesn't send an A, it sends a code which can be seen with sudo evtest:
Event: time 1693317010.094300, type 1 (EV_KEY), code 30 (KEY_A), value 1
As evidenced by the log, the A key corresponds with code 30. Which matches the keycode map KOReader uses to interpret keyboard events on Kobo devices.
+So I thought that maybe the Shift key wasn't being captured properly on the Kobo, which was causing Shift and 1 to output 1 instead of an exclamation mark. So I ran evtest --grab /dev/input/event4 on the Kobo:
+Event: time 1693317622.024915, type 4 (Misc), code 4 (ScanCode), value 70004 +Event: time 1693317554.992894, type 4 (Misc), code 4 (ScanCode), value 700e1 +Event: time 1693317640.632890, type 4 (Misc), code 4 (ScanCode), value 700e1 +Event: time 1693317640.744919, type 4 (Misc), code 4 (ScanCode), value 7001e ++
For whatever reason, the Kobo's kernel reports the key presses not as type 1 but as type 4, all with the same codes. The value is what's important here. According to the values, the first key press is our example, the A key. The second one is the Shift key all by itself. The third and fourth ones are when I attempted to make that exclamation mark by pressing Shift and 1 together. As you can see, the exclamation mark isn't its own key put together by the keyboard's firmware or whatever; it's something else in the system that sees the Shift and 1 being pressed at the same time and chooses to interpret that as an exclamation mark. And that "something else" on the Kobo only likes letters.
+But we know that the Kobo can handle special characters. KOReader has to somehow map the hardware "previous page" and "next page" buttons to, well, turning the pages of the book back or forwards.
+It turns out that our salvation lies in that keycode map in KOReader. If you take another look at it, you can see that not all the keys match up to an ASCII equivalent. For example, Page Up, or whatever key sends keycode 104, gets mapped to "LPgBack". Which matches our standard laptop keyboard again:
+Event: time 1693318576.571605, type 1 (EV_KEY), code 104 (KEY_PAGEUP), value 0
Theoretically we should be able to take an arbitrary key on the keyboard, capture its keycode, and then put it into this map to make it output whatever character we want.
+So let's add the bracket keys, which got omitted for some reason:
+[26] = "[", [27] = "]",
And then let's change all the F1 through F12 buttons to be the special characters locked behind the number keys, as well as the question mark and double quotations:
+
+ [59] = "!",
+ [60] = "@",
+ [61] = "#",
+ [62] = "$",
+ [63] = "%",
+ [64] = "^",
+ [65] = "&",
+ [66] = "*",
+ [67] = "(",
+ [68] = ")",
+ [87] = "?",
+ [88] = '"',
+
+ And just for my cheapo wireless keyboard I got off eBay, let's make the shoulder L and R buttons be the same as the left and right arrow keys:
+[272] = "Left", [273] = "Right",
Save the map and restart KOReader, and the keys should now be working properly as mapped. Still no proper Shift, though...
++
CC BY-NC-SA 4.0 © Vane Vander
+