linux/Documentation/input/iforce-protocol.txt
<<
>>
Prefs
   1** Introduction
   2This document describes what I managed to discover about the protocol used to
   3specify force effects to I-Force 2.0 devices.  None of this information comes
   4from Immerse. That's why you should not trust what is written in this
   5document. This document is intended to help understanding the protocol.
   6This is not a reference. Comments and corrections are welcome.  To contact me,
   7send an email to: johann.deneux@gmail.com
   8
   9** WARNING **
  10I shall not be held responsible for any damage or harm caused if you try to
  11send data to your I-Force device based on what you read in this document.
  12
  13** Preliminary Notes:
  14All values are hexadecimal with big-endian encoding (msb on the left). Beware,
  15values inside packets are encoded using little-endian.  Bytes whose roles are
  16unknown are marked ???  Information that needs deeper inspection is marked (?)
  17
  18** General form of a packet **
  19This is how packets look when the device uses the rs232 to communicate.
  202B OP LEN DATA CS
  21CS is the checksum. It is equal to the exclusive or of all bytes.
  22
  23When using USB:
  24OP DATA
  25The 2B, LEN and CS fields have disappeared, probably because USB handles frames and
  26data corruption is handled or unsignificant.
  27
  28First, I describe effects that are sent by the device to the computer
  29
  30** Device input state
  31This packet is used to indicate the state of each button and the value of each
  32axis
  33OP= 01 for a joystick, 03 for a wheel
  34LEN= Varies from device to device
  3500 X-Axis lsb
  3601 X-Axis msb
  3702 Y-Axis lsb, or gas pedal for a wheel
  3803 Y-Axis msb, or brake pedal for a wheel
  3904 Throttle
  4005 Buttons
  4106 Lower 4 bits: Buttons
  42   Upper 4 bits: Hat
  4307 Rudder
  44
  45** Device effects states
  46OP= 02
  47LEN= Varies
  4800 ? Bit 1 (Value 2) is the value of the deadman switch
  4901 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
  5002 ??
  5103 Address of parameter block changed (lsb)
  5204 Address of parameter block changed (msb)
  5305 Address of second parameter block changed (lsb)
  54... depending on the number of parameter blocks updated
  55
  56** Force effect **
  57OP=  01
  58LEN= 0e
  5900 Channel (when playing several effects at the same time, each must be assigned a channel)
  6001 Wave form
  61        Val 00 Constant
  62        Val 20 Square
  63        Val 21 Triangle
  64        Val 22 Sine
  65        Val 23 Sawtooth up
  66        Val 24 Sawtooth down
  67        Val 40 Spring (Force = f(pos))
  68        Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
  69
  70
  7102 Axes affected and trigger
  72        Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
  73                  Val 4 = X axis only. Byte 05 must contain 5a
  74                  Val 8 = Y axis only. Byte 05 must contain b4
  75                  Val c = X and Y axes. Bytes 05 must contain 60
  76        Bits 0-3: Val 0 = No trigger
  77                  Val x+1 = Button x triggers the effect
  78        When the whole byte is 0, cancel the previously set trigger
  79
  8003-04 Duration of effect (little endian encoding, in ms)
  81
  8205 Direction of effect, if applicable. Else, see 02 for value to assign.
  83
  8406-07 Minimum time between triggering.
  85
  8608-09 Address of periodicity or magnitude parameters
  870a-0b Address of attack and fade parameters, or ffff if none.
  88*or*
  8908-09 Address of interactive parameters for X-axis, or ffff if not applicable
  900a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
  91
  920c-0d Delay before execution of effect (little endian encoding, in ms)
  93
  94
  95** Time based parameters **
  96
  97*** Attack and fade ***
  98OP=  02
  99LEN= 08
 10000-01 Address where to store the parameteres
 10102-03 Duration of attack (little endian encoding, in ms)
 10204 Level at end of attack. Signed byte.
 10305-06 Duration of fade.
 10407 Level at end of fade.
 105
 106*** Magnitude ***
 107OP=  03
 108LEN= 03
 10900-01 Address
 11002 Level. Signed byte.
 111
 112*** Periodicity ***
 113OP=  04
 114LEN= 07
 11500-01 Address
 11602 Magnitude. Signed byte.
 11703 Offset. Signed byte.
 11804 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
 11905-06 Period (little endian encoding, in ms)
 120
 121** Interactive parameters **
 122OP=  05
 123LEN= 0a
 12400-01 Address
 12502 Positive Coeff
 12603 Negative Coeff
 12704+05 Offset (center)
 12806+07 Dead band (Val 01F4 = 5000 (decimal))
 12908 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
 13009 Negative saturation
 131
 132The encoding is a bit funny here: For coeffs, these are signed values. The
 133maximum value is 64 (100 decimal), the min is 9c.
 134For the offset, the minimum value is FE0C, the maximum value is 01F4.
 135For the deadband, the minimum value is 0, the max is 03E8.
 136
 137** Controls **
 138OP=  41
 139LEN= 03
 14000 Channel
 14101 Start/Stop
 142        Val 00: Stop
 143        Val 01: Start and play once.
 144        Val 41: Start and play n times (See byte 02 below)
 14502 Number of iterations n.
 146
 147** Init **
 148
 149*** Querying features ***
 150OP=  ff
 151Query command. Length varies according to the query type.
 152The general format of this packet is:
 153ff 01 QUERY [INDEX] CHECKSUM
 154responses are of the same form:
 155FF LEN QUERY VALUE_QUERIED CHECKSUM2
 156where LEN = 1 + length(VALUE_QUERIED)
 157
 158**** Query ram size ****
 159QUERY = 42 ('B'uffer size)
 160The device should reply with the same packet plus two additional bytes
 161containing the size of the memory:
 162ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
 163
 164**** Query number of effects ****
 165QUERY = 4e ('N'umber of effects)
 166The device should respond by sending the number of effects that can be played
 167at the same time (one byte)
 168ff 02 4e 14 CS would stand for 20 effects.
 169
 170**** Vendor's id ****
 171QUERY = 4d ('M'anufacturer)
 172Query the vendors'id (2 bytes)
 173
 174**** Product id *****
 175QUERY = 50 ('P'roduct)
 176Query the product id (2 bytes)
 177
 178**** Open device ****
 179QUERY = 4f ('O'pen)
 180No data returned.
 181
 182**** Close device *****
 183QUERY = 43 ('C')lose
 184No data returned.
 185
 186**** Query effect ****
 187QUERY = 45 ('E')
 188Send effect type.
 189Returns nonzero if supported (2 bytes)
 190
 191**** Firmware Version ****
 192QUERY = 56 ('V'ersion)
 193Sends back 3 bytes - major, minor, subminor
 194
 195*** Initialisation of the device ***
 196
 197**** Set Control ****
 198!!! Device dependent, can be different on different models !!!
 199OP=  40 <idx> <val> [<val>]
 200LEN= 2 or 3
 20100 Idx
 202   Idx 00 Set dead zone (0..2048)
 203   Idx 01 Ignore Deadman sensor (0..1)
 204   Idx 02 Enable comm watchdog (0..1)
 205   Idx 03 Set the strength of the spring (0..100)
 206   Idx 04 Enable or disable the spring (0/1)
 207   Idx 05 Set axis saturation threshold (0..2048)
 208
 209**** Set Effect State ****
 210OP=  42 <val>
 211LEN= 1
 21200 State
 213   Bit 3 Pause force feedback
 214   Bit 2 Enable force feedback
 215   Bit 0 Stop all effects
 216
 217**** Set overall gain ****
 218OP=  43 <val>
 219LEN= 1
 22000 Gain
 221   Val 00 = 0%
 222   Val 40 = 50%
 223   Val 80 = 100%
 224
 225** Parameter memory **
 226
 227Each device has a certain amount of memory to store parameters of effects.
 228The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
 229is the amount of memory apparently needed for every set of parameters:
 230 - period : 0c
 231 - magnitude : 02
 232 - attack and fade : 0e
 233 - interactive : 08
 234
 235** Appendix: How to study the protocol ? **
 236
 2371. Generate effects using the force editor provided with the DirectX SDK, or 
 238use Immersion Studio (freely available at their web site in the developer section: 
 239www.immersion.com)
 2402. Start a soft spying RS232 or USB (depending on where you connected your 
 241joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
 2423. Play the effect, and watch what happens on the spy screen.
 243
 244A few words about ComPortSpy:
 245At first glance, this software seems, hum, well... buggy. In fact, data appear with a
 246few seconds latency. Personally, I restart it every time I play an effect.
 247Remember it's free (as in free beer) and alpha!
 248
 249** URLS **
 250Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
 251
 252** Author of this document **
 253Johann Deneux <johann.deneux@gmail.com>
 254Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr
 255
 256Additions by Vojtech Pavlik.
 257
 258I-Force is trademark of Immersion Corp.
 259
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.