Colors of Noise

Entries tagged "phosh".

phosh overview
28th December 2020

phosh is graphical shell for mobile, touch based devices like smart phones. It's the default graphical shell on Purism's Librem 5 (and that's where it came to life) but projects like postmarketOS, Mobian and Debian have picked it up putting it into use on other devices as well and contributing patches.

This post is meant as a short overview how things are tied together so further posts can provide more details.

A PHone SHell

As mobile shell phosh provides the interface components commonly found on mobile devices to

phosh's overview 2 phosh's lockscreen phosh's overview 1

It uses GObject object system and GTK to build up the user interface components. Mobile specific patterns are brought in via libhandy.

Since phosh is meant to blend into GNOME as seamlessly as possible it uses the common interfaces present there via D-Bus like org.gnome.Screensaver or org.gnome.keyring.SystemPrompter and retrieves user configuration like keybindings via GSettings from preexisting schema.

The components of a running graphical session roughly look like this:

phosh session

The blue boxes are the very same found on GNOME desktop sessions while the white ones are currently only found on phones.

feedbackd is explained quickly: It's used for providing haptic or visual user feedback and makes your phone rumble and blink when applications (or the shell) want to notify the user about certain events like incoming phone calls or new messages. What about phoc and squeekboard?

phoc and squeekboard

Although some stacks combine the graphical shell with the display server (the component responsible for drawing applications and handling user input) this isn't the case for phosh. phosh relies on a Wayland compositor to be present for that. Keeping shell and compositor apart has some advantages like being able to restart the shell without affecting other applications but also adds the need for some additional communication between compositor and shell. This additional communication is implemented via Wayland protocols. The Wayland compositor used with phosh is called phoc for PHone Compositor.

One of these additional protocols is wlr-layer-shell. It allows the shell to reserve space on the screen that is not used by other applications and allows it to draw things like the top and bottom bar or lock screen. Other protocols used by phosh (and hence implemented by phoc) are wlr-output-management to get information on and control properties of monitors or wlr-foreign-toplevel-management to get information about other windows on the display. The later is used to allow to switch between running applications.

However these (and other) Wayland protocols are not implemented in phoc from scratch. phoc leverages the wlroots library for that. The library also handles many other compositor parts like interacting with the video and input hardware.

The details on how phoc actually puts things up on the screen deserves a separate post. For the moment it's sufficient to note that phosh requires a Wayland compositor like phoc.

We've not talked about entering text without a physical keyboard yet - phosh itself does not handle that either. squeekboard is the on screen keyboard for text (and emoji) input. It again uses Wayland protocols to talk to the Wayland compositor and it's (like phosh) a component that wants exclusive access to some areas of the screen (where the keyboard is drawn) and hence leverages the layer-shell protocol. Very roughly speaking it turns touch input in that area into text and sends that back to the compositor that then passes it back to the application that currently gets the text input. squeekboard's main author dcz has some more details here.

The session

So how does the graphical session in the picture above come into existence? As this is meant to be close to a regular GNOME session it's done via gnome-session that is invoked somewhat like:

phoc -E 'gnome-session --session=phosh'

So the compositor phoc is started up, launches gnome-session which then looks at phosh.session for the session's components. These are phosh, squeekboard and gnome-settings-daemon. These then either connect to already running services via D-Bus (e.g. NetworkManager, ModemManager, ...) or spawn them via D-Bus activation when required (e.g. feedbackd).

Calling conventions

So when talking about phosh it's good to keep several things apart:

On top of that people sometimes refer to 'Phosh' as the software collection consisting of the above plus more components from GNOME (Settings, Contacs, Clocks, Weather, Evince, ...) and components that currently aren't part of GNOME but adapt to small screen sizes, use the same technologies and are needed to make a phone fun to use e.g. Geary for email, Calls for making phone calls and Chats for SMS handling.

Since just overloading the term Phosh is confusing GNOME/Phosh Mobile Environment or Phosh Mobile Environment have been used to describe the above collection of software and I've contacted GNOME on how to name this properly, to not infringe on the GNOME trademark but also give proper credit and hopefully being able to move things upstream that can live upstream.

That's it for a start. phosh's development documentation can be browsed here but is also available in the source code.

Besides the projects mentioned above credits go to Purism for allowing me and others to work on the above and other parts related to moving Free Software on mobile Linux forward.

Tags: librem5, phosh, planetdebian, planetgnome.
Introducing gtherm
7th January 2020

Continuous temperature monitoring from the kernel's /sys/class/thermal/ in an application can be cumbersome. gtherm aims to make that simpler by providing a daemon (gthd) that exports thermal zones and cooling cells over DBus and providing a small library libgtherm (and GObject introspection bindings). gthcli is a simple command line client that displays the currently found values:

Thermal Zones
      dbus path: /org/sigxcpu/Thermal/ThermalZone/0
           type: cpu-thermal
    temperature: 53,00°C
cooling devices: /org/sigxcpu/Thermal/CoolingDevice/0

      dbus path: /org/sigxcpu/Thermal/ThermalZone/3
           type: max170xx_battery
    temperature: 36,60°C

      dbus path: /org/sigxcpu/Thermal/ThermalZone/2
           type: vpu-thermal
    temperature: 54,00°C

      dbus path: /org/sigxcpu/Thermal/ThermalZone/1
           type: gpu-thermal
    temperature: 54,00°C
cooling devices: /org/sigxcpu/Thermal/CoolingDevice/1

Cooling Devices
    dbus path: /org/sigxcpu/Thermal/CoolingDevice/0
         type: thermal-idle-0
    max state: 100
current state: 0

    dbus path: /org/sigxcpu/Thermal/CoolingDevice/1
         type: 38000000.gpu
    max state: 6
current state: 0

There's support for gnome-usage in the works:

gnome-usage thermal view

Next up is support for trip points (and maybe tuning cooling behaviour from userspace later on).

Tags: gnome, librem5, phosh, planetgnome.
GTK+ and the application id
28th August 2018

tl;dr: If you want to be sure your application will be displayed with the correct icon under different Wayland compositors make sure that your GApplication (or GtkApplication) uses


on GTK+3. On GTK+4 this is handled for you.

Details: While working on touch based window switching for the Librem5 I noticed that lots of the GNOME application did not end up with a proper icon when using g_desktop_app_info_new (desktop_id). The desktop_id is determined from the Wayland xdg surface's app_id as specified by in Wayland's xdg-shell protocol.

The protocol says:

The compositor shell will try to group application surfaces together
by their app ID. As a best practice, it is suggested to select app
ID's that match the basename of the application's .desktop file.
For example, "org.freedesktop.FooViewer" where the .desktop file is

It's even more explicit about the relation of the app_id to the D-Bus service name:

For D-Bus activatable applications, the app ID is used as the D-Bus
service name.

So why does this currently fail? It's because GTK+3 historically uses g_get_prgname() to set the app_id and this defaults to application's basename. But what we rather want is

g_application_id == D-Bus service name == $(basename desktop_file_path .desktop) == xdg app_id

There were patches by Jonas Ådahl to fix this but those were partially reverted since it broke existing applications. Now with GTK+4 around the corner we can fix this. See the migration docs.

This will also allow us to get rid of all the rename-desktop-file in the flatpak manifests too.

(The reason why this currently works in gnome-shell is because there's a private protocoll between GTK+ and GNOME Shell that (among other things) works around this).

Update: to check what app_id Wayland is seeing use:

WAYLAND_DEBUG=1 your_program |& grep 'xdg_toplevel@[0-9]\+\.set_app_id'
Tags: librem5, phosh, planetdebian, planetgnome.

RSS Feed