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