JOY(4)

JOY(4) — joystick device driver 💖🎮

okay bestie, sit down, grab a snack, because this is the Kernel Interfaces Manual page for the joystick device driver and it's genuinely iconic. yes, actual physical joysticks. retro. crunchy. main character energy. let's go ✨

---

🌸 NAME 🌸

joy — the joystick device driver 🕹️

---

✨ SYNOPSIS ✨

so to compile this driver into the kernel, you put these lines in your kernel configuration file:

device joy

or, if you'd rather load it as a module at boot time (honestly? valid), you drop this line into loader.conf(5):

joy_load="YES"

and in /boot/device.hints you write exactly this, no cap:

hint.joy.0.at="isa"
hint.joy.0.port="0x201"
hint.joy.1.at="isa"
hint.joy.1.port="0x201"

also you're gonna want this header, it's literally the whole vibe:

#include <sys/joystick.h>

---

💜 DESCRIPTION 💜

The joystick device driver lets applications read the status of the PC joystick. that's it. that's the job. slay.

heads up bestie: this device may be opened by only one process at a time. it's giving exclusive relationship. no sharing. 🫶

You read the joystick status from a structure via a read() call. the structure lives in the header file and looks like this:

struct joystick {
        int x;         /* x position */
        int y;         /* y position */
        int b1;        /* button 1 status */
        int b2;        /* button 2 status */
};

Positions are typically in the range 0-2000. periodt.

🧚 One line perl example:

not me giving you a whole perl one-liner, but here she is, verbatim, she's a legend:

perl -e 'open(JOY,"/dev/joy0")||die;while(1)
{sysread(JOY,$x,16);@j=unpack("iiii",$x);print "@j\n";sleep(1);}'

🎀 ioctl calls

Several ioctl() calls are also available, bestie. They take an argument of type int *.

• JOY_SETTIMEOUT int *limit — sets the time limit (in microseconds) for reading the joystick status. ⚠️ if you set this value too small it may prevent getting correct values for the positions — and when that happens the positions get set to -2147483648. yes, really, that number. but honestly it can be useful if all you care about is the buttons status. buttons stay booked and busy 💅
• JOY_GETTIMEOUT int *limit — gets the time limit (in microseconds) used for reading the joystick status.
• JOY_SET_X_OFFSET int *offset — sets the value that gets added to the X position when reading the joystick status.
• JOY_SET_Y_OFFSET int *offset — sets the value that gets added to the Y position when reading the joystick status.
• JOY_GET_X_OFFSET int *offset — gets the value which is added to the X position when reading the joystick status.
• JOY_GET_Y_OFFSET int *offset — gets the value which is added to the Y position when reading the joystick status.

---

🦋 TECHNICAL SPECIFICATIONS 🦋

the pinout of the DB-15 connector is as follows, and yes we're doing all fifteen pins, no skipping, that would be rude to pin 8 and pin 15:

• 1 — XY1 (+5v)
• 2 — Switch 1
• 3 — X1 (potentiometer #1)
• 4 — Switch 1 (GND)
• 5 — Switch 2 (GND)
• 6 — Y1 (potentiometer #2)
• 7 — Switch 2
• 8 — N.C.
• 9 — XY2 (+5v)
• 10 — Switch 4
• 11 — X2 (potentiometer #3)
• 12 — Switch 3&4 (GND)
• 13 — Y2 (potentiometer #4)
• 14 — Switch 3
• 15 — N.C.

Pots are normally 0-150k variable resistors (0-100k sometimes), and according to the IBM technical reference, the time is given by:

Time = 24.2e-6s + 0.011e-6s * R/Ohms

math girlies rise 🌈

---

🍓 FILES 🍓

• /dev/joy? — joystick device files

---

⭐ HISTORY ⭐

The joy driver appeared in FreeBSD 2.0.5. ancient. legendary. still here.

---

👑 AUTHORS 👑

Jean-Marc Zucconi <jmz@cabri.obs-besancon.fr> — thank you for your service, king 🫶

---

and that's the whole page bestie!! this one came from the Debian crew and it's dated January 23, 1995 — yeah, 1995, we love a vintage moment 💀🎀 go plug in a joystick and read some bytes, you've got this. bye!! 💖✨