kernel/linux/Documentation/input/ff.txt

   1 Force feedback for Linux.
   2 By Johann Deneux <deneux@ifrance.com> on 2001/04/22.
   3 You may redistribute this file. Please remember to include shape.fig and
   4 interactive.fig as well.
   5 ----------------------------------------------------------------------------
   6
   7 0. Introduction
   8 ~~~~~~~~~~~~~~~
   9 This document describes how to use force feedback devices under Linux. The
  10 goal is not to support these devices as if they were simple input-only devices
  11 (as it is already the case), but to really enable the rendering of force
  12 effects.
  13 At the moment, only I-Force devices are supported, and not officially. That
  14 means I had to find out how the protocol works on my own. Of course, the
  15 information I managed to grasp is far from being complete, and I can not
  16 guarranty that this driver will work for you.
  17 This document only describes the force feedback part of the driver for I-Force
  18 devices. Please read joystick.txt before reading further this document.
  19
  20 2. Instructions to the user
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22 Here are instructions on how to compile and use the driver. In fact, this
  23 driver is the normal iforce, input and evdev drivers written by Vojtech
  24 Pavlik, plus additions to support force feedback.
  25
  26 Before you start, let me WARN you that some devices shake violently during the
  27 initialisation phase. This happens for example with my "AVB Top Shot Pegasus".
  28 To stop this annoying behaviour, move you joystick to its limits. Anyway, you
  29 should keep a hand on your device, in order to avoid it to brake down if
  30 something goes wrong.
  31
  32 At the kernel's compilation:
  33         - Enable IForce/Serial
  34         - Enable Event interface
  35
  36 Compile the modules, install them.
  37
  38 You also need inputattach.
  39
  40 You then need to insert the modules into the following order:
  41 % modprobe joydev
  42 % modprobe serport              # Only for serial
  43 % modprobe iforce
  44 % modprobe evdev
  45 % ./inputattach -ifor $2 &      # Only for serial
  46 If you are using USB, you don't need the inputattach step.
  47
  48 Please check that you have all the /dev/input entries needed:
  49 cd /dev
  50 rm js*
  51 mkdir input
  52 mknod input/js0 c 13 0
  53 mknod input/js1 c 13 1
  54 mknod input/js2 c 13 2
  55 mknod input/js3 c 13 3
  56 ln -s input/js0 js0
  57 ln -s input/js1 js1
  58 ln -s input/js2 js2
  59 ln -s input/js3 js3
  60
  61 mknod input/event0 c 13 64
  62 mknod input/event1 c 13 65
  63 mknod input/event2 c 13 66
  64 mknod input/event3 c 13 67
  65
  66 2.1 Does it work ?
  67 ~~~~~~~~~~~~~~~~~~
  68 There is an utility called fftest that will allow you to test the driver.
  69 % fftest /dev/input/eventXX
  70
  71 3. Instructions to the developper
  72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73   All interactions are done using the event API. That is, you can use ioctl()
  74 and write() on /dev/input/eventXX.
  75   This information is subject to change.
  76
  77 3.1 Querying device capabilities
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79 #include <linux/input.h>
  80 #include <sys/ioctl.h>
  81
  82 unsigned long features[1 + FF_MAX/sizeof(unsigned long)];
  83 int ioctl(int file_descriptor, int request, unsigned long *features);
  84
  85 "request" must be EVIOCGBIT(EV_FF, size of features array in bytes )
  86
  87 Returns the features supported by the device. features is a bitfield with the
  88 following bits:
  89 - FF_X          has an X axis (usually joysticks)
  90 - FF_Y          has an Y axis (usually joysticks)
  91 - FF_WHEEL      has a wheel (usually sterring wheels)
  92 - FF_CONSTANT   can render constant force effects
  93 - FF_PERIODIC   can render periodic effects (sine, triangle, square...)
  94 - FF_RAMP       can render ramp effects
  95 - FF_SPRING     can simulate the presence of a spring
  96 - FF_FRICTION   can simulate friction
  97 - FF_DAMPER     can simulate damper effects
  98 - FF_RUMBLE     rumble effects (normally the only effect supported by rumble
  99                 pads)
 100 - FF_INERTIA    can simulate inertia
 101
 102
 103 int ioctl(int fd, EVIOCGEFFECTS, int *n);
 104
 105 Returns the number of effects the device can keep in its memory.
 106
 107 3.2 Uploading effects to the device
 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 109 #include <linux/input.h>
 110 #include <sys/ioctl.h>
 111
 112 int ioctl(int file_descriptor, int request, struct ff_effect *effect);
 113
 114 "request" must be EVIOCSFF.
 115
 116 "effect" points to a structure describing the effect to upload. The effect is
 117 uploaded, but not played.
 118 The content of effect may be modified. In particular, its field "id" is set
 119 to the unique id assigned by the driver. This data is required for performing
 120 some operations (removing an effect, controlling the playback).
 121 This if field must be set to -1 by the user in order to tell the driver to
 122 allocate a new effect.
 123 See <linux/input.h> for a description of the ff_effect stuct. You should also
 124 find help in a few sketches, contained in files shape.fig and interactive.fig.
 125 You need xfig to visualize these files.
 126
 127 3.3 Removing an effect from the device
 128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 129 int ioctl(int fd, EVIOCRMFF, effect.id);
 130
 131 This makes room for new effects in the device's memory. Please note this won't
 132 stop the effect if it was playing.
 133
 134 3.4 Controlling the playback of effects
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 136 Control of playing is done with write(). Below is an example:
 137
 138 #include <linux/input.h>
 139 #include <unistd.h>
 140
 141         struct input_event play;
 142         struct input_event stop;
 143         struct ff_effect effect;
 144         int fd;
 145 ...
 146         fd = open("/dev/input/eventXX", O_RDWR);
 147 ...
 148         /* Play three times */
 149         play.type = EV_FF;
 150         play.code = effect.id;
 151         play.value = 3;
 152
 153         write(fd, (const void*) &play, sizeof(play));
 154 ...
 155         /* Stop an effect */
 156         stop.type = EV_FF;
 157         stop.code = effect.id;
 158         stop.value = 0;
 159
 160         write(fd, (const void*) &play, sizeof(stop));
 161
 162 3.5 Setting the gain
 163 ~~~~~~~~~~~~~~~~~~~~
 164 Not all devices have the same strength. Therefore, users should set a gain
 165 factor depending on how strong they want effects to be. This setting is
 166 persistent across access to the driver, so you should not care about it if
 167 you are writing games, as another utility probably already set this for you.
 168
 169 /* Set the gain of the device
 170 int gain;               /* between 0 and 100 */
 171 struct input_event ie;  /* structure used to communicate with the driver */
 172
 173 ie.type = EV_FF;
 174 ie.code = FF_GAIN;
 175 ie.value = 0xFFFFUL * gain / 100;
 176
 177 if (write(fd, &ie, sizeof(ie)) == -1)
 178         perror("set gain");
 179
 180 3.6 Enabling/Disabling autocenter
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182 The autocenter feature quite disturbs the rendering of effects in my opinion,
 183 and I think it should be an effect, which computation depends on the game
 184 type. But you can enable it if you want.
 185
 186 int autocenter;         /* between 0 and 100 */
 187 struct input_event ie;
 188
 189 ie.type = EV_FF;
 190 ie.code = FF_AUTOCENTER;
 191 ie.value = 0xFFFFUL * autocenter / 100;
 192
 193 if (write(fd, &ie, sizeof(ie)) == -1)
 194         perror("set auto-center");
 195
 196 A value of 0 means "no auto-center".
 197
 198 3.7 Dynamic update of an effect
 199 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 200 Proceed as if you wanted to upload a new effect, except that instead of
 201 setting the id field to -1, you set it to the wanted effect id.
 202 Normally, the effect is not stopped and restarted. However, depending on the
 203 type of device, not all parameters can be dynamically updated. For example,
 204 the direction of an effect cannot be updated with iforce devices. In this
 205 case, the driver stops the effect, up-load it, and restart it.
 206
 207
 208 3.8 Information about the status of effects
 209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 210 Every time the status of an effect is changed, an event is sent. The values
 211 and meanings of the fields of the event are as follows:
 212 struct input_event {
 213 /* When the status of the effect changed */
 214         struct timeval time;
 215
 216 /* Set to EV_FF_STATUS */
 217         unsigned short type;
 218
 219 /* Contains the id of the effect */
 220         unsigned short code;
 221
 222 /* Indicates the status */
 223         unsigned int value;
 224 };
 225
 226 FF_STATUS_STOPPED       The effect stopped playing
 227 FF_STATUS_PLAYING       The effect started to play