Pinephone Hardware Keyboard FAQ

I add to this FAQ when I see a recurring question in the pine chatrooms. You can also send me a message to x@xnux.eu if you have questions. Back to the main page

Hardware

My keyboard doesn't work [well]!: See the troubleshooting section below
How does charging work?: Keyboard uses a powerbank controller chip, which works nicely for a typical powerbank use case, where you charge the powerbank and then discharge it into the phone. Pinephone keyboard use case is different. The keyboard battery is always connected to the phone, even if being charged, so a lot more coordination is necessary to not waste power on needless shifting of charge between batteries, and to avoid having to manually control the power delivery. None of this coordination is implemented currently. See partial list of issues in this blog post.
What charger is best for the keyboard?: None of the standard USB power negotiation is used by the keyboard's Type-C port. The keyboard will work with any power supply which fits the power requirements of the keyboard (10.5 - 15 W at 5 V). Using 5V/3A supporting PD power supplies should be fine. Using regular 5V/1.5A USB-A power supplies may be tricky. The keyboard can and will use them at full load (and more) for extended periods of time. You should monitor your chosen power supply for a while under full load to make sure it will not overheat. Keyboard charger chip monitors the voltage drop on the power supply, and reduces the load accordingly. This should be enough to make it safe to use. You do not want to connect the keyboard to USB port of your computer.
How safe is the charger circuit in the keyboard?: The chip is IP5209. It has undervoltage protection on input and output, output short circuit detection, chip thermal regulation, thermal shutdown with hystheresis, etc. So it should be reasonably safe. The battery has its own overcharge/overdischarge/overcurrent protection circuit, too. Battery thermals are not monitored.
Can I plug something to the phone's Type-C port?: No! When the keyboard is connected to the phone, it powers the phone by internally supplying 5V to the VBUS of the phone's Type-C port. So if you connect another USB power supply to the phone's Type-C port, it's like connecting two chargers to the phone by cutting and splicing their cables. (Likely not a good thing, or something you'd consider doing if it was presented to you that way.) If you connect some USB peripheral there that only consumes power from the port (like mouse, unpowered dock, etc.), it may work (in theory), but only if you make *absolutely sure* the phone will not enable its power output to the USB device! No distros ensure that at the moment. When you plug USB periperal it's the same as plugging in two chargers into the same port, without additional software support that doesn't exist, yet.
What does the button on the side of the keyboard do?: It wakes up the charger chip inside the keyboard and enables the power output to the phone when you press it shortly once. It disables the output to the phone when you double press it. Its status can also be read from software.

Software/drivers

What is the keyboard driver situation?: Samuel Holland submitted kernel driver for the keyboard and another for the IP5209 PMIC for inclusion in mainline Linux. These are the drivers that should be used for the keyboard.
What's the status of the existing software for the keyboard?: Firmware is complete. There will likely be no new releases, unless the hardware changes in the future. Userspace software for flashing the firmware is complete, too. Proposed mainline kernel drivers look good. Userspace daemon to manage charging is yet to be implemented.
How can I read the battery capacity?: Keyboard's power supplies are represented by ip5xxx-charger and ip5xxx-boost in /sys/class/power_supply; You can read the battery voltage and charging/discharging current. Capacity is not readable from the charger chip directly, it needs to be guessed/calculated from the open circuit voltage and the battery discharge curve. I have measured the curves of my keyboard and added support for reporting the capacity to my kernel branch (5.17).
How can I add/change key maps?: There are two layers to this. Keyboard driver produces keyboard event codes for pressed keys. It also produces scan codes, which represent each key physically on the keyboard matrix without any key mapping. You can remap these at the driver level, but that's only useful if you want to physically move keys around on your keyboard. As you can see, if you check the link, these event codes are just meant to represent physical keys on a typical keyboard. For example there's no event code for | or ~. That's because on typical keyboards these are typed by Shift+\ or Shift+`. There are no accented character key codes either. Mapping key codes to what you end up seeing on the screen is supposed to be handled by the applications via a mechanism like xkb.; Locale based keymaps (like Czech, US, Russian), are handled at application level, like on any normal desktop Linux distributions. I don't know if Phosh or Plasma Mobile offer GUI to add these locale keymaps for physical keyboards, but they definitely should! File bug reports (or find and track existing ones) with your distribution if this is not easily available.

Sample keymaps

For use with Linux kernel virtual console, you can load the following keymap via loadkeys -d ppkb.map:

strings as usual
compose as usual for "iso-8859-1"
keymaps 0-63

plain keycode 125 = ShiftR
ShiftR keycode 125 = ShiftR
ShiftR keycode 0x02 = bar
ShiftR keycode 0x03 = backslash
ShiftR keycode 0x06 = asciitilde
ShiftR keycode 0x07 = grave
ShiftR keycode 0x08 = minus
ShiftR keycode 0x09 = equal
ShiftR keycode 0x0a = underscore
ShiftR keycode 0x0b = plus

Afterwards you'll be able to type Pine+1 to type |, Pine+2 to type \, and so on.

Other resources: HazardChem/PinePhone_Keyboard

Troubleshooting

Symptom	Cause	Solution
Keyboard doesn't react to any key presses	Keyboard is not connected to the phone properly	Try re-seating the phone in the chasis.
	POGO pins may be dirty from either side (they are not soldered to the PCB) or they may not be making a good contact with the pads in the keyboard chasis for other reasons.	Clean the POGO pins. If that doesn't work: POGO pads on the keyboard are on a plastic covered PCB that is glued to the keyboard's case. That PCB can be carefully pulled away from the keyboard case (from the top), and padded a bit from the backside (using some non-conductive material, eg. folded paper) so that POGO pads are sticking out more from the case, and make better contact with POGO pins of the keyboard.
	A small tab near the POGO pins did not click in	Push on the keyboard case near the POGO pins to make it click in. It should not take that much force.
	Some people also reported that contact reliablity is affected by how much the screws in the inner frame of the phone are tightened.	Check the screws. Make sure they are screwed tight.
	Your distro doesn't have the keyboard driver.	You can run the `ppkb-i2c-inputd` command from the keyboard utilities package on any Linux distribution, to get the keyboard to work.
	You built the kernel yourself and forgot to update the DTB file.	When doing a custom kernel build, you need to install both kernel Image and the Pinephone DTB files. See my guide on how to build the kernel for Pinephone manually.
Keyboard works but top row of keys is less responsive	Keyboard membrane does not have the perfectly correct shape.	Fixing this is a NP-hard problem, apparently. There were already 4-5 membrane revisions by the vendor. It's still not perfect. Anyway, I'm sure it will be solved in polynomial time. It's possible to fix at home by removing the keycaps from the top row and by padding the key caps from the bottom so that the membrane's rubber ring is pressed deeper with less key travel. Model for 3D printed washers that can be placed under the keycaps to fix the issue is also available. Other method is using enameled copper wire cut from a coil that was wound on a M5 screw. Any kind of padding ~0.3-0.5mm in height will do. It just has to be outside of the inner ring of the keycap.
Some key combinations don't work as expected	Electrical matrix in the keyboard has limitations	See more in-depth explanation in this article
Phone is not charging from the keyboard	The keyboard power output is not enabled	The charger may be sleeping. You can wake it up by pressing the button on the side of the keyboard once.
	Keyboard battery is too discharged	You can verify keyboard battery charge level by using the `ppkb-i2c-charger-ctl info` command from the keyboard utilities package. If the reported voltage is very low (< 3 V) the keyboard battery is completely discharged.
Phone is charging slowly from the keyboard battery	Input current limit on the phone side is set to 500mA by default. Automatic limit setting only works when connecting power supply via the phone's Type-C port without the kyeboard present. Keyboard is connected differently.	If you're using the keyboard, you'll have to manage the input current limit manually via sysfs (`echo 1500000 > /sys/class/power_supply/axp20x-usb/input_current_limit` or if you have Pinephone Pro, substitute rk818-usb for axp20x-usb). This will be automated by yet to be written power management daemon in the future. Typical maximum that can be provided by the keyboard power controller is 5V/2.4A. (Don't put anything into the Pinephone's Type-C port while the keyboard is connected! You may damage your phone or keyboard.)
	`ppkb-i2c-charger-ctl info` prints some 0xff error	Sadly, charger chip sometimes goes to sleep and doesn't respond to I2C communication in this state. Wake it up by pressing the keyboard power button, or by inserting a power supply to the keyboard's Type-C port. This is a HW limitation.
Keyboard battery is charging slowly or not at all	new keyboard batch has a HW issue	Protection diode was placed incorrectly in one of the last KB batches on keyboard's USB input, and this prevents or significantly limits keyboard power sourcing with most USB power supplies. Keyboard charger chip limits power input, when input voltage drops below 4.5V. The additional diode introduces 0.4-0.6V voltage drop by itself, even without taking into account the USB cable voltage drop, and softness of the USB power supply itself. Fix is to short the diode D1 on the PCB. This was fixed in the factory for the most of the units in the April batch, but some units were sent out broken.
Phone is not charging from the keyboard battery at all and keyboard power button does nothing	Keyboard battery is discharged or the charger chip is damaged	When the keyboard battery is discharged, you may not be able to read keyboard battery status from `cat /sys/class/power_supply/ip5xxx-battery/uevent`, because the charger chip may not have enough power to work just from the keyboard battery alone. Connect the keyboard to the USB power supply and the above mentioned file should become readable, and should contain information about battery voltage and charging current. If it doesn't, try pressing the keyboard's power button while the keyboard is connected to the power supply. You should check the the voltage_now property, to see if it's not close to 2600000 (uV) which is the minimum the charger chip can measure and would indicate the battery is possibly shorted by the charger chip. In that case, the charger chip is damaged. Otherwise you just need to wait a bit for the keyboard battery to charge.
	Charger is damaged	If `/sys/class/power_supply/ip5xxx-battery/uevent` does not become available, even when connecting the USB power supply to the keyboard, and is empty, that means that the charger chip is not responding, even when powered up. That means the chip is most likely damaged.
Some 3 key combinations produce 4 key presses (eg. Alt+Fn+F2 => Alt+Fn+F2+F3)	This is natural to the keyboard matrix	See explanation on my blog
power_supply ip5xxx-battery: driver failed to report `voltage_now' property: -5 in dmesg	When the charger chip is sleeping, it stops responding on the I2C bus	This is normal and harmless. You can wake the chip up by pressing the keyboard's power button, or by plugging in the USB power supply to the keyboard. It only shows up in dmesg when some app tries to read the ip5xxx power supply files in sysfs.