1 |
3 |
xianfeng |
Force feedback for Linux.
|
2 |
|
|
By Johann Deneux on 2001/04/22.
|
3 |
|
|
Updated by Anssi Hannula 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
|
50 |
|
|
#include
|
51 |
|
|
|
52 |
|
|
unsigned long features[1 + FF_MAX/sizeof(unsigned long)];
|
53 |
|
|
int ioctl(int file_descriptor, int request, unsigned long *features);
|
54 |
|
|
|
55 |
|
|
"request" must be EVIOCGBIT(EV_FF, size of features array in bytes )
|
56 |
|
|
|
57 |
|
|
Returns the features supported by the device. features is a bitfield with the
|
58 |
|
|
following bits:
|
59 |
|
|
- FF_CONSTANT can render constant force effects
|
60 |
|
|
- FF_PERIODIC can render periodic effects with the following waveforms:
|
61 |
|
|
- FF_SQUARE square waveform
|
62 |
|
|
- FF_TRIANGLE triangle waveform
|
63 |
|
|
- FF_SINE sine waveform
|
64 |
|
|
- FF_SAW_UP sawtooth up waveform
|
65 |
|
|
- FF_SAW_DOWN sawtooth down waveform
|
66 |
|
|
- FF_CUSTOM custom waveform
|
67 |
|
|
- FF_RAMP can render ramp effects
|
68 |
|
|
- FF_SPRING can simulate the presence of a spring
|
69 |
|
|
- FF_FRICTION can simulate friction
|
70 |
|
|
- FF_DAMPER can simulate damper effects
|
71 |
|
|
- FF_RUMBLE rumble effects
|
72 |
|
|
- FF_INERTIA can simulate inertia
|
73 |
|
|
- FF_GAIN gain is adjustable
|
74 |
|
|
- FF_AUTOCENTER autocenter is adjustable
|
75 |
|
|
|
76 |
|
|
Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All
|
77 |
|
|
devices that support FF_RUMBLE support FF_PERIODIC (square, triangle,
|
78 |
|
|
sine) and the other way around.
|
79 |
|
|
|
80 |
|
|
Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver
|
81 |
|
|
supports it yet.
|
82 |
|
|
|
83 |
|
|
|
84 |
|
|
int ioctl(int fd, EVIOCGEFFECTS, int *n);
|
85 |
|
|
|
86 |
|
|
Returns the number of effects the device can keep in its memory.
|
87 |
|
|
|
88 |
|
|
3.2 Uploading effects to the device
|
89 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
90 |
|
|
#include
|
91 |
|
|
#include
|
92 |
|
|
|
93 |
|
|
int ioctl(int file_descriptor, int request, struct ff_effect *effect);
|
94 |
|
|
|
95 |
|
|
"request" must be EVIOCSFF.
|
96 |
|
|
|
97 |
|
|
"effect" points to a structure describing the effect to upload. The effect is
|
98 |
|
|
uploaded, but not played.
|
99 |
|
|
The content of effect may be modified. In particular, its field "id" is set
|
100 |
|
|
to the unique id assigned by the driver. This data is required for performing
|
101 |
|
|
some operations (removing an effect, controlling the playback).
|
102 |
|
|
This if field must be set to -1 by the user in order to tell the driver to
|
103 |
|
|
allocate a new effect.
|
104 |
|
|
|
105 |
|
|
Effects are file descriptor specific.
|
106 |
|
|
|
107 |
|
|
See for a description of the ff_effect struct. You should also
|
108 |
|
|
find help in a few sketches, contained in files shape.fig and interactive.fig.
|
109 |
|
|
You need xfig to visualize these files.
|
110 |
|
|
|
111 |
|
|
3.3 Removing an effect from the device
|
112 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
113 |
|
|
int ioctl(int fd, EVIOCRMFF, effect.id);
|
114 |
|
|
|
115 |
|
|
This makes room for new effects in the device's memory. Note that this also
|
116 |
|
|
stops the effect if it was playing.
|
117 |
|
|
|
118 |
|
|
3.4 Controlling the playback of effects
|
119 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
120 |
|
|
Control of playing is done with write(). Below is an example:
|
121 |
|
|
|
122 |
|
|
#include
|
123 |
|
|
#include
|
124 |
|
|
|
125 |
|
|
struct input_event play;
|
126 |
|
|
struct input_event stop;
|
127 |
|
|
struct ff_effect effect;
|
128 |
|
|
int fd;
|
129 |
|
|
...
|
130 |
|
|
fd = open("/dev/input/eventXX", O_RDWR);
|
131 |
|
|
...
|
132 |
|
|
/* Play three times */
|
133 |
|
|
play.type = EV_FF;
|
134 |
|
|
play.code = effect.id;
|
135 |
|
|
play.value = 3;
|
136 |
|
|
|
137 |
|
|
write(fd, (const void*) &play, sizeof(play));
|
138 |
|
|
...
|
139 |
|
|
/* Stop an effect */
|
140 |
|
|
stop.type = EV_FF;
|
141 |
|
|
stop.code = effect.id;
|
142 |
|
|
stop.value = 0;
|
143 |
|
|
|
144 |
|
|
write(fd, (const void*) &play, sizeof(stop));
|
145 |
|
|
|
146 |
|
|
3.5 Setting the gain
|
147 |
|
|
~~~~~~~~~~~~~~~~~~~~
|
148 |
|
|
Not all devices have the same strength. Therefore, users should set a gain
|
149 |
|
|
factor depending on how strong they want effects to be. This setting is
|
150 |
|
|
persistent across access to the driver.
|
151 |
|
|
|
152 |
|
|
/* Set the gain of the device
|
153 |
|
|
int gain; /* between 0 and 100 */
|
154 |
|
|
struct input_event ie; /* structure used to communicate with the driver */
|
155 |
|
|
|
156 |
|
|
ie.type = EV_FF;
|
157 |
|
|
ie.code = FF_GAIN;
|
158 |
|
|
ie.value = 0xFFFFUL * gain / 100;
|
159 |
|
|
|
160 |
|
|
if (write(fd, &ie, sizeof(ie)) == -1)
|
161 |
|
|
perror("set gain");
|
162 |
|
|
|
163 |
|
|
3.6 Enabling/Disabling autocenter
|
164 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
165 |
|
|
The autocenter feature quite disturbs the rendering of effects in my opinion,
|
166 |
|
|
and I think it should be an effect, which computation depends on the game
|
167 |
|
|
type. But you can enable it if you want.
|
168 |
|
|
|
169 |
|
|
int autocenter; /* between 0 and 100 */
|
170 |
|
|
struct input_event ie;
|
171 |
|
|
|
172 |
|
|
ie.type = EV_FF;
|
173 |
|
|
ie.code = FF_AUTOCENTER;
|
174 |
|
|
ie.value = 0xFFFFUL * autocenter / 100;
|
175 |
|
|
|
176 |
|
|
if (write(fd, &ie, sizeof(ie)) == -1)
|
177 |
|
|
perror("set auto-center");
|
178 |
|
|
|
179 |
|
|
A value of 0 means "no auto-center".
|
180 |
|
|
|
181 |
|
|
3.7 Dynamic update of an effect
|
182 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
183 |
|
|
Proceed as if you wanted to upload a new effect, except that instead of
|
184 |
|
|
setting the id field to -1, you set it to the wanted effect id.
|
185 |
|
|
Normally, the effect is not stopped and restarted. However, depending on the
|
186 |
|
|
type of device, not all parameters can be dynamically updated. For example,
|
187 |
|
|
the direction of an effect cannot be updated with iforce devices. In this
|
188 |
|
|
case, the driver stops the effect, up-load it, and restart it.
|
189 |
|
|
|
190 |
|
|
Therefore it is recommended to dynamically change direction while the effect
|
191 |
|
|
is playing only when it is ok to restart the effect with a replay count of 1.
|
192 |
|
|
|
193 |
|
|
3.8 Information about the status of effects
|
194 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
195 |
|
|
Every time the status of an effect is changed, an event is sent. The values
|
196 |
|
|
and meanings of the fields of the event are as follows:
|
197 |
|
|
|
198 |
|
|
struct input_event {
|
199 |
|
|
/* When the status of the effect changed */
|
200 |
|
|
struct timeval time;
|
201 |
|
|
|
202 |
|
|
/* Set to EV_FF_STATUS */
|
203 |
|
|
unsigned short type;
|
204 |
|
|
|
205 |
|
|
/* Contains the id of the effect */
|
206 |
|
|
unsigned short code;
|
207 |
|
|
|
208 |
|
|
/* Indicates the status */
|
209 |
|
|
unsigned int value;
|
210 |
|
|
};
|
211 |
|
|
|
212 |
|
|
FF_STATUS_STOPPED The effect stopped playing
|
213 |
|
|
FF_STATUS_PLAYING The effect started to play
|
214 |
|
|
|
215 |
|
|
NOTE: Status feedback is only supported by iforce driver. If you have
|
216 |
|
|
a really good reason to use this, please contact
|
217 |
|
|
linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com
|
218 |
|
|
so that support for it can be added to the rest of the drivers.
|
219 |
|
|
|