1 .. _joystick-api:
2
3 =====================
4 Programming Interface
5 =====================
6
7 :Author: Ragnar Hojland Espinosa <ragnar@macula
8
9 Introduction
10 ============
11
12 .. important::
13 This document describes legacy ``js`` inter
14 encouraged to switch to the generic event (
15
16 The 1.0 driver uses a new, event based approac
17 Instead of the user program polling for the jo
18 driver now reports only any changes of its sta
19 joystick.h and jstest.c included in the joysti
20 information. The joystick device can be used i
21 nonblocking mode, and supports select() calls.
22
23 For backward compatibility the old (v0.x) inte
24 Any call to the joystick driver using the old
25 that are compatible to the old interface. This
26 to 2 axes, and applications using it usually d
27 the driver provides up to 32.
28
29 Initialization
30 ==============
31
32 Open the joystick device following the usual s
33 Since the driver now reports events instead of
34 immediately after the open it will issue a ser
35 (JS_EVENT_INIT) that you can read to obtain th
36 joystick.
37
38 By default, the device is opened in blocking m
39
40 int fd = open ("/dev/input/js0", O_RDO
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 times
55 __s16 value; /* value */
56 __u8 type; /* event type
57 __u8 number; /* axis/button
58 };
59
60 If the read is successful, it will return size
61 more than one event per read as described in s
62
63
64 js_event.type
65 -------------
66
67 The possible values of ``type`` are::
68
69 #define JS_EVENT_BUTTON 0x01
70 #define JS_EVENT_AXIS 0x02
71 #define JS_EVENT_INIT 0x80
72
73 As mentioned above, the driver will issue synt
74 events on open. That is, if it's issuing an IN
75 current type value will be::
76
77 int type = JS_EVENT_BUTTON | JS_EVENT_
78
79 If you choose not to differentiate between syn
80 you can turn off the JS_EVENT_INIT bits::
81
82 type &= ~JS_EVENT_INIT;
83
84
85 js_event.number
86 ---------------
87
88 The values of ``number`` correspond to the axi
89 generated the event. Note that they carry sepa
90 is, you have both an axis 0 and a button 0). G
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. S
103 directions, some only in 4. The driver, howeve
104 independent axes, even if the hardware doesn't
105
106
107 js_event.value
108 --------------
109
110 For an axis, ``value`` is a signed integer bet
111 representing the position of the joystick alon
112 don't read a 0 when the joystick is ``dead``,
113 full range, you should recalibrate it (with, f
114
115 For a button, ``value`` for a press button eve
116 button event is 0.
117
118 Though this::
119
120 if (js_event.type == JS_EVENT_BUTTON)
121 buttons_state ^= (1 << js_even
122 }
123
124 may work well if you handle JS_EVENT_INIT even
125
126 ::
127
128 if ((js_event.type & ~JS_EVENT_INIT) =
129 if (js_event.value)
130 buttons_state |= (1 <<
131 else
132 buttons_state &= ~(1 <
133 }
134
135 is much safer since it can't lose sync with th
136 have to write a separate handler for JS_EVENT_
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 `
144 in milliseconds since ... well, since sometime
145 task of detecting double clicks, figuring out
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 rea
153 wait) forever until an event is generated and
154 are two alternatives if you can't afford to wa
155 admittedly, a long time;)
156
157 a) use select to wait until there's da
158 until it timeouts. There's a good e
159 man page.
160
161 b) open the device in non-blocking mod
162
163
164 O_NONBLOCK
165 ----------
166
167 If read returns -1 when reading in O_NONBLOCK
168 necessarily a "real" error (check errno(3)); i
169 are no events pending to be read on the driver
170 all events on the queue (that is, until you ge
171
172 For example,
173
174 ::
175
176 while (1) {
177 while (read (fd, &e, sizeof(e)
178 process_event (e);
179 }
180 /* EAGAIN is returned when the
181 if (errno != EAGAIN) {
182 /* error */
183 }
184 /* do something interesting wi
185 }
186
187 One reason for emptying the queue is that if i
188 missing events since the queue is finite, and
189 overwritten.
190
191 The other reason is that you want to know all
192 delay the processing till later.
193
194 Why can the queue get full? Because you don't
195 mentioned, or because too much time elapses fr
196 and too many events to store in the queue get
197 high system load may contribute to space those
198
199 If time between reads is enough to fill the qu
200 the driver will switch to startup mode and nex
201 synthetic events (JS_EVENT_INIT) will be gener
202 the actual state of the joystick.
203
204
205 .. note::
206
207 As of version 1.2.8, the queue is circular an
208 events. You can increment this size bumping u
209 joystick.h and recompiling the driver.
210
211
212 In the above code, you might as well want to r
213 at a time using the typical read(2) functional
214 replace the read above with something like::
215
216 struct js_event mybuffer[0xff];
217 int i = read (fd, mybuffer, sizeof(myb
218
219 In this case, read would return -1 if the queu
220 other value in which the number of events read
221 sizeof(js_event) Again, if the buffer was ful
222 process the events and keep reading it until y
223
224
225 IOCTLs
226 ======
227
228 The joystick driver defines the following ioct
229
230 /* function
231 #define JSIOCGAXES /* get number
232 #define JSIOCGBUTTONS /* get number
233 #define JSIOCGVERSION /* get driver
234 #define JSIOCGNAME(len) /* get identif
235 #define JSIOCSCORR /* set correct
236 #define JSIOCGCORR /* get correct
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-ti
248 driver is 1.0+ and supports the event interfac
249 IOCTL will fail. For a compile-time decision,
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 str
260 as is being printed at boot time. The 'len' ar
261 buffer provided by the application asking for
262 possible overrun should the name be too long::
263
264 char name[128];
265 if (ioctl(fd, JSIOCGNAME(sizeof(name))
266 strscpy(name, "Unknown", sizeo
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 lo
274 not needed in a normal program, only in joysti
275 such as jscal or kcmjoy. These IOCTLs and data
276 to be in the stable part of the API, and there
277 warning in following releases of the driver.
278
279 Both JSIOCSCORR and JSIOCGCORR expect &js_corr
280 information for all axes. That is, struct js_c
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
293 #define JS_CORR_BROKEN 0x01
294
295
296 Backward compatibility
297 ======================
298
299 The 0.x joystick driver API is quite limited a
300 The driver offers backward compatibility, thou
301
302 struct JS_DATA_TYPE js;
303 while (1) {
304 if (read (fd, &js, JS_RETURN)
305 /* error */
306 }
307 usleep (1000);
308 }
309
310 As you can figure out from the example, the re
311 with the actual state of the joystick::
312
313 struct JS_DATA_TYPE {
314 int buttons; /* immediate b
315 int x; /* immediate x
316 int y; /* immediate y
317 };
318
319 and JS_RETURN is defined as::
320
321 #define JS_RETURN sizeof(struct
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
331 except that the values are non-negative. The 1
332 fixed range for reporting the values, 1 being
333 center, and 255 maximum value.
334
335 The v0.8.0.2 driver also had an interface for
336 called Multisystem joysticks in this driver),
337 doesn't try to be compatible with that interfa
338
339
340 Final Notes
341 ===========
342
343 ::
344
345 ____/| Comments, additions, and speci
346 \ o.O| Documentation valid for at lea
347 =(_)= driver and as usual, the ultim
348 U to "Use The Source Luke" or, a
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.