~anjan/sxmo-docs-stable

1560e9c8eabe8fde250d76a5f3e6762db14a9111 — Maarten van Gompel 6 months ago be767d9
initial major update of the documentation for swmo
1 files changed, 62 insertions(+), 35 deletions(-)

M USERGUIDE.md
M USERGUIDE.md => USERGUIDE.md +62 -35
@@ 14,22 14,34 @@ After login, you will be presented the SXMO interface as follows:

![screenshot](assets/screenshot.jpg)

The core of the Sxmo UI is based on the [dwm](http://dwm.suckless.org) window manager, the
[dmenu](https://tools.suckless.org/dmenu/) menu system, the [lisgd](http://git.sr.ht/~mil/lisgd) gesture daemon and
the [svkbd](https://tools.suckless.org/x/svkbd/) keyboard.
The core of the Sxmo UI is based on:

* a tiling window manager (either [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
installed).

Sxmo itself consists, regardless of the environment you use, of 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.

### **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. Right next to it (the three lines) indicates the dwm
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.

At the top-right you see the status menu, holding various symbols:

* 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
* The wifi icon indicates you are connected to a wireless network
* 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)
* Volume is expressed through the speaker icons.
    * When you have the earpiece as audio output, you see a phone handle icon with sound waves


@@ 52,19 64,19 @@ The default button bindings are:
  - **2 taps**: Launch [global system menu](#strongincluded-menusstrong)
  - **3 taps (or hold)**: Shift current client in stack
- **Volume Lower**:
  - **1 tap**: Toggle virtual keyboard (svkbd)
  - **1 tap**: Toggle virtual keyboard (wvkbd/svkbd)
  - **2 taps**: Toggle dwm layout algorithm (between monocle/tile/bstack)
  - **3 taps**: Kill client
  - **Hold (or 4 taps)**: Close client
- **Powerkey**:
- **Power button**:
  - **1 tap**: Activate [screen lock](#strongscreen-lockstrong)
  - **2 taps**: Reverse [screen lock](#strongscreen-lockstrong)
  - **3 taps (or hold)**: Launch the terminal (st)
  - **3 taps (or hold)**: Launch the terminal (foot/st)


**Swipe gestures**

In addition to the button bindings provided through dwm, a custom application
In addition to the button bindings, a custom application
called [lisgd](http://git.sr.ht/~mil/lisgd) was developed to provide
touchscreen swipe gestures within Sxmo. These gestures are sensitive to the edge of the screen where the gesture is initiated
or where they end up, and some are sensitive to the length/distance of the swipe. Gestures in the main part of the


@@ 111,11 123,7 @@ functionality](#stronguser-customizable-xinitrcstrong).
## **The Menu System**

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](http://tools.suckless.org/dmenu). Note
that while using a menu, dwm's [button bindings](#strongglobal-ui-controlsstrong) won't be triggered as
these grab's are setup to be mutually exclusive from X's point of view.
the Pinephone's 3 hardware buttons:

The default menu bindings for the Pinephone buttons are:



@@ 123,6 131,13 @@ The default menu bindings for the Pinephone buttons are:
- **Volume Lower**: Next item
- **Power**: Select item

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

The menus are essentially scripts around [bemenu](https://github.com/Cloudef/bemenu) or a custom patched version of
[dmenu](http://tools.suckless.org/dmenu). Note that while using a menu, the hardware buttons have different behaviour
than when no manu is running. If you use sway, this mode is explicitly indicated by a red "Menu" block in the top bar.
In dwm, the [button bindings](#strongglobal-ui-controlsstrong) won't be triggered as these grab's are setup to be
mutually exclusive from X's point of view.

## **Included Menus**



@@ 146,7 161,7 @@ in Sxmo. This menu lets you:
- Adjust volume
- Make/Receive [Calls and Texts](#strongcalls-and-textingstrong)
- Launch the Camera
- Connect to Wifi and 4G
- Connect to Wifi and Cellular data (2G/3G/4G)
- Connect to Bluetooth (if bluez is installed)
- Adjust audio output device



@@ 164,6 179,8 @@ aforementioned and selecting *Config*. This menu let you:

### **Layouts**

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.


@@ 177,7 194,7 @@ For more info on DWM and other layouts that you can patch in, see the [upstream 

### **Modem**

If you are in a call, the length of the call will be display adjacent to the title bar.
If you are in a call, the length of the call will be displayed adjacent to the title bar.

## **Screen Lock**



@@ 195,7 212,9 @@ In Sxmo we got 4 screenlock modes:
The power button will wake the phone from the "crust" mode to the
"unlock" mode one at a time. While unlocked, power button will move the phone directly to "off"
mode. When the phone is considered idle (no input, nor playing video, etc), the
phone will slowly go to "crust" one state after one with some time (~8 seconds).
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 "Stop lock idle" (``sxmo_lock_idle.sh``) from the configuration menu. 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, turning the colour of the
three states to respectively cyan, white or yellow.


@@ 204,7 223,7 @@ When you are in deep sleep mode, you
can exit this mode and restore the above bindings by clicking the powerkey once.

To determine if the phone can lock deeper (from lock to off) and if it can
suspend (from off to crust) sxmo rely on the hooks is_idle and can_suspend
suspend (from off to deep sleep (crust)) sxmo relies on the hooks ``is_idle`` and ``can_suspend``
respectively. You can override or replace those with your own custom rules.

Sxmo ensures that cron jobs works, and will actively wake the phone from sleep temporarily to this end.


@@ 235,7 254,7 @@ 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.

Modem functionality is based on using the [dmenu menu system](#strongthe-menu-systemstrong) and accessible through the
Modem functionality is based on using the [menu system](#strongthe-menu-systemstrong) and accessible through the
[global system menu](#strongincluded-menusstrong). You'll need to explicitly toggle the modem there to receive
calls/texts. If your SIM is locked, you must unlock it manually.  The scripting behind the scenes works via
[ModemManager](https://www.freedesktop.org/wiki/Software/ModemManager/) using the


@@ 243,7 262,8 @@ calls/texts. If your SIM is locked, you must unlock it manually.  The scripting 

**Unlocking SIM**

SXMO ask for your SIM's PIN code using dmenu (since sxmo 1.4.1).
As long as your SIM is locked, a lock icon should appear in the status bar.
SXMO automatically asks for your SIM's PIN code using a menu (since sxmo 1.4.1).

Alternatively, you can do so from the command-line as follows:



@@ 265,6 285,9 @@ will automatically be launched which let's you:
- 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.

**Texting**

To view existing text message threads you can use the *Texts* entry in the


@@ 280,7 303,7 @@ You can also 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 by default be dropped into a vim-like editor
([vis](https://github.com/martanne/vis)) to compose your message. Once
your message is as you'd like it, exit the editor using `ZZ`/`:wq!`.  You 
your message is as you'd like it, exit the editor using `ZZ`/`:wq!`.  You
will now be taken to a new menu to confirm your message from which you can
edit/send/add recipients/add attachments/cancel the message.



@@ 288,18 311,18 @@ edit/send/add recipients/add attachments/cancel the message.

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  activities and vibrates the
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 icon that appears
in dwm's bar.
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:

- The vibration motor will trigger for 3 seconds
- The green LED will trigger
- A dmenu will appear to allow you to pickup the call. You can also discard
- A menu will appear to allow you to pickup the call. You can also discard
  the call or mute the ring. If you missed the menu, you can also open either
  the [global or application](#strongincluded-menusstrong) menu and you'll
  see a menu entry to pickup the call; of course this is time-sensitive and this


@@ 333,19 356,19 @@ are already in [the
database](https://wiki.gnome.org/Projects/NetworkManager/MobileBroadband/ServiceProviders).
Consider contributing your own if it is not.

*Note* that your carrier's nameserver must be present in /etc/resolv.conf in
*Note* that your carrier's nameserver must be present in `/etc/resolv.conf` in
order to send/receive mms.  This should be automatic.  However, sometimes
NetworkManager will place the wifi's nameservers *above* the carrier's
nameservers, and since /etc/resolv.conf can only use the first three entries,
nameservers, and since `/etc/resolv.conf` can only use the first three entries,
the carrier's nameservers will not be used.  To fix this, you can set dns=none
in /etc/NetworkManager/NetworkManager.conf and use a static /etc/resolv.conf
in `/etc/NetworkManager/NetworkManager.conf` and use a static `/etc/resolv.conf`
instead.

**Contacts System**

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
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


@@ 413,12 436,16 @@ scripts.
## **Wifi**

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](#strongincluded-menusstrong) to connect
to wifi. This is essentially this is just a wrapper to launch `nmtui`. Make sure
the killswitch for Wifi on your Pinephone is in the enabled position.
is through wifi. There is a menu entry in the [global system menu](#strongincluded-menusstrong) (Networks -> Add a WPA
Network) to connect
to wifi. This is essentially this is just a wrapper to launch `nmtui`. If your phone has a wifi killswitch (like the
Pinephone or Librem 5), make sure it is in the enabled position.

## **Mobile data**

Mobile data should be manually for now (there is no built in menu to do this);
so refer to [postmarketOS](https://wiki.postmarketos.org/wiki/PINE64_PinePhone_(pine64-pinephone)#Modem) pinephone documentation for that aspect.
Mobile data can be simarly added via the menu (Networks -> Add a GSM Network). It will ask for an APN, you may also
consult the [postmarketOS](https://wiki.postmarketos.org/wiki/PINE64_PinePhone_(pine64-pinephone)#Modem) pinephone
documentation for that aspect.

## **Audio Routing**