Jump to content

Catacomb

From postmarketOS Wiki
Catacomb
Catacomb homescreen running on Xiaomi Redmi Note 5A.
Catacomb homescreen running on Xiaomi Redmi Note 5A.
Name Catacomb
Graphics stack Catacomb on Wayland
Toolkit Skia
In postmarketOS
Package N/A
Status Unavailable

Catacomb is a Wayland compositor and desktop environment designed to run on low end hardware with limited battery life like the PinePhone. It aims to provide responsiveness without cutting down on features.

Installation

Catacomb requires OpenGL ES 2.0 support and runs best on Mainline Linux. Both OpenRC and systemd are just as well supported. However, running it on downstream kernels may not work at all or may be buggy, given the focus is on mainline.

A package for catacomb is currently being merged. Once merged, you can simply select it in pmbootstrap:

$ pmbootstrap init
[...]
[17:05:41] Available user interfaces (31): 
[...]
[17:05:41] * catacomb: (Wayland) Lightweight Mobile interface optimized to run on low-end hardware
[...]
[17:05:41] User interface [phosh]: catacomb

Or you can manually install it with:

# apk add postmarketos-ui-catacomb
# apk add alacritty epitaph gorm grim slurp squeekboard swayidle tabula ttyescape tzompantli # optional packages pulled by pmbootstrap

# tinydm-set-session -f -s /usr/share/wayland-sessions/catacomb.desktop
# rc-update add tinydm || systemctl enable tinydm
# rc-service tinydm start || systemctl start tinydm

Components

The Catacomb UI consists of:

  • Catacomb — compositor
  • Kumo — web browser
  • Charon — maps and navigation
  • Tzompantli — application drawer
  • Epitaph — panel and quick actions
  • Gorm — Wi-Fi scanning app
  • Pinax — notes
  • Tabula — wallpaper
  • Aevum — alarm clock

Some Catacomb components are currently missing in postmarketOS: Pinax, Aevum, Charon, and Kumo. For now you can use the Flatpak versions of them if you want, packaging them in Alpine is on TODO (reach out if you want to help!)

Configuration

Catacomb's configuration is a shell script, by default located at /etc/catacomb/initrc. To modify it, you can copy it to your home directory:

$ mkdir -p ~/.config/catacomb
$ cp /etc/catacomb/initrc ~/.config/catacomb/initrc

This is where programs are autolaunched and where keybindings are set (using IPC messages catacomb msg).

Usage

Catacomb is launched by tinydm. Once launched, hold Power to bring up an app launcher. You can launch apps from there, and shutdown/reboot your device.

Swipe from the bottom to reveal the apps overview. This is where running apps are shown.

More details are available on the website: Project homepage.

Tips and tricks

Manually showing the on-screen keyboard

Usually, the keyboard shows up automatically when needed. However, it doesn't always work for some apps. For these, you can tap on the navigation hint at the bottom of the screen to reveal it.

Clock on the homescreen

One can use Conky or Wayout to show a clock on the homescreen.

Install conky:

$ sudo apk add conky

A basic configuration for it might be:

-- Save this as ~/.config/conky/conky.conf
conky.config = {
    out_to_wayland = true,
    out_to_x = false,
    alignment = 'middle_middle',
    own_window_transparent = true,
    own_window_type = 'desktop',
    font = 'Adwaita:size=17',
    use_xft = true,
    update_interval = 15,
    gap_x = 40,
    gap_y = 40,
}
conky.text = [[
${alignc}${font Adwaita:size=70:style=Bold}${time %H:%M}${font}
${alignc}${font Adwaita:size=15}${time %a %d %b %Y}${font}
]]

Then conky can be auto started by adding it to the initrc:

conky &

Working around the notch

Catacomb has native support for deadzones, which can be used to tell it to not render UI elements in certain areas. Furthermore, epitaph (statusbar) can be made to not show anything underneath it.

Add the following to your initrc:

catacomb msg deadzone global --orientation portrait --bottom 90
catacomb msg deadzone global --orientation inverse-portrait --top 120
catacomb msg deadzone global --orientation landscape --top 105 --bottom 105 --left 10 --right 10
catacomb msg deadzone global --orientation inverse-landscape --top 105 --bottom 105 --left 10 --right 10
catacomb msg deadzone fullscreen --top 105 --bottom 105 --left 10 --right 10

You can tweak these values to your liking.

For the status bar, you can simply set the height and padding and move any elements at the center, to the sides (assuming the notch is at the center):

# Save this as ~/.config/epitaph/epitaph.toml
[geometry]
height = 40
padding = 40

[modules]
left = ["Clock"]
center = []

[landscape]

[inverse_portrait.geometry]
height = 30
padding = 40

Notifications

This UI does not ship any notification daemon. However, one can install mako.

Install mako:

$ sudo apk add mako
$ mkdir -p .config/mako

Create a new file .config/mako/config with the following contents:

history=1
default-timeout=20
max-history=10
max-visible=1
margin=10,2
width=400
padding=15
anchor=top-center
on-notify=exec tremor 90 100 2

Then add mako to the initrc:

mako &

To learn more about mako's configuration options:

$ sudo apk add mako-doc
$ man 5 mako

See also