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