@@ 16,36 16,37 @@ After login, you will be presented the SXMO interface as follows:
The core of the Sxmo UI is based on:
-* a tiling window manager (either [sway](https://swaywm.org) if you are running on
+* a tiling window manager ([sway](https://swaywm.org) if you are running on
Wayland, and [dwm](http://dwm.suckless.org) if you are running Xorg)
* a menu program ([bemenu](https://github.com/Cloudef/bemenu) on Wayland, [dmenu](https://tools.suckless.org/dmenu/) for Xorg),
* a gesture deamon for the touchscreen ([lisgd](http://git.sr.ht/~mil/lisgd))
* a virtual keyboard ([wvkbd](https://github.com/jjsullivan5196/wvkbd) on Wayland, [svkbd](https://tools.suckless.org/x/svkbd/) on Xorg)
-As you see, 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 *Configuration* menu (provided you have both
+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).
-Sxmo itself consists, regardless of the environment you use, of a large set of POSIX shell scripts that glue all these
+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 ``/usr/bin/``
-directory.
+directory. A lot of functionality is also in hooks ``sxmo_hook_*.sh`` and can be found in ``/usr/share/sxmo/default_hooks/``
+or ``~/.config/sxmo/hooks``.
### **Status Bar**
-The status bar located at the top displays the various workspaces that you have in the form of the numbers 1,2,3,4.
-Tapping one of these numbers will take you to that workspace. If you are running dwm rather than sway, you see right next to it (the three lines) the
-layout that is activated (see [layouts](#stronglayoutsstrong)). The default layout is a vertical stack.
+The status bar located at the top displays the various workspaces that you have in the form of the numbers 1,2,3,4. (Inactive workspaces are not shown.)
+Tapping one of these numbers will take you to that workspace. If you are running dwm rather than sway, you will see right next to it the
+layout that is activated (see [layouts](#stronglayoutsstrong)). The default layout is a vertical stack (three lines).
-At the top-right you see the status menu, holding various symbols:
+At the top-right you see the status icons:
-* A signal bar icon shows that you have a GSM connection
-* GMS icons shows that you have a data connection (2G/3G/4G)
-* The little phone icon indicate that the modem monitor is running, this needs to be running to receive calls and texts.
-* The wifi icon indicates you are connected to a wireless network (note: the icon does not reflect signal strength)
-* The battery icon shows your battery stage and whether it is charging or not (small lightning symbol)
+* A signal bar icon shows that you have a GSM connection and what strength it is.
+* GSM icons shows that you have a data connection (2G/3G/4G)
+* The wifi icon indicates you are connected to a wireless network and what strength it is
+* The battery icon shows your battery status and whether it is charging or not (small lightning symbol)
* Volume is expressed through the speaker icons.
* When you have the earpiece as audio output, you see a phone handle icon with sound waves
* When you have headphones as audio output, you see a headphone icon
+* An icon also represents what "state" the device is in: unlock (open circle), lock (circle with slash), screenoff (filled circle), or proximity lock (circle with dot)
## **Global UI Controls**
@@ 170,7 171,7 @@ The global config menu is accessible by launching the global system menu
aforementioned and selecting *Config*. This menu let you:
- Adjust system brightness
-- Rotate the screen rotation
+- Rotate the screen
- Upgrade packages
- Edit your configuration (your custom profile)
@@ 181,7 182,7 @@ This section applies to dwm (Xorg) only:
DWM is a dynamic window manager with a master-slave stack layout.
As such, the window manager automatically decides where windows should be placed.
-The algorithm used to decide where windows should be placed is governed by the icon to the right of the 4th workspace icon.
+The algorithm used to decide where windows should be placed is governed by the icon to the right of the workspace number.
Open some windows and you should get an understanding of the various layouts.
By default, the layout is set the vertical stack layout and tapping icon representing the current layout will cycle through the available layouts.
@@ 190,47 191,47 @@ By tapping the left and right hand side of the title bar, you can cycle back and
For more info on DWM and other layouts that you can patch in, see the [upstream website for dwm](https://dwm.suckless.org/).
-### **Modem**
+## **States**
-If you are in a call, the length of the call will be displayed adjacent to the title bar.
+There are five states:
-## **Screen Lock**
+- **Unlocked (unlock)**: Screen is on; touchscreen is enabled.
+- **Locked (lock)**: Screen is on; touchscreen is disabled.
+- **Screenoff (screenoff)**: Screen is off; touchscreen is disabled. There is a short purple blink while in this state.
+- **Proximity Lock (proximitylock/unlock)**: When close to your face, the
+ screen will be off and touchscreen disabled; when far from your face, screen
+ will be on and touchscreen enabled. This is used during phone calls, for
+ instance.
+- **Suspend or Crust**: This is the kernel CRUST.
-In Sxmo we got 4 screenlock modes:
-- **Unlocked (unlock)**: The default state; screen is on and touchscreen is enabled
- - The default state
-- **Screenlock display on mode (lock)**: Locks the screen to disables input; but keeps the screen on
- - Short blue blink while locked
-- **Screenlock display off mode (off)**: Locks the screen to disables input, and turns the screen off
- - Short purple blink while the screen turn off
- - While periodically blink purple if the device stay in this state
-- **Deep sleep mode (crust)**: Enters CRUST suspend / deep sleep
- - Short red blink while suspending
-
-Do note that locking at this stage merely means the screen and buttons are 'locked'. We do not yet have a security check for
+Do note that locking at this stage merely means the screen is off and touchscreen disabled. We do not yet have a security check for
unlocking, such as passphrase entry. This feature is planned soon.
The power button will wake the phone from the deep sleep ("crust") mode to the
-"unlock" mode one at a time. While unlocked, power button will move the phone directly to "off"
+"unlock" mode one at a time. While unlocked, power button will move the phone directly to "screenoff"
mode.
When the phone is considered idle (no input, nor playing video, etc), the
phone will slowly go to deep sleep ("crust") one state after some time (~8 seconds). If you do not want this automatic
-deep sleep behaviour you can override some hooks (see: hooks). Deep sleep can
-always be accessed manually via the menu: *System -> Power -> Suspend* .
+deep sleep behaviour you can override some hooks (see: hooks). You can also toggle these in *System -> Config*.
+Deep sleep can always be accessed manually via the menu: *System -> Power -> Suspend* .
Note that if you receive notifications in any of these states, the green LED will be enabled.
-When you are in deep sleep mode, you
-can exit this mode and restore the above bindings by clicking the powerkey once.
+When you are in deep sleep mode, you can exit this mode and restore the above
+bindings by clicking the powerkey once. This places the device in "lock" state.
+Clicking the powerkey again transitions to "unlock" state. (This prevents
+accident "butt" unlocks.)
+
+To determine if the phone can suspend into CRUST, sxmo relies on the hook
+sxmo_hook_wakelocks.sh. For instance, an active ssh connection will set a
+wakelock so the device won't suspend. You can override or replace those with
+your own custom rules.
-To determine if the phone can lock deeper (from lock to off) and if it can
-suspend (from off to deep sleep (crust)) sxmo relies on the hook ``check_state_mutexes``
-respectively. You can override or replace those with your own custom rules.
### **Cron**
@@ 240,12 241,11 @@ The cron daemon is installed but not enabled in postmarketOS. Cron has to be sta
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 ``sxmo_rtcwake.sh`` which:
-- makes the led blink red/purple while doing the task
- manages the screenlock state while doing the task
- puts the phone back to crust when done
```
-*/15 * * * * sxmo_rtcwake.sh sleep 10 2>> ~/.local/state/tinydm.log
+*/15 * * * * sxmo_rtcwake.sh sleep 10 2>> ~/.local/state/sxmo.log
```
This example will wake the phone up for 10 seconds every 15 minutes. You may want to redirect the
@@ 312,10 312,9 @@ will automatically be launched which let's you:
- Manage audio routing
- Send DTMF (dial) tones
- Hang up the call
-- Lock the screen (via [screen lock](#strongscreen-lockstrong))
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. This behaviour can be disabled via the config menu.
+you have the phone close to your ear.
**Texting**
@@ 349,8 348,6 @@ monitors the modem activities 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](#strongincluded-menusstrong).
-You can tell if modem monitoring is on with the dedicated small phone icon that appears
-in the status bar.
While a call is incoming:
@@ 608,11 605,13 @@ 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.
+Here are some (but not all) hooks available!
+
<table>
<tbody>
<tr>
<td>hooks/sxmo_hook_start.sh</td>
- <td>This is a good place to set the wallpaper for instance, or to start
+ <td>This is a good place to start
some daemons</td>
</tr>
<tr>
@@ 625,7 624,13 @@ hooks depending on the kind of device that you are running.
<tr>
<td>hooks/sxmo_hook_pickup.sh</td>
<td>
- <p>Executable script to run when the phone is accepting an incoming call</p>
+ <p>Executable script to run when the phone is accepting an incoming call.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>hooks/sxmo_hook_hangup.sh</td>
+ <td>
+ <p>Executable script to run when you hangup the phone.</p>
</td>
</tr>
<tr>
@@ 652,9 657,9 @@ hooks depending on the kind of device that you are running.
</td>
</tr>
<tr>
- <td>hooks/sxmo_check_state_mutexes.sh</td>
+ <td>hooks/sxmo_hook_wakelocks.sh</td>
<td>
- <p>This script contains various rules for programs that should block suspend and/or locking.</p>
+ <p>This script contains various rules for programs that should block suspend.</p>
</td>
</tr>
<tr>
@@ 674,11 679,6 @@ hooks depending on the kind of device that you are running.
menu (see sxmo_appmenu.sh)</td>
</tr>
<tr>
- <td>hooks/sxmo_hook_presuspend.sh</td>
- <td>Executable script that is executed prior to suspending the device. If the exit code of this script is
- non-zero, suspend will be cancelled</td>
- </tr>
- <tr>
<td>hooks/sxmo_hook_postwake.sh</td>
<td>Executable script that is executed after waking from suspension. </td>
</tr>
@@ 731,7 731,11 @@ hooks depending on the kind of device that you are running.
that carries in case your device gets compromised.</td>
</tr>
<tr>
- <td>hooks/sxmo_hook_desktopwidget.sh</td>
+ <td>hooks/sxmo_hook_restart_modem_daemons.sh</td>
+ <td>This hook will run when the modem daemons are restarted.</td>
+ </tr>
+ <tr>
+ <td>hooks/sxmo_hook_desktop_widget.sh</td>
<td>This script is run after the window manager starts to provide a desktop widget (like a clock)</td>
</tr>
<tr>
@@ 755,6 759,12 @@ hooks depending on the kind of device that you are running.
</td>
</tr>
<tr>
+ <tr>
+ <td>hooks/sxmo_hook_tailtextlog.sh</td>
+ <td>This hook displays the sms log for a numbers passed as $1.
+ </td>
+ </tr>
+ <tr>
<td>hooks/DEVICENAME/sxmo_hook_inputmenu.sh</td>
<td>This script is called when a (hardware) button is pressed or a touchscreen gesture occurs.
You can override the default button mappings here.
@@ 772,10 782,8 @@ Note: `$XDG_CONFIG_HOME` by default is equal to `~/.config`
<table>
<tbody>
<tr>
- <td>$XDG_CACHE_HOME/.local/state/tinydm.log</td>
+ <td>$XDG_CACHE_HOME/.local/state/sxmo.log</td>
<td>
- <p>tinydm log contains the standard error output of everything launched from your display manager session, so any scripts launched by sxmo will also log their output to this file.</p>
- <p>tinydm.log is helpful for debugging if your hooks are not working.</p>
</td>
</tr>
<tr>
@@ 873,7 881,7 @@ The following environment variables can be set in `~/.config/sxmo/profile`:
The best place to set these default environment variables is in your ``~/.profile``
or in ``~/.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.
+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.
### **Update migrations**
@@ 938,26 946,6 @@ You can merge apk's config changes by running `doas update-conf`. You can also r
to list all the files that have changed from what apk originally installed.
-### Resolving system configs on system upgrade and make
-
-Apk will install new configs as
-`.apk-new` on upgrades if you have modified the original config in `/etc`.
-Moreover, when hacking on Sxmo, you will often run `make install`and 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 `apk audit`
-to list all the files that have changed from what apk originally installed.
-
-
-### Resolving system configs on system upgrade and make
-
-Apk will install new configs as
-`.apk-new` on upgrades if you have modified the original config in `/etc`.
-Moreover, when hacking on Sxmo, you will often run `make install`and 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 `apk audit`
-to list all the files that have changed from what apk originally installed.
-
-
### **X resources**
When running Xorg/dwm, certain interface parameters, such as the font size for dmenu, can be configured through X resources.
@@ 1044,4 1032,36 @@ To see a categorized list of applications that work well with Sxmo and install t
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.
+### **Devices**
+
+This section describes how to add a new device to SXMO. There are three basic steps:
+
+- Determine your ``SXMO_DEVICE_NAME``
+- Add a ``sxmo_deviceprofile_SXMO_DEVICE_NAME.sh`` file to ``scripts/deviceprofiles/`` in the source tree.
+- Add (or symlink to an existing) SXMO_DEVICE_NAME folder in ``configs/default_hooks/`` in the source tree.
+
+#### **Determining the SXMO_DEVICE_NAME**
+
+The ``SXMO_DEVICE_NAME`` is determined by the following code in ``sxmo_init.sh``
+
+```
+tr -c '\0[:alnum:].,-' '_' < /proc/device-tree/compatible | tr '\0' '\n' | head -n1
+```
+
+#### **Add deviceprofile file**
+
+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.
+
+#### **Add a device folder**
+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:
+``three_button_touchscreen``, ``one_button_e_reader``, and ``desktop``. You can also
+create your own, but usually you'll just want to symlink to one of these.