summaryrefslogtreecommitdiff
path: root/Documentation/input/iforce-protocol.rst
blob: 8634beac3fdb67b72d137012664f824eaeb2008c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
===============
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.