]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
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. | |
32357988 | 123 | See <linux/input.h> for a description of the ff_effect struct. You should also |
1da177e4 LT |
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 |