PinePhone Keyboard Case


Introduction Further Reading

Hardware General USB Ports & Safety Power Supplies Inserting the Phone into the Keyboard Case Pogo Pin Connection Side Button

Keyboard Removing Keycaps Top Row Key Presses Not Registering Ghost Key Presses Keycaps Jamming

Software Keyboard Keyboard Layout & Typing Userspace Driver Custom Layouts Custom Keyboard Shortcuts Keys Repeating or Getting Stuck TTY Switching Typing Not Working

Battery & Charging Charging Reading Battery Values Percentage & Charging Indicator Automatic Suspension Inhibited Charging Not Working

Miscellaneous Upgrading the Firmware Disabling On-Screen Keyboard Permanently Rotating Screen (Wayland/X) Permanently Rotating TTY Bigger TTY Font


Most of what I have written here is based on my own experience of working on and with the device a lot for over half a year, as well as public information from Megi, the developer of the keyboard’s firmware and the most knowledgeable person on this topic. Information on the web about the PinePhone keyboard is scarce and hard to find with search engines, and a lot of it is already outdated. I intend to update this page when I as a user daily-driving the device become aware of new information. Of course I cannot guarantee that everything on this page is correct. If you notice that something is wrong, feel free to tell me so I don’t spread wrong information.

If you need any help or have further questions, feel free to contact me via any of these methods. But keep in mind that I’m by no means an expert. The official forum and chat are also great places to get help.

The entire Keyboard Case add-on is commonly abbreviated as PPKB, along with PP and KB for PinePhone and keyboard.

For a review of my experience using the keyboard, see

If you happen to have any spare change, consider donating to the one and only Megi who has been contributing a lot to the Pine64 community and devices. Among many other things he wrote the keyboard’s firmware. The PPKB would not exist without his hard work. Thank you, Megi :)

Should you still have more change and don’t know of anyone else who needs it more, you can donate to me here.

Things on this page you definitely have to read unless you’re certain you already know enough about them:

USB Ports & Safety Power Supplies Inserting the Phone into the Keyboard Case Pogo Pin Connection Side Button Keyboard Layout & Typing Charging Percentage & Charging Indicator Automatic Suspension Inhibited Disabling On-Screen Keyboard

Further Reading



USB Ports & Safety

The keyboard’s USB port is power-only and supplies both the keyboard battery and the phone with power, so you should use this one to charge the device. If you want to use a dock or any non-charger device, plug them into the phone’s port. Plugging a charger into the phone’s port only charges the phone and not the keyboard battery; you should also disable the keyboard battery with the side button in this situation because otherwise the keyboard battery will unnecessarily charge the phone too, eventually leading to a full phone battery and empty keyboard battery.

Previously it was advised not to use the phone’s USB port at all when the keyboard case is attached. However, Megi has done some tests and concluded that using either port by itself should be safe, only using both at once must be avoided. This means that plugging a power supply into the phone to only charge its battery as well as using a (powered) dock is possible after all. I tried it myself after reading from multiple other people that it worked perfectly fine for them and I can confirm that it appears to cause no issues.

Power Supplies

Use a 5V 3A power supply if possible. The keyboard seems to be quite picky and different people report different results for seemingly similar power supplies. According to Megi and contrary to what I had initially believed, the power supply supporting the Power Delivery specification makes no difference. If you plug a power supply into the keyboard and your phone reports that it alternates between being charged and not being charged, the power supply is supplying too much power and the keyboard is shutting off as a safety measure. Using power supplies supplying too little power (like ≤ 5V 1.5A) could have the supply run too hot and/or break. Less power being supplied also means significantly longer charge times with the big extra battery. Especially if you use a power supply with less than 5V 3A, you have to use some sort of automatic power management, otherwise the phone will not get any power until the keyboard is fully charged. That can take a while and your phone could run out of battery in the meantime.

Inserting the Phone into the Keyboard Case

First, power off the phone. You may also want to make sure the keyboard battery is deactivated by pressing its side button twice or by holding it for 10-15 seconds, otherwise the phone could start powering on as soon as the pins make contact during the insertion process and then potentially lose contact again before the pins are properly connected. Then remove the phone’s back as it will be replaced by the keyboard’s upper part where the phone is to be inserted.

The wiki says to insert the side of the phone with the volume and power buttons first, but a Reddit user whose post I was unfortunately unable to find again had a different method that reliably solves the pin connection issue, at least for them and me. Instead of what the wiki says, insert the side with the camera first. Then press down firmly along the edges, starting on the side with the camera and working towards the side with the microphone. Also press down in the pin area. During all of this you should hear several loud clicks.

This video shows the first time I tried this method and I believe the fourth time I put the phone into the keyboard case in general, so it’s not a perfect example as I lacked experience. I’ve done this many more times since then but I didn’t feel like recording another video. Interestingly the click while pressing down in the pin area seems to have disappeared, but the connection is still perfect and inserting the phone has become easy and fast. Also, you should probably do this over a table and not next to one in case you drop it.

Removing the phone from the keyboard case is simple and works the same way as any other back case: Remove it using the notch in the bottom right corner. While the process is simple, it’s unfortunately not that easy to actually get it off successfully. I’ve found it reasonably easy with longer fingernails but nearly impossible with short fingernails. Grip the inside of the notch with the nail of one hand’s thumb and the nail of the other hand’s index finger and then pull both halves apart. I do not recommend using hard objects like the back of a knife to pry open the notch. I tried that once early on when I had freshly and fully trimmed fingernails and it just put a lot of tiny dents in the notch without getting the back off.

Pogo Pin Connection

Power and data are transferred between the keyboard and phone via the pogo pins on the back. A common issue is the pins not connecting properly and therefore charging and/or typing not working. The general advice to fix the connection is to shim the pins. However, according to someone on Reddit whose post I was unfortunately unable to find again later, the real issue lies with the latch near the pins pushing them away if the phone is inserted into the keyboard case incorrectly. The wiki says to insert the side with the volume and power buttons first, but the Reddit user said to insert the side with the camera first, as described in Inserting the Phone. Initially I had no power connection and could only get the phone to charge for as long as I pressed down on the screen where the pins are located, and typing would stop working intermittently, but ever since I inserted the phone this way I’ve had a perfect connection, even after many times of removing and re-inserting the phone and without ever using a shim. If this still doesn’t solve your connection problem, try the shim method or readjust your existing shim. To do that, see the second row of the troubleshooting table in Megi’s PPKB FAQ and other online resources like this video.

Side Button

The side button toggles the keyboard’s charger chip on and off, meaning that it is used to activate and deactivate the keyboard battery supplying the phone with power. A single press switches it on and either a double-press or a long 10-15 seconds press switches it off. Sometimes a double-press doesn’t work, in that case use a long press which always works. It is always automatically switched on while a power supply is plugged into the keyboard’s USB port. The button only affects the keyboard’s battery and has nothing to do with the keyboard’s typing part which is entirely separate and draws its power from the phone battery.

If the keyboard battery is powered off using the button, its values like how much power it currently holds also cannot be read. Once the keyboard battery is discharged to a degree that is referred to as 0%, it automatically switches itself off. It can be manually activated again with the button in that state but will deactivate itself again shortly after. Discharging the battery too much could render it unusable.

Ideally the battery is entirely handled by software and the button is never used, except to turn the keyboard power mechanism on if it fails to do so automatically, to turn it off if you plan to entirely power down the phone down for a longer period of time or to turn it off while you’re plugging a charger or powered dock into the phone’s USB port (not required but it wastes keyboard battery charge otherwise). Alternatively, the button can be used to treat the keyboard battery similarly to a power bank by manually turning it on to fully charge the phone’s battery and then turning it off again. This is more lossy and less convenient though.

Turning only the battery output off and on via software while keeping the chip active is also possible and allows still reading its values like the percentage. This can be done with sudo ppkb-i2c-charger-ctl power-on/off from Megi’s PinePhone Keyboard Tools. These tools are also available on DanctNIX Arch as ppkb-tools and on the AUR as pinephone-keyboard-git, otherwise see this on how to manually install them. For a more convenient way to toggle keyboard battery output on and off this way, you can also use sudo ppkbbat-toggle from ppkbbat-tools. Bind this toggle to a keyboard shortcut for maximum convenience.


Removing Keycaps

The keycaps can be removed to rearrange ones of the same shape for different layouts like QWERTZ or to fix the issue of some keys not properly registering that they have been pressed. All keycaps, except for enter and spacebar which have two additional fixtures each to stabilise them, are only connected to the keyboard via an x-shaped shaft just like mechanical keys and they can simply be pulled out. Since the space between keycaps is quite small, it’s not that easy to do. Using only fingernails I was unable to reach below two opposite sides of a keycap at once. I recommend pressing down two opposite neighbouring keycaps to widen the gaps between them and then using two long and thin objects as levers, such as small slotted screwdrivers. Be careful not to move the screwdrivers too far under the keys, otherwise you could damage the membrane rings.

To re-insert a keycap, simply put it into position and push it down with a little bit of force until it snaps into place.

Top Row Key Presses Not Registering

This issue was fixed with the second public production batch.

A very common issue is the top row keys being less responsive and requiring more force to be applied when they are already pressed down to have a key press register. I’ve read that this was improved in later production batches but I don’t know if that’s true. Just like with the pin connection issue, there are two different ways of solving it with one allegedly properly fixing the root of the problem. This time I have not yet tried the proper solution, but I plan to eventually and will update this section accordingly.

According to johnnycontrario on the Pine64 forum, this issue is caused by the smaller top row keycaps not having enough space at the top for the membrane below. As you can see in the images above and below, the small top row keycaps have very little space around the ring, especially on the top side opposite to the more slanted side. Pressing keys down flattens the membrane. These smaller keycaps then get the upper part of the membrane stuck between them and the base of the keyboard, preventing them from going all the way down.

The supposed best way to solve this is to remove a part of the keycap to make enough room for the membrane, allowing the keycap to go all the way down and the contacts in the membrane to fully and reliably connect. See johnnycontrario’s forum post for more details and images.

The other commonly used way is to place rings underneath the keycaps. These rings then press the membrane down earlier and make the keycap not go down all the way, again creating the needed room for the membrane. This works but is not that reliable and pressing these keys will feel different as they now have less travel distance and impact on a different, likely softer surface. I used this method with simple paper rings and some keys work very reliable while others still don’t register with a normal amount of force many times. It may also depend on the type of ring that is used.

Multiple people have written about how they did this, for example Avery in this blog post including a 3D-printable model for the rings. I simply used paper with two common utensils: A pair of scissors and a hole puncher. I had hoped that the hole puncher’s punched holes have the perfect size to fit around the ring on the keycap. As it turned out they were just a tiny bit too small, but I was still able to squeeze them on with a bit of fiddling around, and the tightness makes sure that the paper doesn’t fall off, so I guess it’s a good thing and it turned out to be the perfect size after all. So I took a stack of paper, punched a couple of holes in them and cut out a surrounding square with the scissors. One layer of these below the keycaps was still very unreliable, so I added a second layer. Some keys now appeared to activate perfectly while others still sometimes didn’t register. I tried putting on a third layer, but the ring at the bottom of the keycap was already almost fully covered and I was unable to get another layer on, so I left it like this. A third layer also made the keys feel even more different. My top row is definitely not perfect and I frequently mistype my password due to it, but fortunately the backspace key is one of the ones that works perfectly, so it’s been working well enough. I hope all keys will work reliably once I try the other method.

Ghost Key Presses

Unfortunately, ghosting, certain key combinations also activating other keys that were not pressed, is quite prevalent on the PinePhone keyboard. Pressing three keys activates a fourth if they form a rectangle in the electrical grid. For example, pressing Q, W and A at once also activates S as they form a rectangle in the electrical matrix. Take a look at the image below. Pressing Q activates column 2 and row 2. Holding it and then also pressing W activates column 3 and row 2, but row 2 is already active. Only an additional column having been activated is still unambiguous in this case as that must simply mean that the newly pressed key is on the same row as the key that was pressed before. However, if now either A or S are pressed, the result looks identical to the keyboard. Both of these keys are in columns whose signals are already active. Pressing either of them only activates a new row, and the keyboard can’t tell which of the two keys was pressed, so it just tells the phone that both were pressed.

The above image shows the physical keyboard layout with its default symbols at the top and the key positions in the electrical matrix at the bottom. It’s based on Megi’s list of physical coordinates and their corresponding electrical coordinates.

To prevent this rectangle ghosting issue with common modifier key combinations, an additional sixth row is being used in the electrical grid for a few modifier keys and their positions along the x-axis differ from their physical location as well, as can be seen the image above. Shift, Ctrl and Fn OR Alt (but not Fn AND Alt) share neither rows nor columns despite what their physical positions appear to suggest, so key combinations with them work perfectly fine.

In my regular usage I constantly notice this issue in my Meta (Meta, Win, Pine, or whatever you prefer calling it) key combinations as I have set up at least one global shortcut with Meta plus every other key, and a lot of them also use Shift + Meta for even more shortcuts. Shift + Meta share the same column in the electrical grid. Using them with any key from the A to ; or Z to / rows results in a ghost key press from the other row. For example, using the default shortcut to reload Sway, Shift + Meta + C also activates D as they form a rectangle. I work around this by using Shift + Meta combinations only for either the upper or the lower key of these rows, as you can see in the image of all my global shortcuts below, so that the ghost key (usually) doesn’t do anything, other than printing that other character to a potentially open and focused application. Pressing this default Sway reload key combination while having the Sway config open for example will not only reload Sway but also put a D into your Sway config and break it. If a shortcut were also bound to Shift + Meta + D, then both of these shortcuts would always be activated together.

The other situation in which I notice this issue is pressing Ctrl + Fn + Alt + 2 or 3 to switch to TTY 2 or 3. Fn + Alt and 2 or 3 form a rectangle in the electrical grid (but Ctrl does not because it is actually in a different row as you can see in the electrical grid visualisation above), so either combination always switches to TTY 3. But that too can be worked around by just not using TTY 2 or by using chvt 2.

Apart from the rectangle issue, at least 5 keys that don’t form rectangles can be pressed at once before the signals start getting buggy, either again creating ghost presses or held keys no longer sending a signal. If and how much this is an issue for you of course depends on your use. Take a look at the image of the electrical grid above and then see if any key combinations you are likely to use would result in the rectangle issue, and if you could somehow circumvent that.

Keycaps Jamming

This refers to keycaps not going down when pressing them. See Keys Repeating or Getting Stuck for when the keyboard keeps printing symbols or activating modifiers like shift after letting go of the corresponding key which is a fixable software issue.

The keycaps are attached to the keyboard via x-shaped shafts, just like regular mechanical keys, only slightly smaller and with the shaft on the keycap side instead of on the switch. See the images in Removing Keycaps. Unfortunately, in their neutral position, the keycaps are a bit wiggly and pressing down on them with a finger that is a bit off from the center will jam the shaft and therefore prevent the key from being pressed down. It makes pressing two neighbouring keys at once with one fingertip impossible, neither key will go down in that case. To press multiple keys with the same finger, that finger has to be parallel to the keys which is usually the case for the thumbs during handheld thumb-only typing, so putting a thumb in a flat position on both Shift and Ctrl for example works perfectly fine.

This seems not to be a commonly experienced issue, in fact I have only seen someone else mention it once recently and others replied that they don’t notice this. This will become less of a problem the more muscle memory is built up and fingers hit the keys more centered, but even after over half a year I still consider this a little annoying, although most of this time was spend working on the keyboard rather than actually using it to type. Many times a key won’t go down properly or has to be pressed down harder or with a slightly adjusted finger, which is especially annoying when typing very quickly and I have to go back to insert a missing letter where the keycap didn’t go down. The spacebar has additional stabilising fixtures on the left and right end just like larger keys have on big keyboards and this allows it to be pressed anywhere along the x-axis perfectly fine, but pressing it too far at the top or bottom still jams it. The same is the case for the enter key, only vertically. Since pressing keys in their center works perfectly fine, this issue probably affects me disproportionately because I tend to type quite fast on the PPKB but I still don’t perfectly hit the keys a lot of the time, and that’s when they won’t go down. On regular keyboards, if my finger accidentally hits the border between two keys, both just go down. That might result in a typo but it still feels better than the keycaps being stuck. If I type slowly and look at the keys, hitting them perfectly, I don’t notice this at all. I guess I just need more practice with this different keyboard size.

It still just does not feel very good that the keys don’t go down sometimes. I’m not aware of a way to fix this other than purposefully typing slower and developing perfect muscle memory. I hope this will be improved in future versions.



Keyboard Layout & Typing

A driver is required for typing to work. Most distros come with the kernel input driver for the PPKB, so typing in general, although not necessarily the extra symbols of the number row, should work out of the box. To check if you have this driver, you can use modinfo pinephone-keyboard. The old version was called kb151 instead, so if your distro uses an older kernel, try modinfo kb151. The kernel driver uses the Pine key as Win, Meta or whatever you prefer calling it, while it’s another Fn-like driver-level modifier key for one of the two groups of extra number row symbols in the userspace driver. If you don’t have the kernel driver, you can simply use the userspace driver instead which also makes the extra symbols work by default, and skip the rest of this section.

The current kernel input driver features two layers: The regular layer and the Fn layer that gives access to movement keys, F1-10 and Delete. The missing symbols of a regular keyboard that are printed on another layer of the number row keycaps are not accessible at all by default. They were in the old driver, but some could only be accessed if shift was also held. This is all due to the way keyboards work in software. To be able to use the extra symbols, a keyboard layout has to be loaded that maps non-standard symbols to the standardised hardware keys, just like how any other language or otherwise customised layout works.

A layout or rather an xkb model called ppkb that adds the extra symbols may also be included with your distro unless it uses an older version of xkb, but you might have to load it first, in addition to specifying a modifier key of your choice to then access the symbols. If it’s already active, you should be able to type the extra symbols with AltGr or possibly Pine and you can skip the rest of this section. To check if you have the xkb model, you can use cat /usr/share/X11/xkb/rules/evdev.xml | grep ppkb and see if it returns something. If not, you have to either use the userspace driver or a layout from my ppkb-layouts repository, and skip the rest of this section. The latter also includes layouts that add more things like F11 and F12, PageUp and PageDown, international symbols or another set of modifier keys on the right which is especially useful for thumb-only typing as it allows the user to press RightShift with the right thumb and A with the left thumb to type a capital A, for example. It also includes their TTY equivalents, a fix for keys repeating or getting stuck after letting go of them and German layouts.

Xkb is the software handling keyboard layouts on Linux, both on X and on Wayland, so your desktop environment should have a way to set the layout, model and extra options, either in graphical settings or in some config file. The following lists some ways I know of to use the included ppkb xkb model with a modifier option to access the extra symbols (a modifier key to reach level 3).


Put the following into your Sway config ~/.config/sxmo/sway. It only changes the keys of the PPKB, so any other hardware keyboard you connect will be unaffected. You can replace ralt_switch with whatever you want, for example lwin_switch to use the Pine key instead of AltGr as modifier, or use multiple lines for multiple modifiers. Use cat /usr/share/X11/xkb/symbols/level3 | grep xkb_symbols to get a list of predefined modifiers.

input "0:0:PinePhone_Keyboard" {
xkb_model ppkb
xkb_options lv3:ralt_switch
Plasma Mobile

Edit /etc/xdg/kxkbrc with sudo and paste the following lines into it:





Unfortunately I was unable to find out how to set the xkb model on Phosh with the exception of Mobian as described below. If you’re on a different distro and also can’t figure it out, try my custom layouts instead. If you only want the number row symbols and nothing else, use the Simple AltGr or Simple Pine layouts.

On Mobian (not on other distros), at least according to the Mobian Wiki, edit /usr/lib/systemd/system/phosh.service.d/override.conf and add the following lines:


Right Alt might already be selected as the modifier key to type layer 3 symbols, so test if it already works. To set it, open the Settings application and go to Keyboard. Scroll down, tap Alternate Characters Key and select the key of your choice. Right Alt or Left Super (the Pine key) is likely what you want.

If All Fails

If you can’t figure out how to set the xkb model and modifier on your system, try my custom layouts instead. If you only want the number row symbols and nothing else, use the Simple AltGr or Simple Pine layouts. If you can’t figure out how to do that either, use the userspace driver. If that also fails, as a last resort you could simply override the default US layout with the custom one you want to use. See the last paragraph of the xkb install instructions for how to do that.

Userspace Driver

The userspace driver can enable typing on any distribution, even if they don’t come with the kernel input driver. It’s also very simple and quick to modify for custom layouts. It uses both Fn and Pine as driver-level modifiers which both improves and restricts customisability depending on your needs. This also means that not one but two modifier keys now suffer from the bug of causing keys to repeat or get stuck after letting go of them. Since Pine is a driver-level modifier, pressing it on its own does nothing and combinations with other keys only do something if a key code was assigned to the Pine level of that key. By default, the number row has F1-F10 on the Pine level and the other keys don’t have anything. If you want to use Pine as a regular Meta/Win key like with the kernel driver or for more extra symbols on keys that don’t have ones by default, you have to use a custom keymap. My custom Full layouts use Pine as Meta.

The userspace driver is part of Megi’s pinephone-keyboard repository. Some distros include it in their repositories and you can use that version if you don’t want to modify the default keymap. You can get it on DanctNIX Arch with sudo pacman -S ppkb-tools and on the AUR as pinephone-keyboard-git. Read the following part to manually compile it from Megi’s repository (it’s very easy and fast) or skip to this if you already have a compiled version ready.

To compile Megi’s pinephone-keyboard tools, clone the repository by using git clone You may have to install make, gcc and php. If you want to use a custom layout, you now have to edit the file pinephone-keyboard/keymaps/factory-keymap.txt. Then compile it by moving into the directory cd pinephone-keyboard and using make. When it’s done, the compiled executables are located in pinephone-keyboard/build/.

To run the userspace driver, the kernel input driver has to be disabled as both cannot be active at the same time. The kernel driver has been renamed in the newer version, so if you’re still on the old version where Fn + number keys prints symbols, replace pinephone-keyboard.disable_input in the following instructions with kb151.disable_input.

On Manjaro, edit /boot/boot.txt and at the end of the line starting with “setenv bootargs”, add pinephone-keyboard.disable_input. Then use sudo pp-uboot-mkscr and reboot.

On Arch, go to cd /boot, edit boot.txt and at the end of the line starting with “setenv bootargs”, add pinephone-keyboard.disable_input. Then use sudo ./mkscr and reboot.

Execute ppkb-i2c-inputd to run the driver temporarily. To have it active at all times in the background, use e.g. a systemd service as described in the next paragraph.

To create a systemd service, edit /etc/systemd/system/ppkb-inputd.service as sudo and paste the following lines. Adjust the path to ppkb-i2c-inputd to fit yours. It’s likely in /usr/bin/ if you installed it with a package manager. If it’s in your path, you can find its location with which ppkb-i2c-inputd.

Description=PinePhone Keyboard userspace daemon



Start the service with sudo systemctl enable --now ppkb-inputd.service.

Custom Layouts

Keyboard layouts can be fully customised to fit your personal needs, to fix keys repeating or getting stuck after letting go of them or to get the extra number row symbols if your distro doesn’t include the ppkb xkb model yet. My ppkb-layouts repository includes various layouts that add more things like F11 and F12, PageUp and PageDown, international symbols or another set of modifier keys on the right which is especially useful for thumb-only typing as it allows the user to press RightShift with the right thumb and A with the left thumb to type a capital A, for example. It also includes their TTY equivalents, a fix for keys repeating or getting stuck after letting go of them and German layouts. To install layouts, see Installing Layouts. If you want to make your own and/or learn how keyboard layouts work, see Customising Layouts which features instructions for xkb (GUIs), kbd (TTYs), the userspace driver and the kernel driver. If you want me to make a layout for you, see Requesting Custom Layouts.

Custom Keyboard Shortcuts

A physical keyboard of course also opens up the world of keyboard shortcuts like Alt + Tab which make using the device a lot more comfortable and faster. By setting up a lot of them for everything you might need more or less frequently, you will be able to do almost anything almost instantly, just as if or even faster than if you were using a mouse on a regular computer. You can take a look at my shortcuts in the image below (potentially outdated) and in my personal sway config for some inspirations.


You can add shortcuts by editing your Sway config at ~/.config/sxmo/sway. A shortcut definition looks like this:

bindsym $mod+b exec firefox

Definitions start with bindsym followed by the key combination. $mod is the Pine key by default but it won’t work if this key is being used as a modifier for e.g. the additional number row symbols. Multiple modifiers can be stacked, for example $mod+shift+ctrl+m. The key names are whatever xkb symbol they are bound to. You can find any key’s name by executing the command xev and pressing the corresponding key (if you don’t have xev, install xorg-xev). Capitalisation does not matter. The key combination is followed by exec. It won’t work without it. If your shortcut isn’t working, check if you’ve forgotten the exec as I have multiple times. Also make sure not to define the same key combination multiple times. Check if a predefined default shortcut already exists for a key combination you want to define. The last part is the command. This can be anything, or directly a Sway command like reload. It takes your $PATH into account, so you don’t have to specify full paths.

You should also be aware that some key combination produce ghost key presses, most notably Shift + Pine + anything from the A and Z rows as described in Ghost Key Presses. If you plan to use this key combination, make sure to read that section, take a look at the electrical grid and only bind either the upper or lower key from these rows to a Shift + Pine combination, for example either F or V. Otherwise both shortcuts would be activated every time either of them is pressed.

Plasma Mobile

The mobile settings application doesn’t have shortcut settings. Install the desktop settings and the shortcuts module with with e.g. sudo pacman -S systemsettings khotkeys. Now you should have two settings in the app list: The mobile version called Settings and the desktop version called System Settings. The desktop settings used to have a shortcuts menu in the main list to the left but on my test install from November 2022 it wasn’t there anymore. It seems to have been removed according to If this is the case for you too, launch the settings with QT_QPA_PLATFORM=xcb systemsettings instead which will make the shortcut option appear. Now create shortcuts as you would on desktop. Tap Edit at the bottom and use your keyboard arrow keys instead of the touchscreen to select New -> Global Shortcut -> Command/URL. Type in a custom name and press enter. In the Trigger tab to the right, tap Shortcut: None and press your desired key combination. The Pine key is a good fit for this, unless of course you decided to use it as a modifier for additional keyboard symbols. Select the Action tab and type the desired command into the text box. Tap Apply at the bottom right to save it.


Open the Settings application and go to Keyboard. Scroll down and select View and Customize Shortcuts. Here you can configure all kinds of pre-made shortcuts, for example to open applications, change the volume and control media. To make shortcut with a custom command instead, scroll down and select the category Custom Shortcuts. Tap Add Shortcut and type in any name. Put the command you want it to run into the Command field. Then tap Set Shortcut and press the desired key combination. Tap Set and it’s set.

Multiple shortcuts are already set, look through them to find out what they are. I don’t use Phosh and when I tried it out to write this, I was unable to set shortcuts with the Pine key (this key is the same as the Win key on standard keyboards), even though many preset shortcuts work with it.

Keys Repeating or Getting Stuck

This refers to the keyboard continuously printing symbols or activating modifiers like shift after letting go of the corresponding key. See Keycaps Jamming for keycaps not going down when pressing them.

This issue was fixed with the reworked Fn layer handling in the kernel input driver of kernel version 6.1. You only need the workaround described in this section if your kernel doesn’t have this change yet. Note that the userspace driver currently still has this issue, so use the kernel driver if this bothers you.

Driver-based modifier keys (Fn and, if using the userspace driver, Pine) currently have the unfortunate behaviour of not stopping a key press event when the modifier key is let go of before other keys of a key combination, e.g. holding Fn -> holding -> releasing Fn -> releasing will continue to send that keypress indefinitely until you “un-stuck” the affected key by doing the key combination again and releasing Fn last or just pressing the affected key, depending on what works. You can also get normal modifier keys stuck like this, e.g. holding Fn -> holding Shift -> releasing Fn -> releasing Shift will continue sending the Shift signal, making it impossible to use non-shift layers. If it happens, get it unstuck as just described.

To prevent it from happening in the first place, get used to always releasing Fn last which is of course suboptimal, or use other ways of obtaining multiple layers per key that don’t have this issue, like “regular” symbol-level layers like Shift in xkb/kbd or scancode-level layers as with kbct and remove the existing driver-based modifier key functionality. All layouts from ppkb-layouts are compatible with this fix. Unfortunately I have no idea how to remove the Fn and Pine layers from the userspace driver, but I was able to remove the Fn layer from the kernel driver. Since driver/firmware-based layers work perfectly fine in kbct and in other keyboards featuring an Fn key, I assume there must be some way that the PPKB’s drivers too could implement layers that somehow check if an active keycode should still be active based on the actual key still being pressed instead of simply switching the keycode table upon the press of a (modifier) button and treating multiple levels as entirely different keys. So it is possible that this will be fixed in the future and then not require this workaround anymore.

ppkb-layouts includes patch files to modify the kernel driver in its kernel-driver/ directory. The ones that have improved in their name remove the layer functionality entirely and therefore eliminate this bug. To use them you will have to compile the modified kernel yourself as described here, and do so again with every kernel update. If you just want to use the default layout, use the file pinephone-keyboard-regular-improved.patch in combination with my Simple AltGr or Simple Pine layouts. If you want to use a different custom layout from my repository, use this same patch file for any of the layouts from the xkb/kbd-Only Layouts category, or the alternative kernel driver version with improved in its name according to each layout’s listed requirements.

I myself use the full-improved driver that is currently used for all layouts in the “Full Layouts” category. I could make the DanctNIX Arch kernel with this modification publicly accessible in some way if others want to use it too, to possibly spare others the hassle of compiling it themselves. I could also add the regular-improved version while I’m at it. So if you’re on Arch and would like this fix without compiling the kernel yourself every time, contact me via any of these methods.

Just as a note: The full* drivers that are currently used for all layouts in the “Full Layouts” category change some of the default scan codes, most notably / becomes -, ; becomes / and " [ ] are random other codes. They then become whatever key the layout of your choice says, but that won’t be in effect yet during the FDE password prompt during boot. So if you use FDE and your password includes one of these symbols, you might have to press a different key with the full-improved driver (but the PPKB is already a bit restricted for FDE since the extra number row symbols aren’t accessible in that stage either, you have to use the on-screen keyboard for them). Keep that in mind or use the regular-improved driver. The full driver only uses these different scan codes because that is what I used when I made my own personal layout and I build all Full layouts on top of these codes to make them all work with the same modified driver. If this is an issue for you, either wait for me to potentially some day rework the Full layouts to use separate more appropriate scan codes or contribute that yourself.

TTY Switching

TTY switching with keyboard shortcuts works generally with the PPKB. With the current default kernel driver, press Ctrl + Fn + Alt + any number. With the userspace driver or the old kernel driver, press Ctrl + Pine + Alt + any number.

The keyboard shortcuts to switch from a GUI to TTY (not the other way around) directly read scan codes, so they only work with the scan codes that are supposed to be used for F1-F12. The kernel drivers included in ppkb-layouts that remove the Fn layer (*-improved) don’t have these scan codes at all, so the GUI to TTY shortcuts can’t be used with them. Layouts that have these scan codes but F1-F12 mapped to something else, like the mirrored layouts that map them to Fn + AltGr or LFn + RFn require just pressing Ctrl + Fn + Alt + any number. Within TTYs, the switching command is a part of kbd keymaps and they can be mapped to anything. By default you have to use the same as when switching from GUI to TTY (scan codes). With the layouts from ppkb-layouts, using whatever actually prints F1-F12 for the shortcut also works (e.g. LFn + RFn + Ctrl + Alt + any number), but the layouts also add the switching command to the same key combinations that are required to use them in GUIs for consistency. Remember that chvt <number> can also be used, and if you use Plasma Mobile… I mean if your GUI is bugged, TTYescape exists for postmarketOS and in the AUR which allows you to switch to TTY using the buttons on the side of the phone.

Currently it seems like TTY shortcuts from within GUIs don’t work at all, at least on DanctNIX Arch and with the PPKB. I don’t know why that is and it definitely worked before, I used to make plenty use of it, especially when I was still using Plasma Mobile. For now, use the above options of chvt when you have access to a terminal/SSH or otherwise TTYescape.

Typing Not Working

If only the number row extra symbols don’t work, check if holding AltGr or Pine makes them work. If Fn makes some number keys print ~, you are typing F1-F10. Using F5-F8 in a terminal prints ~. The current kernel driver binds the Fn level of the number row to F1-F10. If you still can’t type symbols with any other modifier, go to this.

If you can’t type at all, check if you have the kernel driver like this. If you don’t have it, install the userspace driver.

If you do have the kernel or userspace driver but typing still isn’t working, your pins might not be connecting. Re-insert the phone exactly as described here or read this.

With an appropriate driver and a stable pin connection, typing should always work. The typing mechanism is entirely separate from the keyboard battery, it draws its power from the phone. The keyboard’s side button has nothing to do with it either.

Battery & Charging


The battery and charging indicators of most/all UIs don’t paint an accurate picture of what’s actually going on when the PPKB is connected. See Percentage & Charging Indicator and Reading Battery Values. If you want to skip the lengthy explanations here, just read this and set up ppkbbat-d.

The default behaviour of the PinePhone Keyboard battery is not optimal and presents the user with some issues. These are mostly caused by two things: The charging priority which is KB battery -> PP -> PP battery and the input current limits which are only 0.5A for the PP and 2.3A for the KB. This results in the phone receiving very little power from the KB battery or power supplies, and even when this is modified, the aforementioned order of priorities still makes especially charging with power supplies very difficult. The keyboard battery will take up 2.3A first and only pass the remainder through to the phone. Only when the keyboard battery is full will the priority switch to the phone and supply it with the full amount the power supply can provide. So, especially with the unchanged default behaviour, a power supply as recommended, 5V 3A, is a minimum. Supplying 3A will leave about 0.6A for the phone while the keyboard battery is charging and has priority, which it will have for a couple of hours due to its high capacity. Power supplies with less power may be used but definitely require power management as provided by ppkbbat-d, see a couple of paragraphs below for an explanation.

Now imagine the situation of both batteries being low. You plug a 5V 3A power supply into the keyboard’s USB port. The keyboard battery takes priority as it is not full and receives 2.3A, leaving the phone with the remaining 0.6A from the 3A power supply. 0.6A is about what a PinePhone uses if not doing anything too power intensive. This means, in the best scenario, the PinePhone’s battery will stay constant for a few hours until the keyboard battery is full, and only then start charging. But if the phone uses more power, the percentage will continue to go down for those few hours, possibly reaching 0%. And if you have a power supply with only 1A or 2A, the phone won’t get anything until the keyboard battery has fully charged, and on top of that it will take a lot longer for the keyboard battery to become full, so the phone will most likely go down to 0% first.

It’s currently not possible to influence the charging priority. It is possible to change the input current limits for the keyboard battery and phone battery. Adjusting them dynamically according to the current situation achieves a similar effect, for example setting the keyboard battery’s input limit to the minimum passes more power from a connected power supply through to the phone.

Megi is working on proper PPKB power management that will be integrated into the kernel. Keep an eye out for announcements on Megi’s blog. Until then, the minimum you have to do is setting the phone’s input limit to something higher than the default 0.5A as described in the next paragraph. Alternatively you can use a userspace power management tool that dynamically adjusts the limits, like ppkbbat-d from ppkbbat-tools (Arch-based users may use this PKGBUILD that includes the recommended systemd setup, otherwise read these instructions; you should manually tune it to your power supply if it supplies less than 5V 3A as described here) or kbpwrd.

Setting the limits is not permanent. It resets not only after each boot but also each time a power supply is removed. You can modify the limit of what the phone receives from the keyboard by writing a value in µA to /sys/class/power_supply/axp20x-usb/input_current_limit (PinePhone) or /sys/class/power_supply/rk818-usb/input_current_limit (PinePhone Pro). The common suggestion is to set it to 1500000, but if you want to make absolutely sure the pins won’t overheat you can also set it to 1000000. Use echo 1500000 | sudo tee /sys/class/power_supply/axp20x-usb/input_current_limit for example. To set it permanently using a systemd service, see this.

Charging can work without issues, but the charger chip is very unreliable and strange. When I made ppkbbat-d and ppkbbat-info, it constantly exhibited weird behaviour like not accepting any power from a connected power supply until it is re-plugged. This seems to have been caused mostly by writing to or even just reading the keyboard’s sysfs values. With the recommended ppkbbat-d systemd setup it has been working perfectly for me though.

Reading Battery Values

Most distros come with the kernel driver for the PPKB battery. It’s not required for charging via the keyboard to work, it’s only needed to read and control both the keyboard battery and charging via the keyboard’s USB port. You can check if you have it by using modinfo ip5xxx-power. If you don’t have it, you should still set up a permanent limit for the phone and you can still read some values and control some things by using ppkb-i2c-charger-ctl from Megi’s pinephone-keyboard repository, e.g. ppkb-i2c-charger-ctl info which tells you among other things the keyboard battery’s OCV (4200mV means it’s full, 3000mV means empty). However, you will definitely need a power supply with 5V 3A if you don’t have the kernel driver, otherwise you will experience the issue of the phone losing charge until the keyboard is full as described here because the required power management to solve this relies on the kernel driver.

If you have the kernel driver, the keyboard’s values are exposed in /sys/class/power_supply/ip5xxx-*. If they report nothing, the keyboard battery is either empty or was shut off using the side button. To conveniently read them all at once in a labelled table which is very useful for debugging charging and generally finding out what’s going on with both batteries at any given moment, you can use ppkbbat-info. If you want to read them manually instead, here are some important ones (some paths might be different if you still have the old version of the kernel driver, ppkbbat-info is compatible with both; replace instances of axp20x with rk818 if you use the PinePhone Pro):

cat /sys/class/power_supply/ip5xxx-battery/capacity: Keyboard battery capacity in percent (not that reliable and fluctuates a lot, also not available on older driver versions)
cat /sys/class/power_supply/ip5xxx-battery/voltage_ocv: Open-circuit voltage that is also useful to tell how full the battery is if your distro doesn’t yet support capacity in percent or to get a more reliable non-fluctuating value; 4200000 is full, 3000000 is empty but it’s not linear
cat /sys/class/power_supply/ip5xxx-battery/current_now: The keyboard’s net current value, useful to tell by how much the keyboard battery is charging/discharging
cat /sys/class/power_supply/axp20x-usb/input_current_limit: The maximum current the phone can get from the keyboard battery or keyboard USB port, it’s 500000 by default but should be increased while charging
cat /sys/class/power_supply/axp20x-battery/current_now: The phone’s net current value, useful to tell by how much the phone battery is charging/discharging
cat /sys/class/power_supply/axp20x-battery/status: If the phone is receiving/accepting power from an external source, including the keyboard battery or keyboard USB port

Percentage & Charging Indicator

Sxmo displays all connected batteries separately in the top status bar but most other UIs unfortunately don’t. They usually display the average of all batteries, which is better than nothing but introduces two problems: The phone’s battery could reach 0% and cause the phone to shut down without a warning because the keyboard battery could still hold power and the displayed average could be anywhere up to 50%. And the keyboard battery’s maximum capacity is twice as high as the phone’s, so the average is not very accurate in regard to the actual capacity or remaining battery life. 100% keyboard capacity is about the same as 200% phone capacity. Phosh currently has another issue: With the PPKB connected, it sees a third “ghost battery” that does not actually exist and is always at 0%, and the displayed percentage is calculated as the average of the phone, the keyboard with a very different maximum capacity and another 0%, making the maximum displayed value when both batteries are full 66%. Until these UIs improve their battery indicator or make them customisable like in Sxmo/Sway, there is nothing you can do other than manually reading the values to find out what the percentage of both batteries actually is. I believe in Phosh you can also see the separate percentages in the settings application. A convenient way to get both percentages is binding ppkbbat-notif to a global keyboard shortcut to get a notification containing the percentages at the press of a button.

Another issue is the displayed charging status not telling the full story. The keyboard battery itself is an external power source to the phone, so while the keyboard battery is active (i.e. not empty or shut off via the side button or software) the phone’s status will always be “charging”, which is not necessarily what one would expect or want when no external USB power supply is connected. It also has the unfortunate side effect of preventing automatic suspension since it is usually inhibited while charging, meaning that the phone won’t suspend as long as the keyboard battery is active. This should be changed as described here.

Since Sxmo/Sway is fully customisable, you can do anything you want to the battery indicators, like making the phone battery status only show as charging when the keyboard battery is also charging to solve what was mentioned in the previous paragraph or making the keyboard battery display the maximum as 200% to make both percentages have the same relative value instead of one of them going down twice as fast as the other. Some examples of custom battery indicators with the PPKB can be found here.

Automatic Suspension Inhibited

As already explained here, the phone’s status is always “charging” when the keyboard battery is connected, holds power and was not disabled with the side button or software. Most desktop environments apart from Sxmo inhibit automatic suspension while charging by default, so the phone won’t suspend automatically in these cases which is of course very bad as it will waste a lot of battery power. You should change this if possible.


Open the Settings application and go to Power. Scroll down and tap Automatic Suspend. Activate the switch next to Plugged In and set the delay to the same value as the one above.

Plasma Mobile

Execute kcmshell5 powerdevilprofilesconfig. You can likely only scroll in it using the scroll bar on the side. In the On AC Power tab, activate Suspend session and set it to automatically sleep after the same time as it’s set to in the On Battery tab.

If All Fails

You could also just manually turn the keyboard battery off and on before and after suspend via the physical button or via ppkbbat-toggle, maybe even using it similarly to a power bank instead by manually turning it on to fully charge the phone’s battery and then turning it off again, although that would be more lossy and less convenient than automatic power management. Or just always manually suspend the phone (e.g. systemctl suspend, I used that for a while on Plasma Mobile with a keyboard shortcut), possibly in combination with disabling and enabling the keyboard battery output with ppkb-i2c-charger-ctl power-off/on from Megi’s PPKB tools because otherwise the phone might automatically wake up later and then not go back to sleep.

Charging Not Working

“Charging not working” can have a variety of causes and mean a lot of different things, especially considering that the percentage and charging indicators of most UIs status bar battery indicators don’t accurately tell you what’s going on, so it might be working as intended but you don’t see it in the status bar. You should also set up some sort of power management or at least permanently increase the limit of what amount of power the phone can receive from the phone as described in Charging.

The first thing to check is if you have the kernel driver for the PPKB’s power part by using modinfo ip5xxx-power. Most distros for the PinePhone should have it. If you don’t have it, read the first paragraph of Reading Battery Values.

If you have the kernel driver, ls /sys/class/power_supply/ should return multiple entries containing ip5xxx. To find out what is actually going on with both batteries, take a look at all of their sysfs values which can be done conveniently with ppkbbat-info from ppkbbat-tools.

If ppkbbat-info reports no values for the keyboard, the keyboard charger chip is likely off. This is normal when the keyboard battery is empty or when it was shut off with the side button. Plugging a power supply into the keyboard or pressing the side button should make values appear again. If both don’t make a difference even after multiple tries, check your pin connection.

If ppkbbat-info reports that the PP Status is something other than Charging when a power supply is connected to the keyboard or even when just the keyboard battery itself holds power and was not shut off, except for when the PP battery has recently become full and is above 90%, re-plug your charger if you were charging it or check your pin connection.

If ppkbbat-info reports a negative PP Current when a power supply is plugged into the keyboard, meaning that the PP Capacity is going down, check the KB to PP Limit. If it’s set to 0.5A even a minute after plugging in a power supply, you likely don’t have automatic power management or at least a permanently increased limit set up as described here. If the limit is higher but the PP Capacity is still negative and the KB Status is Charging at a KB Current of above 0.5A, the power from the power supply is going into the keyboard battery as it always charges the keyboard first and not enough is left over for the phone. Automatic power management should solve this. If this still happens with power management, you might have a power supply that supplies less than 5V 3A. In that case you have to decrease the parallel_kb_charge_limit in ppkbbat-d’s config file to a value that makes enough power go the phone while the keyboard still has charging priority. It is also possible that the phone simply uses too much power. ppkbbat-d properly set up should cover this case unless it’s too much for the power supply. To see how much the phone uses, unplug the charging cables and shut the keyboard battery off with a double or long side button press. Then read the PP current again which now tells you just how much the phone uses instead of the net current of what it uses plus what it receives.

If you’re using ppkbbat-d with systemd, you can also access its log by using journalctl -f | grep "$HOSTNAME ppkbbat-d". Omit the -f to see the past log instead of the live log.

If you can’t figure out a solution by yourself, the best way to get help is to provide as much information as possible. Don’t just say “charging isn’t working”, that could mean way too many things. State your OS, desktop environment, phone model, kernel version and drivers, charger specifications which should be printed on it somewhere (especially voltage V and current A), which of the two USB ports you’re using, if and how you either set up a permanently increased limit for what the phone can receive from the keyboard or automatic power management like ppkbbat-d or kbpwrd, and add a sample of ppkbbat-info output from when the issue happens. Give as many details as possible about what isn’t working and what you’re doing while that happens. If applicable and helpful, say what the ppkbbat-d log returns during the issue by using journalctl -f | grep "$HOSTNAME ppkbbat-d". Omit the -f to see the past log instead of the live log and optionally save it to a file with journalctl | grep "$HOSTNAME ppkbbat-d" > ~/ppkbbat-d.log. If helpful or requested, you can save a log of ppkbbat-info for longer observation with ppkbbat-info -l | tee ~/ppkbbat-info.log.


Upgrading the Firmware

If you haven’t done so yet, you should upgrade the firmware to the latest version. The current 1.3 release significantly decreases the amount of power the keyboard uses and fixes the bug of the keyboard consuming too much power when the phone is powered off. See Megi’s blog post for his explanations and upgrade instructions. You will have to do the following:

# download the latest version from, e.g.:
tar -xzvf pinephone-keyboard-1.3.tar.gz
cd pinephone-keyboard-1.3
./arm64/ppkb-i2c-flasher -e i2c -i fw-user.bin write reset

Disabling On-Screen Keyboard


On Sxmo, the on-screen keyboard only opens with a press of the volume down button or a swipe up from the bottom of the screen, so there is no need to disable anything and it can be accessed at any time if needed, for example if the extra number row symbols have not yet been set up or in case of an unreliable connection. It does however open automatically in some Sxmo menus. I’m not aware of a dedicated method to edit the non-hook scripts, but you can edit /usr/bin/ and add a # at the beginning of the line open to disable automatically opening the on-screen keyboard in Sxmo menus.

Plasma Mobile

Swipe down from the upper edge of the screen to open the top menu and toggle Virtual Keyboard off. In older versions of Plasma Mobile where this option does not exist, instead make a long tap on an empty spot of the home screen to open the widget menu and add the on-screen keyboard widget to the home screen. Tapping this widget will enable and disable the on-screen keyboard.


According to ragreenburg on the forum, open the settings, go to Accessibility and toggle Screen Keyboard off. Mobian users can also try the method described on the Mobian Wiki.

Permanently Rotating Screen (Wayland/X)


Add the following line to ~/.config/sxmo/sway:

Plasma Mobile

Execute kcmshell5 kscreen. Set the orientation to Manual, select the last of the four rotated monitor icons and confirm. This is the same settings page as in the mobile settings app but the mobile version might be bugged.

Alternatively, open the settings application and go to Display Configuration. Set the orientation to Manual and select the last of the four rotated monitor icons. In early 2022 I believe this worked fine. In November 2022 I tested it again and the monitor icon would always reset after 15 seconds because of a confirmation dialogue that does not appear in landscape mode. Setting the rotation in the top swipe-down menu to no automatic rotate while it’s in landscape also seems to be not permanent. As long as this happens, use the instructions from the previous paragraph instead.

Permanently Rotating TTY

You have to add fbcon=rotate:1 to the boot parameters.


Go to cd /boot, edit boot.txt and at the end of the line starting with “setenv bootargs”, add fbcon=rotate:1. Then use sudo ./mkscr and reboot.


Edit /boot/boot.txt and at the end of the line starting with “setenv bootargs”, add fbcon=rotate:1. Then use sudo pp-uboot-mkscr and reboot.


If you can’t figure out how to do this on your distro, according to the Pine64 Wiki PPKB FAQ you can also use echo 1 | sudo tee /sys/class/graphics/fbcon/rotate. You could probably make this permanent by automatically running it on boot with e.g. a systemd service by editing /etc/systemd/system/rotate-tty.service, pasting the following code block into it and then activating it with sudo systemctl enable --now rotate-tty.service (untested):

Description=Rotate TTY

ExecStart=/bin/bash -c "echo 1 > /sys/class/graphics/fbcon/rotate"


Bigger TTY Font

To permanently set a different TTY font, edit /etc/vconsole.conf and paste FONT=sun12x22 into a new line. Replace the font name with any you want. This will come into effect after a reboot.

To list installed TTY fonts, use ls /usr/share/kbd/consolefonts. Temporarily try out one by using setfont sun12x22, or remotely via SSH sudo setfont -C /dev/console sun12x22.