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.