1 ===============
2 Iforce Protocol
3 ===============
4
5 :Author: Johann Deneux <johann.deneux@gmail.com
6
7 Home page at `<http://web.archive.org/web/*/ht
8
9 :Additions: by Vojtech Pavlik.
10
11
12 Introduction
13 ============
14
15 This document describes what I managed to disc
16 specify force effects to I-Force 2.0 devices.
17 from Immerse. That's why you should not trust
18 document. This document is intended to help un
19 This is not a reference. Comments and correcti
20 send an email to: johann.deneux@gmail.com
21
22 .. warning::
23
24 I shall not be held responsible for any da
25 send data to your I-Force device based on
26
27 Preliminary Notes
28 =================
29
30 All values are hexadecimal with big-endian enc
31 values inside packets are encoded using little
32 unknown are marked ??? Information that needs
33
34 General form of a packet
35 ------------------------
36
37 This is how packets look when the device uses
38
39 == == === ==== ==
40 2B OP LEN DATA CS
41 == == === ==== ==
42
43 CS is the checksum. It is equal to the exclusi
44
45 When using USB:
46
47 == ====
48 OP DATA
49 == ====
50
51 The 2B, LEN and CS fields have disappeared, pr
52 frames and data corruption is handled or insig
53
54 First, I describe effects that are sent by the
55
56 Device input state
57 ==================
58
59 This packet is used to indicate the state of e
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 d
82 01 Bit 8 is set if the effect is playing.
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 chang
87 ... depending on the number of parameter b
88
89 Force effect
90 ------------
91
92 ::
93
94 OP= 01
95 LEN= 0e
96 00 Channel (when playing several effects a
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(velocit
107 (Force = f(acceleration))
108
109
110 02 Axes affected and trigger
111 Bits 4-7: Val 2 = effect along one
112 Val 4 = X axis only. Byte
113 Val 8 = Y axis only. Byte
114 Val c = X and Y axes. Byte
115 Bits 0-3: Val 0 = No trigger
116 Val x+1 = Button x trigger
117 When the whole byte is 0, cancel t
118
119 03-04 Duration of effect (little endian en
120
121 05 Direction of effect, if applicable. Els
122
123 06-07 Minimum time between triggering.
124
125 08-09 Address of periodicity or magnitude
126 0a-0b Address of attack and fade parameter
127 *or*
128 08-09 Address of interactive parameters fo
129 or ffff if not applicable
130 0a-0b Address of interactive parameters fo
131 or ffff if not applicable
132
133 0c-0d Delay before execution of effect (li
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 parameter
147 02-03 Duration of attack (little endian en
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 m
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 (dec
188 09 Negative saturation
189
190 The encoding is a bit funny here: For coeffs,
191 maximum value is 64 (100 decimal), the min is
192 For the offset, the minimum value is FE0C, the
193 For the deadband, the minimum value is 0, the
194
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 (Se
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
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
232 The device should reply with the same packet p
233 containing the size of the memory:
234 ff 03 42 03 e8 CS would mean that the device h
235
236 Query number of effects
237 ~~~~~~~~~~~~~~~~~~~~~~~
238
239 ::
240
241 QUERY = 4e ('N'umber of effects)
242
243 The device should respond by sending the numbe
244 at the same time (one byte)
245 ff 02 4e 14 CS would stand for 20 effects.
246
247 Vendor's id
248 ~~~~~~~~~~~
249
250 ::
251
252 QUERY = 4d ('M'anufacturer)
253
254 Query the vendors'id (2 bytes)
255
256 Product id
257 ~~~~~~~~~~
258
259 ::
260
261 QUERY = 50 ('P'roduct)
262
263 Query the product id (2 bytes)
264
265 Open device
266 ~~~~~~~~~~~
267
268 ::
269
270 QUERY = 4f ('O'pen)
271
272 No data returned.
273
274 Close device
275 ~~~~~~~~~~~~
276
277 ::
278
279 QUERY = 43 ('C')lose
280
281 No data returned.
282
283 Query effect
284 ~~~~~~~~~~~~
285
286 ::
287
288 QUERY = 45 ('E')
289
290 Send effect type.
291 Returns nonzero if supported (2 bytes)
292
293 Firmware Version
294 ~~~~~~~~~~~~~~~~
295
296 ::
297
298 QUERY = 56 ('V'ersion)
299
300 Sends back 3 bytes - major, minor, subminor
301
302 Initialisation of the device
303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
304
305 Set Control
306 ~~~~~~~~~~~
307
308 .. note::
309 Device dependent, can be different on diff
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 (
320 Idx 04 Enable or disable the spring (0/
321 Idx 05 Set axis saturation threshold (0
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 ----------------
349
350 Each device has a certain amount of memory to
351 The amount of RAM may vary, I encountered valu
352 is the amount of memory apparently needed for
353
354 - period : 0c
355 - magnitude : 02
356 - attack and fade : 0e
357 - interactive : 08
358
359 Appendix: How to study the protocol?
360 ====================================
361
362 1. Generate effects using the force editor pro
363 use Immersion Studio (freely available at thei
364 www.immersion.com)
365 2. Start a soft spying RS232 or USB (depending
366 joystick/wheel). I used ComPortSpy from fCoder
367 3. Play the effect, and watch what happens on
368
369 A few words about ComPortSpy:
370 At first glance, this software seems, hum, wel
371 few seconds latency. Personally, I restart it
372 Remember it's free (as in free beer) and alpha
373
374 URLS
375 ====
376
377 Check http://www.immerse.com for Immersion Stu
378 and http://www.fcoder.com for ComPortSpy.
379
380
381 I-Force is trademark of Immersion Corp.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.