joystick(4)

💖 joystick — the joystick(4) manual, bestie edition 💖

okay so. you opened man 4 joystick. welcome. this is the joystick input driver page and it's lowkey long so grab a snack 🍓

---

✨ NAME ✨

joystick — Joystick input driver 🕹️

---

🌸 SYNOPSIS 🌸

Snipped for xorg.conf.d(5):

Section "InputClass"
  Identifier "joystick-all"
  Driver "joystick"
  Option "MatchIsJoystick"   "on"
  Option "MatchDevicePath"   "/dev/input/event*"
  ...
EndSection

---

💅 DESCRIPTION 💅

joystick is an Xorg input driver for controlling the pointer with a joystick device. that's it, that's the whole job, she's a pointer-wrangler 🎀

Use this driver, if you want to:

• generate cursor movement, perform button or key events to control desktop and applications
• generate cursor key events for playing legacy games, that have no native joystick support

Do not use, if you want to:

• play games, that have native joystick support
• use XI2 applications. The evdev(4) driver will suffice for those in most cases.

You may mix above scenarios by setting the device floating. The driver reports relative cursor movement, button and key events, as well as raw axis values through valuators. ✨

---

🎮 SUPPORTED HARDWARE 🎮

The joystick input module can be used on top of the following kernel devices:

• Linux's evdev device
• Linux's joystick device
• BSD's usbhid device

Every joystick supported by the kernel should be supported by the joystick input driver. The joystick is assumed to be calibrated and reporting axis values between -32768 and 32768. See the Linux kernel documentation for a complete list of supported devices.

There is no support for force feedback at the moment. 😭 no rumble bestie, we're mourning that one together

---

🛠️ CONFIGURATION DETAILS 🛠️

Please refer to xorg.conf(5) for general configuration details. This section only covers configuration details specific to this driver. iykyk, the general stuff lives elsewhere 💜

The following Driver Options are supported:

• Option "Device" "string"
• Option "Path" "string" — Specifies the device through which the joystick can be accessed. This option is mandatory and there is no default setting.

In Linux, joysticks are usually accessible through /dev/input/jsX or /dev/input/eventX.

In *BSD, joysticks are usually recognized as /dev/uhidX.

• Option "AutoRepeat" "delay rate" — Sets the auto repeat behaviour for key events. delay is the time in milliseconds before a key starts repeating. rate is the number of times a key repeats per second. Default: Xorg default.
• Option "DebugLevel" "integer" — Controls the verbosity of the driver for debugging purposes. The higher the DebugLevel, the more output is produced. Default: 0.
• Option "MapButton<number>" "string" — Sets the mapping of a joystick button to the desired action. Button counting starts with 1. Possible options are:
  • none — Don't do anything
  • "button=<number>" — Generate a pointer button event with button number (starting with 1).
  • "axis=[<factor>]<axis>" — Where <axis> is one of: x, y, zx, zy

and <factor> is an optional amplifier of the axis, like -, +, -5, 0.4, 1.3, ... Negative values invert the direction. Default: 1.0

• "amplify=<factor>" — Amplifies the movement of all axes by the given factor when this button is held down. Different factors can be combined.
• "key=<scancode>[,<scancode>[,<scancode>[,<scancode>]]]" — When button is pressed, a series of keydown events with the specified scancodes is generated. When the button is released, matching keyup events in the opposite order are generated. You can specify up to 4 scancodes per button.

See special section about key events below.

• "disable-mouse"
• "disable-keys"
• "disable-all" — Disables either the generation of mouse events, key events or the generation of all X events by the driver. Press button again to allow the driver to generate events again.

You may also set the device floating from client space to prevent it from generating core events.

• Option "MapAxis<number>" "string" — Sets the mapping of the axis to the desired action. Axis counting starts with 1, the parameter may contain:
  • "mode=<string>" — Where <string> can be one of:

none, relative, accelerated, absolute

• "valuator" — Send extra valuator events for this axis. The valuators will be numbered ascending, starting with 2 (valuator 0 and 1 are reserved for pointer movement). Please consider using the evdev(4) input driver if you are only interested in XI2 features.

The range of the valuators is always -32767 to 32768. Neither mode nor axis needs to be set to generate extra valuator events. The axis will be labelled according to its physical axis number, beginning with 1, e.g. "Axis 1" for the first axis (being the 3rd valuator). Default: not set.

• "axis=[<factor>]<axis>" — Where <axis> is one of: x, y, zx, zy, key (see keylow/keyhigh)

and <factor> is an optional amplifier of the axis, like -, +, -5, 0.4, 1.3, ... Negative values will invert the movement. Default: 1.0

• "keylow=<scancode>[,<scancode>[,<scancode>[,<scancode>]]]"
• "keyhigh=<scancode>[,<scancode>[,<scancode>[,<scancode>]]]" — When the axis is moved out of the deadzone, a series of keydown events according to the direction of the movement is generated. When the axis is released, matching keyup events in opposite order will be generated. You can specify up to 4 scancodes for each direction.

keylow defines the keys to be generated when the axis is moved in negative direction (left or up), keyhigh defines the keys to be generated when the axis is moved in positive direction (right or down).

If mode is set to relative: The driver will emulate autorepeat according to the current value of the axis. A keydown and subsequent keyup event will be generated in short time intervals. To modify that interval and the autorepeat speed, supply the "axis=[<factor>]KEY" parameter.

If mode is set to accelerated: Keydown and keyup events will be generated repeatedly. The time between a keydown and a keyup event corresponds to the deflection of the axis. If the axis is deflected by 30%, the key will be considered to be down 300ms out of 1 second. The exact intervals may vary and can be adjusted with the amplify parameter. If the axis is deflected by 100%, there will only be one keydown event, so the key is considered down all the time. The keys will be autorepeated according to the Xorg keyboard settings.

See special section about key events below.

• "deadzone=<number>" — Sets the unresponsive range of the axis to <number>. This can be between 0 and 30000. Default: 5000

• Option "StartKeysEnabled" "boolean" — Set to False to disable key event generation after startup. You can toggle key event generation with the disable-keys button mapping. Default: enabled
• Option "StartMouseEnabled" "boolean" — Set to False to disable mouse event generation after startup. You can toggle mouse event generation with the disable-mouse button mapping. Default: enabled

---

🌈 DEFAULT CONFIGURATION 🌈

The default configuration is as follows:

  Option "DebugLevel"        "0"
  Option "StartKeysEnabled"  "True"
  Option "StartMouseEnabled" "True"
  Option "MapButton1"        "button=1"
  Option "MapButton2"        "button=2"
  Option "MapButton3"        "button=3"
  Option "MapButton4"        "none"
  ...
  Option "MapAxis1"          "mode=relative    axis=+1x  deadzone=5000"
  Option "MapAxis2"          "mode=relative    axis=+1y  deadzone=5000"
  Option "MapAxis3"          "mode=relative    axis=+1zx deadzone=5000"
  Option "MapAxis4"          "mode=relative    axis=+1zy deadzone=5000"
  Option "MapAxis5"          "mode=accelerated axis=+1x  deadzone=5000"
  Option "MapAxis6"          "mode=accelerated axis=+1y  deadzone=5000"
  Option "MapAxis7"          "mode=none"
  ...

---

🚀 ACCELERATED AXIS CONFIGURATION 🚀

accelerated mode should be selected, if the axis is a directional pad, which reports only three states: negative, center, positive. It will result in smoothly accelerated movement when the axis is deflected. An optional factor will affect the acceleration and final speed. she zooms ✨

This example will set up the axis as scrolling vertically inverted, with half the speed:

  Option "MapAxis1"     "mode=accelerated axis=-0.5zy"

This example maps four buttons to the four pointer directions, so you can use the buttons like a d-pad. The movement will be accelerated with half the normal speed:

  Option "MapButton1"     "axis=+0.5x"
  Option "MapButton2"     "axis=-0.5x"
  Option "MapButton3"     "axis=+0.5y"
  Option "MapButton4"     "axis=-0.5y"

---

🎯 ABSOLUTE AXIS CONFIGURATION 🎯

In absolute axis mode, the position of the cursor will match the position of the configured axis, but relative to the previous position of the cursor. You can specify the range in which the cursor can move. The default range is the screen size. 👑

In this example the first axis gets a range from left to the right of the screen. The second axis gets a total range of 200 pixels, 100 to the top and 100 to the bottom:

  Option "MapAxis1"     "mode=absolute axis=x"
  Option "MapAxis2"     "mode=absolute axis=200y"

---

okay that's the first half bestie, hold on, there's more coming 💖

⌨️ GENERATING KEY EVENTS ⌨️

okay so bestie, you can make the joystick spit out actual X Events instead of cursor moves. How? You drop a "key=<scancode>[,<scancode>[...]]" option and it just... does it. ✨ And here's the cute part: when the button or axis gets released, the keys get released in the opposite order. Symmetry, we love to see it. 💅

Want a specific KeySym but don't know which scancode it maps to? Bestie, just run xmodmap -pk and look up the match. Easy. 🎀 And heads up — the scancodes you get depend on whatever keyboard layout you've got configured, so don't be surprised if things move around. You can also grab unused keycodes and map them to a KeySym of your choosing with xmodmap(1). Fully your call.

You get up to 4 scancodes per joystick button/axis, which is lowkey perfect for stacking modificators so you land on exactly the KeySym you wanted. 👑

Examples, because examples are everything:

Option "MapButton1"     "key=64,23"

that one generates Alt_L+Tab the moment you press the button. Chef's kiss. 🫶

Option "MapButton1"     "key=50,40"

this generates a Shift_L+d, which lands you an uppercase d. The way that works is so satisfying honestly.

Option "MapButton1"     "key=65"

boom — space key. 🍓

Option  "MapAxis1"      "mode=relative    keylow=113  keyhigh=114 axis=0.5key"
Option  "MapAxis2"      "mode=relative    keylow=111  keyhigh=116"
Option  "MapAxis3"      "mode=accelerated keylow=113  keyhigh=114"
Option  "MapAxis4"      "mode=accelerated keylow=111  keyhigh=116"

and this whole thing maps the first and third axis to the arrow keys left and right, and the second and fourth axis to the arrow keys up and down. Iconic. 🌈

Now the deets on timing, because this part matters:

• The keys for the first two axes get generated in an interval according to the value of the axis. And listen — the autorepeat speed of the first axis will be half the speed of that of the second axis. Yes, literally half. 🫠
• The keys for the third and fourth axis are generated once when the axis moves out of the deadzone, and again when it moves back into the deadzone. Then X.Org will autorepeat those keys according to your current keyboard settings. So it's giving "hand it off to the keyboard, she's got it from here." 💅

---

🦋 XI2 Events 🦋

ngl, if all you actually care about is raw valuator events and you're not trying to drive the cursor around with your joystick, do yourself a favor and check out the evdev(4) input driver instead. Just saying. 👀

But if you're still using the joystick driver for raw events anyway (respect), then make sure you unmap all axes/buttons and add the valuator option to the axes:

Option  "MapAxis1"      "mode=none valuator"
Option  "MapAxis2"      "mode=none valuator"
Option  "MapAxis3"      "mode=none valuator"
Option  "MapAxis4"      "mode=none valuator"
...
Option  "MapButton1"      "button=1"
Option  "MapButton2"      "button=2"
Option  "MapButton3"      "button=3"
Option  "MapButton4"      "button=4"
Option  "MapButton5"      "button=5"
...

⚠️ Remember bestie — valuators 0 and 1 are reserved for pointer movement. Your additional axes will start with valuator 2. Don't fight it, that's just the law. 💀

You might also wanna set the device "floating" so it stops reporting core events:

Option  "Floating"      "true"

---

📝 NOTES 📝

okay real talk, here's the stuff you actually need to know:

• It is not recommended to enable the joystick input driver by default unless the user explicitly asks for it. Like, don't just turn it on for everyone, that's chaos energy. 🙈
• Configuration through InputClass sections is recommended in X servers 1.8 and later. Peep xorg.conf.d(5) for more details. There's an example xorg.conf.d(5) file waiting for you at ${sourcecode}/config/50-joystick-all.conf. 🎀
• Configuration through hal fdi files is recommended in X servers 1.5, 1.6 and 1.7. An example hal policy file is still provided in ${sourcecode}/config/50-x11-input-joystick.fdi, and you'd place it in /etc/hal/fdi/policy. ✨

---

👀 SEE ALSO 👀

Xorg(1), xorg.conf(5), xorg.conf.d(5), Xserver(1), X(7), xmodmap(1)

go read those if you want the full lore, iykyk 💜

---

👑 AUTHORS 👑

• Sascha Hlusiak (2007-2012)
• Frederic Lepied (1995-1999)

legends, fr fr 🫶

---

and that's the whole page bestie!! 🎉 this was X Version 11, xf86-input-joystick 1.6.4, and the page is joystick(4). slay, you made it to the end, go map some axes 💅✨🌸