Documentation/input/devices/iforce-protocol.rst

   1 ===============
   2 Iforce Protocol
   3 ===============
   4
   5 :Author: Johann Deneux <johann.deneux@gmail.com>
   6
   7 Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
   8
   9 :Additions: by Vojtech Pavlik.
  10
  11
  12 Introduction
  13 ============
  14
  15 This document describes what I managed to discover about the protocol used to
  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 what is written in this
  18 document. This document is intended to help understanding the protocol.
  19 This is not a reference. Comments and corrections are welcome.  To contact me,
  20 send an email to: johann.deneux@gmail.com
  21
  22 .. warning::
  23
  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 what you read in this document.
  26
  27 Preliminary Notes
  28 =================
  29
  30 All values are hexadecimal with big-endian encoding (msb on the left). Beware,
  31 values inside packets are encoded using little-endian.  Bytes whose roles are
  32 unknown are marked ???  Information that needs deeper inspection is marked (?)
  33
  34 General form of a packet
  35 ------------------------
  36
  37 This is how packets look when the device uses the rs232 to communicate.
  38
  39 == == === ==== ==
  40 2B OP LEN DATA CS
  41 == == === ==== ==
  42
  43 CS is the checksum. It is equal to the exclusive or of all bytes.
  44
  45 When using USB:
  46
  47 == ====
  48 OP DATA
  49 == ====
  50
  51 The 2B, LEN and CS fields have disappeared, probably because USB handles
  52 frames and data corruption is handled or unsignificant.
  53
  54 First, I describe effects that are sent by the device to the computer
  55
  56 Device input state
  57 ==================
  58
  59 This packet is used to indicate the state of each button and the value of each
  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 deadman switch
  82     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 updated
  88
  89 Force effect
  90 ------------
  91
  92 ::
  93
  94     OP=  01
  95     LEN= 0e
  96     00 Channel (when playing several effects at the same time, each must
  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(velocity)) and Inertia
 107                    (Force = f(acceleration))
 108
 109
 110     02 Axes affected and trigger
 111             Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
 112                     Val 4 = X axis only. Byte 05 must contain 5a
 113                     Val 8 = Y axis only. Byte 05 must contain b4
 114                     Val c = X and Y axes. Bytes 05 must contain 60
 115             Bits 0-3: Val 0 = No trigger
 116                     Val x+1 = Button x triggers the effect
 117             When the whole byte is 0, cancel the previously set trigger
 118
 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 parameters
 126     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 applicable
 130     0a-0b Address of interactive parameters for Y-axis,
 131           or ffff if not applicable
 132
 133     0c-0d Delay before execution of effect (little endian encoding, in ms)
 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 parameters
 147     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
 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 ms)
 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 (decimal) Val 64 = 10000 (decimal))
 188     09 Negative saturation
 189
 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 9c.
 192 For the offset, the minimum value is FE0C, the maximum value is 01F4.
 193 For the deadband, the minimum value is 0, the max is 03E8.
 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 (See byte 02 below)
 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 the query type.
 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 plus two additional bytes
 233 containing the size of the memory:
 234 ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
 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 number of effects that can be played
 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 different models!
 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 (0..100)
 320        Idx 04 Enable or disable the spring (0/1)
 321        Idx 05 Set axis saturation threshold (0..2048)
 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 store parameters of effects.
 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 every set of parameters:
 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 provided with the DirectX SDK, or
 363 use Immersion Studio (freely available at their web site in the developer section:
 364 www.immersion.com)
 365 2. Start a soft spying RS232 or USB (depending on where you connected your
 366 joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
 367 3. Play the effect, and watch what happens on the spy screen.
 368
 369 A few words about ComPortSpy:
 370 At first glance, this software seems, hum, well... buggy. In fact, data appear with a
 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!
 373
 374 URLS
 375 ====
 376
 377 Check http://www.immerse.com for Immersion Studio,
 378 and http://www.fcoder.com for ComPortSpy.
 379
 380
 381 I-Force is trademark of Immersion Corp.