1 files changed, 48 insertions(+), 73 deletions(-)

M USERGUIDE.md

@@ 16,43 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
-
-The statusbar will add an icon if device suspend is disabled. The icon will
-change depending on the reason(s) suspend is disabled. For example,
-an "S" icon in the status bar means there is an active ssh/mosh connection and the device will
-not suspend to keep the ssh/mosh connection alive. For an explanation of all the
-icons when using the default status bar hook, see the ``set_lockedby()`` function in:
-``/usr/share/sxmo/default_hooks/sxmo_hook_statusbar.sh``.
+* 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**
 


@@ 177,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)
 


@@ 188,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.
 


@@ 197,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**
-
-If you are in a call, the length of the call will be displayed adjacent to the title bar.
+## **States**
 
-## **Screen Lock**
+There are five states:
 
-In Sxmo we got 4 screenlock modes:
+- **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.
 
-- **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.
 
 ![schema of the lock states when pressing power](schemas/lock-power-states.png)
 
 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**
 


@@ 247,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


@@ 319,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**
 


@@ 356,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:
 


@@ 615,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>


@@ 665,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>


@@ 687,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>


@@ 795,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>


@@ 961,16 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.
-
-
 ### **X resources**
 
 When running Xorg/dwm, certain interface parameters, such as the font size for dmenu, can be configured through X resources.