diff options
Diffstat (limited to 'Documentation/input/ff.rst')
| -rw-r--r-- | Documentation/input/ff.rst | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst new file mode 100644 index 000000000000..6a265a6934e6 --- /dev/null +++ b/Documentation/input/ff.rst @@ -0,0 +1,265 @@ +======================== +Force feedback for Linux +======================== + +:Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22. +:Updated: Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. + +You may redistribute this file. Please remember to include shape.svg and +interactive.svg as well. + +Introduction +~~~~~~~~~~~~ + +This document describes how to use force feedback devices under Linux. The +goal is not to support these devices as if they were simple input-only devices +(as it is already the case), but to really enable the rendering of force +effects. +This document only describes the force feedback part of the Linux input +interface. Please read joystick.txt and input.txt before reading further this +document. + +Instructions to the user +~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable force feedback, you have to: + +1. have your kernel configured with evdev and a driver that supports your + device. +2. make sure evdev module is loaded and /dev/input/event* device files are + created. + +Before you start, let me WARN you that some devices shake violently during the +initialisation phase. This happens for example with my "AVB Top Shot Pegasus". +To stop this annoying behaviour, move you joystick to its limits. Anyway, you +should keep a hand on your device, in order to avoid it to break down if +something goes wrong. + +If you have a serial iforce device, you need to start inputattach. See +joystick.txt for details. + +Does it work ? +-------------- + +There is an utility called fftest that will allow you to test the driver:: + + % fftest /dev/input/eventXX + +Instructions to the developer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All interactions are done using the event API. That is, you can use ioctl() +and write() on /dev/input/eventXX. +This information is subject to change. + +Querying device capabilities +---------------------------- + +:: + + #include <linux/input.h> + #include <sys/ioctl.h> + + #define BITS_TO_LONGS(x) \ + (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) + unsigned long features[BITS_TO_LONGS(FF_CNT)]; + int ioctl(int file_descriptor, int request, unsigned long *features); + +"request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) + +Returns the features supported by the device. features is a bitfield with the +following bits: + +- FF_CONSTANT can render constant force effects +- FF_PERIODIC can render periodic effects with the following waveforms: + + - FF_SQUARE square waveform + - FF_TRIANGLE triangle waveform + - FF_SINE sine waveform + - FF_SAW_UP sawtooth up waveform + - FF_SAW_DOWN sawtooth down waveform + - FF_CUSTOM custom waveform + +- FF_RAMP can render ramp effects +- FF_SPRING can simulate the presence of a spring +- FF_FRICTION can simulate friction +- FF_DAMPER can simulate damper effects +- FF_RUMBLE rumble effects +- FF_INERTIA can simulate inertia +- FF_GAIN gain is adjustable +- FF_AUTOCENTER autocenter is adjustable + +.. note:: + + - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All + devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, + sine) and the other way around. + + - The exact syntax FF_CUSTOM is undefined for the time being as no driver + supports it yet. + +:: + + int ioctl(int fd, EVIOCGEFFECTS, int *n); + +Returns the number of effects the device can keep in its memory. + +Uploading effects to the device +------------------------------- + +:: + + #include <linux/input.h> + #include <sys/ioctl.h> + + int ioctl(int file_descriptor, int request, struct ff_effect *effect); + +"request" must be EVIOCSFF. + +"effect" points to a structure describing the effect to upload. The effect is +uploaded, but not played. +The content of effect may be modified. In particular, its field "id" is set +to the unique id assigned by the driver. This data is required for performing +some operations (removing an effect, controlling the playback). +This if field must be set to -1 by the user in order to tell the driver to +allocate a new effect. + +Effects are file descriptor specific. + +See <uapi/linux/input.h> for a description of the ff_effect struct. You +should also find help in a few sketches, contained in files shape.svg +and interactive.svg: + +.. figure:: shape.svg + + Shape + +.. figure:: interactive.svg + + Interactive + + +Removing an effect from the device +---------------------------------- + +:: + + int ioctl(int fd, EVIOCRMFF, effect.id); + +This makes room for new effects in the device's memory. Note that this also +stops the effect if it was playing. + +Controlling the playback of effects +----------------------------------- + +Control of playing is done with write(). Below is an example: + +:: + + #include <linux/input.h> + #include <unistd.h> + + struct input_event play; + struct input_event stop; + struct ff_effect effect; + int fd; + ... + fd = open("/dev/input/eventXX", O_RDWR); + ... + /* Play three times */ + play.type = EV_FF; + play.code = effect.id; + play.value = 3; + + write(fd, (const void*) &play, sizeof(play)); + ... + /* Stop an effect */ + stop.type = EV_FF; + stop.code = effect.id; + stop.value = 0; + + write(fd, (const void*) &play, sizeof(stop)); + +Setting the gain +---------------- + +Not all devices have the same strength. Therefore, users should set a gain +factor depending on how strong they want effects to be. This setting is +persistent across access to the driver. + +:: + + /* Set the gain of the device + int gain; /* between 0 and 100 */ + struct input_event ie; /* structure used to communicate with the driver */ + + ie.type = EV_FF; + ie.code = FF_GAIN; + ie.value = 0xFFFFUL * gain / 100; + + if (write(fd, &ie, sizeof(ie)) == -1) + perror("set gain"); + +Enabling/Disabling autocenter +----------------------------- + +The autocenter feature quite disturbs the rendering of effects in my opinion, +and I think it should be an effect, which computation depends on the game +type. But you can enable it if you want. + +:: + + int autocenter; /* between 0 and 100 */ + struct input_event ie; + + ie.type = EV_FF; + ie.code = FF_AUTOCENTER; + ie.value = 0xFFFFUL * autocenter / 100; + + if (write(fd, &ie, sizeof(ie)) == -1) + perror("set auto-center"); + +A value of 0 means "no auto-center". + +Dynamic update of an effect +--------------------------- + +Proceed as if you wanted to upload a new effect, except that instead of +setting the id field to -1, you set it to the wanted effect id. +Normally, the effect is not stopped and restarted. However, depending on the +type of device, not all parameters can be dynamically updated. For example, +the direction of an effect cannot be updated with iforce devices. In this +case, the driver stops the effect, up-load it, and restart it. + +Therefore it is recommended to dynamically change direction while the effect +is playing only when it is ok to restart the effect with a replay count of 1. + +Information about the status of effects +--------------------------------------- + +Every time the status of an effect is changed, an event is sent. The values +and meanings of the fields of the event are as follows:: + + struct input_event { + /* When the status of the effect changed */ + struct timeval time; + + /* Set to EV_FF_STATUS */ + unsigned short type; + + /* Contains the id of the effect */ + unsigned short code; + + /* Indicates the status */ + unsigned int value; + }; + + FF_STATUS_STOPPED The effect stopped playing + FF_STATUS_PLAYING The effect started to play + +.. note:: + + - Status feedback is only supported by iforce driver. If you have + a really good reason to use this, please contact + linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com + so that support for it can be added to the rest of the drivers. |