megi's PinePhone Development Log RSS


2021–05–30: PinePhone keyboard – more observations

After further eyeballing of the firmware in Ghidra, with the help of a linker symbol map, I've reverse engineered the USB flashing protocol completely.

I'll not publish complete details at this time, but here's a general idea of how it works:

All the details of the flashing protocol are known to me now, and I have a flashing tool in the works. It should be possible to finish most of it even prior to getting my hands on any hardware, but I guess there's no hurry at this point with all the details known. :)

Out of all this research I personally plan to do these HW modifications on the keyboard to help make it more useable/robust:

Overall, the situation around flashing arbitrary firmware to the keyboard controller reliably seems quite reasonable, without too many gotchas for the end-users. With a known good keyboard firmware users should be able to recover from flashing failures without the need to open the keyboard or a huge risk of bricking the keyboard.

The only thing that will be troublesome to end-users is the possible non-confirmance of the charging circuit to USB specification, as mentioned in the previous post. It will be probably challenging to insert the keyboard into the USB ports on the computer without the port shutting down due to overcurrent.

I'll be also looking at the actual keyboard firmware (main app). Most of the existing code deals with exposing the USB HID interface, which is not used by Pinephone. Actual keyboard interface used by Pinephone is HID over I2C. Code for that is much simpler. There's a lot of dead code in the existing firmware provided by the vendor. All that's needed is just reading out currently pressed keys from the key matrix, and providing updates over I2C on changes. That should be a few hundred lines of code tops, not the current ~6000 lines. USB interface is only used for initiating the switch to flashing mode of the bootlader from the main app, but we can instead use a fixed key combination to do that (Pine key+F+M, for example) and drop all that other dead weight from the firmware. This will make firmware also much smaller and faster to flash (currently it's 19 KiB, or 16 KiB when compiled with optimizations, but it can be ~2 KiB).

If you'd like to support the effort to make FOSS firmware flashing tool and customizable firmware for the Pinephone keyboard, donations are welcome.