After login, you will be presented the SXMO interface as follows:
The core of the Sxmo UI is based on:
Sxmo runs on either Xorg or Wayland, with different but very similar software to make it possible. You may switch between the two environment via the Toggle WM option in the Power menu (provided you have both installed).
Regardless of the environment you use Sxmo consists in a large set of POSIX shell scripts that glue all these
tools together. All these shell scripts comply to the pattern
sxmo_*.sh and can be found in your
directory. A lot of functionality is also in hooks
sxmo_hook_*.sh and can be found in
The status bar (from left to right) has icons for:
The default button bindings are:
In addition to the button bindings, a custom application called lisgd was developed to provide touchscreen swipe gestures within Sxmo. These gestures are sensitive to the edge of the screen where the gesture is initiated or where they end up, and some are sensitive to the length/distance of the swipe. Gestures in the main part of the screen, staying clear of the edges, are usually not interpreted and passed to the underlying application unmodified (assuming it has gesture support).
The SXMO gestures are visualized in the following schematic:
The default swipe gestures are:
There are various default gestures that translate to keypresses for the underlying application, this facilitates navigation in a variety of applications, including terminal-based applications, without needing the virtual keyboard:
Menus are a central feature of Sxmo and are navigable through using the Pinephone's 3 hardware buttons or by swiping down from the top of the screen.
The default menu bindings for the Pinephone buttons are:
You can also simply use the touchscreen to tap your selection if you'd like as well.
Tip: You can close any open menu with a gesture, swipe straight up (vertically) onto the top edge of the screen and all the open menu will close.
Sxmo recognizes five basic states:
The usual workflow is this. If the phone is in the "unlock" state and you wish to suspend it, click the power button once. This will transition to the "screenoff" state which will automatically move to the "suspend" state unless something is blocking it. If the phone is in the "suspend" state and you wish to use it, click the power button once (to move to "lock" state) and then once more to move to "unlock" state.
Sxmo also handles automatic transitions from some states to others.
You can set up suspend blockers in the wakelocks hook.
Sxmo ensures that cron jobs run and will actively wake the phone from sleep temporarily to this end.
The cron daemon is installed but not enabled in postmarketOS. Cron has to be started manually
rc-service crond start) and set to start on boot (
rc-update add crond default). We use a little
program called mnc to wake the phone up before the next planned cron job. We also wrap some sxmo logic in a
dedicated script called
*/15 * * * * sxmo_rtcwake.sh sleep 10
This example will wake the phone up for 10 seconds every 15 minutes. You may want to redirect the standard error output to the main log as shown in the example above.
If you omit
sxmo_rtcwake.sh for a job, the system will not wake up from crust. Note that in such cases, you might want to use
sxmo_wm.sh execwait instead, e.g.:
*/15 * * * * sxmo_wm.sh execwait sleep 20
This will make sure that the SXMO environmental variables are sent to your script.
Calling and texting is fully functional and should work out-of-the-box. Make sure you have the modem killswitch in the enabled position and wait a little bit after booting before trying modem functionality to allow the modem to connect.
As long as your SIM is locked, a lock icon should appear in the status bar. SXMO automatically asks for your SIM's PIN code using a menu (since sxmo 1.4.1).
Alternatively, you can do so from the command-line as follows:
mmcli -i 0 --pin 1234
You could put this in your unlock sim hook (
~/.config/sxmo/hooks/sxmo_hook_modem.sh), but there is of course a
significant security risk involved if your device gets compromised!
To place a new call, you can use the Dialer entry in the global system menu. You will be prompted for a number to dial. Once the call connects, a menu will automatically be launched which let's you:
A proximity lock is automatically enabled that will lock and turn off your screen during a call if you have the phone close to your ear.
To compose a new text message, from the Texts entry you will see a
Send a Text entry which first prompt you for a number. After entering
the destination number you will by default be dropped into a vim-like editor
(vis) to compose your message. Once
your message is as you'd like it, exit the editor using
will now be taken to a new menu to confirm your message from which you can
edit/send/add recipients/add attachments/cancel the message.
To view existing text message threads you can use the Texts entry in the global system menu. This menu will let you tail follow a logfile for your conversation with each number. When a new text is sent or received; the tail will automatically be updated with the new text contents.
While displaying the conversation you can pop out a contextual menu with power up button to reply by text or to start a call with the number.
You can also open a "conversation" window with a gesture from the botton edge. It will open your editor and the virtual keyboard to type your sms. Save and close the file to send the sms. A new editor will be openned again to type a new message.
Monitoring for Incoming Calls/Texts
A vital feature of a working phone is being able to receive new texts and pickup calls. This functionality is made possible through a script that monitors the modem activities and vibrates the phone, plays a notification or ringing sound, and blinks the green LED when there is an incoming text/call.
While a call is incoming:
When a new text message comes in:
To have a working gsm connection you can use the dedicated Networks submenu entry "Add a GSM Network". You then must type the APN your provider gave you. You can then toggle this GSM entry as other network manager ones.
MMS messaging should work just like regular text messaging. When you Send a Text there will be the option to add multiple recipients or attachments. To make mms work, sxmo relies on mmsd-tng. The main configuration will be located in ~/.mms/modemmanager/mms. To make things easier in sxmo, we have a dedicated menu entry in Configuration called Config MMS. This menu will create a default config and you then can edit fields one by one. The script should take care of restarting mmsd when closed.
Note that you likely will not have to configure mmsd-tng, if your settings are already in the database. Consider contributing your own if it is not.
Note that your carrier's nameserver must be present in
order to send/receive mms. This should be automatic. However, sometimes
NetworkManager will place the wifi's nameservers above the carrier's
nameservers, and since
/etc/resolv.conf can only use the first three entries,
the carrier's nameservers will not be used. To fix this, you can set dns=none
/etc/NetworkManager/NetworkManager.conf and use a static
The Sxmo contacts system based on a plain TSV file that can be placed at
$XDG_CONFIG_HOME/sxmo/contacts.tsv. This TSV file is expected to have
two tab separated columns: phonenumber, and contactname. Upon receiving a call if you
have a contact stored associated with the incoming number, the contact
name will appear instead of the number. Also contact names will appear
in the Texts and Dialer menus if they are present in the contacts TSV
file. If no
contacts.tsv is present, or the number is missing from
this file; the contact in menus will show up as
contacts.tsv example might look like:
+122345628 John Smith +128371642 Jeff Foo +31612345678 Jan Janssen
In App and Scripts menu there are some included scripts. See the sxmo_hook_apps.sh and sxmo_hook_scripts.sh for the full list. This is a selection:
Some Included Scripts:
Some Supported Applications:
The application menu supports a wide variety of applications, and will only show them if installed. For some of these applications special context menus are availables. Some of the notable examples are (not exhaustive):
There is a menu entry in the Networks Menu to add an APN and connect to wifi.
This is essentially this is just a wrapper to launch
If your phone has a wifi killswitch (like the Pinephone or Librem 5), make sure it is in the enabled position.
Mobile data can be simarly added via the Networks Menu. It will ask for an APN, you may also consult the postmarketOS pinephone documentation for that aspect.
You can use the Audio Menu to toggle which audio output you want to send sound to.
Sxmo uses pipewire and pulseaudio nowadays. You can access an Audio menu and a Bluetooth menu from the main menu. We use callaudiod to route audio during a phone call.
Currently, bluetooth audio during phone calls does not work. Please see:
Sxmo's packages are currently distributed through packages in pmOS so when new package versions are periodically pushed; your install can be
To update run:
apk update apk upgrade -aiv
There is also a menu entry within the Config Menu to update as well which runs the same commands as above.
For details on what changed between package versions or image releases refer to the changelog.
If a user-defined hook file does not exist on activity, sxmo will run the
corresponding project defined default hook from
For example, if you pickup a call and
/usr/share/sxmo/default_hooks/sxmo_hook_pickup.sh will be run.
Note also that some hooks will be in a subdirectory with a devicename. For
/usr/share/sxmo/default_hooks/ there are
three_button_touchscreen and various names linked to them. (We determine
the name of your device by looking at
/sys/firmware/devicetree/base/compatible.) This allows you to have unique
hooks depending on the kind of device that you are running.
Search above for 'Relevant Hooks' in each section.
Sxmo places its information in ~/.local/state/sxmo.log. You might find the other logfiles in that directory of use as well (e.g. ~/.local/state/superd/logs/*)
The following environment variables can be set in
-o | clickclack -f /usr/share/sxmo/keytap.wav
USfor the Unites States.
The best place to set these default environment variables is in your
~/.config/sxmo/profile if they are sxmo specific.
Other environmental variables that are more device specific can be found in README.md file in deviceprofiles/ in the source. For information on adding a new device, see below.
While developing Sxmo, we will regularly update certain configuration files such as the xinit/sway template, the hooks or whatever. These files are typically a mixture of changes by us and customizations by the user. This mixture gives the user maximum flexibility to adapt Sxmo to their liking. However, when we update such files, the challenge is to ensure that user modifications can be easily merged back in again. Moreover, we must ensure the system is never in a broken state because of outdated configurations and version mismatches.
Whenever your configuration files are out-of-date when starting Sxmo,
they will be moved aside (i.e. renamed with
and the default configuration will take its place. A red notification
will pop up telling you have configuration files that need to be
migrated. This migration is done by running a script named
sxmo_migrate.sh. This script can simply be launched from the
configuration menu or via ssh (recommended).
It first shows the differences between your configuration and the new
default, and allows you to edit and apply your configuration accordingly.
$DIFFTOOL to help you merge your changes. By default
$DIFFTOOL is set to
If you have any pending migrations, always make sure to complete the migration process before making any new changes to your configuration. It is also recommended to keep your configuration under version control (e.g. git).
Sxmo (since 1.8.1) uses explicitly versioned configuration files, meaning that they each carry a simple version hash unique to the file. This version hash is expressed in a comment in the file itself, such as:
# configversion: d8aaf01c9489793bda3686ef23b2b192
You should only update this version hash when
prompts you to do so by showing a diff of a newer configversion hash.
If you want to see what files are disabled and need migration, run
sxmo_migrate.sh state, or run
sxmo_migrate.sh sync state if
you just performed an upgrade and haven't restarted yet. If you want to
revert all your configuration files to the default, then you can
sxmo_migrate.sh reset. This is usually a last resort if you
end up with a broken system and can be considered a kind of factory
reset, all your configuration files will moved out of the way and
flagged for migration then.
The process that checks the versions of your configuration files is
sxmo_migrate.sh sync, it runs automatically when Sxmo starts.
Apk will install new configs as
.apk-new on upgrades if you have modified the original config in
Moreover, when hacking on Sxmo, you will often run
make installand this may "modify"
a config in /etc from apk's perspective.
You can merge apk's config changes by running
doas update-conf. You can also run
to list all the files that have changed from what apk originally installed.
User scripts are custom scripts the user can run via the Scripts Menu.
To add your own custom
userscript, you have two options: edit the
userscripts file or
place a shell script in the
$XDG_CONFIG_HOME/sxmo/userscriptsand write your entries in it, following the appmenu format
<name> ^ <should-return-to-menu> ^ <script-path-or-command>one entry per line. Example:
Weather ^ 0 ^ sxmo_terminal.sh -f "monospace:size=5" sh -c "curl http://wttr.in/ | less -SR"
$XDG_CONFIG_HOME/sxmo/userscriptsdirectory and place your
.shscripts in the
userscriptsdirectory. Note, Userscripts should be set to be executable. You can set a title for the script by adding a comment line of the following ofrmat near the top of the file:
# title="$icon_glb My World"
For examples of scripts Sxmo users have made for their mobile devices, see:
Much of Sxmo's core-functionality in regards to menus are built out via plain shell scripts. So further cutomization should be simple. See sxmo-util's scripts directory to get a better sense of how things are put together. You can edit the scripts on your system for temporary fixes and please consider contributing your changes if you believe your modifications may be useful to other users.
sxmo_files.sh script (accessible via sxmo_appmenu.sh) follows the
XDG MIME Applications
standard. We have our own custom xdg-open implementation called
that will parse the mimeapps.list files and open the default application
as set by the user. To change a default application review
of the mimeapps.list and edit
We use tinydm as login manager. The
tinydm goal is to simply automatically login a target user on boot. You can configure the
UID to login as in
/etc/conf.d/tinydm. (make sure to adapt this if you create a custom user!)
SXMO just provides you with a simple graphical environment on top of your favourite distribution, which by default is postmarketOS for SXMO. PostmarketOS is in turn based on Alpine Linux. You can install any packages your distribution provides from the command line as follows:
$ apk update $ apk add name-of-the-package
To see a categorized list of applications that work well with Sxmo and install the apps via a gui, install and use the appstore.sh userscript.
The built-in application menu of sxmo is only aware of a subset of applications, and will only show them when installed, feel free to add more tools to the menus and submit a patch.
This section describes how to add a new device to SXMO. There are three basic steps:
scripts/deviceprofiles/in the source tree.
configs/default_hooks/in the source tree.
SXMO_DEVICE_NAME is determined by the following code in
tr -c '\0[:alnum:].,-' '_' < /proc/device-tree/compatible | tr '\0' '\n' | head -n1
In the source tree navigate to
scripts/deviceprofiles/ and make a file called
sxmo_deviceprofile_SXMO_DEVICE_NAME.sh. This file should contain various
shell variables that define things unique to your device, e.g., input ids, etc.
There is a
README.md in the same directory that will help.
In addition to the deviceprofile file, which defines things like touch input
ids, etc., you will also want to set a locking workflow for the device. We
have three basic defaults to which all the devices symlink. Navigate to
configs/default_hooks/ in the source tree. You will see there are three
folders and several symlinks. These folders contain various hooks that handle
locking mechanisms. There are at present three basic folders:
desktop. You can also
create your own, but usually you'll just want to symlink to one of these.