Input: iforce - convert documentation into ReST format
This file seems to be using some other markup language, (maybe mediawiki?). Manually convert it to ReST markup, with is the one we're using along the Kernel documentaiton. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
This commit is contained in:
Mauro Carvalho Chehab
Dmitry Torokhov
parent
0119184986
commit
f863995224
|
|
@ -1,4 +1,17 @@
|
|||
** Introduction
|
||||
===============
|
||||
Iforce Protocol
|
||||
===============
|
||||
|
||||
:Author: Johann Deneux <johann.deneux@gmail.com>
|
||||
|
||||
Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
|
||||
|
||||
:Additions: by Vojtech Pavlik.
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This document describes what I managed to discover about the protocol used to
|
||||
specify force effects to I-Force 2.0 devices. None of this information comes
|
||||
from Immerse. That's why you should not trust what is written in this
|
||||
|
|
@ -6,30 +19,46 @@ document. This document is intended to help understanding the protocol.
|
|||
This is not a reference. Comments and corrections are welcome. To contact me,
|
||||
send an email to: johann.deneux@gmail.com
|
||||
|
||||
** WARNING **
|
||||
.. warning::
|
||||
|
||||
I shall not be held responsible for any damage or harm caused if you try to
|
||||
send data to your I-Force device based on what you read in this document.
|
||||
|
||||
** Preliminary Notes:
|
||||
Preliminary Notes
|
||||
=================
|
||||
|
||||
All values are hexadecimal with big-endian encoding (msb on the left). Beware,
|
||||
values inside packets are encoded using little-endian. Bytes whose roles are
|
||||
unknown are marked ??? Information that needs deeper inspection is marked (?)
|
||||
|
||||
** General form of a packet **
|
||||
General form of a packet
|
||||
------------------------
|
||||
|
||||
This is how packets look when the device uses the rs232 to communicate.
|
||||
|
||||
== == === ==== ==
|
||||
2B OP LEN DATA CS
|
||||
== == === ==== ==
|
||||
|
||||
CS is the checksum. It is equal to the exclusive or of all bytes.
|
||||
|
||||
When using USB:
|
||||
|
||||
== ====
|
||||
OP DATA
|
||||
The 2B, LEN and CS fields have disappeared, probably because USB handles frames and
|
||||
data corruption is handled or unsignificant.
|
||||
== ====
|
||||
|
||||
The 2B, LEN and CS fields have disappeared, probably because USB handles
|
||||
frames and data corruption is handled or unsignificant.
|
||||
|
||||
First, I describe effects that are sent by the device to the computer
|
||||
|
||||
** Device input state
|
||||
Device input state
|
||||
==================
|
||||
|
||||
This packet is used to indicate the state of each button and the value of each
|
||||
axis
|
||||
axis::
|
||||
|
||||
OP= 01 for a joystick, 03 for a wheel
|
||||
LEN= Varies from device to device
|
||||
00 X-Axis lsb
|
||||
|
|
@ -42,7 +71,11 @@ LEN= Varies from device to device
|
|||
Upper 4 bits: Hat
|
||||
07 Rudder
|
||||
|
||||
** Device effects states
|
||||
Device effects states
|
||||
=====================
|
||||
|
||||
::
|
||||
|
||||
OP= 02
|
||||
LEN= Varies
|
||||
00 ? Bit 1 (Value 2) is the value of the deadman switch
|
||||
|
|
@ -53,10 +86,15 @@ LEN= Varies
|
|||
05 Address of second parameter block changed (lsb)
|
||||
... depending on the number of parameter blocks updated
|
||||
|
||||
** Force effect **
|
||||
Force effect
|
||||
------------
|
||||
|
||||
::
|
||||
|
||||
OP= 01
|
||||
LEN= 0e
|
||||
00 Channel (when playing several effects at the same time, each must be assigned a channel)
|
||||
00 Channel (when playing several effects at the same time, each must
|
||||
be assigned a channel)
|
||||
01 Wave form
|
||||
Val 00 Constant
|
||||
Val 20 Square
|
||||
|
|
@ -65,7 +103,8 @@ LEN= 0e
|
|||
Val 23 Sawtooth up
|
||||
Val 24 Sawtooth down
|
||||
Val 40 Spring (Force = f(pos))
|
||||
Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
|
||||
Val 41 Friction (Force = f(velocity)) and Inertia
|
||||
(Force = f(acceleration))
|
||||
|
||||
|
||||
02 Axes affected and trigger
|
||||
|
|
@ -86,15 +125,22 @@ LEN= 0e
|
|||
08-09 Address of periodicity or magnitude parameters
|
||||
0a-0b Address of attack and fade parameters, or ffff if none.
|
||||
*or*
|
||||
08-09 Address of interactive parameters for X-axis, or ffff if not applicable
|
||||
0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
|
||||
08-09 Address of interactive parameters for X-axis,
|
||||
or ffff if not applicable
|
||||
0a-0b Address of interactive parameters for Y-axis,
|
||||
or ffff if not applicable
|
||||
|
||||
0c-0d Delay before execution of effect (little endian encoding, in ms)
|
||||
|
||||
|
||||
** Time based parameters **
|
||||
Time based parameters
|
||||
---------------------
|
||||
|
||||
Attack and fade
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
*** Attack and fade ***
|
||||
OP= 02
|
||||
LEN= 08
|
||||
00-01 Address where to store the parameters
|
||||
|
|
@ -103,13 +149,21 @@ LEN= 08
|
|||
05-06 Duration of fade.
|
||||
07 Level at end of fade.
|
||||
|
||||
*** Magnitude ***
|
||||
Magnitude
|
||||
^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
OP= 03
|
||||
LEN= 03
|
||||
00-01 Address
|
||||
02 Level. Signed byte.
|
||||
|
||||
*** Periodicity ***
|
||||
Periodicity
|
||||
^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
OP= 04
|
||||
LEN= 07
|
||||
00-01 Address
|
||||
|
|
@ -118,7 +172,11 @@ LEN= 07
|
|||
04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
|
||||
05-06 Period (little endian encoding, in ms)
|
||||
|
||||
** Interactive parameters **
|
||||
Interactive parameters
|
||||
----------------------
|
||||
|
||||
::
|
||||
|
||||
OP= 05
|
||||
LEN= 0a
|
||||
00-01 Address
|
||||
|
|
@ -134,7 +192,11 @@ maximum value is 64 (100 decimal), the min is 9c.
|
|||
For the offset, the minimum value is FE0C, the maximum value is 01F4.
|
||||
For the deadband, the minimum value is 0, the max is 03E8.
|
||||
|
||||
** Controls **
|
||||
Controls
|
||||
--------
|
||||
|
||||
::
|
||||
|
||||
OP= 41
|
||||
LEN= 03
|
||||
00 Channel
|
||||
|
|
@ -144,9 +206,14 @@ LEN= 03
|
|||
Val 41: Start and play n times (See byte 02 below)
|
||||
02 Number of iterations n.
|
||||
|
||||
** Init **
|
||||
Init
|
||||
----
|
||||
|
||||
|
||||
Querying features
|
||||
^^^^^^^^^^^^^^^^^
|
||||
::
|
||||
|
||||
*** Querying features ***
|
||||
OP= ff
|
||||
Query command. Length varies according to the query type.
|
||||
The general format of this packet is:
|
||||
|
|
@ -155,47 +222,94 @@ responses are of the same form:
|
|||
FF LEN QUERY VALUE_QUERIED CHECKSUM2
|
||||
where LEN = 1 + length(VALUE_QUERIED)
|
||||
|
||||
**** Query ram size ****
|
||||
Query ram size
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 42 ('B'uffer size)
|
||||
|
||||
The device should reply with the same packet plus two additional bytes
|
||||
containing the size of the memory:
|
||||
ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
|
||||
|
||||
**** Query number of effects ****
|
||||
Query number of effects
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 4e ('N'umber of effects)
|
||||
|
||||
The device should respond by sending the number of effects that can be played
|
||||
at the same time (one byte)
|
||||
ff 02 4e 14 CS would stand for 20 effects.
|
||||
|
||||
**** Vendor's id ****
|
||||
Vendor's id
|
||||
~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 4d ('M'anufacturer)
|
||||
|
||||
Query the vendors'id (2 bytes)
|
||||
|
||||
**** Product id *****
|
||||
Product id
|
||||
~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 50 ('P'roduct)
|
||||
|
||||
Query the product id (2 bytes)
|
||||
|
||||
**** Open device ****
|
||||
Open device
|
||||
~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 4f ('O'pen)
|
||||
|
||||
No data returned.
|
||||
|
||||
**** Close device *****
|
||||
Close device
|
||||
~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 43 ('C')lose
|
||||
|
||||
No data returned.
|
||||
|
||||
**** Query effect ****
|
||||
Query effect
|
||||
~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 45 ('E')
|
||||
|
||||
Send effect type.
|
||||
Returns nonzero if supported (2 bytes)
|
||||
|
||||
**** Firmware Version ****
|
||||
Firmware Version
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
QUERY = 56 ('V'ersion)
|
||||
|
||||
Sends back 3 bytes - major, minor, subminor
|
||||
|
||||
*** Initialisation of the device ***
|
||||
Initialisation of the device
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Set Control
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
Device dependent, can be different on different models!
|
||||
|
||||
::
|
||||
|
||||
**** Set Control ****
|
||||
!!! Device dependent, can be different on different models !!!
|
||||
OP= 40 <idx> <val> [<val>]
|
||||
LEN= 2 or 3
|
||||
00 Idx
|
||||
|
|
@ -206,7 +320,11 @@ LEN= 2 or 3
|
|||
Idx 04 Enable or disable the spring (0/1)
|
||||
Idx 05 Set axis saturation threshold (0..2048)
|
||||
|
||||
**** Set Effect State ****
|
||||
Set Effect State
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
OP= 42 <val>
|
||||
LEN= 1
|
||||
00 State
|
||||
|
|
@ -214,7 +332,11 @@ LEN= 1
|
|||
Bit 2 Enable force feedback
|
||||
Bit 0 Stop all effects
|
||||
|
||||
**** Set overall gain ****
|
||||
Set overall
|
||||
~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
OP= 43 <val>
|
||||
LEN= 1
|
||||
00 Gain
|
||||
|
|
@ -222,17 +344,20 @@ LEN= 1
|
|||
Val 40 = 50%
|
||||
Val 80 = 100%
|
||||
|
||||
** Parameter memory **
|
||||
Parameter memory
|
||||
----------------
|
||||
|
||||
Each device has a certain amount of memory to store parameters of effects.
|
||||
The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
|
||||
is the amount of memory apparently needed for every set of parameters:
|
||||
|
||||
- period : 0c
|
||||
- magnitude : 02
|
||||
- attack and fade : 0e
|
||||
- interactive : 08
|
||||
|
||||
** Appendix: How to study the protocol ? **
|
||||
Appendix: How to study the protocol?
|
||||
====================================
|
||||
|
||||
1. Generate effects using the force editor provided with the DirectX SDK, or
|
||||
use Immersion Studio (freely available at their web site in the developer section:
|
||||
|
|
@ -246,13 +371,11 @@ At first glance, this software seems, hum, well... buggy. In fact, data appear w
|
|||
few seconds latency. Personally, I restart it every time I play an effect.
|
||||
Remember it's free (as in free beer) and alpha!
|
||||
|
||||
** URLS **
|
||||
Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
|
||||
URLS
|
||||
====
|
||||
|
||||
** Author of this document **
|
||||
Johann Deneux <johann.deneux@gmail.com>
|
||||
Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr
|
||||
Check http://www.immerse.com for Immersion Studio,
|
||||
and http://www.fcoder.com for ComPortSpy.
|
||||
|
||||
Additions by Vojtech Pavlik.
|
||||
|
||||
I-Force is trademark of Immersion Corp.
|
||||
|
|
|
|||
Loading…
Reference in New Issue