~anjan/sxmo-docs-stable

37ef39f10a6dc0e4990bed101015cd1b200658cb — Maarten van Gompel 6 months ago 5b98a6d
adapted hooks/templates for swmo
1 files changed, 56 insertions(+), 112 deletions(-)

M USERGUIDE.md
M USERGUIDE.md => USERGUIDE.md +56 -112
@@ 507,7 507,13 @@ refer to [the changelog](./CHANGELOG.md).
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/xinit</td>
      <td>Automatically executed script executed upon starting X.</td>
      <td>Automatically executed script executed upon starting X. (not used for Sway/Wayland). This is a good place to
      set the wallpaper for instance. But uou might want to look at
      the start hook instead.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/sway</td>
      <td>Sway configuration file (not used for dwm/Xorg), sets key bindings, wallpaper etc..</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/contacts.tsv</td>


@@ 558,7 564,14 @@ refer to [the changelog](./CHANGELOG.md).
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sms [^1]</td>
      <td>
	<p>Executable script to run when the phone is receiving a text</p>
	<p>This script is called with "$1" set to the incoming number and contact name.</p>
	<p>This script is called with "$1" set to the incoming number and contact name and "$2" the actual text.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sendsms [^1]</td>
      <td>
	<p>Executable script to run when the phone has just sent a text</p>
	<p>This script is called with "$1" set to the incoming number and contact name and "$2" the actual text.</p>
      </td>
    </tr>
    <tr>


@@ 572,13 585,20 @@ refer to [the changelog](./CHANGELOG.md).
      <td>$XDG_CONFIG_HOME/sxmo/hooks/can_suspend [^1]</td>
      <td>
	<p>Check script run before suspending the system</p>
	<p>This script must return a non zero exit code if the phone cannot suspend now</p>
	<p>This script must return a non zero exit code if the phone cannot suspend at the time the script is invoked</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/statusbar [^1]</td>
      <td>
	<p>This scripts stdout will be used as the status bar content</p>
  	    <p>This output of this script (stdout) will be used as the status bar content. You can use it to customize the
        status bar to your liking.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/statusupdate [^1]</td>
      <td>
  	    <p>This script is after the status bar gets an explicit nudge to update (by another process)</p>
      </td>
    </tr>
    <tr>


@@ 619,11 639,12 @@ refer to [the changelog](./CHANGELOG.md).
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/start [^1]</td>
      <td>Executable script that is executed just after the window manager</td>
      <td>Executable script that is executed just after the window manager (dwm/sway) starts. It can be used to start background
      processes you want in your session.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/unlock [^1]</td>
      <td>Executable script that is executed immediately after closing the window manager</td>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/stop [^1]</td>
      <td>Executable script that is executed immediately after closing the window manager (dwm/sway)</td>
    </tr>
    <tr>
    <tr>


@@ 635,14 656,6 @@ refer to [the changelog](./CHANGELOG.md).
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/audiostart [^1]</td>
      <td>
      </td>
      <td>This script is run by the default sway or xinit startup script to
      "Force audio over the main speaker and and set a sane default volume".
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/discard [^1]</td>
      <td>This script is executed (asynchronously) when you discard an incoming
      call


@@ 664,6 677,10 @@ refer to [the changelog](./CHANGELOG.md).
            something like ``mmcli -i 0 --pin 1234`` in it to unlock automatically, if you don't mind the negative security implications
            that carries in case your device gets compromised.</td>
	</tr>
	<tr>
		<td>$XDG_CONFIG_HOME/sxmo/hooks/desktopwidget [^1]</td>
		<td>This script is run after the window manager starts to provide a desktop widget (like a clock)</td>
	</tr>
  </tbody>
</table>



@@ 683,7 700,14 @@ not exist, `/usr/share/sxmo/default_hooks/pickup` will be run.
      <td>$XDG_CACHE_HOME/sxmo/dwm.log</td>
      <td>
	<p>dwm log contains the standard error output of everything launched from your dwm session, so any scripts launched by sxmo will also log their output to this file.</p>
	<p>dwm.log is helpful for debugging if your hooks are not working</p>
	<p>dwm.log is helpful for debugging if your hooks are not working. This is the Xorg equivalent of sway.log</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CACHE_HOME/sxmo/sway.log</td>
      <td>
	<p>the sway log contains the standard error output of everything launched from your sway session, so any scripts launched by sxmo will also log their output to this file.</p>
	<p>sway.log is helpful for debugging if your hooks are not working. This is the wayland equivalent of dwm.log</p>
      </td>
    </tr>
    <tr>


@@ 693,7 717,7 @@ not exist, `/usr/share/sxmo/default_hooks/pickup` will be run.
      </td>
    </tr>
	<tr>
      <td>$XDG_CACHE_HOME/sxmo/youtubehistory.tsv</td>
      <td>`$XDG_CACHE_HOME/sxmo/youtubehistory.tsv`</td>
      <td>This log file will save all the terms you've searched for using the youtube script.</td>
	</tr>



@@ 713,8 737,8 @@ The following environment variables can be set:
      <td><strong>Description</strong></td>
    </tr>
    <tr>
      <td>$TERM</td>
      <td>Terminal to launch on double-clicking power button and used in scripts. Defaults to `st`.</td>
      <td>$TERMCMD</td>
      <td>Terminal to launch on double-clicking power button and used in scripts. Defaults to `foot` (wayland) or `st` (Xorg).</td>
    </tr>
    <tr>
      <td>$BROWSER</td>


@@ 784,95 808,21 @@ The following environment variables can be set:
  </tbody>
</table>

### **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. You will automatically be
provided with a custom xinit based on the following template:

```sh
#!/usr/bin/env sh

# Please modify this file to your liking

# Important Instructions:
#  All processes you launch from this script must
#  be non-blocking: launch them in the background (using &)
#  or ensure they return quickly. Only after this script
#  finishes will the window manager be loaded
The best place to set these default environment variables is in your ``~/.profile``.

# Set a pretty wallpaper
feh --bg-fill /usr/share/sxmo/background.jpg
### **Update migrations**

# Show conky (the clock)
conky -c /usr/share/sxmo/appcfg/conky.conf -d #12 hour clock (am/pm)
#conky -c /usr/share/sxmo/appcfg/conky24h.conf -d  #24 hour clock

# Force audio over the main speaker
# and set a sane default volume
sxmo_audioout.sh Speaker
amixer sset 'Line Out Source' 'Mono Differential','Mono Differential'
amixer set "Line Out" 50%

# Play a funky startup tune
#mpv --quiet --no-video /usr/share/sxmo/startup.ogg &

# enter SIM PIN (WARNING! SECURITY RISK!)
#  the sleep is there because the modem
#  might take a bit to be available
#  after first boot.
#sleep 20 && mmcli -i 0 --pin 1234

# turn on modemmonitor on login
# Note: if the modemmonitor is not on you can
# not receive texts/calls!
#sleep 22 && sxmo_modemmonitortoggle.sh on &



### Configuration Parameters ###

# Note that this is just a subset of all available
# parameters, see the sxmo documentation for more.

# Use firefox as default browser if installed
command -v firefox && export BROWSER=firefox

# Prepopulate Subreddits menu with custom subreddits
#export SXMO_SUBREDDITS="postmarketos pinephoneOfficial pinephone unixporn"

# Temporarily wake every 5 minutes during sleep
#(useful for getting notifications)
#export SXMO_RTCWAKEINTERVAL=300

# Immediately turn the screen off when locking the device
#export SXMO_LOCK_SCREEN_OFF=1

# Immediately suspend the phone when locking
#export SXMO_LOCK_SUSPEND=1

# When scrolling past the beginning or end of a menu, wrap it around:
#export DMENU_WRAP_AROUND=1

# Enable audio feedback on keypress
#export KEYBOARD_ARGS="-o | clickclack -f /usr/share/sxmo/keypress.wav"

# Or, enable vibration feedback on keypress
#export KEYBOARD_ARGS="-o | clickclack -V"
```

Place the contents above into `~/.config/sxmo/xinit` and restart X and
customize away. Make sure that everything you launch from your custom xinitrc is either quick to run or launched in the
background, otherwise your window manager (dwm) won't be loaded.

A good alternative place to put environment variables is in your ``~/.profile``, the advantage there is that it will
also be available if you ssh into your phone.
While developing Sxmo, we will eventually update the xinit/sway template, or
environment variable names, or update hooks or whatever. We use a script
named `sxmo_migrate.sh` that try to simplify migrations. This script will
first show the differences between configurations can also override them
completely. You should run this script after every Sxmo to check if your hooks/configs
are up to date enough with the latest version of the system.

### **X resources**

Certain interface parameters, such as the font size for dmenu, can be configured through X resources. Create a file
``~/.Xresources`` and you have the following notable settings to tweak:
When running Xorg/dwm, certain interface parameters, such as the font size for dmenu, can be configured through X resources.
Create a file ``~/.Xresources`` and you have the following notable settings to tweak:

<table>
  <tbody>


@@ 930,8 880,9 @@ of the mimeapps.list and edit `~/.config/mimeapps.list`.
### **Tinydm**

We use [tinydm](https://gitlab.com/postmarketOS/tinydm) as login manager. The
tinydm goal is to simply login a target user on boot. You can configure the
userid in `/etc/conf.d/tinydm`.
tinydm goal is to simply automatically login a target user on boot. You can configure the
UID to login as in `/etc/conf.d/tinydm`. (make sure to adapt this if you create a custom user!)


### **Applications**



@@ 950,10 901,3 @@ The built-in application menu of sxmo is only aware of a subset of applications,
feel free to add more tools to the menus and submit a patch.


**Update migrations**

While developing Sxmo, we will eventually update the xinit template, or
environment variable names, or update hooks or whatever. We use a script
named `sxmo_migrate.sh` that try to simplify migrations. This script will
first show the differences between configurations can also override them
completely.