1 files changed, 64 insertions(+), 49 deletions(-)

M USERGUIDE.md

@@ 157,12 157,12 @@ that it can be the starting point to access much of the functionality
 in Sxmo. This menu lets you:
 
 - Launch [Scripts and Applications](#strongincluded-scripts-and-applicationsstrong)
-- Adjust volume
 - Make/Receive [Calls and Texts](#strongcalls-and-textingstrong)
 - Launch the Camera
 - Connect to Wifi and Cellular data (2G/3G/4G)
 - Connect to Bluetooth (if bluez is installed)
 - Adjust audio output device
+- Adjust modem settings
 
 **3. Global config menu (Config)**
 


@@ 170,7 170,6 @@ The global config menu is accessible by launching the global system menu
 aforementioned and selecting *Config*. This menu let you:
 
 - Adjust system brightness
-- Toggle modem monitoring, view modem information and the modem log
 - Rotate the screen rotation
 - Upgrade packages
 - Edit your configuration (your custom profile)


@@ 230,7 229,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 deep sleep (crust)) sxmo relies on the hooks ``is_idle`` and ``can_suspend``
+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**


@@ 246,18 245,16 @@ dedicated script called ``sxmo_rtcwake.sh`` which:
 - puts the phone back to crust when done
 
 ```
-*/15 * * * * sxmo_rtcwake.sh sleep 10 2>> ~/.cache/sxmo/logs/dwm.log
+*/15 * * * * sxmo_rtcwake.sh sleep 10 2>> ~/.local/state/tinydm.log
 ```
 
 This example will wake the phone up for 10 seconds every 15 minutes. You may want to redirect the
-standard error output to the main log as shown in the example above. You can pass the ``--strict``
-parameter to ``sxmo_rtcwake.sh`` to only run when the phone is indeed in crust mode, otherwise it
-will run regardless of the lock state.
+standard error output to the main log as shown in the example above.
 
 If you omit ``sxmo_rtcwake.sh`` for a job, the system will *not* wake up from crust.  Note that in such cases, you might want to use ``sxmo_wm.sh execwait`` instead, e.g.:
 
 ```
-*/15 * * * * sxmo_wm.sh execwait sleep 20 2>> ~/.cache/sxmo/logs/dwm.log
+*/15 * * * * sxmo_wm.sh execwait sleep 20 2>> ~/.local/state/tinydm.log
 ```
 
 This will make sure that the SXMO environmental variables are sent to your script.


@@ 303,7 300,7 @@ Alternatively, you can do so from the command-line as follows:
 mmcli -i 0 --pin 1234
 ```
 
-You could put this in your unlock sim hook (``~/.config/sxmo/hooks/unlocksim``), but there is of course a
+You could put this in your unlock sim hook (``~/.config/sxmo/hooks/sxmo_hook_modem.sh``), but there is of course a
 significant security risk involved if your device gets compromised!
 
 **Calling**


@@ 410,7 407,7 @@ 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 `Unknown Number`.
+this file; the contact in menus will show up as `???`.
 An `contacts.tsv` example might look like:
 
 ```


@@ 562,7 559,7 @@ refer to [the changelog](./CHANGELOG.md).
       You can also trigger commands in it with "exec".</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/start [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_start.sh [^1]</td>
       <td>This is a good place to set the wallpaper for instance, or to start
       some daemons</td>
     </tr>


@@ 593,100 590,91 @@ refer to [the changelog](./CHANGELOG.md).
       <td>Directory or file to place user scripts which will automatically appear in the menu system</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/ring [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_ring.sh [^1]</td>
       <td>
       <p>Executable script to run when the phone is receiving a call / rings</p>
       <p>This script is called with "$1" set to the contact name or incoming number if not in contacts.</p>
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/pickup [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh [^1]</td>
       <td>
       <p>Executable script to run when the phone is accepting an incoming call</p>
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/missed_call [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_missed_call.sh [^1]</td>
       <td>
       <p>Executable script to run when the phone missed an incoming call</p>
       <p>This script is called with "$1" set to the contact name or incoming number if not in contacts.</p>
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/sms [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_sms.sh [^1]</td>
       <td>
-      <p>Executable script to run when the phone is receiving a text</p>
+      <p>Executable script to run when the phone is receiving a text, mms, or vvm (visual voice mail)</p>
       <p>This script is called with "$1" set to the contact name or incoming number if not in contacts and "$2" the actual text.</p>
-      <p>If it is a group text, "$1" is set to the sender's contact name (or number if not in contacts) followed by a space
-      followed by the group's contact name (or number if not in contacts) in between pointed brackets, e.g., Bob <MyFamily></p>
+      <p>As well, if this is a Visual Voice Mail or an MMS, "$3" will be set to the payload ID.</p>
+      <p>Finally, if this is a Group Text, "$4" will be set to the group contact name or number if not in contacts.</p>
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/sendsms [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_sendsms.sh [^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 number and "$2" the actual text.</p>
+      <p>This script is called with "$1" set to the number (or contact name) and "$2" the actual text.</p>
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/is_idle [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_check_state_mutexes.sh [^1]</td>
       <td>
-      <p>Check script run before going deeper in screen lock levels</p>
-      <p>This script must return a non zero exit code if the phone cannot lock deeper</p>
+      <p>This script contains various rules for programs that should block suspend and/or locking.</p>
       </td>
     </tr>
     <tr>
-      <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 at the time the script is invoked</p>
-      </td>
-    </tr>
-    <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/statusbar [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_statusbar.sh [^1]</td>
       <td>
         <p>This script contain methods to update some status bar components. See SYSTEMGUIDE</p>
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/apps</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_apps.sh</td>
       <td>Executable script to run when display of the app menu is requested, outputs to stdout and allows you to override the default app
       menu (see sxmo_appmenu.sh)</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/scripts</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_scripts.sh</td>
       <td>Executable script to run when display of the scripts menu is requested, outputs to stdout and allows you to override the default app
       menu (see sxmo_appmenu.sh)</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/presuspend [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_presuspend.sh [^1]</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>$XDG_CONFIG_HOME/sxmo/hooks/postwake [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_postwake.sh [^1]</td>
       <td>Executable script that is executed after waking from suspension. </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/lock [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICE_NAME/sxmo_hook_lock.sh [^1]</td>
       <td>Executable script that is executed prior to locking the device</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/unlock [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICE_NAME/sxmo_hook_unlock.sh [^1]</td>
       <td>Executable script that is executed immediately after unlocking the device</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/lisgdstart [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_lisgdstart.sh [^1]</td>
       <td>Script that is executed to start the gesture deamon, overrides the defaults (see ``sxmo_lisgdstart.sh``). This
       allows defining custom gestures.</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/stop [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_stop.sh [^1]</td>
       <td>Executable script that is executed immediately after closing the window manager (dwm/sway)</td>
     </tr>
     <tr>
-    <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/inputhandler [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICE_NAME/sxmo_hook_inputhandler.sh [^1]</td>
       <td>Script that is executed when a gesture is to be interpreted. It is passed the WM_CLASS of the active window as
       first parameter and the identifier/name of the gesture (or command to run) in the second argument, as configured with lisgd. See
       ``sxmo_inputhandler.sh`` for details. This script allows you to define your own context-sensitive (i.e. application


@@ 694,31 682,58 @@ refer to [the changelog](./CHANGELOG.md).
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/discard [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_discard.sh [^1]</td>
       <td>This script is executed (asynchronously) when you discard an incoming
       call
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/mute_ring [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_mute_ring.sh [^1]</td>
       <td>This script is executed (asynchronously) when you mute an incoming call
       </td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/notification [^1]</td>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_notification.sh [^1]</td>
       <td>This script will run whenever any kind of notification is received. It can be used for example to blink the
       led if you want to override the default behaviour</td>
     </tr>
     <tr>
-      <td>$XDG_CONFIG_HOME/sxmo/hooks/unlocksim [^1]</td>
-      <td>This hook will run when your SIM needs to be unlocked with a PIN code. You can consider putting
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_modem.sh [^1]</td>
+      <td>This hook will run when the modem changes state.  This is where you can use custom code if the SIM is locked.
+	    You can consider putting
             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>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_desktopwidget.sh [^1]</td>
       <td>This script is run after the window manager starts to provide a desktop widget (like a clock)</td>
     </tr>
+    <tr>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_suspend.sh [^1]</td>
+      <td>This script is run when system suspends.  It contains the actual suspend call.
+      </td>
+    </tr>
+    <tr>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_rotate.sh [^1]</td>
+      <td>This script is called when we rotate.  $1 is the new orientation (normal, left, right).
+      </td>
+    </tr>
+    <tr>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_icons.sh [^1]</td>
+      <td>This script is called every time we load a script.  You can override icons here.
+      </td>
+    </tr>
+    <tr>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_contextmenu.sh [^1]</td>
+      <td>This script is called when a menu is loaded.  You may override or add new menu options here.
+      </td>
+    </tr>
+    <tr>
+      <td>$XDG_CONFIG_HOME/sxmo/hooks/$DEVICENAME/sxmo_hook_inputmenu.sh [^1]</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.
+      </td>
+    </tr>
   </tbody>
 </table>
 


@@ 726,8 741,8 @@ Note: `$XDG_CONFIG_HOME` by default is equal to `~/.config`
 
 [^1]: If a user-defined hook file does not exist on activity, sxmo will run the
 corresponding project defined default hook from `/usr/share/sxmo/default_hooks/`.
-For example, if you pickup a call and `$XDG_CONFIG_HOME/sxmo/hooks/pickup` does
-not exist, `/usr/share/sxmo/default_hooks/pickup` will be run. More details
+For example, if you pickup a call and `$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh` does
+not exist, `/usr/share/sxmo/default_hooks/sxmo_hook_pickup.sh` will be run. More details
 about hooks in SYSTEMGUIDE.