Pinephone Hardware Keyboard

This website is written by the keyboard firmware author, and contains information useful for the users of the keyboard.

If you're new to the keyboard, you should probably read FAQ first.

Firmware features

Advanced uses of the keyboard

The firmware is specially designed with easy tinkering in mind. During development I've requested that access to the unused GPIO pins of the MCU is provided on user solderable pads on the top of the PCB, so that anyone can add HW extensions to the keyboard itself.

This allows you to add extra buttons or other controls to the keyboard and connect them to the MCU to be exposed over I2C to the phone itself. You can also directly connect any I2C based extension boards or sensors to the shared I2C bus, and access these directly from Pinpehone SoC.

It's hard to brick the MCU just by flashing it wrong. There are multiple progresively harder ways to recover from a bricked firmware. Easiest is just to hold some keyboard keys to switch to the factory firmware, and flash your user firmware again. The hardest one is to solder a USB cable to some pads on the PCB and flash the firmware over USB via the tools I've written.

All this makes modding the keyboard quite easy and pleasant.

Getting the firmware

The firmware I wrote is already pre-flashed on the keyboard comming from the factory. Unless you'll want to extend it, you should not need to do anything.

To use the keyboard all you need is some software that will run on the Pinephone side that will communicate with the keyboard. There are two options. You can use Samuel's kernel driver, or you can use the userspace daemon that is easier to experiment with and modify. This daemon is included in the project's repository.

The firmware repository is available at: https://xff.cz/git/pinephone-keyboard/.

Documentation

The firmware, its interface and the relevant tooling is documented in the code repository of the firmware project in various README files.

News

2022-01-11
FAQ added
2021-11-03
This page was created. :)

Related projects

Bugs and support

Please report bugs via email:

Development

Project status: maintained by the original author.

You can join development of the firmware by sending questions, ideas, bugreports and patches to the above mailing address.

GIT repository is available at: https://xff.cz/git/pinephone-keyboard/.

Firmware history

Hi, I'm Ondřej (aka megi, one of the Pinephone Linux kernel maintainers). I liked the idea of hardware keyboard for Pinephone, so when the first prototypes were made I asked for one to play with. The firmware that came with those prototypes was quite a mess. It seemed like it was taken from some other keyboard that included a touchpad, and in the end it didn't work due to completely different layout. The firmware was written for a proprietary Keil C compiler, so it was hard to build on Linux.

So I decided to write a new firmware from scratch, that could be built and flashed using free and opensource tools, and would be easier to tinker with. It shouldn't be all that hard, I thought. A few months later, it turned out I was kinda wrong about it. :)

Obscure Taiwanese MCU with no publicly available tooling, and lack of any information about flashing protocols and formats were big obstacles. In the end I figured all that out and created the firmware itself, reverse engineered all the protocols and file formats, learned a lot about an obscure MCU I'll never use again, created a flashing and debugging tooling for both the MCU's factory USB bootloader, and for my own custom I2C flashing protocol so that the firmware can be updated in the field directly from the Pinephone.

The whole blog series can be written (and was written :)) about dealing with various hardware quirks and issues with the charging controller's I2C interface, so that the charging can be monitored and controlled via software from the phone itself.

Samuel Holland also wrote a Linux kernel driver for the keyboard and helped with testing and understanding of the charging controller for the integrated battery.

Support the project

Pinephone keyboard firmware is free and opensource software released under GPLv3. It is an independent personal project.

You can contribute by writing code, helping improve documentation, spreading the word, and/or by donating money to the author.

Shortly before keyboard's release, Pine64 agreed to give me 2.5 USD per unit sold, which will hopefully help offset some of the development costs, depending on the keyboard's popularity.

Share on: Twitter, Facebook, etc.