aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/input
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/input')
-rw-r--r--Documentation/input/ff.txt112
1 files changed, 52 insertions, 60 deletions
diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt
index c7e10eaff203..c53b1c11aa40 100644
--- a/Documentation/input/ff.txt
+++ b/Documentation/input/ff.txt
@@ -1,67 +1,37 @@
1Force feedback for Linux. 1Force feedback for Linux.
2By Johann Deneux <deneux@ifrance.com> on 2001/04/22. 2By Johann Deneux <deneux@ifrance.com> on 2001/04/22.
3Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
3You may redistribute this file. Please remember to include shape.fig and 4You may redistribute this file. Please remember to include shape.fig and
4interactive.fig as well. 5interactive.fig as well.
5---------------------------------------------------------------------------- 6----------------------------------------------------------------------------
6 7
70. Introduction 81. Introduction
8~~~~~~~~~~~~~~~ 9~~~~~~~~~~~~~~~
9This document describes how to use force feedback devices under Linux. The 10This document describes how to use force feedback devices under Linux. The
10goal is not to support these devices as if they were simple input-only devices 11goal 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(as it is already the case), but to really enable the rendering of force
12effects. 13effects.
13At the moment, only I-Force devices are supported, and not officially. That 14This document only describes the force feedback part of the Linux input
14means I had to find out how the protocol works on my own. Of course, the 15interface. Please read joystick.txt and input.txt before reading further this
15information I managed to grasp is far from being complete, and I can not 16document.
16guarranty that this driver will work for you.
17This document only describes the force feedback part of the driver for I-Force
18devices. Please read joystick.txt before reading further this document.
19 17
202. Instructions to the user 182. Instructions to the user
21~~~~~~~~~~~~~~~~~~~~~~~~~~~ 19~~~~~~~~~~~~~~~~~~~~~~~~~~~
22Here are instructions on how to compile and use the driver. In fact, this 20To enable force feedback, you have to:
23driver is the normal iforce, input and evdev drivers written by Vojtech 21
24Pavlik, plus additions to support force feedback. 221. have your kernel configured with evdev and a driver that supports your
23 device.
242. make sure evdev module is loaded and /dev/input/event* device files are
25 created.
25 26
26Before you start, let me WARN you that some devices shake violently during the 27Before you start, let me WARN you that some devices shake violently during the
27initialisation phase. This happens for example with my "AVB Top Shot Pegasus". 28initialisation phase. This happens for example with my "AVB Top Shot Pegasus".
28To stop this annoying behaviour, move you joystick to its limits. Anyway, you 29To stop this annoying behaviour, move you joystick to its limits. Anyway, you
29should keep a hand on your device, in order to avoid it to brake down if 30should keep a hand on your device, in order to avoid it to break down if
30something goes wrong. 31something goes wrong.
31 32
32At the kernel's compilation: 33If you have a serial iforce device, you need to start inputattach. See
33 - Enable IForce/Serial 34joystick.txt for details.
34 - Enable Event interface
35
36Compile the modules, install them.
37
38You also need inputattach.
39
40You 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
46If you are using USB, you don't need the inputattach step.
47
48Please check that you have all the /dev/input entries needed:
49cd /dev
50rm js*
51mkdir input
52mknod input/js0 c 13 0
53mknod input/js1 c 13 1
54mknod input/js2 c 13 2
55mknod input/js3 c 13 3
56ln -s input/js0 js0
57ln -s input/js1 js1
58ln -s input/js2 js2
59ln -s input/js3 js3
60
61mknod input/event0 c 13 64
62mknod input/event1 c 13 65
63mknod input/event2 c 13 66
64mknod input/event3 c 13 67
65 35
662.1 Does it work ? 362.1 Does it work ?
67~~~~~~~~~~~~~~~~~~ 37~~~~~~~~~~~~~~~~~~
@@ -70,9 +40,9 @@ There is an utility called fftest that will allow you to test the driver.
70 40
713. Instructions to the developper 413. Instructions to the developper
72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73 All interactions are done using the event API. That is, you can use ioctl() 43All interactions are done using the event API. That is, you can use ioctl()
74and write() on /dev/input/eventXX. 44and write() on /dev/input/eventXX.
75 This information is subject to change. 45This information is subject to change.
76 46
773.1 Querying device capabilities 473.1 Querying device capabilities
78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 48~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -86,18 +56,29 @@ int ioctl(int file_descriptor, int request, unsigned long *features);
86 56
87Returns the features supported by the device. features is a bitfield with the 57Returns the features supported by the device. features is a bitfield with the
88following bits: 58following 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 59- FF_CONSTANT can render constant force effects
93- FF_PERIODIC can render periodic effects (sine, triangle, square...) 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
94- FF_RAMP can render ramp effects 67- FF_RAMP can render ramp effects
95- FF_SPRING can simulate the presence of a spring 68- FF_SPRING can simulate the presence of a spring
96- FF_FRICTION can simulate friction 69- FF_FRICTION can simulate friction
97- FF_DAMPER can simulate damper effects 70- FF_DAMPER can simulate damper effects
98- FF_RUMBLE rumble effects (normally the only effect supported by rumble 71- FF_RUMBLE rumble effects
99 pads)
100- FF_INERTIA can simulate inertia 72- FF_INERTIA can simulate inertia
73- FF_GAIN gain is adjustable
74- FF_AUTOCENTER autocenter is adjustable
75
76Note: 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
80Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver
81 supports it yet.
101 82
102 83
103int ioctl(int fd, EVIOCGEFFECTS, int *n); 84int ioctl(int fd, EVIOCGEFFECTS, int *n);
@@ -108,7 +89,7 @@ Returns the number of effects the device can keep in its memory.
108~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109#include <linux/input.h> 90#include <linux/input.h>
110#include <sys/ioctl.h> 91#include <sys/ioctl.h>
111 92
112int ioctl(int file_descriptor, int request, struct ff_effect *effect); 93int ioctl(int file_descriptor, int request, struct ff_effect *effect);
113 94
114"request" must be EVIOCSFF. 95"request" must be EVIOCSFF.
@@ -120,6 +101,9 @@ to the unique id assigned by the driver. This data is required for performing
120some operations (removing an effect, controlling the playback). 101some operations (removing an effect, controlling the playback).
121This if field must be set to -1 by the user in order to tell the driver to 102This if field must be set to -1 by the user in order to tell the driver to
122allocate a new effect. 103allocate a new effect.
104
105Effects are file descriptor specific.
106
123See <linux/input.h> for a description of the ff_effect struct. You should also 107See <linux/input.h> for a description of the ff_effect struct. You should also
124find help in a few sketches, contained in files shape.fig and interactive.fig. 108find help in a few sketches, contained in files shape.fig and interactive.fig.
125You need xfig to visualize these files. 109You need xfig to visualize these files.
@@ -128,8 +112,8 @@ You need xfig to visualize these files.
128~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 112~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129int ioctl(int fd, EVIOCRMFF, effect.id); 113int ioctl(int fd, EVIOCRMFF, effect.id);
130 114
131This makes room for new effects in the device's memory. Please note this won't 115This makes room for new effects in the device's memory. Note that this also
132stop the effect if it was playing. 116stops the effect if it was playing.
133 117
1343.4 Controlling the playback of effects 1183.4 Controlling the playback of effects
135~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -149,22 +133,21 @@ Control of playing is done with write(). Below is an example:
149 play.type = EV_FF; 133 play.type = EV_FF;
150 play.code = effect.id; 134 play.code = effect.id;
151 play.value = 3; 135 play.value = 3;
152 136
153 write(fd, (const void*) &play, sizeof(play)); 137 write(fd, (const void*) &play, sizeof(play));
154... 138...
155 /* Stop an effect */ 139 /* Stop an effect */
156 stop.type = EV_FF; 140 stop.type = EV_FF;
157 stop.code = effect.id; 141 stop.code = effect.id;
158 stop.value = 0; 142 stop.value = 0;
159 143
160 write(fd, (const void*) &play, sizeof(stop)); 144 write(fd, (const void*) &play, sizeof(stop));
161 145
1623.5 Setting the gain 1463.5 Setting the gain
163~~~~~~~~~~~~~~~~~~~~ 147~~~~~~~~~~~~~~~~~~~~
164Not all devices have the same strength. Therefore, users should set a gain 148Not all devices have the same strength. Therefore, users should set a gain
165factor depending on how strong they want effects to be. This setting is 149factor depending on how strong they want effects to be. This setting is
166persistent across access to the driver, so you should not care about it if 150persistent across access to the driver.
167you are writing games, as another utility probably already set this for you.
168 151
169/* Set the gain of the device 152/* Set the gain of the device
170int gain; /* between 0 and 100 */ 153int gain; /* between 0 and 100 */
@@ -204,11 +187,14 @@ type of device, not all parameters can be dynamically updated. For example,
204the direction of an effect cannot be updated with iforce devices. In this 187the direction of an effect cannot be updated with iforce devices. In this
205case, the driver stops the effect, up-load it, and restart it. 188case, the driver stops the effect, up-load it, and restart it.
206 189
190Therefore it is recommended to dynamically change direction while the effect
191is playing only when it is ok to restart the effect with a replay count of 1.
207 192
2083.8 Information about the status of effects 1933.8 Information about the status of effects
209~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210Every time the status of an effect is changed, an event is sent. The values 195Every time the status of an effect is changed, an event is sent. The values
211and meanings of the fields of the event are as follows: 196and meanings of the fields of the event are as follows:
197
212struct input_event { 198struct input_event {
213/* When the status of the effect changed */ 199/* When the status of the effect changed */
214 struct timeval time; 200 struct timeval time;
@@ -225,3 +211,9 @@ struct input_event {
225 211
226FF_STATUS_STOPPED The effect stopped playing 212FF_STATUS_STOPPED The effect stopped playing
227FF_STATUS_PLAYING The effect started to play 213FF_STATUS_PLAYING The effect started to play
214
215NOTE: 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