Root/
1 | Force feedback for Linux. |
2 | By Johann Deneux <johann.deneux@gmail.com> on 2001/04/22. |
3 | Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. |
4 | You may redistribute this file. Please remember to include shape.fig and |
5 | interactive.fig as well. |
6 | ---------------------------------------------------------------------------- |
7 | |
8 | 1. Introduction |
9 | ~~~~~~~~~~~~~~~ |
10 | This document describes how to use force feedback devices under Linux. The |
11 | goal is not to support these devices as if they were simple input-only devices |
12 | (as it is already the case), but to really enable the rendering of force |
13 | effects. |
14 | This document only describes the force feedback part of the Linux input |
15 | interface. Please read joystick.txt and input.txt before reading further this |
16 | document. |
17 | |
18 | 2. Instructions to the user |
19 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
20 | To enable force feedback, you have to: |
21 | |
22 | 1. have your kernel configured with evdev and a driver that supports your |
23 | device. |
24 | 2. make sure evdev module is loaded and /dev/input/event* device files are |
25 | created. |
26 | |
27 | Before you start, let me WARN you that some devices shake violently during the |
28 | initialisation phase. This happens for example with my "AVB Top Shot Pegasus". |
29 | To stop this annoying behaviour, move you joystick to its limits. Anyway, you |
30 | should keep a hand on your device, in order to avoid it to break down if |
31 | something goes wrong. |
32 | |
33 | If you have a serial iforce device, you need to start inputattach. See |
34 | joystick.txt for details. |
35 | |
36 | 2.1 Does it work ? |
37 | ~~~~~~~~~~~~~~~~~~ |
38 | There is an utility called fftest that will allow you to test the driver. |
39 | % fftest /dev/input/eventXX |
40 | |
41 | 3. Instructions to the developer |
42 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
43 | All interactions are done using the event API. That is, you can use ioctl() |
44 | and write() on /dev/input/eventXX. |
45 | This information is subject to change. |
46 | |
47 | 3.1 Querying device capabilities |
48 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
49 | #include <linux/input.h> |
50 | #include <sys/ioctl.h> |
51 | |
52 | #define BITS_TO_LONGS(x) \ |
53 | (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) |
54 | unsigned long features[BITS_TO_LONGS(FF_CNT)]; |
55 | int ioctl(int file_descriptor, int request, unsigned long *features); |
56 | |
57 | "request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) |
58 | |
59 | Returns the features supported by the device. features is a bitfield with the |
60 | following bits: |
61 | - FF_CONSTANT can render constant force effects |
62 | - FF_PERIODIC can render periodic effects with the following waveforms: |
63 | - FF_SQUARE square waveform |
64 | - FF_TRIANGLE triangle waveform |
65 | - FF_SINE sine waveform |
66 | - FF_SAW_UP sawtooth up waveform |
67 | - FF_SAW_DOWN sawtooth down waveform |
68 | - FF_CUSTOM custom waveform |
69 | - FF_RAMP can render ramp effects |
70 | - FF_SPRING can simulate the presence of a spring |
71 | - FF_FRICTION can simulate friction |
72 | - FF_DAMPER can simulate damper effects |
73 | - FF_RUMBLE rumble effects |
74 | - FF_INERTIA can simulate inertia |
75 | - FF_GAIN gain is adjustable |
76 | - FF_AUTOCENTER autocenter is adjustable |
77 | |
78 | Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All |
79 | devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, |
80 | sine) and the other way around. |
81 | |
82 | Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver |
83 | supports it yet. |
84 | |
85 | |
86 | int ioctl(int fd, EVIOCGEFFECTS, int *n); |
87 | |
88 | Returns the number of effects the device can keep in its memory. |
89 | |
90 | 3.2 Uploading effects to the device |
91 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
92 | #include <linux/input.h> |
93 | #include <sys/ioctl.h> |
94 | |
95 | int ioctl(int file_descriptor, int request, struct ff_effect *effect); |
96 | |
97 | "request" must be EVIOCSFF. |
98 | |
99 | "effect" points to a structure describing the effect to upload. The effect is |
100 | uploaded, but not played. |
101 | The content of effect may be modified. In particular, its field "id" is set |
102 | to the unique id assigned by the driver. This data is required for performing |
103 | some operations (removing an effect, controlling the playback). |
104 | This if field must be set to -1 by the user in order to tell the driver to |
105 | allocate a new effect. |
106 | |
107 | Effects are file descriptor specific. |
108 | |
109 | See <linux/input.h> for a description of the ff_effect struct. You should also |
110 | find help in a few sketches, contained in files shape.fig and interactive.fig. |
111 | You need xfig to visualize these files. |
112 | |
113 | 3.3 Removing an effect from the device |
114 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
115 | int ioctl(int fd, EVIOCRMFF, effect.id); |
116 | |
117 | This makes room for new effects in the device's memory. Note that this also |
118 | stops the effect if it was playing. |
119 | |
120 | 3.4 Controlling the playback of effects |
121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
122 | Control of playing is done with write(). Below is an example: |
123 | |
124 | #include <linux/input.h> |
125 | #include <unistd.h> |
126 | |
127 | struct input_event play; |
128 | struct input_event stop; |
129 | struct ff_effect effect; |
130 | int fd; |
131 | ... |
132 | fd = open("/dev/input/eventXX", O_RDWR); |
133 | ... |
134 | /* Play three times */ |
135 | play.type = EV_FF; |
136 | play.code = effect.id; |
137 | play.value = 3; |
138 | |
139 | write(fd, (const void*) &play, sizeof(play)); |
140 | ... |
141 | /* Stop an effect */ |
142 | stop.type = EV_FF; |
143 | stop.code = effect.id; |
144 | stop.value = 0; |
145 | |
146 | write(fd, (const void*) &play, sizeof(stop)); |
147 | |
148 | 3.5 Setting the gain |
149 | ~~~~~~~~~~~~~~~~~~~~ |
150 | Not all devices have the same strength. Therefore, users should set a gain |
151 | factor depending on how strong they want effects to be. This setting is |
152 | persistent across access to the driver. |
153 | |
154 | /* Set the gain of the device |
155 | int gain; /* between 0 and 100 */ |
156 | struct input_event ie; /* structure used to communicate with the driver */ |
157 | |
158 | ie.type = EV_FF; |
159 | ie.code = FF_GAIN; |
160 | ie.value = 0xFFFFUL * gain / 100; |
161 | |
162 | if (write(fd, &ie, sizeof(ie)) == -1) |
163 | perror("set gain"); |
164 | |
165 | 3.6 Enabling/Disabling autocenter |
166 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
167 | The autocenter feature quite disturbs the rendering of effects in my opinion, |
168 | and I think it should be an effect, which computation depends on the game |
169 | type. But you can enable it if you want. |
170 | |
171 | int autocenter; /* between 0 and 100 */ |
172 | struct input_event ie; |
173 | |
174 | ie.type = EV_FF; |
175 | ie.code = FF_AUTOCENTER; |
176 | ie.value = 0xFFFFUL * autocenter / 100; |
177 | |
178 | if (write(fd, &ie, sizeof(ie)) == -1) |
179 | perror("set auto-center"); |
180 | |
181 | A value of 0 means "no auto-center". |
182 | |
183 | 3.7 Dynamic update of an effect |
184 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
185 | Proceed as if you wanted to upload a new effect, except that instead of |
186 | setting the id field to -1, you set it to the wanted effect id. |
187 | Normally, the effect is not stopped and restarted. However, depending on the |
188 | type of device, not all parameters can be dynamically updated. For example, |
189 | the direction of an effect cannot be updated with iforce devices. In this |
190 | case, the driver stops the effect, up-load it, and restart it. |
191 | |
192 | Therefore it is recommended to dynamically change direction while the effect |
193 | is playing only when it is ok to restart the effect with a replay count of 1. |
194 | |
195 | 3.8 Information about the status of effects |
196 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
197 | Every time the status of an effect is changed, an event is sent. The values |
198 | and meanings of the fields of the event are as follows: |
199 | |
200 | struct input_event { |
201 | /* When the status of the effect changed */ |
202 | struct timeval time; |
203 | |
204 | /* Set to EV_FF_STATUS */ |
205 | unsigned short type; |
206 | |
207 | /* Contains the id of the effect */ |
208 | unsigned short code; |
209 | |
210 | /* Indicates the status */ |
211 | unsigned int value; |
212 | }; |
213 | |
214 | FF_STATUS_STOPPED The effect stopped playing |
215 | FF_STATUS_PLAYING The effect started to play |
216 | |
217 | NOTE: Status feedback is only supported by iforce driver. If you have |
218 | a really good reason to use this, please contact |
219 | linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com |
220 | so that support for it can be added to the rest of the drivers. |
221 | |
222 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9