349 lines · plain
1.. _joystick-api:2 3=====================4Programming Interface5=====================6 7:Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 19988 9Introduction10============11 12.. important::13 This document describes legacy ``js`` interface. Newer clients are14 encouraged to switch to the generic event (``evdev``) interface.15 16The 1.0 driver uses a new, event based approach to the joystick driver.17Instead of the user program polling for the joystick values, the joystick18driver now reports only any changes of its state. See joystick-api.txt,19joystick.h and jstest.c included in the joystick package for more20information. The joystick device can be used in either blocking or21nonblocking mode, and supports select() calls.22 23For backward compatibility the old (v0.x) interface is still included.24Any call to the joystick driver using the old interface will return values25that are compatible to the old interface. This interface is still limited26to 2 axes, and applications using it usually decode only 2 buttons, although27the driver provides up to 32.28 29Initialization30==============31 32Open the joystick device following the usual semantics (that is, with open).33Since the driver now reports events instead of polling for changes,34immediately after the open it will issue a series of synthetic events35(JS_EVENT_INIT) that you can read to obtain the initial state of the36joystick.37 38By default, the device is opened in blocking mode::39 40 int fd = open ("/dev/input/js0", O_RDONLY);41 42 43Event Reading44=============45 46::47 48 struct js_event e;49 read (fd, &e, sizeof(e));50 51where 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 60If the read is successful, it will return sizeof(e), unless you wanted to read61more than one event per read as described in section 3.1.62 63 64js_event.type65-------------66 67The 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 73As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed74events on open. That is, if it's issuing an INIT BUTTON event, the75current type value will be::76 77 int type = JS_EVENT_BUTTON | JS_EVENT_INIT; /* 0x81 */78 79If you choose not to differentiate between synthetic or real events80you can turn off the JS_EVENT_INIT bits::81 82 type &= ~JS_EVENT_INIT; /* 0x01 */83 84 85js_event.number86---------------87 88The values of ``number`` correspond to the axis or button that89generated the event. Note that they carry separate numeration (that90is, you have both an axis 0 and a button 0). Generally,91 92 =============== =======93 Axis number94 =============== =======95 1st Axis X 096 1st Axis Y 197 2nd Axis X 298 2nd Axis Y 399 ...and so on100 =============== =======101 102Hats vary from one joystick type to another. Some can be moved in 8103directions, some only in 4. The driver, however, always reports a hat as two104independent axes, even if the hardware doesn't allow independent movement.105 106 107js_event.value108--------------109 110For an axis, ``value`` is a signed integer between -32767 and +32767111representing the position of the joystick along that axis. If you112don't read a 0 when the joystick is ``dead``, or if it doesn't span the113full range, you should recalibrate it (with, for example, jscal).114 115For a button, ``value`` for a press button event is 1 and for a release116button event is 0.117 118Though this::119 120 if (js_event.type == JS_EVENT_BUTTON) {121 buttons_state ^= (1 << js_event.number);122 }123 124may 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 else132 buttons_state &= ~(1 << js_event.number);133 }134 135is much safer since it can't lose sync with the driver. As you would136have to write a separate handler for JS_EVENT_INIT events in the first137snippet, this ends up being shorter.138 139 140js_event.time141-------------142 143The time an event was generated is stored in ``js_event.time``. It's a time144in milliseconds since ... well, since sometime in the past. This eases the145task of detecting double clicks, figuring out if movement of axis and button146presses happened at the same time, and similar.147 148 149Reading150=======151 152If you open the device in blocking mode, a read will block (that is,153wait) forever until an event is generated and effectively read. There154are two alternatives if you can't afford to wait forever (which is,155admittedly, a long time;)156 157 a) use select to wait until there's data to be read on fd, or158 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 164O_NONBLOCK165----------166 167If read returns -1 when reading in O_NONBLOCK mode, this isn't168necessarily a "real" error (check errno(3)); it can just mean there169are no events pending to be read on the driver queue. You should read170all events on the queue (that is, until you get a -1).171 172For 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 187One reason for emptying the queue is that if it gets full you'll start188missing events since the queue is finite, and older events will get189overwritten.190 191The other reason is that you want to know all that happened, and not192delay the processing till later.193 194Why can the queue get full? Because you don't empty the queue as195mentioned, or because too much time elapses from one read to another196and too many events to store in the queue get generated. Note that197high system load may contribute to space those reads even more.198 199If time between reads is enough to fill the queue and lose an event,200the driver will switch to startup mode and next time you read it,201synthetic events (JS_EVENT_INIT) will be generated to inform you of202the 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 64208 events. You can increment this size bumping up JS_BUFF_SIZE in209 joystick.h and recompiling the driver.210 211 212In the above code, you might as well want to read more than one event213at a time using the typical read(2) functionality. For that, you would214replace the read above with something like::215 216 struct js_event mybuffer[0xff];217 int i = read (fd, mybuffer, sizeof(mybuffer));218 219In this case, read would return -1 if the queue was empty, or some220other value in which the number of events read would be i /221sizeof(js_event) Again, if the buffer was full, it's a good idea to222process the events and keep reading it until you empty the driver queue.223 224 225IOCTLs226======227 228The 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 238For example, to read the number of axes::239 240 char number_of_axes;241 ioctl (fd, JSIOCGAXES, &number_of_axes);242 243 244JSIOGCVERSION245-------------246 247JSIOGCVERSION is a good way to check in run-time whether the running248driver is 1.0+ and supports the event interface. If it is not, the249IOCTL will fail. For a compile-time decision, you can test the250JS_VERSION symbol::251 252 #ifdef JS_VERSION253 #if JS_VERSION > 0xsomething254 255 256JSIOCGNAME257----------258 259JSIOCGNAME(len) allows you to get the name string of the joystick - the same260as is being printed at boot time. The 'len' argument is the length of the261buffer provided by the application asking for the name. It is used to avoid262possible 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 270JSIOC[SG]CORR271-------------272 273For usage on JSIOC[SG]CORR I suggest you to look into jscal.c They are274not needed in a normal program, only in joystick calibration software275such as jscal or kcmjoy. These IOCTLs and data types aren't considered276to be in the stable part of the API, and therefore may change without277warning in following releases of the driver.278 279Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold280information for all axes. That is, struct js_corr corr[MAX_AXIS];281 282struct js_corr is defined as::283 284 struct js_corr {285 __s32 coef[8];286 __u16 prec;287 __u16 type;288 };289 290and ``type``::291 292 #define JS_CORR_NONE 0x00 /* returns raw values */293 #define JS_CORR_BROKEN 0x01 /* broken line */294 295 296Backward compatibility297======================298 299The 0.x joystick driver API is quite limited and its usage is deprecated.300The 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 310As you can figure out from the example, the read returns immediately,311with 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 319and JS_RETURN is defined as::320 321 #define JS_RETURN sizeof(struct JS_DATA_TYPE)322 323To test the state of the buttons,324 325::326 327 first_button_state = js.buttons & 1;328 second_button_state = js.buttons & 2;329 330The axis values do not have a defined range in the original 0.x driver,331except that the values are non-negative. The 1.2.8+ drivers use a332fixed range for reporting the values, 1 being the minimum, 128 the333center, and 255 maximum value.334 335The v0.8.0.2 driver also had an interface for 'digital joysticks', (now336called Multisystem joysticks in this driver), under /dev/djsX. This driver337doesn't try to be compatible with that interface.338 339 340Final Notes341===========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 joystick347 =(_)= driver and as usual, the ultimate source for documentation is348 U to "Use The Source Luke" or, at your convenience, Vojtech ;)349