~anjan/sxmo-docs-next

Table of Contents

  1. Sxmo: Simple X Mobile - System Guide
  2. Start-up Process
  3. Event Handling
  4. Sxmo toolbox
  5. Hooks
  6. Notifications
  7. Device profiles

#Sxmo: Simple X Mobile - System Guide

Project Overview | Install Guide | User Guide | System Guide | Contributing | Images | Demo Video

Documentation (postmarketOS Stable) | Documentation (postmarketOS edge) | Documentation (Development Version)

#Start-up Process

#U-boot

The default PinePhone boot priority is first the SD card and then the eMMC so inserting your own SD card with your preferred release will result in the phone booting your image.

#postmarketOS initramfs

After the kernel is booted, the init.sh script in initial RAM disk runs. This performs various low-level startup and setup tasks, mostly relating to partitions and filesystems. This largely relies on the busybox binary present in the initial RAM disk. When completed the script exec's a switch_root to the root filesystem and starts /sbin/init which is just a symlink to BusyBox.

#BusyBox init

When called as init, busybox will use /etc/inittab for its configuration, if present. Note, busybox has its own interpretation of inittab syntax. The /etc/inittab included in the filesystem specifies the following:

  • Run /sbin/getty on /dev/tty[1-6] for virtual consoles, and on the /tty/S0 for the serial console.
  • Run sysvinit actions first, waiting for completion
    • /sbin/openrc sysinit
    • /sbin/openrc boot
  • Run wait actions next, waiting for completion
    • /sbin/openrc default -- this is the "actual" init.
  • If ctrl-alt-delete is pressed, run /sbin/reboot
  • When shutdown is initiated, run /sbin/openrc shutdown.
#OpenRC init

OpenRC init system is a dependency-based init system that manages system init scripts and the associated services.

Named runlevels in OpenRC are stored in directories under /etc/runlevels. When called with a runlevel as an argument, /sbin/openrc loads the init scripts in the runlevel's directory, and then run them in alphabetical order, unless a script has dependency information, in which case the order is changed to provide a valid start-up sequence.

#Display Manager - tinydm

Details on tinydm and the configuration can be found in the tinydm ticket page.

  • /var/lib/tinydm/default-session.desktop is a symlink to the wayland/x11 session to be started.
  • tinydm.initd
    • openrc service file, runs autologin user tinydm-run-session
    • the username should be determined by uid, and the uid provided in a config file that postmarketos-base installs
    • essentially we can do rc-service tinydm restart then, just as if it was lightdm
  • tinydm-run-session
    • resolves /var/lib/tinydm/default-session.desktop
    • starts the session (wayland or x11 is determined by the resolved path)
  • tinydm-set-session is used to update this link
    • example: tinydm-set-session /usr/share/wayland-sessions/phosh.desktop
    • a force flag [-f] would overwrite it in any case
  • tinydm-unset-session is used to remove a known outdated link
    • example: tinydm-unset-session /usr/share/wayland-sessions-pmos/phosh.desktop
    • if the link exists and points to exactly that file, it is removed.

#Event Handling

Various processes are started when certain events occur, rather than always being run at startup or login. Some of the most significant ones are listed below:

#Key and Button Presses - dwm

The keys and button presses which dwm responds to are specified at compile-time in the config.h for sxmo-dwm. See the userguide for a description.

#Screen Gestures - lisgd

The built-in responses to screen gestures that are specified at compile-time in config.h for lisgd, are overridden by command-line specifications in sxmo_lisgdstart.sh. See the userguide for a description.

#System Events - udev

A variety of system activities trigger udev events which are matched by rules in /etc/udev/rules.d/ and /usr/lib/udev/rules.d.

#Sxmo toolbox

#Daemons managments

To manage user daemons in an unified way we got the sxmo_daemons.sh script:

$ sxmo_daemons.sh start a_daemon_name sleep 60
$ sxmo_daemons.sh list
a_daemon_name
$ sxmo_daemons.sh running a_daemon_name
a_daemon_name is still running
$ sxmo_daemons.sh stop a_daemon_name

Every daemons that run on the sxmo system are initiated in the "start" hook or at specific moments. See daemons more as a way to manage easily asynchronous works more than system daemons.

Here are some default daemons:

  • idle_locker: An idle monitor that will eventuall move the phone in a deepest state
  • lisgd: The touch gesture daemon that trigger actions
  • modem_monitor: Listen to modem manager dbus signals to manage sms, incoming calls, etc…
  • wob: The progress status bar that appear when increasing/decreasing volume/brightness
  • notification_monitor: Listen to new notifications and trigger UI popups
  • network_monitor: Will update the status bar components
  • statusbar_periodics: Will update some status bar components periodically
  • desktop_widget: The background text oclock, either conky or wayout,
  • mmsd: The mms daemons manager that works with modem manager
  • menu_mode_toggler: A little daemon that change the sway mode to "menu" when openning a menu
  • desktop_notifier: The popup notifier, either dunst or mako
#Status bar

To manage the status bar, sxmo relies on sxmo_status.sh. This script allow us to add, change or remove displayed components.

$ sxmo_status.sh add 10-foo foo
$ sxmo_status.sh show
foo
$ sxmo_status.sh add 20-bar bar
$ sxmo_status.sh show
foo bar
$ sxmo_status.sh add 15-int -
$ sxmo_status.sh show
foo - bar
$ sxmo_status.sh del 10-foo
$ sxmo_status.sh show
- bar
$ printf world | sxmo_status.sh add 10-hello
world - bar

Most of the sxmo status bar component are configured by "statusbar" hook. Some periodic components (the time by example) are triggered by the hook as a daemon "statusbar_periodics".

#Hooks

Some parts of the sxmo code are wrapped in hooks. If the user got the hook in their ~/.config/sxmo/hooks/ then this hook is used instead. You can copy the default hooks from /usr/share/sxmo/default_hooks and modify, extend or remove some behaviors.

A list of the default hooks can be found in the User Guide.

#Notifications

#Notification Format

Notifications to the user are created by calling /usr/bin/sxmo_notificationwrite.sh with the appropriate arguments. These arguments are:

  • The filepath of the notification to write (or "random" to generate a random id)
    • If "random" is specified, then the notification file will be created in $NOTIFDIR as specified in /usr/bin/sxmo_common.sh.
  • Action that the notification invokes upon selecting/tapping the notification window
    • select/tapping on the notification will trigger removal of the notification, as well as the associated action.
  • The file to watch for deactivation (which occurs if anything at all happens to the file).
    • This file, if specified, should be one which will be affected by the user dealing with the interaction, in order to trigger removal of the notification. In the absence of a file, a string representing a non-existent file can be provided (e.g. "none")
    • e.g. if a SMS text is removed, the watch file should be the one containing the SMS message, so when the user reads/deletes/saves the message, the notification will be removed.
  • The text displayed in the notification

The last 3 arguments are written out by sxmo_notificationwrite.sh, with one per line (though the message text can be multi-line, I think.) into the notification file specified by the first argument.

#Notification Handling

When created, notifications in $NOTIFDIR will be processed by /usr/bin/sxmo_notificationmonitor.sh.

When started, sxmo_notificationmonitor.sh will scan and display any notifications in the directory specified in $NOTIFDIR, then will begin monitoring that directory for any new notification files.

If a new notification is detected, the following actions are taken by the handlenewnotiffile() function:

  1. Checks the validity of notification file ( files must be at least 3 lines long )
  2. The notificationhook() function passes the notification file to the user-defined notification script in "$XDG_CONFIG_HOME"/sxmo/hooks/notification, if present; otherwise, it makes the phone vibrate.
  3. The notification message is displayed using dunstify.
  4. If the displayed notification is clicked/tapped, then the action specified in the notification file is run.
  5. If the specified notification watch file exists, it is watched by inotifywait and upon the report of any event, the notification file is removed.
#Notification Browsing

Pending notifications can be viewed by running /usr/bin/sxmo_notificationsmenu.sh either from a terminal or from the system menu. This script displays the notification times (hh:mm) and the associated messages using dmenu. If selected, the action specified in the notification file is performed and the notification is removed.

#Device profiles

To support multiple devices, Sxmo relies on a device profile system that defines multiple device names for Sxmo to source.

#Writing a deviceprofile
  1. On the device you want run Sxmo, run: git clone https://git.sr.ht/~mil/sxmo-utils. To obtain ssh access, see USB Network - postmarketOS wiki.
  2. Read sxmo-utils/scripts/deviceprofiles/README.md for what to name the device profile file and what environmental variables to set in the device profile file.
  3. The sxmo-utils/scripts/deviceprofiles directory has deviceprofiles for other devices. Feel free to look through those as a reference

The edge version of postmarketOS is recommended to create a device profile because sxmo-utils' master branch is most likely to work with edge. sxmo-utils can work on stable but you need to be willing to debug issues with sxmo-utils.

Once you have edited device's device profile, you can activate the profile by:

  1. Install the makedepends:

doas apk add libx11-dev xproto linux-headers

Note: for people reading this in the future, the makedepends may have changed. Please install the makedepends listed in this file: https://git.alpinelinux.org/aports/tree/community/sxmo-utils/APKBUILD

  1. install make. Installing alpine-sdk which will install make and let you use aports:

doas apk add alpine-sdk

  1. Change into the root of the sxmo-utils directory and run doas make install. You may need to reboot or restart sway/dwm and superd.

  2. sshing into your device, you should now get:

deviceprofile file /usr/bin/<NEXUS-7-DEVICE-TREE-COMPATIBLE-STRING>.sh loaded.

If you get that, Sxmo has successfully loaded the device profile you made.

  1. Feel free to edit sxmo-utils/deviceprofiles/your-device.sh, run doas make install inside sxmo-utils, and reboot till everything you want working works.

  2. If everything works, please contribute your changes https://sxmo.org/contribute

Please do not be scared of git send-email. If you post too much to our mailing list while learning how to use it, we dont mind and will fix it up. We need Sxmo on more devices!

If you need realtime help in this process, please join irc:

https://sxmo.org/support

About this wiki

commit 89ea52759abab986fdd119a75c83f6bbc2ec9398
Author: Maarten van Gompel <proycon@anaproy.nl>
Date:   2024-03-09T13:14:52+01:00

fixed svkbd link to upstream
Clone this wiki
https://git.sr.ht/~anjan/sxmo-docs-next (read-only)
git@git.sr.ht:~anjan/sxmo-docs-next (read/write)