NAME¶

sxmo - a simple X mobile operating system

SYNOPSIS¶

sxmo is a collection of simple and suckless programs and scripts used together to create a fully functional mobile user interface adhering to the Unix philosophy. We focus on Linux smartphones such as the Pinephone. Sxmo is primarily written in POSIX shell scripts and can be easily modified and extended using our hook system.

Sxmo >= 1.6.0 runs both on Xorg (using dwm) as well as on Wayland (using sway). The X in our name historically referred to Xorg, but is now open to whatever interpretation you prefer (eXtensible, eXcellent, eXperimental, etc...)

A brief overview of sxmo's features (in order of presentation):

And more (not documented here):

Sxmo 1.4.1 was presented at AlpineConf 2021, you can watch the video.

DESCRIPTION¶

Sxmo uses tinydm(1) to automatically launch the window manager of your choice (sway(1) or dwm(1)). Note: You can configure the UID in /etc/conf.d/tinydm. Make sure to change this if you create a custom user. You may switch between the two window managers in the Power Menu.

Once the window manager launches, it will execute sxmo_hook_start.sh. Sxmo relies on superd(1) and sxmo_daemons.sh(1) to launch various applications from this start hook. You can edit the start hook directly and also edit ~/.config/sxmo/profile and ~/.profile to override certain common environmental variables such as background image (see ENVIRONMENT). Note that sxmo respects the xdg specification, e.g., $XDG_CACHE_HOME, $XDG_CONFIG_HOME, etc.

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 most can be found in your /usr/bin/ directory.

HOOKS: sxmo_hook_start.sh (what executes on startup)

SEE ALSO: tinydm(1), superd(1), sxmo_daemons.sh(1)

HOOKS¶

A lot of functionality is also contained in hooks (sxmo_hook_*.sh). Sxmo uses PATH to determine which hook executes. It will look first for hooks in ~/.config/sxmo/hooks/ before it looks in /usr/share/sxmo/default_hooks/. For example, if you pickup a call and ~/.config/sxmo/hooks/sxmo_hook_pickup.sh does not exist, /usr/share/sxmo/default_hooks/sxmo_hook_pickup.sh will be run.

Note that some hooks are in a subdirectory under the hooks/ main directory which will allow you to have hooks associated with a certain device. See DEVICES. For instance, in /usr/share/sxmo/default_hooks/ there are several device subdirectories, one of which will be your $SXMO_DEVICE_NAME. It should be a symlink to another subdirectory, e.g., one_button_ereader or three_button_touchscreen. Device-specific hooks go here.

While you can manually copy and edit hooks to your liking, sxmo_hookmenu.sh (MENU > config > hooks) simplifies this process.

Note also that hooks do not have their own man pages. We have documented each hook in the comments of that hook.

STATUSBAR¶

After login, you will be presented the sxmo interface as follows:

https://sxmo.org/assets/screenshot.jpg

The statusbar relies upon sxmobar(1). It has space for the following information (from left to right) has icons for:

HOOKS: sxmo_hook_statusbar.sh (override look and feel of the statusbar), sxmo_hook_icons.sh (adjust icons)

SEE ALSO: sxmobar(1)

INPUT¶

The main forms of input are Hardware buttons (power, raise volume, lower volume), Touchscreen (i.e., touching the screen), and Gestures (i.e., swipes). Sxmo also allows input for a Hardware keyboard (e.g., the pinephone keyboard case or a bluetooth keyboard) and a Stylus. Sxmo also supports a virtual keyboard (svkbd(1) or wvkbd(1)).

MENUS¶

Menus are a central feature of sxmo and are navigable through using hardware buttons. On three button devices like the pinephone:

You can also simply use the touchscreen to tap your selection if you'd like as well.

In addition to a Main Menu, each application can have its own Context Menu associated with it which defines functions unique to that application (e.g., zoom in, zoom out, etc.).

If no application is focused, swiping down from the top of the screen, or pressing the volume raise button once, will bring up the Main Menu. If an application is focused, this will bring up the application's Context Menu instead. (To access the Main Menu while an application is focussed, press the volume raise button twice.)

You can close any open menu with a gesture: swipe straight up (vertically) onto the top edge of the screen and all the open menus will close. See INPUT.

HOOKS: sxmo_hook_apps.sh (what shows up on Apps submenu), sxmo_hook_scripts.sh (what shows up in Scripts submenu), sxmo_hook_contextmenu.sh (controls the content of all the menus, including contextmenus), sxmo_hook_icons.sh (icons)

 Weather ^ 0 ^ sxmo_terminal.sh -f "Sxmo:size=5" sh -c "curl http://wttr.in/ | less -SR"

# title="$icon_glb My World"

STATES¶

Sxmo recognizes five basic states:

A diagram of the states can be found here:

https://sxmo.org/assets/lock-power-states.png

The usual workflow is this.

Sxmo also handles automatic transitions from some states to others.

You can set up suspend blockers in the wakelocks hook.

HOOKS: sxmo_hook_postwake.sh (what to do after waking up from suspend state), sxmo_hook_lock.sh (what to do when transitioning into lock state), sxmo_hook_screenoff.sh (what to do when transitioning into screenoff state), sxmo_hook_unlock.sh (what to do when transitioning into unlock state), sxmo_hook_wakelocks.sh (set what block suspend)

CRONJOBS¶

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 with rc-service crond start and set to start on boot with rc-update add crond default. We use a little program called mnc(1) to wake the phone up before the next planned cron job. We also wrap some sxmo logic in sxmo_rtcwake(1) which launches the cronjob and puts the phone back to sleep when finished.

*/15 * * * * sxmo_rtcwake.sh sleep 10

This example will wake the phone up for 10 seconds every 15 minutes.

If you omit sxmo_rtcwake.sh for a job, the system will not wake up from crust to execute the job. Note that in such cases, you might want to use sxmo_wm.sh execwait instead as this will set most of the sxmo environment variables, e.g.:

*/15 * * * * sxmo_wm.sh execwait sleep 20

HOOKS: sxmo_hook_mnc.sh (change the program that calculates when to wakeup)

SEE ALSO: sxmo_rtcwake.sh(1), mnc(1)

CALLS AND TEXTING¶

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.

The scripting behind the scenes works via mmcli(1).

mmcli -i 0 --pin 1234

CONTACTS¶

The sxmo contacts system based on a plain TSV file that can be placed at ~/.config/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 ???. A contacts.tsv example might look like:

+122345628	John Smith
+128371642	Jeff Foo
+31612345678	Jan Janssen

SEE ALSO: sxmo_contacts.sh(1)

WIFI¶

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 nmtui(1).. If your phone has a wifi killswitch (like the Pinephone or Librem 5), make sure it is in the enabled position.

HOOKS: sxmo_hook_network_up.sh (what to do when network goes up), sxmo_hook_network_down.sh (what to do when network goes down), sxmo_hook_network_preup.sh, sxmo_hook_network_predown.sh

AUDIO¶

You can use the Audio Menu to toggle which audio output you want to send sound to. Sxmo uses pipewire(1) and pulseaudio(1). We use callaudiod(1) to route audio during a phone call.

Currently, bluetooth audio during phone calls does not work. Please see:

SEE ALSO: sxmo_hook_call_audio.sh (adjust volume after/before a call)

BLUETOOTH¶

To enable bluetooth, toggle it in Config. A Bluetooth Menu will appear in the Main Menu.

UPDATING¶

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 do this.

After you update the sxmo packages themselves, be sure to run sxmo_migrate.sh(1) to upgrade your (local) config files.

SEE ALSO: sxmo_migrate.sh(1)

NOTIFICATIONS¶

TODO

SEE ALSO: sxmo_notificationwrite.sh(1)

DEVICES¶

This section describes how to add a new device to sxmo. There are three basic steps:

tr -c '0[:alnum:].,-' '_' < /proc/device-tree/compatible | tr '0' 'n' | head -n1

MISC¶

sxmo offers so much more. For instance, sxmo_rotate.sh(1) for screen rotation, TODO

ENVIRONMENT¶

Hint: type env to see environmental variables. Environmental variables can be overridden (generally) in ~/.config/sxmo/profile or ~/.profile. See also ~/.Xdefaults, ~/.config/sxmo/xinit, and ~/.config/sxmo/sway.

sxmo respects the xdg protocal, falling back to some sane defaults if this is missing on your system. The most relevant ones are:

When the system boots, tinydm will will run either sxmo_xinit.sh or sxmo_winit.sh depending on if you are running Xorg (dwm) or Wayland (sway). Each of these then will load /etc/profile.d/sxmo_init.sh which will set the following environmental variables. Hint: you can type _sxmo_grab_session from the commandline to reload these (e.g., if you switch window managers but are logged into an ssh connection).

It will then also set the following variables:

It will then load everything in ~/.Xresources and ~/.config/sxmo/xinit (if dwm).

You might also want to set various variables not listed above:

There are other environmental variables that are device specific. See DEVICES. As well, several scripts have their own environmental variables which we do not list here.

FILES¶

~/.local/state/sxmo.log - sxmo's logfiles

~/.config/sxmo - most sxmo config files

~/.config/sxmo/hooks - your local hooks. See HOOKS

~/.config/sxmo/userscripts - either a file or a directory containing your userscripts. See MENUS.

~/. TODO

AUTHORS¶

TODO

REPORTING BUGS¶

TODO

COPYRIGHT¶

TODO

SEE ALSO¶