Simple X Mobile (SXmo) Notes

Sxmo, or Simple X Mobile, is a collection of simple and suckless X programs and scripts used together to create a fully functional mobile UI adhering to the Unix philosophy for the Pinephone. You control the UI largely through using the Pinephone buttons (press different numbers of times quickly for different actions) and swipe gestures.1

UI Controls

Default button bindings:

  • Volume Raise:
    • 1 tap: Launch application-specific context menu
    • 2 taps: Launch global system menu
    • 3 taps (or hold): Activate screen lock
  • Volume Lower:
    • 1 tap: Toggle dwm layout algorithm (between monocle/tile/bstack)
    • 2 taps: Shift current client in stack
    • 3 taps (or hold): Kill client
  • Powerkey:
    • 1 tap: Toggle svkbd onscreen keyboard
    • 2 taps: Launch st (terminal)
    • 3 taps (or hold): Launch surf (browser)

Swipe gestures

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:

  • 1 finger R-to-L: Focus next tag
  • 1 finger L-to-R: Focus previous tag
  • 1 finger LD-to-RU: Increase volume
  • 1 finger RU-to-LD: Decrease volume
  • 1 finger RD-to-LU: Increase brightness
  • 1 finger LU-to-RD: Decrease brightness
  • 2 fingers R-to-L: Move focused application to next tag
  • 2 fingers L-to-R: Move focused application to previous tag
  • 2 fingers D-to-U: Launch onscreen keyboard, svkbd
  • 2 fingers U-to-D: Close onscreen keyboard, svkbd

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. Note that while using a menu, dwm’s button bindings won’t be triggered as these grabs are setup to be mutually exclusive from X’s point of view.

The default menu bindings for the Pinephone buttons are:

  • Volume Raise: Previous item
  • Volume Lower: Next item
  • Power: Select item

Customization

User Customizable Functionality

Files and Folders

Filepath Description
$XDG_CONFIG_HOME/sxmo/xinit Automatically executed script executed upon starting X.
$XDG_CONFIG_HOME/sxmo/contacts.tsv 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
$XDG_CONFIG_HOME/sxmo/hooks/ring 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.
$XDG_CONFIG_HOME/sxmo/hooks/sms 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.

Note: $XDG_CONFIG_HOME by default is equal to ~/.config

Environment Variables

The following enviroment variables can be set:

Environment variable Description
$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.
$SXMO_GPSLOCATIONSFILES 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 latitude, longitude pair.

User-customizable xinitrc

For setting the above Environment Variables and also to launch custom programs upon starting X you can use the user customizable xinit 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 customize away.

User Scripts

User scripts are custom scripts the user can run via the global system menu. To add your own custom userscript, create the $XDG_CONFIG_HOME/sxmo/userscripts directory and place your .sh scripts in the userscripts directory. If the userscripts folder is populated with at least one script, a new menu item called Userscripts will appear in the global system menu. Note: Userscripts should be set to be executable.

Further Customization

Much of Sxmo’s core-functionality in regards to menus are built out via plain shell scripts, so further customization should be simple. See sxmo-util’s scripts directory to get a better sense of how things are put together.

  1. (https://sr.ht/~mil/Sxmo/) ↩