0001 ===============
0002 Iforce Protocol
0003 ===============
0004
0005 :Author: Johann Deneux <johann.deneux@gmail.com>
0006
0007 Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
0008
0009 :Additions: by Vojtech Pavlik.
0010
0011
0012 Introduction
0013 ============
0014
0015 This document describes what I managed to discover about the protocol used to
0016 specify force effects to I-Force 2.0 devices. None of this information comes
0017 from Immerse. That's why you should not trust what is written in this
0018 document. This document is intended to help understanding the protocol.
0019 This is not a reference. Comments and corrections are welcome. To contact me,
0020 send an email to: johann.deneux@gmail.com
0021
0022 .. warning::
0023
0024 I shall not be held responsible for any damage or harm caused if you try to
0025 send data to your I-Force device based on what you read in this document.
0026
0027 Preliminary Notes
0028 =================
0029
0030 All values are hexadecimal with big-endian encoding (msb on the left). Beware,
0031 values inside packets are encoded using little-endian. Bytes whose roles are
0032 unknown are marked ??? Information that needs deeper inspection is marked (?)
0033
0034 General form of a packet
0035 ------------------------
0036
0037 This is how packets look when the device uses the rs232 to communicate.
0038
0039 == == === ==== ==
0040 2B OP LEN DATA CS
0041 == == === ==== ==
0042
0043 CS is the checksum. It is equal to the exclusive or of all bytes.
0044
0045 When using USB:
0046
0047 == ====
0048 OP DATA
0049 == ====
0050
0051 The 2B, LEN and CS fields have disappeared, probably because USB handles
0052 frames and data corruption is handled or unsignificant.
0053
0054 First, I describe effects that are sent by the device to the computer
0055
0056 Device input state
0057 ==================
0058
0059 This packet is used to indicate the state of each button and the value of each
0060 axis::
0061
0062 OP= 01 for a joystick, 03 for a wheel
0063 LEN= Varies from device to device
0064 00 X-Axis lsb
0065 01 X-Axis msb
0066 02 Y-Axis lsb, or gas pedal for a wheel
0067 03 Y-Axis msb, or brake pedal for a wheel
0068 04 Throttle
0069 05 Buttons
0070 06 Lower 4 bits: Buttons
0071 Upper 4 bits: Hat
0072 07 Rudder
0073
0074 Device effects states
0075 =====================
0076
0077 ::
0078
0079 OP= 02
0080 LEN= Varies
0081 00 ? Bit 1 (Value 2) is the value of the deadman switch
0082 01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
0083 02 ??
0084 03 Address of parameter block changed (lsb)
0085 04 Address of parameter block changed (msb)
0086 05 Address of second parameter block changed (lsb)
0087 ... depending on the number of parameter blocks updated
0088
0089 Force effect
0090 ------------
0091
0092 ::
0093
0094 OP= 01
0095 LEN= 0e
0096 00 Channel (when playing several effects at the same time, each must
0097 be assigned a channel)
0098 01 Wave form
0099 Val 00 Constant
0100 Val 20 Square
0101 Val 21 Triangle
0102 Val 22 Sine
0103 Val 23 Sawtooth up
0104 Val 24 Sawtooth down
0105 Val 40 Spring (Force = f(pos))
0106 Val 41 Friction (Force = f(velocity)) and Inertia
0107 (Force = f(acceleration))
0108
0109
0110 02 Axes affected and trigger
0111 Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
0112 Val 4 = X axis only. Byte 05 must contain 5a
0113 Val 8 = Y axis only. Byte 05 must contain b4
0114 Val c = X and Y axes. Bytes 05 must contain 60
0115 Bits 0-3: Val 0 = No trigger
0116 Val x+1 = Button x triggers the effect
0117 When the whole byte is 0, cancel the previously set trigger
0118
0119 03-04 Duration of effect (little endian encoding, in ms)
0120
0121 05 Direction of effect, if applicable. Else, see 02 for value to assign.
0122
0123 06-07 Minimum time between triggering.
0124
0125 08-09 Address of periodicity or magnitude parameters
0126 0a-0b Address of attack and fade parameters, or ffff if none.
0127 *or*
0128 08-09 Address of interactive parameters for X-axis,
0129 or ffff if not applicable
0130 0a-0b Address of interactive parameters for Y-axis,
0131 or ffff if not applicable
0132
0133 0c-0d Delay before execution of effect (little endian encoding, in ms)
0134
0135
0136 Time based parameters
0137 ---------------------
0138
0139 Attack and fade
0140 ^^^^^^^^^^^^^^^
0141
0142 ::
0143
0144 OP= 02
0145 LEN= 08
0146 00-01 Address where to store the parameters
0147 02-03 Duration of attack (little endian encoding, in ms)
0148 04 Level at end of attack. Signed byte.
0149 05-06 Duration of fade.
0150 07 Level at end of fade.
0151
0152 Magnitude
0153 ^^^^^^^^^
0154
0155 ::
0156
0157 OP= 03
0158 LEN= 03
0159 00-01 Address
0160 02 Level. Signed byte.
0161
0162 Periodicity
0163 ^^^^^^^^^^^
0164
0165 ::
0166
0167 OP= 04
0168 LEN= 07
0169 00-01 Address
0170 02 Magnitude. Signed byte.
0171 03 Offset. Signed byte.
0172 04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
0173 05-06 Period (little endian encoding, in ms)
0174
0175 Interactive parameters
0176 ----------------------
0177
0178 ::
0179
0180 OP= 05
0181 LEN= 0a
0182 00-01 Address
0183 02 Positive Coeff
0184 03 Negative Coeff
0185 04+05 Offset (center)
0186 06+07 Dead band (Val 01F4 = 5000 (decimal))
0187 08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
0188 09 Negative saturation
0189
0190 The encoding is a bit funny here: For coeffs, these are signed values. The
0191 maximum value is 64 (100 decimal), the min is 9c.
0192 For the offset, the minimum value is FE0C, the maximum value is 01F4.
0193 For the deadband, the minimum value is 0, the max is 03E8.
0194
0195 Controls
0196 --------
0197
0198 ::
0199
0200 OP= 41
0201 LEN= 03
0202 00 Channel
0203 01 Start/Stop
0204 Val 00: Stop
0205 Val 01: Start and play once.
0206 Val 41: Start and play n times (See byte 02 below)
0207 02 Number of iterations n.
0208
0209 Init
0210 ----
0211
0212
0213 Querying features
0214 ^^^^^^^^^^^^^^^^^
0215 ::
0216
0217 OP= ff
0218 Query command. Length varies according to the query type.
0219 The general format of this packet is:
0220 ff 01 QUERY [INDEX] CHECKSUM
0221 responses are of the same form:
0222 FF LEN QUERY VALUE_QUERIED CHECKSUM2
0223 where LEN = 1 + length(VALUE_QUERIED)
0224
0225 Query ram size
0226 ~~~~~~~~~~~~~~
0227
0228 ::
0229
0230 QUERY = 42 ('B'uffer size)
0231
0232 The device should reply with the same packet plus two additional bytes
0233 containing the size of the memory:
0234 ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
0235
0236 Query number of effects
0237 ~~~~~~~~~~~~~~~~~~~~~~~
0238
0239 ::
0240
0241 QUERY = 4e ('N'umber of effects)
0242
0243 The device should respond by sending the number of effects that can be played
0244 at the same time (one byte)
0245 ff 02 4e 14 CS would stand for 20 effects.
0246
0247 Vendor's id
0248 ~~~~~~~~~~~
0249
0250 ::
0251
0252 QUERY = 4d ('M'anufacturer)
0253
0254 Query the vendors'id (2 bytes)
0255
0256 Product id
0257 ~~~~~~~~~~
0258
0259 ::
0260
0261 QUERY = 50 ('P'roduct)
0262
0263 Query the product id (2 bytes)
0264
0265 Open device
0266 ~~~~~~~~~~~
0267
0268 ::
0269
0270 QUERY = 4f ('O'pen)
0271
0272 No data returned.
0273
0274 Close device
0275 ~~~~~~~~~~~~
0276
0277 ::
0278
0279 QUERY = 43 ('C')lose
0280
0281 No data returned.
0282
0283 Query effect
0284 ~~~~~~~~~~~~
0285
0286 ::
0287
0288 QUERY = 45 ('E')
0289
0290 Send effect type.
0291 Returns nonzero if supported (2 bytes)
0292
0293 Firmware Version
0294 ~~~~~~~~~~~~~~~~
0295
0296 ::
0297
0298 QUERY = 56 ('V'ersion)
0299
0300 Sends back 3 bytes - major, minor, subminor
0301
0302 Initialisation of the device
0303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0304
0305 Set Control
0306 ~~~~~~~~~~~
0307
0308 .. note::
0309 Device dependent, can be different on different models!
0310
0311 ::
0312
0313 OP= 40 <idx> <val> [<val>]
0314 LEN= 2 or 3
0315 00 Idx
0316 Idx 00 Set dead zone (0..2048)
0317 Idx 01 Ignore Deadman sensor (0..1)
0318 Idx 02 Enable comm watchdog (0..1)
0319 Idx 03 Set the strength of the spring (0..100)
0320 Idx 04 Enable or disable the spring (0/1)
0321 Idx 05 Set axis saturation threshold (0..2048)
0322
0323 Set Effect State
0324 ~~~~~~~~~~~~~~~~
0325
0326 ::
0327
0328 OP= 42 <val>
0329 LEN= 1
0330 00 State
0331 Bit 3 Pause force feedback
0332 Bit 2 Enable force feedback
0333 Bit 0 Stop all effects
0334
0335 Set overall
0336 ~~~~~~~~~~~
0337
0338 ::
0339
0340 OP= 43 <val>
0341 LEN= 1
0342 00 Gain
0343 Val 00 = 0%
0344 Val 40 = 50%
0345 Val 80 = 100%
0346
0347 Parameter memory
0348 ----------------
0349
0350 Each device has a certain amount of memory to store parameters of effects.
0351 The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
0352 is the amount of memory apparently needed for every set of parameters:
0353
0354 - period : 0c
0355 - magnitude : 02
0356 - attack and fade : 0e
0357 - interactive : 08
0358
0359 Appendix: How to study the protocol?
0360 ====================================
0361
0362 1. Generate effects using the force editor provided with the DirectX SDK, or
0363 use Immersion Studio (freely available at their web site in the developer section:
0364 www.immersion.com)
0365 2. Start a soft spying RS232 or USB (depending on where you connected your
0366 joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
0367 3. Play the effect, and watch what happens on the spy screen.
0368
0369 A few words about ComPortSpy:
0370 At first glance, this software seems, hum, well... buggy. In fact, data appear with a
0371 few seconds latency. Personally, I restart it every time I play an effect.
0372 Remember it's free (as in free beer) and alpha!
0373
0374 URLS
0375 ====
0376
0377 Check http://www.immerse.com for Immersion Studio,
0378 and http://www.fcoder.com for ComPortSpy.
0379
0380
0381 I-Force is trademark of Immersion Corp.
