Table of Contents:
The core of the Sxmo UI is based on the dwm window manager patched with (among other patches), the multikey patch. This patch allows dwm to recognize rapid successive (e.g. double/triple clicks) button presses to trigger different actions. The three hardware buttons on the Pinephone thus can trigger 9 different actions.
The default button bindings are:
In addition to the button bindings provided through dwm, a custom application called lisgd was developed to provide touchscreen swipe gestures within Sxmo.
Wherein L=left, R=right, D=down, U=up, the default swipe gestures are:
Note, earlier versions of Sxmo based on lisgd prior to version 0.1 used 3 and four finger gestures; please update to get the up-to-date gestures mentioned above.
Menus are a central feature of Sxmo and are navigable through using the Pinephone's 3 hardware buttons. Also you can use the touchscreen to tap your selection if you'd like as well. The menus are essentially scripts around a custom patched version of dmenu. Note that while using a menu, dwm's button bindings won't be triggered as these grab's are setup to be mutually exclusive from X's point of view.
The default menu bindings for the Pinephone buttons are:
1. Application-specific context menus
The application-specific context menu (triggered by single tapping the volume raise key) lets you you access application-specific features of the currently focused window. For example while using mpv, the application-specific context menu lets you pause the video, increase/decrease volume, seek, etc. You can reference the sxmo_appmenu.sh script for a full list of functionality.
2. Global system menu (Sys)
The global system menu (triggered by double tapping the volume raise button) lets you launch applications, toggle system preferences and more. This is probably the closest thing to 'homescreen' in traditional phone OS's in that it can be the starting point to access much of the functionality in Sxmo. This menu lets you:
3. Global config menu (Config)
The global config menu is accessible by launching the global system menu aforementioned and selecting Config. This menu let you:
A custom application (sxmo_screenlock) enables you to lock the screen so no tap events are processed. This application also allows you to enter suspend (deep sleep / CRUST). You can activate the screen lock by tapping the volume raise key three times quickly or holding the volume raise key down. You will see the Pinephone's blue LED indicator activate.
The Screenlock has three modes:
While using the Screenlock, only the following bindings apply (and override the default dwm button bindings):
When you are in deep sleep mode (entered by tapping volume raise 3 times), you can exit this mode and restore the above bindings by clicking the powerkey once. After exiting deep sleeep mode, within 5 seconds you should either press the volume lower or powerkey 3 times to switch modes or exit. After 5 seconds, the blinking stops and you will be kicked back into deep sleep mode. The purpose of this 5 second timeout is so that if you accidently press the powerkey when the phone is in your pocket, you won't inadvertently be kicked out of CRUST.
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.
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:
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.
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 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
by holding down (or triple clicking) the volume down key. You will
now be taken to a new menu to confirm your message from which you can
edit/send/cancel the 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 every few seconds for new activity and vibrates the phone and blinks the green LED when there is an incoming text/call. This functionality is optional and can be toggled on/off (e.g. to have a 'silent' mode) via the Config menu. By default the modem monitoring is set to off. You can tell if modem monitoring is on as there will be an "M" icon that appears in dwm's bar.
While a call is incoming:
When a new text message comes in:
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 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
Note that you should always prefix numbers you call out with, text to,
or add to the contact system with their international prefix code
but without the plus. Behind the scenes for
mmcli, numbers always
come into the system with international prefixes from my testing. So if
you receieve a call from the number
54321 for example; it would come
into mmcli as
+154321 if this was a US number. To compensate for this
behavior, our scripts strip the plus (
+) symbol but otherwise leave the
number as-is. This means if you dial, text, and store contacts with
the internationl prefix, you can be assured that texts / outgoing /
incoming calls will line up in regards to deduplication of contacts in
menus and text message threads will stay intact.
In the global system menu there are entries for both applications and scripts.
At the time being the primary way to get connected to the Internet in Sxmo
is through wifi. There is a menu entry in the global system menu to connect
to wifi. This is essentially this is just a wrapper to launch
nnmtui. Make sure
the killswitch for Wifi on your Pinephone is in the enabled position.
Mobile data should be manually for now (there is no built in menu to do this); so refer to postmarketos pinephone documentation for that aspect.
You can use the Audio entry in the global system menu to toggle which audio output you want to send sound to.
Note that when in a call, the audio device selected in the global system menu won't automatically apply; rather audio will automatically be initially routed to the earpiece and then changeable through the in call menu. Upon the call ending, audio is always routed back to the headphone jack.
Sxmo's packages are currently distributed through packages in pmOS so
when new package versions are periodically pushed; your install can be
updated through standard mechanisms using
To update run:
apk update apk upgrade
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.
Files and Folders
|$XDG_CONFIG_HOME/sxmo/xinit||Automatically executed script executed upon starting X.|
TSV file wherein each row is: contactnumber TAB contactname
If unset all contacts will show up as 'Unknown Number'
|$XDG_CONFIG_HOME/sxmo/sfeedrc||Sfeedrc file (see sfeed documentation used by RSS script)|
|$XDG_CONFIG_HOME/sxmo/userscripts||Directory to place user scripts which will automatically appear in the menu system|
Executable script to run when the phone is receiving a call / rings
This script is called with "$1" set to the incoming number and contact name.
Executable script to run when the phone is receiving a text
This script is called with "$1" set to the incoming number and contact name.
$XDG_CONFIG_HOME by default is equal to
The following enviroment variables can be set:
|$TERM||Terminal to launch on double-clicking power button and used in scripts. Defaults to `st`.|
|$BROWSER||Browser to launch on triple-clicking/holding power-button and used in scripts. Defaults to `surf`.|
|$KEYBOARD||Keyboard to launch on single-clicking power button and used in scripts. Defaults to `svkbd-sxmo`.|
|$EDITOR||Editor to use to handle files (partial support; full support plans for composing texts etc). Defaults to `vis`.|
|$SXMO_RECDIR||Directory that the Record script will save recordings to.|
|$SXMO_SUBREDDITS||Subreddits (comma-separated) to appear in menu for Reddit script.|
Files of GPS coordinates to populate the locations menu in the foxtrotgps menu.
Each file is expected to be a tsv; the first entry being the location; the second being lat, lon pair.
For setting the above Enviroment Variables and also to launch custom
programs upon starting X you can use the user customizable
described in the Files and Folders section. An example you might use
to get started could look like:
#!/usr/bin/env sh # Launch firefox instead of surf triple-clicking/holding down powerdown export BROWSER=firefox # Prepopulate Subreddits menu with custom subreddits export SXMO_SUBREDDITS="asmr unixporn wtf" # Launch st that says hello world on starting enviroment st -e sh -c 'echo hello world!; read' &
Place the contents above into
~/.config/sxmo/xinit and restart X and
User scripts are custom scripts the user can run via the global
system menu. To add your own custom
userscript, create the
and place your
.sh scripts in the
userscripts directory. If the
userscripts folder is populated with atleast one script, a new
menu item called
Userscripts will appear in the global system
menu. Note, Userscripts should be set to
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.