diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 517 |
1 files changed, 517 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..544c6a7 --- /dev/null +++ b/README.md @@ -0,0 +1,517 @@ +# desktopctl + +*"A desktop environment for window managers"* + +Using a window manager (i3/sway/awesome/etc) should not mean that one has to +completely reinvent the wheel and manage a strange collection of one-liners to +get wifi status or to see if headphones are connected. This project aims to be +a solution to this problem. + +Some of these tools are simple one-liners, some are more complex. The idea is to +create a suite of platform-independent (Distro/Desktop Environment independent) +tools to get and set system information. + +Similar in nature to [neofetch](https://github.com/dylanaraps/neofetch), but +also allows for *setting* information too (not just *getting*). + +### Project status + +The code is not particularly robust. It can and will fail in non-obvious ways if +certain utility programs are not installed. + +Notably, this program assumes certain permissions are granted to the user. For +example, to change the brightness in Archlinux, the user must be part of the +`video` group; or to non-interactively change the time zone with `timedatectl` +one needs a polkit rule. + +### Features + +* **Session Authentication** Show session authentication status +* **Backlight Manager** Get and set backlight +* **Battery Manager** Get battery status +* **Bluetooth Manager** Get and set Bluetooth +* **Colour picker** Colour picker +* **CPU frequency** Get CPU frequency +* **Headphone indicator** Get whether headpones are plugged in +* **IP Address** Get local IP address +* **Media Watch Time** Print total media time of listed files +* **Memory** Get memory usage +* **Monitor Directories/Files** Monitor directories/files +* **Check if online** Get current internet connection status +* **Screenshots** Take screenshots +* **Sound Manager** Get and set sound +* **Internet speedtest** Show current internet speed +* **SSH** List ssh clients on local network +* **Time zone** Get and set current time zone +* **Wifi Status** Set wifi on/off + +Limited features + +* **Configuration file differences** Show configuration file differences (Archlinux only) +* **Power Manager** Set power and charging profiles (Dell only) +* **Reboot check** List programs that need to be restarted (Archlinux only) +* **Xwayland clients** List number of xwayland clients (Sway only) + +--- + +### Configuring + +The configuration is read from `~/.config/desktopctl/desktopctlrc`. + +--- + +#### Session Authentication + +Show session + +Prints whether the session is [correctly +authenticated](https://wiki.archlinux.org/title/General_troubleshooting#Session_permissions) +using `loginctl`. + +Arguments: None + +#### Backlight Manager + +Get and set backlight + +Is configured to give non-linear brightness changes with a very simple +interface. Can easily be bound to keyboard brightness keys. + +``` +Arguments: + NUMBER, Set backlight to NUMBER percentage. + +NUMBER, Increase backlight percentage by NUMBER. + -NUMBER, Decrease backlight percentage by NUMBER. + + +, Go to the next backlight intensity level. + -, Go to the previous backlight intensity level. + + -p, --print, Print current backlight percentages. + -n, --notify, Send desktop notification with current backlight intensity. + -h, --help, Display this help. +``` + +Changes are made with `xbacklight` under the hood. + +The brightness profile can be configured by setting `$BACKLIGHT_LEVELS` in the +configuration file. + +The default is + +``` +BACKLIGHT_LEVELS=(0 1 2 3 4 5 6 7 8 9 10 15 20 25 30 40 50 60 70 80 90 100) +``` + +(Small steps at lower brightnesses and larger steps at higher brightnesses) + +#### Battery Manager + +Get battery status + +Gives very detailed statistics about the battery usage rate. Useful for building +a status line. Comes shipped with a default status line. + +``` +Arguments: + power, Current power usage (in W) + voltage, Current battery voltage (in uV) + current, Current battery current (in uA) + capacity, Current battery capacity (in %) + charge, Current battery capacity (in C) + charging, Exit value 0 if charging + charged, Exit value 0 if fully charged + + remaining, If on battery: remaining time until battery depleted + If charging: remaining time until battery full + (Human readable string) + + info, Statusline like information about battery + (May need correct font configuration) +``` + +Configure battery icons with `$BATTERY_LEVELS_CHARGING` and `$BATTERY_LEVELS`. + +The defaults are set using [Overpass Mono Nerd +Fonts](https://github.com/ryanoasis/nerd-fonts). + +``` +BATTERY_LEVELS_CHARGING=( ) +BATTERY_LEVELS=( ) +``` + +(You may not be able to see these in browser) + +#### Bluetooth Manager + +Get and set Bluetooth + +``` +Arguments: + on, Power bluetooth on + off, Power bluetooth off + --daemon, daemon, Interact with the bluetooth daemon + -i, --indicator, Print current bluetooth connection indicator + -l, --list, list, List connected bluetooth devicees + -r, --restart, restart, Restart bluetooth + -c, --connect, connect, Connect to bluetooth device + -d, --disconnect, disconnect, Connect to bluetooth device + -h, --help, help, Print this help +``` + +To display battery status of bluetooth devices, experimental features must be +enabled in `/etc/bluetooth/main.conf` in the `[General]` section by setting + +``` +Experimental = true +``` + +Allows configuring bluetooth from the command line whilst aliasing devices with +nice names. For example + +``` +desktopctl bluetooth connect sony-headphones +``` + +Instead of + +``` +bluetooth on +bluetoothctl agent on +bluetoothctl default-agent +# Find out the MAC address of your Bluetooth device +# Suppose it is 00:23:02:C0:A9:6F +bluetoothctl connect 00:23:02:C0:A9:6F +``` + +These aliases are defined in the configuration file with a function which must +be called `desktopctl.bt.config` and should return from an alias the correct MAC +address. + +Here is an example + +``` +# Inside ~/.config/desktopctl/desktopctlrc +desktopctl.bt.config () { + case "$1" in + aukey) ID=00:23:02:C0:A9:6F ;; + soundcore) ID=08:EB:ED:5F:37:28 ;; + dell-keyboard) ID=ED:DD:9A:5F:57:DB ;; + dell-mouse) ID=EE:79:C0:96:C5:C3 ;; + hr) ID=DA:80:4B:56:CE:4E ;; + sony) ID=38:18:4C:BE:BB:00 ;; + jlab) ID=00:23:10:0C:74:47 ;; + wacom) ID=DC:2C:26:09:C7:70 ;; + shokz) ID=C0:86:B3:57:39:67 ;; + *) ID=$1 ;; + esac +} +```` + +Bluetooth is also quite fragile. Often one needs to restart to make things work. +This script handles this automatically. + +May require polkit rule to allow restarting bluetooth without password + +This rule will allow any user in the `wheel` group to restart the systemd +`bluetooth.service`. + +``` +polkit.addRule(function(action, subject) { + if (action.id == "org.freedesktop.systemd1.manage-units" && + subject.isInGroup("wheel") && + action.lookup("unit") == "bluetooth.service") { + return polkit.Result.YES; + }; +}); +``` + +#### Colour picker + +Simple colour picker. Copies value to clipboard in RBG, Hex and SRGB values. + +Compatible with wayland and X11. + +#### CPU frequency + +Prints `<avg CPU clock speed>/<max CPU clock speed>` in human readable form + +Data as reported by: `/sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq` + +``` +Arguments: + -a, --avg, avg, Only print average CPU clock speed over all cores + -m, --max, max, Only print maximum CPU clock speed over all cores + -r, --raw, raw, Do not make human readable + + -h, --help, help, Display this help +``` + +Useful for status lines. + +#### Headphone indicator + +Prints indicator if headphones are plugged in + +Uses `pactl` under the hood + +Configure the icon in the configuration file by setting `HEADPHONE_INDICATOR`. + +Useful for status lines. + +#### IP Address + +Get local IP address. + +#### Media Watch Time + +Prints watch times of media with remaining time and percentage. + +Requires `column` from `util-linux`. + +``` +Arguments: + A list of media files (mp4) +``` + +Example: + +``` +$ cd tv-shows/planet-earth +$ desktopctl mediawatchtime *mp4 +Item | Title | Duration | Watched | % Watched | Remaining +1 | S01E01-planet-earth-from-pole-to-pole.mp4: | 0:59 | 0:59 | 9.00 | 9:44 +2 | S01E02-planet-earth-mountains.mp4: | 0:57 | 1:56 | 18.00 | 8:47 +3 | S01E03-planet-earth-fresh-water.mp4: | 0:58 | 2:55 | 27.00 | 7:48 +4 | S01E04-planet-earth-caves.mp4: | 0:57 | 3:52 | 36.00 | 6:51 +5 | S01E05-planet-earth-deserts.mp4: | 0:57 | 4:50 | 45.00 | 5:53 +6 | S01E06-planet-earth-ice-worlds.mp4: | 0:58 | 5:49 | 54.00 | 4:54 +7 | S01E07-planet-earth-great-plains.mp4: | 0:58 | 6:48 | 63.00 | 3:55 +8 | S01E08-planet-earth-jungles.mp4: | 0:58 | 7:46 | 72.00 | 2:56 +9 | S01E09-planet-earth-shallow-seas.mp4: | 0:58 | 8:45 | 81.00 | 1:57 +10 | S01E10-planet-earth-seasonal-forests.mp4: | 0:58 | 9:44 | 90.00 | 0:58 +11 | S01E11-planet-earth-ocean-deep.mp4: | 0:58 | 10:43 | 100.00 | 0:00 +``` + +#### Memory + +Print memory usage (human readable). + +``` +Options + -r, --raw, raw, Display in raw bytes (not human readable). +``` + +Useful for status lines + +#### Monitor Directories/Files + +Prints size, number of files in directory, and changes since last polling. + +Argument: Directory or file to monitor + +``` +Arguments: + dir, Directory or file to monitor + -i, --interval, Time interval to re-compute file sizes and changes in seconds + (Default 60) +``` + +E.g. + +``` +$ rsync /path/to/src/dir /path/to/dest/dir +``` + +Forgot to add progress options! ... instead of cancelling the transfer, just +monitor the destination directory directly + +``` +$ desktopctl mondir -i 5 /path/to/dest/dir +mondir: Monitoring '/path/to/dest/dir' with interval 5s. + +2024-03-30-15:23:14 Total: 188G Files: 349222 +2024-03-30-15:23:20 Total: 188G Files: 349266 Diff: 500MiB Files diff: 44 Speed: 100MiB/s +2024-03-30-15:23:26 Total: 189G Files: 349339 Diff: 525MiB Files diff: 73 Speed: 105MiB/s +... +``` + +Of course this is also useful for tools that do not offer progress statistics. + +#### Check if online + +Get current internet connection status + +``` +Arguments: + -t, --timeout, Set timeout in seconds + -q, --quiet, Do not print. Only uses exit value +``` + +Note: Options must be specified separately i.e. `-q -t 30` and not `-qt30` or +`-qt 30`. + +Useful in scripts, to start backups or synchronise emails only when connected to +the internet. + +#### Screenshots + +Take screenshots + +Supports taking a partial selection of the screen + +Supports wayland/x11 + +Screenshots are copied to the clipboard + +``` +Arguments: + --select, Will ask user to make selection of area to screenshot + --blurred, (x11 only) Will blur screenshot +``` + +Blurred screenshots are nice for creating a lockscreen with current screen +contents blurred. + +#### Sound Manager + +Get and set sound + +``` +Arguments: + +, Increase volume + -, Decrease volume + sink, Print current default output sink + ismuted, Print "yes" if muted all devices are muted, else no + notify, Send a desktop notification of current volume + get-volume, get Print current volume + mute, Mute current default sink + toggle, Toggle mute status +``` + +Uses `pactl` under the hood + +Useful for displaying current volume in status line or when binding keyboard +buttons. + +#### Internet speedtest + +Show current internet speed + +`curl`s a file from Linode + +``` +http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest +``` + +#### SSH + +List ssh clients on local network + +Useful for finding a headless Raspberry Pi after setting it up. + +#### Time zone + +Get and set current time zone. + +Uses [ip-api.com](http://ip-api.com/) to get the time zone based on IP address. + +Uses systemd's `timedatectl` to set the time zone. To do this non-interactively +one needs the following polkit rule + +``` +# /etc/polkit-1/rules.d/timedate.rules +polkit.addRule(function(action, subject) { + if (action.id == "org.freedesktop.timedate1.set-time") { + return polkit.Result.YES; + } +}); +``` + +#### Wifi Status + +Set wifi on/off. Show wifi connection status, signal strength. Useful for status +lines. + +``` +Arguments: + ssid, Print connected ssid + icons, Print ssid with icons + only-icons Only print icons + off, Turn wifi off + on, Turn wifi on +``` + +Configuration values + +``` +WIFI_ICON_CONFIGURING= +WIFI_ICON_LOW_STRENGTH= +WIFI_ICON_MED_STRENGTH= +WIFI_ICON_HIG_STRENGTH= +WIFI_ICON_DISCONNECTED= +WIFI_ICON_OFF= +# nm for Network Manager and iwd for IWD +WIFI_BACKEND=nm +WIFI_DEVICE=wlan0 +``` + +--- + +### Limited Features + +#### Config Diff + +Uses configured `DIFFTOOL` (from configuration file) to display changes of files +that have been modified on disk from how they were originally shipped with the +package manager. + +``` +Arguments: + path, Path to configuration file +``` + +Example: See changes from the default in the bluetooth configuration file, call + +``` +desktopctl config_diff /etc/bluetooth/main.conf +``` + +Only works on Archlinux. + +#### Power Manager + +``` +Charging Profiles: + ac, Primarily AC Charging, Auto performance + express, Express charging, Low performance + +Performance: + auto, Automatically adjust performance + cool, Set performance profile to cool + desktop, Highest performance settings + laptop, Laptop performance settings + low, Set perforamnce to power saving + quiet, Set performance profile to quiet +``` + +#### Reboot check + +Prints information about what services need to be restarted, and whether the +kernel is old + +Used to generally inform, whether the system should be rebooted + +Can be wrapped with pacman hook to give information after update + +``` +Options: + -d, --detailed, Print more detailed information +``` + +#### Xwayland clients + +Count xwayland clients + +Arguemnts: + format, A format string in which '%n' will replace number of Xwayland clients + if there are any. If there are none, nothing will be printed. |