1 .. _joystick-api:
2
3 =====================
4 Programming Interface
5 =====================
6
7 :Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 1998
8
9 Introduction
10 ============
11
12 .. important::
13 This document describes legacy ``js`` interface. Newer clients are
14 encouraged to switch to the generic event (``evdev``) interface.
15
16 The 1.0 driver uses a new, event based approach to the joystick driver.
17 Instead of the user program polling for the joystick values, the joystick
18 driver now reports only any changes of its state. See joystick-api.txt,
19 joystick.h and jstest.c included in the joystick package for more
20 information. The joystick device can be used in either blocking or
21 nonblocking mode, and supports select() calls.
22
23 For backward compatibility the old (v0.x) interface is still included.
24 Any call to the joystick driver using the old interface will return values
25 that are compatible to the old interface. This interface is still limited
26 to 2 axes, and applications using it usually decode only 2 buttons, although
27 the driver provides up to 32.
28
29 Initialization
30 ==============
31
32 Open the joystick device following the usual semantics (that is, with open).
33 Since the driver now reports events instead of polling for changes,
34 immediately after the open it will issue a series of synthetic events
35 (JS_EVENT_INIT) that you can read to obtain the initial state of the
36 joystick.
37
38 By default, the device is opened in blocking mode::
39
40 int fd = open ("/dev/input/js0", O_RDONLY);
41
42
43 Event Reading
44 =============
45
46 ::
47
48 struct js_event e;
49 read (fd, &e, sizeof(e));
50
51 where js_event is defined as::
52
53 struct js_event {
54 __u32 time; /* event timestamp in milliseconds */
55 __s16 value; /* value */
56 __u8 type; /* event type */
57 __u8 number; /* axis/button number */
58 };
59
60 If the read is successful, it will return sizeof(e), unless you wanted to read
61 more than one event per read as described in section 3.1.
62
63
64 js_event.type
65 -------------
66
67 The possible values of ``type`` are::
68
69 #define JS_EVENT_BUTTON 0x01 /* button pressed/released */
70 #define JS_EVENT_AXIS 0x02 /* joystick moved */
71 #define JS_EVENT_INIT 0x80 /* initial state of device */
72
73 As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed
74 events on open. That is, if it's issuing an INIT BUTTON event, the
75 current type value will be::
76
77 int type = JS_EVENT_BUTTON | JS_EVENT_INIT; /* 0x81 */
78
79 If you choose not to differentiate between synthetic or real events
80 you can turn off the JS_EVENT_INIT bits::
81
82 type &= ~JS_EVENT_INIT; /* 0x01 */
83
84
85 js_event.number
86 ---------------
87
88 The values of ``number`` correspond to the axis or button that
89 generated the event. Note that they carry separate numeration (that
90 is, you have both an axis 0 and a button 0). Generally,
91
92 =============== =======
93 Axis number
94 =============== =======
95 1st Axis X 0
96 1st Axis Y 1
97 2nd Axis X 2
98 2nd Axis Y 3
99 ...and so on
100 =============== =======
101
102 Hats vary from one joystick type to another. Some can be moved in 8
103 directions, some only in 4. The driver, however, always reports a hat as two
104 independent axes, even if the hardware doesn't allow independent movement.
105
106
107 js_event.value
108 --------------
109
110 For an axis, ``value`` is a signed integer between -32767 and +32767
111 representing the position of the joystick along that axis. If you
112 don't read a 0 when the joystick is ``dead``, or if it doesn't span the
113 full range, you should recalibrate it (with, for example, jscal).
114
115 For a button, ``value`` for a press button event is 1 and for a release
116 button event is 0.
117
118 Though this::
119
120 if (js_event.type == JS_EVENT_BUTTON) {
121 buttons_state ^= (1 << js_event.number);
122 }
123
124 may work well if you handle JS_EVENT_INIT events separately,
125
126 ::
127
128 if ((js_event.type & ~JS_EVENT_INIT) == JS_EVENT_BUTTON) {
129 if (js_event.value)
130 buttons_state |= (1 << js_event.number);
131 else
132 buttons_state &= ~(1 << js_event.number);
133 }
134
135 is much safer since it can't lose sync with the driver. As you would
136 have to write a separate handler for JS_EVENT_INIT events in the first
137 snippet, this ends up being shorter.
138
139
140 js_event.time
141 -------------
142
143 The time an event was generated is stored in ``js_event.time``. It's a time
144 in milliseconds since ... well, since sometime in the past. This eases the
145 task of detecting double clicks, figuring out if movement of axis and button
146 presses happened at the same time, and similar.
147
148
149 Reading
150 =======
151
152 If you open the device in blocking mode, a read will block (that is,
153 wait) forever until an event is generated and effectively read. There
154 are two alternatives if you can't afford to wait forever (which is,
155 admittedly, a long time;)
156
157 a) use select to wait until there's data to be read on fd, or
158 until it timeouts. There's a good example on the select(2)
159 man page.
160
161 b) open the device in non-blocking mode (O_NONBLOCK)
162
163
164 O_NONBLOCK
165 ----------
166
167 If read returns -1 when reading in O_NONBLOCK mode, this isn't
168 necessarily a "real" error (check errno(3)); it can just mean there
169 are no events pending to be read on the driver queue. You should read
170 all events on the queue (that is, until you get a -1).
171
172 For example,
173
174 ::
175
176 while (1) {
177 while (read (fd, &e, sizeof(e)) > 0) {
178 process_event (e);
179 }
180 /* EAGAIN is returned when the queue is empty */
181 if (errno != EAGAIN) {
182 /* error */
183 }
184 /* do something interesting with processed events */
185 }
186
187 One reason for emptying the queue is that if it gets full you'll start
188 missing events since the queue is finite, and older events will get
189 overwritten.
190
191 The other reason is that you want to know all that happened, and not
192 delay the processing till later.
193
194 Why can the queue get full? Because you don't empty the queue as
195 mentioned, or because too much time elapses from one read to another
196 and too many events to store in the queue get generated. Note that
197 high system load may contribute to space those reads even more.
198
199 If time between reads is enough to fill the queue and lose an event,
200 the driver will switch to startup mode and next time you read it,
201 synthetic events (JS_EVENT_INIT) will be generated to inform you of
202 the actual state of the joystick.
203
204
205 .. note::
206
207 As of version 1.2.8, the queue is circular and able to hold 64
208 events. You can increment this size bumping up JS_BUFF_SIZE in
209 joystick.h and recompiling the driver.
210
211
212 In the above code, you might as well want to read more than one event
213 at a time using the typical read(2) functionality. For that, you would
214 replace the read above with something like::
215
216 struct js_event mybuffer[0xff];
217 int i = read (fd, mybuffer, sizeof(mybuffer));
218
219 In this case, read would return -1 if the queue was empty, or some
220 other value in which the number of events read would be i /
221 sizeof(js_event) Again, if the buffer was full, it's a good idea to
222 process the events and keep reading it until you empty the driver queue.
223
224
225 IOCTLs
226 ======
227
228 The joystick driver defines the following ioctl(2) operations::
229
230 /* function 3rd arg */
231 #define JSIOCGAXES /* get number of axes char */
232 #define JSIOCGBUTTONS /* get number of buttons char */
233 #define JSIOCGVERSION /* get driver version int */
234 #define JSIOCGNAME(len) /* get identifier string char */
235 #define JSIOCSCORR /* set correction values &js_corr */
236 #define JSIOCGCORR /* get correction values &js_corr */
237
238 For example, to read the number of axes::
239
240 char number_of_axes;
241 ioctl (fd, JSIOCGAXES, &number_of_axes);
242
243
244 JSIOGCVERSION
245 -------------
246
247 JSIOGCVERSION is a good way to check in run-time whether the running
248 driver is 1.0+ and supports the event interface. If it is not, the
249 IOCTL will fail. For a compile-time decision, you can test the
250 JS_VERSION symbol::
251
252 #ifdef JS_VERSION
253 #if JS_VERSION > 0xsomething
254
255
256 JSIOCGNAME
257 ----------
258
259 JSIOCGNAME(len) allows you to get the name string of the joystick - the same
260 as is being printed at boot time. The 'len' argument is the length of the
261 buffer provided by the application asking for the name. It is used to avoid
262 possible overrun should the name be too long::
263
264 char name[128];
265 if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0)
266 strscpy(name, "Unknown", sizeof(name));
267 printf("Name: %s\n", name);
268
269
270 JSIOC[SG]CORR
271 -------------
272
273 For usage on JSIOC[SG]CORR I suggest you to look into jscal.c They are
274 not needed in a normal program, only in joystick calibration software
275 such as jscal or kcmjoy. These IOCTLs and data types aren't considered
276 to be in the stable part of the API, and therefore may change without
277 warning in following releases of the driver.
278
279 Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold
280 information for all axes. That is, struct js_corr corr[MAX_AXIS];
281
282 struct js_corr is defined as::
283
284 struct js_corr {
285 __s32 coef[8];
286 __u16 prec;
287 __u16 type;
288 };
289
290 and ``type``::
291
292 #define JS_CORR_NONE 0x00 /* returns raw values */
293 #define JS_CORR_BROKEN 0x01 /* broken line */
294
295
296 Backward compatibility
297 ======================
298
299 The 0.x joystick driver API is quite limited and its usage is deprecated.
300 The driver offers backward compatibility, though. Here's a quick summary::
301
302 struct JS_DATA_TYPE js;
303 while (1) {
304 if (read (fd, &js, JS_RETURN) != JS_RETURN) {
305 /* error */
306 }
307 usleep (1000);
308 }
309
310 As you can figure out from the example, the read returns immediately,
311 with the actual state of the joystick::
312
313 struct JS_DATA_TYPE {
314 int buttons; /* immediate button state */
315 int x; /* immediate x axis value */
316 int y; /* immediate y axis value */
317 };
318
319 and JS_RETURN is defined as::
320
321 #define JS_RETURN sizeof(struct JS_DATA_TYPE)
322
323 To test the state of the buttons,
324
325 ::
326
327 first_button_state = js.buttons & 1;
328 second_button_state = js.buttons & 2;
329
330 The axis values do not have a defined range in the original 0.x driver,
331 except that the values are non-negative. The 1.2.8+ drivers use a
332 fixed range for reporting the values, 1 being the minimum, 128 the
333 center, and 255 maximum value.
334
335 The v0.8.0.2 driver also had an interface for 'digital joysticks', (now
336 called Multisystem joysticks in this driver), under /dev/djsX. This driver
337 doesn't try to be compatible with that interface.
338
339
340 Final Notes
341 ===========
342
343 ::
344
345 ____/| Comments, additions, and specially corrections are welcome.
346 \ o.O| Documentation valid for at least version 1.2.8 of the joystick
347 =(_)= driver and as usual, the ultimate source for documentation is
348 U to "Use The Source Luke" or, at your convenience, Vojtech ;)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.