[mirror_ubuntu-bionic-kernel.git] / Documentation / input / devices / iforce-protocol.rst

===============
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
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::

    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
=================

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

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.

First, I describe effects that are sent by the device to the computer

Device input state
==================

This packet is used to indicate the state of each button and the value of each
axis::

    OP= 01 for a joystick, 03 for a wheel
    LEN= Varies from device to device
    00 X-Axis lsb
    01 X-Axis msb
    02 Y-Axis lsb, or gas pedal for a wheel
    03 Y-Axis msb, or brake pedal for a wheel
    04 Throttle
    05 Buttons
    06 Lower 4 bits: Buttons
       Upper 4 bits: Hat
    07 Rudder

Device effects states
=====================

::

    OP= 02
    LEN= Varies
    00 ? Bit 1 (Value 2) is the value of the deadman switch
    01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
    02 ??
    03 Address of parameter block changed (lsb)
    04 Address of parameter block changed (msb)
    05 Address of second parameter block changed (lsb)
    ... depending on the number of parameter blocks updated

Force effect
------------

::

    OP=  01
    LEN= 0e
    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
	    Val 21 Triangle
	    Val 22 Sine
	    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))


    02 Axes affected and trigger
	    Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
		    Val 4 = X axis only. Byte 05 must contain 5a
		    Val 8 = Y axis only. Byte 05 must contain b4
		    Val c = X and Y axes. Bytes 05 must contain 60
	    Bits 0-3: Val 0 = No trigger
		    Val x+1 = Button x triggers the effect
	    When the whole byte is 0, cancel the previously set trigger

    03-04 Duration of effect (little endian encoding, in ms)

    05 Direction of effect, if applicable. Else, see 02 for value to assign.

    06-07 Minimum time between triggering.

    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

    0c-0d Delay before execution of effect (little endian encoding, in ms)


Time based parameters
---------------------

Attack and fade
^^^^^^^^^^^^^^^

::

    OP=  02
    LEN= 08
    00-01 Address where to store the parameters
    02-03 Duration of attack (little endian encoding, in ms)
    04 Level at end of attack. Signed byte.
    05-06 Duration of fade.
    07 Level at end of fade.

Magnitude
^^^^^^^^^

::

    OP=  03
    LEN= 03
    00-01 Address
    02 Level. Signed byte.

Periodicity
^^^^^^^^^^^

::

    OP=  04
    LEN= 07
    00-01 Address
    02 Magnitude. Signed byte.
    03 Offset. Signed byte.
    04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
    05-06 Period (little endian encoding, in ms)

Interactive parameters
----------------------

::

    OP=  05
    LEN= 0a
    00-01 Address
    02 Positive Coeff
    03 Negative Coeff
    04+05 Offset (center)
    06+07 Dead band (Val 01F4 = 5000 (decimal))
    08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
    09 Negative saturation

The encoding is a bit funny here: For coeffs, these are signed values. The
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
--------

::

    OP=  41
    LEN= 03
    00 Channel
    01 Start/Stop
	    Val 00: Stop
	    Val 01: Start and play once.
	    Val 41: Start and play n times (See byte 02 below)
    02 Number of iterations n.

Init
----


Querying features
^^^^^^^^^^^^^^^^^
::

    OP=  ff
    Query command. Length varies according to the query type.
    The general format of this packet is:
    ff 01 QUERY [INDEX] CHECKSUM
    responses are of the same form:
    FF LEN QUERY VALUE_QUERIED CHECKSUM2
    where LEN = 1 + length(VALUE_QUERIED)

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 = 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
~~~~~~~~~~~

::

    QUERY = 4d ('M'anufacturer)

Query the vendors'id (2 bytes)

Product id
~~~~~~~~~~

::

    QUERY = 50 ('P'roduct)

Query the product id (2 bytes)

Open device
~~~~~~~~~~~

::

    QUERY = 4f ('O'pen)

No data returned.

Close device
~~~~~~~~~~~~

::

    QUERY = 43 ('C')lose

No data returned.

Query effect
~~~~~~~~~~~~

::

    QUERY = 45 ('E')

Send effect type.
Returns nonzero if supported (2 bytes)

Firmware Version
~~~~~~~~~~~~~~~~

::

    QUERY = 56 ('V'ersion)

Sends back 3 bytes - major, minor, subminor

Initialisation of the device
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set Control
~~~~~~~~~~~

.. note::
    Device dependent, can be different on different models!

::

    OP=  40 <idx> <val> [<val>]
    LEN= 2 or 3
    00 Idx
       Idx 00 Set dead zone (0..2048)
       Idx 01 Ignore Deadman sensor (0..1)
       Idx 02 Enable comm watchdog (0..1)
       Idx 03 Set the strength of the spring (0..100)
       Idx 04 Enable or disable the spring (0/1)
       Idx 05 Set axis saturation threshold (0..2048)

Set Effect State
~~~~~~~~~~~~~~~~

::

    OP=  42 <val>
    LEN= 1
    00 State
       Bit 3 Pause force feedback
       Bit 2 Enable force feedback
       Bit 0 Stop all effects

Set overall
~~~~~~~~~~~

::

    OP=  43 <val>
    LEN= 1
    00 Gain
       Val 00 = 0%
       Val 40 = 50%
       Val 80 = 100%

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?
====================================

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:
www.immersion.com)
2. Start a soft spying RS232 or USB (depending on where you connected your
joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
3. Play the effect, and watch what happens on the spy screen.

A few words about ComPortSpy:
At first glance, this software seems, hum, well... buggy. In fact, data appear with a
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 http://www.immerse.com for Immersion Studio,
and http://www.fcoder.com for ComPortSpy.


I-Force is trademark of Immersion Corp.
Commit	Line	Data
f8639952 MCC	1	===============
	2	Iforce Protocol
	3	===============
	4
	5	:Author: Johann Deneux <johann.deneux@gmail.com>
	6
	7	Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
	8
	9	:Additions: by Vojtech Pavlik.
	10
	11
	12	Introduction
	13	============
	14
6d0b842d LT	15	This document describes what I managed to discover about the protocol used to
	16	specify force effects to I-Force 2.0 devices. None of this information comes
	17	from Immerse. That's why you should not trust what is written in this
	18	document. This document is intended to help understanding the protocol.
	19	This is not a reference. Comments and corrections are welcome. To contact me,
118e78d1	20	send an email to: johann.deneux@gmail.com
6d0b842d	21
f8639952 MCC	22	.. warning::
	23
	24	I shall not be held responsible for any damage or harm caused if you try to
	25	send data to your I-Force device based on what you read in this document.
	26
	27	Preliminary Notes
	28	=================
6d0b842d	29
6d0b842d LT	30	All values are hexadecimal with big-endian encoding (msb on the left). Beware,
	31	values inside packets are encoded using little-endian. Bytes whose roles are
	32	unknown are marked ??? Information that needs deeper inspection is marked (?)
	33
f8639952 MCC	34	General form of a packet
	35	------------------------
	36
6d0b842d	37	This is how packets look when the device uses the rs232 to communicate.
f8639952 MCC	38
f8639952 MCC	39	== == === ==== ==
6d0b842d	40	2B OP LEN DATA CS
f8639952 MCC	41	== == === ==== ==
f8639952 MCC	42
6d0b842d LT	43	CS is the checksum. It is equal to the exclusive or of all bytes.
	44
	45	When using USB:
f8639952 MCC	46
f8639952 MCC	47	== ====
6d0b842d	48	OP DATA
f8639952 MCC	49	== ====
	50
	51	The 2B, LEN and CS fields have disappeared, probably because USB handles
	52	frames and data corruption is handled or unsignificant.
6d0b842d LT	53
	54	First, I describe effects that are sent by the device to the computer
	55
f8639952 MCC	56	Device input state
	57	==================
	58
6d0b842d	59	This packet is used to indicate the state of each button and the value of each
f8639952 MCC	60	axis::
	61
	62	OP= 01 for a joystick, 03 for a wheel
	63	LEN= Varies from device to device
	64	00 X-Axis lsb
	65	01 X-Axis msb
	66	02 Y-Axis lsb, or gas pedal for a wheel
	67	03 Y-Axis msb, or brake pedal for a wheel
	68	04 Throttle
	69	05 Buttons
	70	06 Lower 4 bits: Buttons
	71	Upper 4 bits: Hat
	72	07 Rudder
	73
	74	Device effects states
	75	=====================
	76
	77	::
	78
	79	OP= 02
	80	LEN= Varies
	81	00 ? Bit 1 (Value 2) is the value of the deadman switch
	82	01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
	83	02 ??
	84	03 Address of parameter block changed (lsb)
	85	04 Address of parameter block changed (msb)
	86	05 Address of second parameter block changed (lsb)
	87	... depending on the number of parameter blocks updated
	88
	89	Force effect
	90	------------
	91
	92	::
	93
	94	OP= 01
	95	LEN= 0e
	96	00 Channel (when playing several effects at the same time, each must
	97	be assigned a channel)
	98	01 Wave form
	99	Val 00 Constant
	100	Val 20 Square
	101	Val 21 Triangle
	102	Val 22 Sine
	103	Val 23 Sawtooth up
	104	Val 24 Sawtooth down
	105	Val 40 Spring (Force = f(pos))
	106	Val 41 Friction (Force = f(velocity)) and Inertia
	107	(Force = f(acceleration))
	108
	109
	110	02 Axes affected and trigger
	111	Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
	112	Val 4 = X axis only. Byte 05 must contain 5a
	113	Val 8 = Y axis only. Byte 05 must contain b4
	114	Val c = X and Y axes. Bytes 05 must contain 60
	115	Bits 0-3: Val 0 = No trigger
	116	Val x+1 = Button x triggers the effect
	117	When the whole byte is 0, cancel the previously set trigger
	118
	119	03-04 Duration of effect (little endian encoding, in ms)
	120
	121	05 Direction of effect, if applicable. Else, see 02 for value to assign.
	122
	123	06-07 Minimum time between triggering.
124
125	08-09 Address of periodicity or magnitude parameters
126	0a-0b Address of attack and fade parameters, or ffff if none.
127	or
128	08-09 Address of interactive parameters for X-axis,
129	or ffff if not applicable
130	0a-0b Address of interactive parameters for Y-axis,
131	or ffff if not applicable
132
133	0c-0d Delay before execution of effect (little endian encoding, in ms)
134
135
136	Time based parameters
137	---------------------
138
139	Attack and fade
140	^^^^^^^^^^^^^^^
141
142	::
143
144	OP= 02
145	LEN= 08
146	00-01 Address where to store the parameters
147	02-03 Duration of attack (little endian encoding, in ms)
148	04 Level at end of attack. Signed byte.
149	05-06 Duration of fade.
150	07 Level at end of fade.
151
152	Magnitude
153	^^^^^^^^^
154
155	::
156
157	OP= 03
158	LEN= 03
159	00-01 Address
160	02 Level. Signed byte.
161
162	Periodicity
163	^^^^^^^^^^^
164
165	::
166
167	OP= 04
168	LEN= 07
169	00-01 Address
170	02 Magnitude. Signed byte.
171	03 Offset. Signed byte.
172	04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
173	05-06 Period (little endian encoding, in ms)
174
175	Interactive parameters
176	----------------------
177
178	::
179
180	OP= 05
181	LEN= 0a
182	00-01 Address
183	02 Positive Coeff
184	03 Negative Coeff
185	04+05 Offset (center)
186	06+07 Dead band (Val 01F4 = 5000 (decimal))
187	08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
188	09 Negative saturation
6d0b842d LT	189
	190	The encoding is a bit funny here: For coeffs, these are signed values. The
	191	maximum value is 64 (100 decimal), the min is 9c.
	192	For the offset, the minimum value is FE0C, the maximum value is 01F4.
	193	For the deadband, the minimum value is 0, the max is 03E8.
	194
f8639952 MCC	195	Controls
	196	--------
	197
	198	::
	199
	200	OP= 41
	201	LEN= 03
	202	00 Channel
	203	01 Start/Stop
	204	Val 00: Stop
	205	Val 01: Start and play once.
	206	Val 41: Start and play n times (See byte 02 below)
	207	02 Number of iterations n.
	208
	209	Init
	210	----
	211
	212
	213	Querying features
	214	^^^^^^^^^^^^^^^^^
	215	::
	216
	217	OP= ff
	218	Query command. Length varies according to the query type.
	219	The general format of this packet is:
	220	ff 01 QUERY [INDEX] CHECKSUM
	221	responses are of the same form:
	222	FF LEN QUERY VALUE_QUERIED CHECKSUM2
	223	where LEN = 1 + length(VALUE_QUERIED)
	224
	225	Query ram size
	226	~~~~~~~~~~~~~~
	227
	228	::
	229
	230	QUERY = 42 ('B'uffer size)
	231
01dd2fbf	232	The device should reply with the same packet plus two additional bytes
6d0b842d LT	233	containing the size of the memory:
	234	ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
	235
f8639952 MCC	236	Query number of effects
	237	~~~~~~~~~~~~~~~~~~~~~~~
	238
	239	::
	240
	241	QUERY = 4e ('N'umber of effects)
	242
6d0b842d LT	243	The device should respond by sending the number of effects that can be played
	244	at the same time (one byte)
	245	ff 02 4e 14 CS would stand for 20 effects.
	246
f8639952 MCC	247	Vendor's id
	248	~~~~~~~~~~~
	249
	250	::
	251
	252	QUERY = 4d ('M'anufacturer)
	253
6d0b842d LT	254	Query the vendors'id (2 bytes)
6d0b842d LT	255
f8639952 MCC	256	Product id
	257	~~~~~~~~~~
	258
	259	::
	260
	261	QUERY = 50 ('P'roduct)
	262
6d0b842d LT	263	Query the product id (2 bytes)
6d0b842d LT	264
f8639952 MCC	265	Open device
	266	~~~~~~~~~~~
	267
	268	::
	269
	270	QUERY = 4f ('O'pen)
	271
6d0b842d LT	272	No data returned.
6d0b842d LT	273
f8639952 MCC	274	Close device
	275	~~~~~~~~~~~~
	276
	277	::
	278
	279	QUERY = 43 ('C')lose
	280
6d0b842d LT	281	No data returned.
6d0b842d LT	282
f8639952 MCC	283	Query effect
	284	~~~~~~~~~~~~
	285
	286	::
	287
	288	QUERY = 45 ('E')
	289
6d0b842d LT	290	Send effect type.
	291	Returns nonzero if supported (2 bytes)
	292
f8639952 MCC	293	Firmware Version
	294	~~~~~~~~~~~~~~~~
	295
	296	::
	297
	298	QUERY = 56 ('V'ersion)
	299
6d0b842d LT	300	Sends back 3 bytes - major, minor, subminor
6d0b842d LT	301
f8639952 MCC	302	Initialisation of the device
	303	^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	304
	305	Set Control
	306	~~~~~~~~~~~
	307
	308	.. note::
	309	Device dependent, can be different on different models!
	310
	311	::
	312
	313	OP= 40 <idx> <val> [<val>]
	314	LEN= 2 or 3
	315	00 Idx
	316	Idx 00 Set dead zone (0..2048)
	317	Idx 01 Ignore Deadman sensor (0..1)
	318	Idx 02 Enable comm watchdog (0..1)
	319	Idx 03 Set the strength of the spring (0..100)
	320	Idx 04 Enable or disable the spring (0/1)
	321	Idx 05 Set axis saturation threshold (0..2048)
	322
	323	Set Effect State
	324	~~~~~~~~~~~~~~~~
	325
	326	::
	327
	328	OP= 42 <val>
	329	LEN= 1
	330	00 State
	331	Bit 3 Pause force feedback
	332	Bit 2 Enable force feedback
	333	Bit 0 Stop all effects
	334
	335	Set overall
	336	~~~~~~~~~~~
	337
	338	::
	339
	340	OP= 43 <val>
	341	LEN= 1
	342	00 Gain
	343	Val 00 = 0%
	344	Val 40 = 50%
	345	Val 80 = 100%
	346
	347	Parameter memory
	348	----------------
6d0b842d LT	349
	350	Each device has a certain amount of memory to store parameters of effects.
	351	The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
	352	is the amount of memory apparently needed for every set of parameters:
f8639952	353
6d0b842d LT	354	- period : 0c
	355	- magnitude : 02
	356	- attack and fade : 0e
	357	- interactive : 08
	358
f8639952 MCC	359	Appendix: How to study the protocol?
f8639952 MCC	360	====================================
6d0b842d	361
f8639952 MCC	362	1. Generate effects using the force editor provided with the DirectX SDK, or
f8639952 MCC	363	use Immersion Studio (freely available at their web site in the developer section:
01dd2fbf	364	www.immersion.com)
f8639952	365	2. Start a soft spying RS232 or USB (depending on where you connected your
01dd2fbf	366	joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
6d0b842d LT	367	3. Play the effect, and watch what happens on the spy screen.
	368
	369	A few words about ComPortSpy:
01dd2fbf ML	370	At first glance, this software seems, hum, well... buggy. In fact, data appear with a
01dd2fbf ML	371	few seconds latency. Personally, I restart it every time I play an effect.
6d0b842d LT	372	Remember it's free (as in free beer) and alpha!
6d0b842d LT	373
f8639952 MCC	374	URLS
f8639952 MCC	375	====
6d0b842d	376
f8639952 MCC	377	Check http://www.immerse.com for Immersion Studio,
f8639952 MCC	378	and http://www.fcoder.com for ComPortSpy.
6d0b842d	379
6d0b842d LT	380
6d0b842d LT	381	I-Force is trademark of Immersion Corp.