joystickwake(1)

📦 version 1.0, in ubuntu stonking

💖 joystickwake 💖

okay bestie, gather round, because joystickwake(1) is literally the hero your gaming setup has been waiting for. it's a joystick-aware screen waker, and it lives in the General Commands Manual. yes, the manual name is joystickwake, we're already slaying.

✨ NAME ✨

joystickwake — a joystick-aware screen waker 🕹️✨

🎀 SYNOPSIS 🎀

joystickwake -h|--help|--version

joystickwake [--command CMD] [--cooldown SECONDS] [--loglevel LEVEL]

that's it, that's the whole vibe. three little flags and you're off. 💅

🦋 DESCRIPTION 🦋

so picture this: you're a Linux gamer, you're locked in, main character energy, and then the screen just... blanks. mid-game. not because you stopped playing, but because your display server doesn't recognize game controllers as input devices at all 😭 so the screen blanker thinks you've been idle this whole time and does its little timeout thing right in the middle of your clutch moment.

joystickwake exists to fix exactly that. it works around the problem by suppressing screen blankers while joystick activity is detected. no cap. 🫶

🌸 OVERVIEW 🌸

if you installed it from a package, joystickwake launches automatically whenever a user logs in to any modern linux desktop environment. iconic. but you can also just run it manually, no formal installation needed, because the executable is self-contained. very low maintenance queen behavior. 👑

while it's running, it monitors udev to find devices with the ID_INPUT_JOYSTICK property — and yes, that includes devices you plug in later, it's not going to miss your new controller showing up mid-session 💖 — and it reacts to activity from any of them.

so how does the screen actually stay awake? by periodically running a heartbeat-like wake command: an external tool provided by the system. most desktop environments and screen savers include such a command, and joystickwake already knows how to use the common ones, so normally you do not need to install or configure anything yourself. this design keeps joystickwake compatible with just about every screensaver and power management system there is. it's giving versatility. 🌈

⚙️ OPERATION ⚙️

when joystick activity is detected, all known wake commands are executed. any command that reports an error, or that's missing from the system, gets skipped thereafter. this process repeats in a loop, with a cooldown period between wakes. so joystickwake learns which commands are actually available on the host system, avoids excessive work that might cause game lag, and minimizes log clutter. in practice? it is very lightweight. we love an efficient bestie. 💅

if the python3 dbus-fast package is installed, joystickwake will also try to inhibit screen idle state by obtaining a cookie from the org.freedesktop.ScreenSaver D-Bus interface and holding it while joystick activity continues. this helps with certain environments whose heartbeat-style wake interfaces are missing or broken. cookie-based inhibition, periodt. 🍪

now, the sad part: if all known wakers fail, joystickwake will quit. this could happen if no screen blanker is running, or if one that is running requires a custom wake command (see below).

if the python3 Xlib package is installed, joystickwake will quit when the X11 desktop session ends. otherwise, it will quit when its parent process exits. (this keeps old instances from persisting after the user logs out, on both X and Wayland. so no zombie joystickwake haunting your session, thank u.) 💀

log messages are written to standard error, which is normally captured by the desktop environment in a file such as $HOME/.xsession-errors. at the default log level, few messages will be produced, if any. quiet queen. 🤫

👑 CONFIGURATION AND OPTIONS 👑

in many desktop environments, no configuration is needed. joystickwake comes preconfigured with commands that will suppress common screensavers and DPMS power-off. those commands are:

xset dpms force on
xset s reset
xscreensaver-command -deactivate
gnome-screensaver-command --deactivate
mate-screensaver-command --poke
xfce4-screensaver-command --poke
dbus-send [...] org.freedesktop.ScreenSaver.SimulateUserActivity
dbus-send [...] org.freedesktop.ScreenSaver.Inhibit
dbus-send [...] org.gnome.ScreenSaver.SetActive false

a whole arsenal, preloaded, no setup required. 🎀

if needed, an additional wake command can be configured in either of the following files:

$XDG_CONFIG_HOME/joystickwake/joystickwake.conf
$HOME/.config/joystickwake/joystickwake.conf

this example illustrates the configuration file format and settings:

command = xdg-screensaver reset # This might work on some desktops
cooldown = 30                   # Number of seconds between wakes
loglevel = warning              # Also: debug, info, error, critical

and listen: command line options --command, --cooldown, and --loglevel will override their corresponding config file settings. cli wins, always. 💪

🔍 TROUBLESHOOTING 🔍

the first step in diagnosing a problem is to set joystickwake's log level to debug, restart it, and look for unexpected messages when the problem occurs. running it in a terminal window may help with log visibility. front-row seats to the drama, honestly.

note: joystickwake cannot see your screen, and therefore has no way to be certain of its state. a success message in the log means only that a wake command ran without reporting an error. that is a good sign, but not always sufficient to wake the screen, especially if that wake command was designed for a screen blanker other than the one in use. so don't come for it, it's doing its best 🥺

every log message begins with "joystickwake" and a timestamp, so if you see text in some other format, it comes from another program. for example, one of the wake commands might print a message about being unable to find its screen saver, or your shell's command-not-found script might offer suggestions when joystickwake probes for a command that is not installed on your system. both of these examples are harmless, and should appear only a few times, since joystickwake avoids commands that keep failing after a few tries. like, it learns. it's smart. ✨

if joystickwake keeps the screen awake even when all joysticks are idle, it is likely due to a worn joystick sensor constantly reporting movement. this is unfortunately common in game controllers, and related to the "stick drift" problem that is well known in console gaming. it can usually be resolved by repairing or replacing the hardware, disconnecting it when not in use, or calibrating the dead zones used by the linux joystick and evdev APIs as described here:

<https://wiki.archlinux.org/title/Gamepad#Setting_up_deadzones_and_calibration>

calibration tips:

  • joystickwake uses the joystick API by default, so it's best to calibrate that first. consider calibrating evdev only if required for a particular device.
  • the jstest-gtk tool is probably the easiest way to calibrate the joystick API. see the above wiki page for guidance.
  • if calibrating evdev, focus on the fuzz setting. the flatness or deadzone setting may have no effect at all.
  • calibration settings reset when the operating system is restarted. to make them persist, they must be saved in a file and then re-applied whenever the system starts or the game controller is reconnected. this is best done with a udev rule. Debian-based systems offer a joystick package that will automatically restore calibration settings once they have been saved by running sudo jscal-store. the same can be achieved on other distros using the information given here: <https://sourceforge.net/p/linuxconsole/code/ci/master/tree/README>

if the screen wakes with joystick input, but never blanks again even after all joysticks are disconnected, it is possible that one of the wake commands detected on your system is communicating incorrectly with your screen blanker. for example, one user experienced this in a modern GNOME Shell after installing a legacy gnome-screensaver package. in that case, the solution was to remove packages intended for old or unused screen blankers, and rely on Joystickwake's cookie-based D-Bus idle inhibitor instead. switching from GNOME's Wayland session to X11 might also help in some cases. 🙈

if the log shows at least one waker succeeding but the screen still blanks while a joystick is in use, your screen blanker's timeout might be too short for joystickwake. if so, increasing that timeout or decreasing joystickwake's cooldown setting (making it the shorter of the two) will help.

alternatively, it is possible that multiple screen blankers are running, such as a graphical screen saver and a power manager, with joystickwake only knowing how to wake one of them. the solution is to find a command that will wake the problematic one, make sure that command is installed, and if joystickwake doesn't recognize it by default, configure it as a custom command.

if all wakers fail and the screen still blanks, the solution is the same as above: identify your desktop's screen blanker, install a command that will wake it, and (if necessary) configure joystickwake to use it.

🛠️ CUSTOM WAKE COMMANDS 🛠️

if none of joystickwake's preconfigured commands wake the screen in a particular desktop environment, finding one that does can require some effort. asking community members who use the same environment might yield a helpful answer. once you know the name of the component that blanks the screen, consult its documentation to see if it has a command line tool for controlling it. it may also be worthwhile to query your linux distribution's package manger to see if such a tool was installed along with the screen blanker.

after identifying a command that might work, the next step is to test it, preferably without joystickwake running. the simplest way is to set your screen blanker to use a short timeout (e.g. one minute), run the command preceded by a sleep delay longer than the blanker's timeout, and let your system sit idle to see if it works. science. 🔬

for example, this command line does it with a 77 second delay:

sleep 77; my-cmd --wake

if the screen blanks as expected and then wakes after the sleep delay, the command will probably work with joystickwake. you can try it in a terminal window, like so:

joystickwake --loglevel debug --cooldown 2 --command "my-cmd --wake"

if joystickwake logs a "custom waker failed" message, it means the custom command either produced an error or could not be executed. if pressing a joystick button wakes the screen and logs a "custom waker succeeded" message, then the command works, and can be saved in the configuration file for future login sessions. slay, you did it. 🎉

when run in a terminal window, Control+C will tell joystickwake to quit.

the xdg-screensaver tool might work as a custom wake command in some environments:

xdg-screensaver reset

users of KDE Plasma with XWayland might find that joystickwake's preconfigured commands do not suppress the screen energy saving feature. this appears to be a bug in KDE's SimulateUserActivity implementation, reported as bug #440882. a KDE maintainer stated in that report that XWayland is not supported, so the bug seems unlikely to be fixed, but the following custom wake command might be an effective workaround:

qdbus org.kde.Solid.PowerManagement /org/kde/Solid/PowerManagement wakeup

...and bestie, there's more coming, don't go anywhere 💜

🛠️ MANUAL INSTALLATION (we do it by hand, bestie) 🛠️

Okay so some Linux distros just do not ship a joystickwake package, and that's fine, you can absolutely install it yourself. The iconic thing about this program: it's a self-contained single-file Python program, so there is literally no build step, no extra files to drag along. It's giving "I'm low maintenance" and we love that for her. 💅

  1. Copy the joystickwake file into a directory that's listed in the user's PATH environment variable, like /usr/local/bin or $HOME/bin. ✨
  2. Grant execute permission on that copy. (The classic chmod moment, iykyk.) 🔥

Want your desktop environment to automatically launch joystickwake at login time? Then copy joystickwake.desktop into /etc/xdg/autostart or $HOME/.config/autostart. 🎀

You can usually get the same effect with a window manager that doesn't support .desktop file autostart, but ngl the method totally depends on the GUI startup system in use, so the manpage can't give general instructions here. (Hint: it may involve a GUI session startup script, like $HOME/.xinitrc if you're using startx.) 🧚

joystickwake can also be added to a desktop environment's applications menu by copying joystickwake.desktop to /usr/share/applications or $HOME/.local/share/applications. But this is not recommended, bestie — it can lead users to accidentally launch multiple joystickwake instances, and automatic launching at login time is usually more convenient anyway. 🙈

Yo, make sure the dependencies are installed before you try to launch joystickwake. No cap. ⭐

🐍 PYTHON DEPENDENCIES 🐍

👀 SEE ALSO (the extended universe) 👀

And that's the whole vibe, bestie!! 💖✨ That was the joystickwake(1) manual, dated 2026-08-03 — go forth and never let your screen go dark mid-game again. Slay, periodt. 🎀🦋

📦 where this page comes from