1===============
2Iforce Protocol
3===============
4
5:Author: Johann Deneux <johann.deneux@gmail.com>
6
7Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
8
9:Additions: by Vojtech Pavlik.
10
11
12Introduction
13============
14
15This document describes what I managed to discover about the protocol used to
16specify force effects to I-Force 2.0 devices.  None of this information comes
17from Immerse. That's why you should not trust what is written in this
18document. This document is intended to help understanding the protocol.
19This is not a reference. Comments and corrections are welcome.  To contact me,
20send an email to: johann.deneux@gmail.com
21
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
27Preliminary Notes
28=================
29
30All values are hexadecimal with big-endian encoding (msb on the left). Beware,
31values inside packets are encoded using little-endian.  Bytes whose roles are
32unknown are marked ???  Information that needs deeper inspection is marked (?)
33
34General form of a packet
35------------------------
36
37This is how packets look when the device uses the rs232 to communicate.
38
39== == === ==== ==
402B OP LEN DATA CS
41== == === ==== ==
42
43CS is the checksum. It is equal to the exclusive or of all bytes.
44
45When using USB:
46
47== ====
48OP DATA
49== ====
50
51The 2B, LEN and CS fields have disappeared, probably because USB handles
52frames and data corruption is handled or insignificant.
53
54First, I describe effects that are sent by the device to the computer
55
56Device input state
57==================
58
59This packet is used to indicate the state of each button and the value of each
60axis::
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
74Device 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
89Force 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
136Time based parameters
137---------------------
138
139Attack 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
152Magnitude
153^^^^^^^^^
154
155::
156
157    OP=  03
158    LEN= 03
159    00-01 Address
160    02 Level. Signed byte.
161
162Periodicity
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
175Interactive 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
189
190The encoding is a bit funny here: For coeffs, these are signed values. The
191maximum value is 64 (100 decimal), the min is 9c.
192For the offset, the minimum value is FE0C, the maximum value is 01F4.
193For the deadband, the minimum value is 0, the max is 03E8.
194
195Controls
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
209Init
210----
211
212
213Querying 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
225Query ram size
226~~~~~~~~~~~~~~
227
228::
229
230    QUERY = 42 ('B'uffer size)
231
232The device should reply with the same packet plus two additional bytes
233containing the size of the memory:
234ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
235
236Query number of effects
237~~~~~~~~~~~~~~~~~~~~~~~
238
239::
240
241    QUERY = 4e ('N'umber of effects)
242
243The device should respond by sending the number of effects that can be played
244at the same time (one byte)
245ff 02 4e 14 CS would stand for 20 effects.
246
247Vendor's id
248~~~~~~~~~~~
249
250::
251
252    QUERY = 4d ('M'anufacturer)
253
254Query the vendors'id (2 bytes)
255
256Product id
257~~~~~~~~~~
258
259::
260
261    QUERY = 50 ('P'roduct)
262
263Query the product id (2 bytes)
264
265Open device
266~~~~~~~~~~~
267
268::
269
270    QUERY = 4f ('O'pen)
271
272No data returned.
273
274Close device
275~~~~~~~~~~~~
276
277::
278
279    QUERY = 43 ('C')lose
280
281No data returned.
282
283Query effect
284~~~~~~~~~~~~
285
286::
287
288    QUERY = 45 ('E')
289
290Send effect type.
291Returns nonzero if supported (2 bytes)
292
293Firmware Version
294~~~~~~~~~~~~~~~~
295
296::
297
298    QUERY = 56 ('V'ersion)
299
300Sends back 3 bytes - major, minor, subminor
301
302Initialisation of the device
303^^^^^^^^^^^^^^^^^^^^^^^^^^^^
304
305Set 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
323Set 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
335Set 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
347Parameter memory
348----------------
349
350Each device has a certain amount of memory to store parameters of effects.
351The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
352is the amount of memory apparently needed for every set of parameters:
353
354 - period : 0c
355 - magnitude : 02
356 - attack and fade : 0e
357 - interactive : 08
358
359Appendix: How to study the protocol?
360====================================
361
3621. Generate effects using the force editor provided with the DirectX SDK, or
363use Immersion Studio (freely available at their web site in the developer section:
364www.immersion.com)
3652. Start a soft spying RS232 or USB (depending on where you connected your
366joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
3673. Play the effect, and watch what happens on the spy screen.
368
369A few words about ComPortSpy:
370At first glance, this software seems, hum, well... buggy. In fact, data appear with a
371few seconds latency. Personally, I restart it every time I play an effect.
372Remember it's free (as in free beer) and alpha!
373
374URLS
375====
376
377Check http://www.immerse.com for Immersion Studio,
378and http://www.fcoder.com for ComPortSpy.
379
380
381I-Force is trademark of Immersion Corp.
382