382 lines · plain
1===============2Iforce Protocol3===============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 12Introduction13============14 15This document describes what I managed to discover about the protocol used to16specify force effects to I-Force 2.0 devices. None of this information comes17from Immerse. That's why you should not trust what is written in this18document. 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.com21 22.. warning::23 24 I shall not be held responsible for any damage or harm caused if you try to25 send data to your I-Force device based on what you read in this document.26 27Preliminary Notes28=================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 are32unknown are marked ??? Information that needs deeper inspection is marked (?)33 34General form of a packet35------------------------36 37This is how packets look when the device uses the rs232 to communicate.38 39== == === ==== ==402B OP LEN DATA CS41== == === ==== ==42 43CS is the checksum. It is equal to the exclusive or of all bytes.44 45When using USB:46 47== ====48OP DATA49== ====50 51The 2B, LEN and CS fields have disappeared, probably because USB handles52frames and data corruption is handled or insignificant.53 54First, I describe effects that are sent by the device to the computer55 56Device input state57==================58 59This packet is used to indicate the state of each button and the value of each60axis::61 62 OP= 01 for a joystick, 03 for a wheel63 LEN= Varies from device to device64 00 X-Axis lsb65 01 X-Axis msb66 02 Y-Axis lsb, or gas pedal for a wheel67 03 Y-Axis msb, or brake pedal for a wheel68 04 Throttle69 05 Buttons70 06 Lower 4 bits: Buttons71 Upper 4 bits: Hat72 07 Rudder73 74Device effects states75=====================76 77::78 79 OP= 0280 LEN= Varies81 00 ? Bit 1 (Value 2) is the value of the deadman switch82 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 updated88 89Force effect90------------91 92::93 94 OP= 0195 LEN= 0e96 00 Channel (when playing several effects at the same time, each must97 be assigned a channel)98 01 Wave form99 Val 00 Constant100 Val 20 Square101 Val 21 Triangle102 Val 22 Sine103 Val 23 Sawtooth up104 Val 24 Sawtooth down105 Val 40 Spring (Force = f(pos))106 Val 41 Friction (Force = f(velocity)) and Inertia107 (Force = f(acceleration))108 109 110 02 Axes affected and trigger111 Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction112 Val 4 = X axis only. Byte 05 must contain 5a113 Val 8 = Y axis only. Byte 05 must contain b4114 Val c = X and Y axes. Bytes 05 must contain 60115 Bits 0-3: Val 0 = No trigger116 Val x+1 = Button x triggers the effect117 When the whole byte is 0, cancel the previously set trigger118 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 parameters126 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 applicable130 0a-0b Address of interactive parameters for Y-axis,131 or ffff if not applicable132 133 0c-0d Delay before execution of effect (little endian encoding, in ms)134 135 136Time based parameters137---------------------138 139Attack and fade140^^^^^^^^^^^^^^^141 142::143 144 OP= 02145 LEN= 08146 00-01 Address where to store the parameters147 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 152Magnitude153^^^^^^^^^154 155::156 157 OP= 03158 LEN= 03159 00-01 Address160 02 Level. Signed byte.161 162Periodicity163^^^^^^^^^^^164 165::166 167 OP= 04168 LEN= 07169 00-01 Address170 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 parameters176----------------------177 178::179 180 OP= 05181 LEN= 0a182 00-01 Address183 02 Positive Coeff184 03 Negative Coeff185 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 saturation189 190The encoding is a bit funny here: For coeffs, these are signed values. The191maximum 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 195Controls196--------197 198::199 200 OP= 41201 LEN= 03202 00 Channel203 01 Start/Stop204 Val 00: Stop205 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 209Init210----211 212 213Querying features214^^^^^^^^^^^^^^^^^215::216 217 OP= ff218 Query command. Length varies according to the query type.219 The general format of this packet is:220 ff 01 QUERY [INDEX] CHECKSUM221 responses are of the same form:222 FF LEN QUERY VALUE_QUERIED CHECKSUM2223 where LEN = 1 + length(VALUE_QUERIED)224 225Query ram size226~~~~~~~~~~~~~~227 228::229 230 QUERY = 42 ('B'uffer size)231 232The device should reply with the same packet plus two additional bytes233containing 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 effects237~~~~~~~~~~~~~~~~~~~~~~~238 239::240 241 QUERY = 4e ('N'umber of effects)242 243The device should respond by sending the number of effects that can be played244at the same time (one byte)245ff 02 4e 14 CS would stand for 20 effects.246 247Vendor's id248~~~~~~~~~~~249 250::251 252 QUERY = 4d ('M'anufacturer)253 254Query the vendors'id (2 bytes)255 256Product id257~~~~~~~~~~258 259::260 261 QUERY = 50 ('P'roduct)262 263Query the product id (2 bytes)264 265Open device266~~~~~~~~~~~267 268::269 270 QUERY = 4f ('O'pen)271 272No data returned.273 274Close device275~~~~~~~~~~~~276 277::278 279 QUERY = 43 ('C')lose280 281No data returned.282 283Query effect284~~~~~~~~~~~~285 286::287 288 QUERY = 45 ('E')289 290Send effect type.291Returns nonzero if supported (2 bytes)292 293Firmware Version294~~~~~~~~~~~~~~~~295 296::297 298 QUERY = 56 ('V'ersion)299 300Sends back 3 bytes - major, minor, subminor301 302Initialisation of the device303^^^^^^^^^^^^^^^^^^^^^^^^^^^^304 305Set Control306~~~~~~~~~~~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 3315 00 Idx316 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 State324~~~~~~~~~~~~~~~~325 326::327 328 OP= 42 <val>329 LEN= 1330 00 State331 Bit 3 Pause force feedback332 Bit 2 Enable force feedback333 Bit 0 Stop all effects334 335Set overall336~~~~~~~~~~~337 338::339 340 OP= 43 <val>341 LEN= 1342 00 Gain343 Val 00 = 0%344 Val 40 = 50%345 Val 80 = 100%346 347Parameter memory348----------------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. Below352is the amount of memory apparently needed for every set of parameters:353 354 - period : 0c355 - magnitude : 02356 - attack and fade : 0e357 - interactive : 08358 359Appendix: How to study the protocol?360====================================361 3621. Generate effects using the force editor provided with the DirectX SDK, or363use 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 your366joystick/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 a371few seconds latency. Personally, I restart it every time I play an effect.372Remember it's free (as in free beer) and alpha!373 374URLS375====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