Translation(s): English - Português (Brasil)

Contents

  1. Hardware Accessories
    1. PinePhone Keyboard
      1. Known Issues
      2. Automatic settings
      3. Automatic settings (alternative version)
      4. Automatic settings (Above Solutions Combined)
      5. Charging
      6. Symbol Keys
    2. PinePhone Docking Station/External monitor over HDMI
      1. Packages and checklist
      2. What should happen
      3. Workarounds
      4. Overall experience, other hints

Hardware Accessories

PinePhone Keyboard

Known Issues

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: 

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:

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. 

# 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:

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

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/systemd/user/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:

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:

?PinePhone Pro:

Symbol Keys

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

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/External monitor over HDMI

For the PinePhone Convergence Edition docking station (docking bar), and Debian/Mobian bookworm or more recent, 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" on your PP, no matter what the person responsible for the beamer might think.

Packages and checklist

Packages

Useful installs/commands include 

sudo apt install wlr-randr wdisplays inxi
wlr-randr # to see your currently available display parameters in the terminal
wdisplays # to see display info in a gui
inxi --graphics -xxxz # diagnostic info

Main workarounds

Checklist for what may go wrong and their workarounds:

What should happen

After connecting the docking bar to your phone + external keyboard + mouse + external monitor over HDMI, and waiting for many seconds, you should see a background image in the monitor. You should be able to open a terminal or launch a gui.

You should be able to type in the terminal using the external keyboard or the touchscreen. You should be able to use the mouse to slide the terminal into the monitor screen.

If you fail to get the background image, or if the terminal doesn't open, disconnecting the phone from the docking bar, waiting a few seconds, reconnecting, and waiting, may help. It is unclear if restarting phosh with sudo systemctl restart phosh is relevant.

If you have the background image in the monitor but the terminal only appears on your phone, closing the terminal and reopening it may place it on the monitor. Alternatively, drag the terminal slowly with a mouse.

Workarounds

Lower the resolution

Type wlr-randr or inxi --graphics -xxxz in a terminal. If you don't see 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 switching to a lower resolution can help in several ways (e.g. the cable may send data too slowly for high resolution), e.g. 

wlr-randr --output HDMI-A-1 --mode 640x480 --freq 60.25Hz # where `640x480 60.250000Hz` is one of the modes you found listed as available.

Find a mouse-draggable spot

You should be able to hold down the "super" key (on a typical 2010s "US" style keyboard, this will usually be the key marked by a Windows symbol at bottom left, e.g. between the left Ctrl and Alt keys, or `Fn` and left `Alt` keys) and use the left mouse button to click and drag. If not, then experiment to find which parts of windows (widgets) can be clicked, held, and dragged with the mouse. This might be, for example, a small "no-button" area on firefox: docking_bar_ff_click.jpg; or an odd-looking grey border on a foot terminal that only borders part of the terminal: docking_bar_foot_click.jpg (where to click and drag: tip of red arrow).

Then (slowly if needed), drag and slide the window from the phone to the monitor. In Wayland, these are defined as a single screen.

Avoid logout

For giving a seminar/lecture, you risk distracting your audience with "Sorry, I have to tap the screen to keep it awake" or "Just a moment, I'll retype my password in front of all of you for the n-th time." Better solutions, assuming that you have plugged the docking station itself into a power source, include: 

gnome-session-inhibit --inhibit-only

gsettings set org.gnome.settings-daemon.plugins.power idle-dim false
gsettings set org.gnome.desktop.session idle-delay 3600

Charger current rating/battery condition

For the PinePhone + external keyboard + mouse + external monitor over HDMI, you will likely need a 5V charger that allows for a current up to 3A. The cable will need to be compatible with that.

Lower current ratings may give the result that your keyboard and/or mouse will not be "seen" by your phone.

A battery in poor condition, e.g. one that discharges rapidly, may prevent connecting to the beamer. A new battery is likely needed.

Intermittent blanking hack

Some beamers have intermittent blanking, for a few seconds every few minutes or so, which is often attributed to HDMI cables being too long, independent of the computer used to send the signal. Known workarounds for the PinePhone include: 

sudo systemctl stop eg25-manager

Alternative programs

Be prepared to experiment among different guis such as xpdf, evince and okular for displaying pdf files as full-screen presentations, as these may have some bugs (e.g. April 2024: xpdf: black window; evince: sometimes crashes). A heavy but reliable backup is firefox myfile.pdf. As of April 2024, a gui that works on a normal desktop or your phone screen might have strange edges or fail totally on the beamer screen. Test your preferred program and consider alternatives as backups. In all cases, (re)-learn how to click and drag with a mouse.

Overall experience, other hints

As of June 2024, the above list of workarounds is likely to be enough for giving PP-to-monitor seminars/lectures. However, better have a plan B for your 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 .

Order of plugging in

Megi warned that the order of plugging in the phone and the charger to the docking bar might be significant.

Reboot

As of Mobian/trixie (early 2025), if your phone charging icon does show the lightning symbol when plugged in directly to the power point but does not show it when plugged in via the docking bar, then a reboot may be sufficient (along with the above techniques) to successfully use the external monitor over HDMI.