Force Feedback for Linux

Force-feedback 사용 준비와 안전

이 문서는 Linux input interface의 force-feedback 부분을 사용해 장치가 실제 force effect를 렌더링하게 하는 방법을 설명합니다. 단순 input-only 지원은 범위가 아니며 먼저 `joydev/joystick.rst`와 `input.rst`를 읽는 것이 권장됩니다.

문서를 재배포할 때는 관련 그림 `shape.svg`와 `interactive.svg`도 포함해야 합니다. Force feedback을 사용하려면 kernel에 `evdev`와 해당 장치 driver를 구성하고, `evdev` module이 로드돼 `/dev/input/event*` node가 생성돼야 합니다.

일부 장치는 초기화 중 매우 거칠게 흔들릴 수 있습니다. 원문 예는 AVB Top Shot Pegasus이며, joystick을 양 끝으로 움직이면 멈출 수 있다고 설명합니다. 오작동으로 장치가 파손되지 않도록 손으로 장치를 잡고 시험해야 합니다.

Developer의 모든 상호작용은 event API를 통해 `/dev/input/eventXX`에 `ioctl()`과 `write()`를 사용합니다. 이 API 정보는 변경될 수 있습니다.

========================
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 joydev/joystick.rst and input.rst 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 your 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
joydev/joystick.rst 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.

지원 effect와 장치 메모리 조회

지원 기능은 `EVIOCGBIT(EV_FF, sizeof(features))` ioctl로 읽습니다. `features`는 `BITS_TO_LONGS(FF_CNT)` 길이의 bitfield이며 장치가 렌더링할 수 있는 effect와 전역 제어를 나타냅니다.

대부분의 경우 `FF_RUMBLE`보다 `FF_PERIODIC`을 사용해야 합니다. Rumble 지원 장치는 square·triangle·sine periodic도 지원하고 반대도 성립한다고 문서는 설명합니다.

`EVIOCGEFFECTS` ioctl은 장치 memory에 동시에 보관할 수 있는 effect 수를 반환합니다.

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.

Effect upload, ID 할당과 제거

Effect는 `struct ff_effect`를 채워 `EVIOCSFF` ioctl로 upload합니다. Upload는 effect를 장치에 저장할 뿐 재생하지 않습니다. 새 effect를 만들 때 사용자는 `id=-1`로 설정하고, driver가 고유 ID를 구조체에 써 돌려줍니다.

할당된 ID는 effect 제거와 playback 제어에 필요합니다. `ff_effect`의 정확한 구조는 `<uapi/linux/input.h>`를 참조하며 effect shape와 interactive 관계는 `shape.svg`, `interactive.svg`에 설명돼 있습니다.

`EVIOCRMFF` ioctl에 `effect.id`를 전달하면 장치 memory에서 effect를 제거해 새 slot을 확보합니다. 재생 중인 effect를 제거하면 동시에 정지합니다.

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).
The "id" 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:

.. kernel-figure:: shape.svg

    Shape

.. kernel-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.

재생 횟수, 정지, gain과 autocenter

Effect playback은 `struct input_event`를 `/dev/input/eventXX`에 `write()`해 제어합니다. `type=EV_FF`, `code=effect.id`, `value`는 재생 횟수입니다. 예제의 value 3은 세 번 재생하고 value 0은 즉시 정지합니다.

장치마다 물리적 힘이 다르므로 사용자는 원하는 강도에 맞춰 gain factor를 설정해야 합니다. 이 설정은 driver access 사이에도 지속됩니다. Percent 0~100을 `0xFFFFUL * gain / 100`으로 변환해 `EV_FF`, `FF_GAIN` event로 보냅니다.

Autocenter는 effect 렌더링을 방해할 수 있으며 게임 유형에 따라 계산되는 effect로 다루는 편이 낫다는 저자의 의견이 기록돼 있습니다. 필요하면 0~100 비율로 활성화하고 0은 no auto-center입니다.

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*) &stop, 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".

동적 effect 갱신과 EV_FF_STATUS

기존 effect를 동적으로 갱신할 때는 새 upload와 같은 `EVIOCSFF` 절차를 사용하되 `id=-1` 대신 대상 effect ID를 넣습니다. 일반적으로 effect를 정지·재시작하지 않지만 장치가 일부 parameter의 live update를 지원하지 않을 수 있습니다.

예를 들어 iforce 장치는 effect direction을 동적으로 바꿀 수 없어 driver가 effect를 정지하고 다시 upload한 뒤 재시작합니다. 재생 중 direction을 바꿀 때는 replay count 1로 재시작돼도 괜찮은 상황에서만 수행하는 것이 권장됩니다.

Effect status가 바뀔 때 `EV_FF_STATUS` event가 전송됩니다. `time`은 변경 시각, `type`은 `EV_FF_STATUS`, `code`는 effect ID, `value`는 stopped 또는 playing 상태입니다.

문서 작성 시점에는 status feedback을 iforce driver만 지원합니다. 다른 driver에 추가하려면 원문에 적힌 joystick mailing list 또는 담당자에게 사용 이유를 알려 달라고 안내합니다.

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.