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