Sxmo: Simple X Mobile - System Guide

Project Overview | Documentation | Install Guide | User Guide | System Guide | Contributing | Images | Demo Video

Documentation (Development Version)

This document describes various aspects of how Sxmo runs and is configured.

Start-up Process * U-boot * postmarketOS initramfs * BusyBox init * OpenRC init * X Display Manager - xdm *

Event Handling * Key and Button Presses - dwm * Screen Gestures - lisgd * System Events - udev

Notifications * File format * Handling * Browsing

Start-up Process


The default PinePhone boot priority is first the SD card and then the eMMC so inserting your own SD card with your preferred release will result in the phone booting your image.

postmarketOS initramfs

After the kernel is booted, the script in initial RAM disk runs. This performs various low-level startup and setup tasks, mostly relating to partitions and filesystems. This largely relies on the busybox binary present in the initial RAM disk. When completed the script exec’s a switch_root to the root filesystem and starts /sbin/init which is just a symlink to BusyBox.

BusyBox init

When called as init, busybox will use /etc/inittab for its configuration, if present. Note, busybox has its own interpretation of inittab syntax. The /etc/inittab included in the filesystem specifies the following: * Run /sbin/getty on /dev/tty[1-6] for virtual consoles, and on the /tty/S0 for the serial console. * Run sysvinit actions first, waiting for completion * /sbin/openrc sysinit * /sbin/openrc boot * Run wait actions next, waiting for completion * /sbin/openrc default – this is the “actual” init. * If ctrl-alt-delete is pressed, run /sbin/reboot * When shutdown is initiated, run /sbin/openrc shutdown.

OpenRC init

OpenRC init system is a dependency-based init system that manages system init scripts and the associated services.

Named runlevels in OpenRC are stored in directories under /etc/runlevels. When called with a runlevel as an argument, /sbin/openrc loads the init scripts in the runlevel’s directory, and then run them in alphabetical order, unless a script has dependency information, in which case the order is changed to provide a valid start-up sequence.

X Display Manager - xdm

Details on xdm and the login widget configuration can be found in the xdm man page.

When the user logs out, xdm will run /usr/lib/X11/Xreset which currently only deregisters the user. Then the X server is reset and Xsetup_0 is run again.)

This script, located at /usr/sbin/, sets up the basic interface for Sxmo:

Event Handling

Various processes are started when certain events occur, rather than always being run at startup or login. Some of the most significant ones are listed below:

Key and Button Presses - dwm

The keys and button presses which dwm responds to are specified at compile-time in the config.h for sxmo-dwm. See the userguide for a description.

Screen Gestures - lisgd

The built-in responses to screen gestures that are specified at compile-time in config.h for lisgd, are overridden by command-line specifications in See the userguide for a description.

System Events - udev

A variety of system activities trigger udev events which are matched by rules in /etc/udev/rules.d/ and /usr/lib/udev/rules.d.


Notification Format

Notifications to the user are created by calling /usr/bin/ with the appropriate arguments. These arguments are: * The filepath of the notification to write (or “random” to generate a random id) * If “random” is specified, then the notification file will be created in $NOTIFDIR as specified in /usr/bin/ * Action that the notification invokes upon selecting/tapping the notification window * select/tapping on the notification will trigger removal of the notification, as well as the associated action. * The file to watch for deactivation (which occurs if anything at all happens to the file). * This file, if specified, should be one which will be affected by the user dealing with the interaction, in order to trigger removal of the notification. In the absence of a file, a string representing a non-existent file can be provided (e.g. “none”) * e.g. if a SMS text is removed, the watch file should be the one containing the SMS message, so when the user reads/deletes/saves the message, the notification will be removed. * The text displayed in the notification

The last 3 arguments are written out by, with one per line (though the message text can be multi-line, I think.) into the notification file specified by the first argument.

Notification Handling

When created, notifications in $NOTIFDIR will be processed by /usr/bin/

When started, will scan and display any notifications in the directory specified in $NOTIFDIR, then will begin monitoring that directory for any new notification files.

If a new notification is detected, the following actions are taken by the handlenewnotiffile() function: 1) Checks the validity of notification file ( files must be at least 3 lines long ) 2) The notificationhook() function passes the notification file to the user-defined notification script in "$XDG_CONFIG_HOME"/sxmo/hooks/notification, if present; otherwise, it makes the phone vibrate. 3) The notification message is displayed using dunstify. 4) If the displayed notification is clicked/tapped, then the action specified in the notification file is run. 5) If the specified notification watch file exists, it is watched by inotifywait and upon the report of any event, the notification file is removed.

Notification Browsing

Pending notifications can be viewed by running /usr/bin/ either from a terminal or from the system menu. This script displays the notification times (hh:mm) and the associated messages using dmenu. If selected, the action specified in the notification file is performed and the notification is removed.