meta data for this page
  •  

Pinephone Accessories

Pinephone Keyboard

Known Issues
  • You cannot see the charger capacity in settings
  • The Charger defaults to charging at 500 mA, so it may not be enough to charge the phone when in operation
  • You need to `modprobe i2c-dev` to use megi's tools(link megi tools guide or documentation in wiki, git, or discussion). They also need to be compiled from source, as the release version segfaults
  • Fn+F8 and Fn+F10 Alias to = with the kernel driver.
Automatic settings

The following user session service detects the hardware keyboard and disables the on-screen keyboard.

Create this file as ~/.config/systemd/user/kbd-gsettings.service:

[Unit]
Description=PinePhone Keyboard Case detector to disable on-screen keyboard
[Service]
Restart=on-failure
ExecStart=/home/mobian/bin/kbd-gsettings.sh
[Install]
WantedBy=default.target

and this file in ~/bin/kbd-gsettings.sh:

#!/bin/bash
set -euo pipefail
LAST=""
while true; do
  if [ -e /sys/class/power_supply/ip5xxx-battery/voltage_now ]; then
    NEW="false"
  else
    NEW="true"
  fi
  if [ "$NEW" != "$LAST" ] || [ "$(ps -p $(pgrep -n -U $UID phosh) -o etimes=)" -lt 120 ]; then
    gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled "$NEW"
    echo "Keyboard case change, using on-screen keyboard: $NEW" >&2
    LAST="$NEW"
  fi
  sleep 30
done

and then enable the service:

systemctl enable --user --now kbd-gsettings
Automatic settings (alternative version)

Automatic switch between onscreen and hardware keyboard on reboot.

Make a script like this. I named it ~/.local/bin/keyboard-external.sh. I “scale 1” in landscape mode, don't forget to change it to your needs.

#!/usr/bin/env bash
# required: sudo apt-get install wlr-randr #for screen rotation and dpi settings
#
# obsolete 'kb151' driver
# if [ -L "/sys/bus/i2c/drivers/kb151/2-0015" ]; then
# changed to use with 'pinephone-keyboard' driver
if [ -e /sys/class/power_supply/ip5xxx-battery/voltage_now ]; then
  gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false
  wlr-randr --output DSI-1 --scale 1 --transform 270
else
  gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true
  wlr-randr --output DSI-1 --transform normal
fi
# return status
gsettings get org.gnome.desktop.a11y.applications screen-keyboard-enabled

Add this to “~/.config/autostart/keyboard-external.desktop”.

[Desktop Entry]
Name=Keyboard
Type=Application
Icon=object-rotate-left-symbolic
Exec=/home/mobian/.local/bin/keyboard-external.sh
Categories=Utility;
NoDisplay=true

May be there are better solutions. But this works for me at the moment.

Automatic settings (Above Solutions Combined)

This will automatically switch between onscreen and hardware keyboard as a background service. You do need to install wlr-randr. You can either installed it via GNOME Software (or your preferred GUI software manager) or in a terminal:

sudo apt install wlr-randr

Copy this script below to “~/.local/bin/kbd-gsettings.sh”:

#!/bin/bash
set -euo pipefail
LAST=""
DISPLAY=:0
while true; do
  if [ -e /sys/class/power_supply/ip5xxx-battery/voltage_now ]; then
    NEW="false"
  else
    NEW="true"
  fi
  if [ "$NEW" != "$LAST" ] || [ "$(ps -p $(pgrep -n -U $UID phosh) -o etimes=)" -lt 120 ]; then
    gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled "$NEW"
    if [ "$NEW" = "false" ]; then
        wlr-randr --output DSI-1 --scale 1.5 --transform 270
    else
        wlr-randr --output DSI-1 --scale 2 --transform normal
    fi
    echo "Keyboard case change, using on-screen keyboard: $NEW" >&2
    LAST="$NEW"
  fi
  sleep 30
done

Add this to “~/.config/autostart/kbd-gsettings.service”:

[Unit]
Description=PinePhone Keyboard Case detector to disable on-screen keyboard
[Service]
ExecStartPre=/bin/sleep 10
Restart=on-failure
ExecStart=/home/mobian/.local/bin/kbd-gsettings.sh
[Install]
WantedBy=default.target

and then enable the service:

systemctl enable --user --now kbd-gsettings

Note: You can change the “1.5” in the line “wlr-randr –output DSI-1 –scale 1.5 –transform 270” in the script above to fit your scaling needs. By default, Phosh uses a scale factor of “2”.

Warning: Currently, the script doesn't consider if a dock with a keyboard is plugged in or not. So if you do plug in a dock to a PinePhone running that script (make sure the PinePhone keyboard attachment isn't connected at the time), the on-screen keyboard will be enabled.

Charging

WARNING: Do not alter the current limit without knowing what you're doing. 500mA is the safest default to not damage hardware. If you don't have anything plugged into either of the USB-C ports, then it should be fine to change it as shown in the instructions below. If you have a power supply plugged into the keyboard, read through the FAQ before altering the current limit. If you want to connect a power supply directly to the Pinephone, disable the keyboard's battery bank output by double pressing the button on the side of the keyboard first.

The keyboard charges the phone with 500mA by default, to change it to 1500mA do this PinePhone:

echo 1500000 | sudo tee /sys/class/power_supply/axp20x-usb/input_current_limit

PinePhone Pro:

echo 1500000 | sudo tee /sys/class/power_supply/rk818-usb/input_current_limit
Symbol Keys

With the latest version of the keyboard drivers, the Fn-symbol keys disappear. This can be fixed by:

  • Installing xkb-data >= 2.35.1-1mobian1.
  • Setting XKB_DEFAULT_MODEL=ppkb in Phosh's environment. Add the following to /usr/lib/systemd/system/phosh.service.d/override.conf:
[Service]
Environment=XKB_DEFAULT_MODEL=ppkb
  • Reboot or restart Phosh.

After this, the top row symbols will be available as L3-{0-9}. The L3 key can be configured in settings → keyboard → Alternative Characters Key.

New versions of Mobian do not launch Phosh as a systemd service. In that case the override above will not work. Instead, add the following line to ~/.profile:

export XKB_DEFAULT_MODEL=ppkb

and reboot.

Pinephone Docking Station

For the Pinephone Convergence Edition docking station (docking bar), and Debian/Mobian bookworm, you should be able to plug in an external keyboard and mouse through the usb ports, and use an external monitor (a desktop monitor or a beamer or tv screen for a seminar, lecture, or other presentation). You will need direct HDMI access - typically you may have to select the “source” button on a remote control for a beamer. You do not need to “install an app” as some proprietary “presentation” software packages or “software-must-control-us” humans try to convince you to do. You should install wlr-randr:

sudo apt install wlr-randr
wlr-randr # to see your currently available display parameters.
  • You should see a background image in the monitor. Open a terminal such as foot (low cpu usage) or kgx (high cpu usage, more powerful).
    • If you fail to get the background image, or if the terminal doesn't open, you may have to disconnect and reconnect a few times, or do some tests.
      • Try wlr-randr in a terminal. If you don't get a section for HDMI-A-1, then your phone is not in communication with the monitor.
      • If you do get an HDMI-A-1 section then you can try a lower resolution, since the pinphone may not have enough RAM for high resolution, e.g. wlr-randr –output HDMI-A-1 –mode 640×480 where 640×480 is one of the modes you found listed as available.
      • If you have the background image in the monitor but the terminal only appears on your phone, try closing it and reopening it.
  • Type in the terminal using the external keyboard or the touchscreen. Use the mouse to slide the terminal into the monitor screen.

For giving a seminar/lecture, plug the docking station itself into a power source and temporarily change your power settings against screen dimming and suspension and extend your auto-logout time; otherwise you'll distract your audience with “Sorry, I have to tap the screen” or “Just a moment, I'll retype my password in front of all of you for the n-th time.” Remember to reset these to their normal values after your lecture.

As of December 2022, better have a plan B if you're giving a seminar or lecture; display on the monitor may not always work and there is not much documentation, except for Megi's notes, e.g. at https://xnux.eu/log/#033 . There's an obsolete pine64 link. The technical description of the PP docking bar is at https://xnux.eu/log/#063 .

Pinephone Pro docking station: should probably work. See Megi's debugging and coding notes at https://xnux.eu/log/#053 and earlier pinephone notes at https://xnux.eu/log/#050 and https://xnux.eu/log/#045.

Early Braveheart Edition and the Ubports Community Edition: see mods for hardware hacks for these early pinephones.