I recently acquired a PinePhone, and I must say that I am impressed with it. Finally, a real computer that I can fit in my pocket! And it even comes with schematics!
The various volunteers for the respective software packages have done an amazing job putting everything together into something that mostly works as a smartphone. However, there are still a number of rough edges that stop the PinePhone from being usable out of the box as a daily driver. I have spent quite a bit of time tweaking my phone to get it fully usable, and this page documents some fixes for specific issues, and also some discussion on the choice of apps for various purposes. I can't take credit for all of this - many of the fixes are documented elsewhere - but I hope that giving a summary will get other people up and running with the minimum of fuss, and there are also some modifications and patches that I believe to be novel.
I'm hoping to eventually push some of these changes into the upstream packages, so there is more of a chance that things will work out of the box for new users, but I can't say at this stage how difficult this will be or how long it will take. In the meantime, you should be able to take advantage of these changes by following the instructions below.
Here are the details of the system configuration that I am using. The fixes may or may not be applicable to other configurations:
2025-01-11
I have found, at least with my phone provider, that the filenames supplied for MMS attachments (e.g. JPEG photos) do not have filename extensions. It is inconvenient to have to add these manually with the virtual keyboards when saving attachments, so I modified the code to automatically supply an extension based on the MIME type of the attachment. Download the patch against commit 5b17cd8 2024-12-28 of Chatty. The general process of applying the patch is as described above.
I tried out quite a few MP3 player apps before I found one that was to my liking. I'm not much of a fan of apps that force you to use their own "collection"/database of tracks, preferring a simple playlist-based app, similar to the now unsupported XMMS version 1, that I still run on my desktop machines.
I did consider attempting to compile XMMS for the PinePhone, but I could see that it would be a lot of work getting all the dependencies compiled too. Eventually, I discovered Audacious, which appears to be at least a conceptual descendant of XMMS. It actually has switchable user interfaces, and I found the Qt one was mostly usable on the PinePhone. However, there was no easy way to select tracks using the touchscreen, and so I resorted to making some code changes to implement this feature. I mapped a touch in the playlist to the "enqueue" function, though it would also have been possibly to make it play the track directly. (Once a track is highlighted, you can jump to it by displaying the keyboard and pressing enter.) Note that this feature disables the drag & drop playlist reordering, but I thought this was an acceptable price to play.
There was also no support for flick scrolling in the playlist, which slows down navigation considerably, so I added this. (There appears to be no support for this for the QTreeView control, so I had to hack together a manual implementation, but it seems to work well enough.)
A further problem was that the idle timer would time out and stop the music playing. There is a long standing feature request for this on the Audacious site, but no resolution as yet, so I put together a plugin to inhibit suspend while playing, based on the "song change" plugin.
You can download the patch against audacious-plugins 4.4.1 for these features. Note that there is a small bug with the suspend inhibit - it will be in effect as soon as the program starts, even if the music initially starts out paused - but fixing this would require a change to the main program source tree, as well as the plugin.
I looked at quite a few image viewer/gallery applications for the PinePhone. Geeqie, my preferred choice for desktop use, wasn't really usable with the touchscreen. The thumbnail view in pcmanfm was adequate, but needed to be used in conjunction with something else for viewing single pictures. The loupe viewer doesn't have a good gallery view, and it's flick scrolling is quite laggy. I discovered Eye of GNOME (eog) (formerly GNOME Image Viewer), which was a good basic viewer with a gallery view, but it still a couple of usability issues on the PinePhone. It is necessary to be able to easily switch to a full screen display of an image, to make best use of the small screen, and easily toggle between this view and the gallery view. It also lacked flick scrolling. I therefore implemented a few modifications to the code. I made a touch on the image switch to full screen view, and automatically hide the gallery. Another touch returns to the original view, and restores the gallery if it was visible previously. I also implemented basic (non-animated) flick scrolling. While this isn't the best in terms of user feedback, it is functional at least. You can download the patch against commit 8e8e2c7 2024-09-10. This is all a bit of a hack, but it does work.
It appears that there are a number of solutions for getting GPS location data into the various applications that use it, but gpsd is the obvious choice for this. Installation is a simple matter of # apt-get install gpsd xgps. The GPS receiver is a component of the GSM modem, and it has its own virtual serial port for NMEA data at /dev/ttyUSB1. Configuring gpsd to use this is simply a matter of setting DEVICES="/dev/ttyUSB1" in /etc/default/gpsd. However, this is not the whole story. It is necessary for the GPS engine to be powered up before it will output NMEA data on its serial port. The power is controlled via AT commands on the modem serial port, /dev/ttyUSB2, it can be turned on with the command AT+QGPS=1 (Apparently, this can also be made to happen automatically at startup with AT+QGPSCFG="autogps",1, but I experienced problems in getting this setting to persist.)
In the PinePhone, the GSM modem is under the control of ModemManager, so the above AT commands cannot be used unless ModemManager is first stopped. It is also possible to turn the GPS power on using ModemManager, with the command # mmcli -m any --location-enable-gps-unmanaged. I read a forum post about using /etc/gpsd/device-hook to do this automatically when an application connects to gpsd, but this turned out to be surprisingly difficult to get working. The script would not run, and turning on logging in gpsd showed an unexpected exit code from the script. I rebuilt gpsd from source and attempted to run it a debugger, but it suddenly started working, at least until I installed the new binary in /usr/sbin Now thoroughly suspicious, I found that the device-hook script would run correctly, as long as the gpsd binary was not located at /usr/sbin/gpsd
Eventually I traced this problem to the "apparmor" security module disallowing program execution by gpsd. Disabling this allowed the device-hook script to run, but it executed as the "gpsd" user, who does not have sufficient permissions to access the modem using mmcli and DBus. I looked into how the DBus permissions system worked, but couldn't see an easy way of granting this permission. I then considered writing a suid wrapper for mmcli, but eventually found a way to grant the permission via sudo. So, to get the automatic powerup of the GPS working, download /etc/gpsd/device-hook, and chmod it 755. Then, delete /etc/apparmor.d/usr.sbin.gpsd to disable the execution prevention. (No doubt it would be possible to make a more fine-grained control than completely removing all the protection, but I was in no mood to learn how to configure yet another unfamiliar program after all the hassle caused by apparmor. Even without it, the risk is still fairly low, it only protects against possible security holes in gpsd.) Finally, download /etc/sudoers.d/mmcli into /etc/sudoers.d, with permissions 640 and ownership root:root
After having done this, the command gpspipe -r should power up the GPS and start outputting the raw NMEA data. Alternatively, xgps or cgps can be used to view the data in a processed form.
Having got the GPS working, it was necessary to find a suitable mapping application to use on the PinePhone. The default installation included the gnome-maps app, which works, but is a bit basic. I had previously used the KDE "Marble" mapping app on the desktop, which has a fairly comprehensive feature set. (As is often the case, KDE apps are more featureful and configurable, while GNOME apps emphasise simplicity and streamlining for basic use cases.) Although not designed as a mobile/touchscreen app, I found the UI of Marble to be fairly usable at 150% scaling.
However, I did experience some problems getting the position tracking to work. Eventually, I found the "position tracking source" dropdown on the "Location" tab, which needed to be set to "gpsd". However, the application was still not showing the GPS position. Further investigation showed that there was a bug in the way the application processed the data from gpsd, and I was able to fix this. I also added a couple of features that I considered fairly high priority for using the PinePhone for navigation in a car - a "track up" display mode, and inhibiting the screen blanking timeout while in motion. I have prepared a patch against commit be4e4b9 2021-10-17 with these changes. (Note that I was working from quite an old branch, it is possible that these have already been implemented upstream.)
To apply the patch and build Marble from source, run git clone https://invent.kde.org/education/marble, cd marble, and git checkout be4e4b9. Build the source according to the instructions in install/INSTALL, following the instructions for the "Qt app". Download the patch and apply it with git apply johnwa_marble_pinephone_gps_fix_track_up_screen_blank_inhibit_be4e4b9.patch. Rebuild the application and run it. Note the "Orient View to Track" option in the Location tab.
I experienced a number of UI freezes, but these were mostly solved by upgrading to Mobian trixie
There appears to be a considerable amount of ongoing work to improve the camera image quality, and I hope to be able to investigate this myself in a bit more depth at some stage, but I found that a quick fix was simply boosting the colour saturation in postprocessing. Edit /usr/share/megapixels/postprocess.sh, and add the command line parameters -modulate 100,175,100 to the convert command on line 76.
In the interests of better security, it may be desirable to prohibit incoming ssh connections from the GSM WAN interface, and only accept them from a trusted WiFi network, which would typically be behind a firewall. This can be done by setting a static IP address, e.g. 192.168.0.22 in the WiFi network settings, and then adding a ListenAddress 192.168.0.22 line to /etc/ssh/sshd_config. However, this will cause sshd to crash if it starts up while the WiFi interface is down (e.g. out-of-range). Therefore, you should also add a ListenAddress 127.0.0.1 line to the config file, which will always give sshd an interface (the loopback interface) to listen on. It is also necessary to restart sshd when the interface is brought up, which can be done be creating the file /etc/NetworkManager/dispatcher.d/restart-sshd.sh with the following contents:
#!/bin/bash if [[ $1 != "wlan0" ]] && [ $2 != "up" ]] then exit 0 fi killall -HUP sshd
Note that this file must be chmodded 700 (i.e. only readable and executable by root), otherwise it will not be run. The script can also be used to e.g. automatically mount NFS shares when the network is connected
Issue fixed in release 47.0 of gnome-calls
This is related to the sensitivity of the IR head proximity sensor. Add the file /etc/udev/rules.d/10-proximity.rules with the following contents:
ACTION=="add", SUBSYSTEM=="iio", TEST=="in_proximity_raw", ENV{PROXIMITY_NEAR_LEVEL}="32"
The sensor can be monitored with the command monitor-sensor | grep -i prox. The process for deriving the calibration value is documented elsewhere on the web, but the value given above will probably do for a start.
It took quite a bit of effort to find a terminal emulator that was usable on the PinePhone. On the desktop, I have used xterm for over 25 years, never seeing the need to switch to anything using a more modern framework or toolkit. While xterm does start normally under phosh, it permanently loses focus as soon as another X11 application window is opened, making it impossible to type anything. It appears that this is a known issue in phosh that also affects other X11 applications, see issue 301. I'd be interested to hear from anyone who has been looking at this issue, it seems it would open up quite a few more applications to be usable on the PinePhone if it were addressed. Currently unresolved.
With this app, I found that, after the output had scrolled down to the bottom, the virtual keyboard covered the current line, making it impossible to see what you are typing (at least, at the 150% scaling setting). I did dig into the code, it seems that there is a minimum size (number of rows) being enforced somewhere, something to do with the widget layout management, but I'm not familiar enough with GTK+ programming to diagnose this further. It did appear to be in the app itself, rather than the terminal emulator widget (VTE) Currently unresolved.
I therefore found that the best solution for a terminal emulator was to use gnome-terminal. Note that this is distinct from gnome-console/kgx.
There are already a number of custom virtual keyboard layouts for the PinePhone, but I decided to make my own, specially adapted for using command line interfaces and programming. This has more special keys and symbols (dash, slash and tab are particularly important!). While this does mean that the keys have to be somewhat smaller, I have found that it is surprisingly usable. I didn't bother making a separate "terminal" layout, but just made mine the default. There is a separate "wide" version though. Save us.yaml and us_wide.yaml to ~/.local/share/squeekboard/keyboards/.
Although there is an option for this in the config GUI, I had considerable difficulty in getting this to work, being unable to select an audio file. I had to RTFS in order to determine that the file has to be in OGG format - at least, that is what the filter on the file selector is set to, though I wouldn't be surprised if the underlying code is able to handle other formats. While I am all in favour of open formats, I think enforcing them in this manner is taking things a bit far...
This is only applicable for users in Australia using the Aldi Mobile carrier (a reseller for Telstra). Despite setting the values shown on the Aldi Mobile website in Chatty, I was unable to receive MMSs (Credit to Aldi Mobile for putting that info on their website though.) I discovered that the GSM module was only acquiring an IPv6 address, but the proxy given was an IPv4 address. It was possible to force an IPv4 connection by viewing the connections with nmcli con show, then issuing the command # nmcli con mod xxx ipv6.method disabled (replace xxx with your connection name). I found that the telstra.internet APN worked better than the mdata.net.au one.
Note: all patches are released under the license terms of their respective projects.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
loopgain.net