0001 ========================
0002 Force feedback for Linux
0003 ========================
0004
0005 :Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
0006 :Updated: Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
0007
0008 You may redistribute this file. Please remember to include shape.svg and
0009 interactive.svg as well.
0010
0011 Introduction
0012 ~~~~~~~~~~~~
0013
0014 This document describes how to use force feedback devices under Linux. The
0015 goal is not to support these devices as if they were simple input-only devices
0016 (as it is already the case), but to really enable the rendering of force
0017 effects.
0018 This document only describes the force feedback part of the Linux input
0019 interface. Please read joydev/joystick.rst and input.rst before reading further
0020 this document.
0021
0022 Instructions to the user
0023 ~~~~~~~~~~~~~~~~~~~~~~~~
0024
0025 To enable force feedback, you have to:
0026
0027 1. have your kernel configured with evdev and a driver that supports your
0028 device.
0029 2. make sure evdev module is loaded and /dev/input/event* device files are
0030 created.
0031
0032 Before you start, let me WARN you that some devices shake violently during the
0033 initialisation phase. This happens for example with my "AVB Top Shot Pegasus".
0034 To stop this annoying behaviour, move your joystick to its limits. Anyway, you
0035 should keep a hand on your device, in order to avoid it to break down if
0036 something goes wrong.
0037
0038 If you have a serial iforce device, you need to start inputattach. See
0039 joydev/joystick.rst for details.
0040
0041 Does it work ?
0042 --------------
0043
0044 There is an utility called fftest that will allow you to test the driver::
0045
0046 % fftest /dev/input/eventXX
0047
0048 Instructions to the developer
0049 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0050
0051 All interactions are done using the event API. That is, you can use ioctl()
0052 and write() on /dev/input/eventXX.
0053 This information is subject to change.
0054
0055 Querying device capabilities
0056 ----------------------------
0057
0058 ::
0059
0060 #include <linux/input.h>
0061 #include <sys/ioctl.h>
0062
0063 #define BITS_TO_LONGS(x) \
0064 (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long)))
0065 unsigned long features[BITS_TO_LONGS(FF_CNT)];
0066 int ioctl(int file_descriptor, int request, unsigned long *features);
0067
0068 "request" must be EVIOCGBIT(EV_FF, size of features array in bytes )
0069
0070 Returns the features supported by the device. features is a bitfield with the
0071 following bits:
0072
0073 - FF_CONSTANT can render constant force effects
0074 - FF_PERIODIC can render periodic effects with the following waveforms:
0075
0076 - FF_SQUARE square waveform
0077 - FF_TRIANGLE triangle waveform
0078 - FF_SINE sine waveform
0079 - FF_SAW_UP sawtooth up waveform
0080 - FF_SAW_DOWN sawtooth down waveform
0081 - FF_CUSTOM custom waveform
0082
0083 - FF_RAMP can render ramp effects
0084 - FF_SPRING can simulate the presence of a spring
0085 - FF_FRICTION can simulate friction
0086 - FF_DAMPER can simulate damper effects
0087 - FF_RUMBLE rumble effects
0088 - FF_INERTIA can simulate inertia
0089 - FF_GAIN gain is adjustable
0090 - FF_AUTOCENTER autocenter is adjustable
0091
0092 .. note::
0093
0094 - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All
0095 devices that support FF_RUMBLE support FF_PERIODIC (square, triangle,
0096 sine) and the other way around.
0097
0098 - The exact syntax FF_CUSTOM is undefined for the time being as no driver
0099 supports it yet.
0100
0101 ::
0102
0103 int ioctl(int fd, EVIOCGEFFECTS, int *n);
0104
0105 Returns the number of effects the device can keep in its memory.
0106
0107 Uploading effects to the device
0108 -------------------------------
0109
0110 ::
0111
0112 #include <linux/input.h>
0113 #include <sys/ioctl.h>
0114
0115 int ioctl(int file_descriptor, int request, struct ff_effect *effect);
0116
0117 "request" must be EVIOCSFF.
0118
0119 "effect" points to a structure describing the effect to upload. The effect is
0120 uploaded, but not played.
0121 The content of effect may be modified. In particular, its field "id" is set
0122 to the unique id assigned by the driver. This data is required for performing
0123 some operations (removing an effect, controlling the playback).
0124 The "id" field must be set to -1 by the user in order to tell the driver to
0125 allocate a new effect.
0126
0127 Effects are file descriptor specific.
0128
0129 See <uapi/linux/input.h> for a description of the ff_effect struct. You
0130 should also find help in a few sketches, contained in files shape.svg
0131 and interactive.svg:
0132
0133 .. kernel-figure:: shape.svg
0134
0135 Shape
0136
0137 .. kernel-figure:: interactive.svg
0138
0139 Interactive
0140
0141
0142 Removing an effect from the device
0143 ----------------------------------
0144
0145 ::
0146
0147 int ioctl(int fd, EVIOCRMFF, effect.id);
0148
0149 This makes room for new effects in the device's memory. Note that this also
0150 stops the effect if it was playing.
0151
0152 Controlling the playback of effects
0153 -----------------------------------
0154
0155 Control of playing is done with write(). Below is an example:
0156
0157 ::
0158
0159 #include <linux/input.h>
0160 #include <unistd.h>
0161
0162 struct input_event play;
0163 struct input_event stop;
0164 struct ff_effect effect;
0165 int fd;
0166 ...
0167 fd = open("/dev/input/eventXX", O_RDWR);
0168 ...
0169 /* Play three times */
0170 play.type = EV_FF;
0171 play.code = effect.id;
0172 play.value = 3;
0173
0174 write(fd, (const void*) &play, sizeof(play));
0175 ...
0176 /* Stop an effect */
0177 stop.type = EV_FF;
0178 stop.code = effect.id;
0179 stop.value = 0;
0180
0181 write(fd, (const void*) &stop, sizeof(stop));
0182
0183 Setting the gain
0184 ----------------
0185
0186 Not all devices have the same strength. Therefore, users should set a gain
0187 factor depending on how strong they want effects to be. This setting is
0188 persistent across access to the driver.
0189
0190 ::
0191
0192 /* Set the gain of the device
0193 int gain; /* between 0 and 100 */
0194 struct input_event ie; /* structure used to communicate with the driver */
0195
0196 ie.type = EV_FF;
0197 ie.code = FF_GAIN;
0198 ie.value = 0xFFFFUL * gain / 100;
0199
0200 if (write(fd, &ie, sizeof(ie)) == -1)
0201 perror("set gain");
0202
0203 Enabling/Disabling autocenter
0204 -----------------------------
0205
0206 The autocenter feature quite disturbs the rendering of effects in my opinion,
0207 and I think it should be an effect, which computation depends on the game
0208 type. But you can enable it if you want.
0209
0210 ::
0211
0212 int autocenter; /* between 0 and 100 */
0213 struct input_event ie;
0214
0215 ie.type = EV_FF;
0216 ie.code = FF_AUTOCENTER;
0217 ie.value = 0xFFFFUL * autocenter / 100;
0218
0219 if (write(fd, &ie, sizeof(ie)) == -1)
0220 perror("set auto-center");
0221
0222 A value of 0 means "no auto-center".
0223
0224 Dynamic update of an effect
0225 ---------------------------
0226
0227 Proceed as if you wanted to upload a new effect, except that instead of
0228 setting the id field to -1, you set it to the wanted effect id.
0229 Normally, the effect is not stopped and restarted. However, depending on the
0230 type of device, not all parameters can be dynamically updated. For example,
0231 the direction of an effect cannot be updated with iforce devices. In this
0232 case, the driver stops the effect, up-load it, and restart it.
0233
0234 Therefore it is recommended to dynamically change direction while the effect
0235 is playing only when it is ok to restart the effect with a replay count of 1.
0236
0237 Information about the status of effects
0238 ---------------------------------------
0239
0240 Every time the status of an effect is changed, an event is sent. The values
0241 and meanings of the fields of the event are as follows::
0242
0243 struct input_event {
0244 /* When the status of the effect changed */
0245 struct timeval time;
0246
0247 /* Set to EV_FF_STATUS */
0248 unsigned short type;
0249
0250 /* Contains the id of the effect */
0251 unsigned short code;
0252
0253 /* Indicates the status */
0254 unsigned int value;
0255 };
0256
0257 FF_STATUS_STOPPED The effect stopped playing
0258 FF_STATUS_PLAYING The effect started to play
0259
0260 .. note::
0261
0262 - Status feedback is only supported by iforce driver. If you have
0263 a really good reason to use this, please contact
0264 linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com
0265 so that support for it can be added to the rest of the drivers.
