Documentation/input/iforce-protocol.txt

   1 ** Introduction
   2 This document describes what I managed to discover about the protocol used to
   3 specify force effects to I-Force 2.0 devices.  None of this information comes
   4 from Immerse. That's why you should not trust what is written in this
   5 document. This document is intended to help understanding the protocol.
   6 This is not a reference. Comments and corrections are welcome.  To contact me,
   7 send an email to: johann.deneux@gmail.com
   8
   9 ** WARNING **
  10 I shall not be held responsible for any damage or harm caused if you try to
  11 send data to your I-Force device based on what you read in this document.
  12
  13 ** Preliminary Notes:
  14 All values are hexadecimal with big-endian encoding (msb on the left). Beware,
  15 values inside packets are encoded using little-endian.  Bytes whose roles are
  16 unknown are marked ???  Information that needs deeper inspection is marked (?)
  17
  18 ** General form of a packet **
  19 This is how packets look when the device uses the rs232 to communicate.
  20 2B OP LEN DATA CS
  21 CS is the checksum. It is equal to the exclusive or of all bytes.
  22
  23 When using USB:
  24 OP DATA
  25 The 2B, LEN and CS fields have disappeared, probably because USB handles frames and
  26 data corruption is handled or unsignificant.
  27
  28 First, I describe effects that are sent by the device to the computer
  29
  30 ** Device input state
  31 This packet is used to indicate the state of each button and the value of each
  32 axis
  33 OP= 01 for a joystick, 03 for a wheel
  34 LEN= Varies from device to device
  35 00 X-Axis lsb
  36 01 X-Axis msb
  37 02 Y-Axis lsb, or gas pedal for a wheel
  38 03 Y-Axis msb, or brake pedal for a wheel
  39 04 Throttle
  40 05 Buttons
  41 06 Lower 4 bits: Buttons
  42    Upper 4 bits: Hat
  43 07 Rudder
  44
  45 ** Device effects states
  46 OP= 02
  47 LEN= Varies
  48 00 ? Bit 1 (Value 2) is the value of the deadman switch
  49 01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
  50 02 ??
  51 03 Address of parameter block changed (lsb)
  52 04 Address of parameter block changed (msb)
  53 05 Address of second parameter block changed (lsb)
  54 ... depending on the number of parameter blocks updated
  55
  56 ** Force effect **
  57 OP=  01
  58 LEN= 0e
  59 00 Channel (when playing several effects at the same time, each must be assigned a channel)
  60 01 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
  71 02 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
  80 03-04 Duration of effect (little endian encoding, in ms)
  81
  82 05 Direction of effect, if applicable. Else, see 02 for value to assign.
  83
  84 06-07 Minimum time between triggering.
  85
  86 08-09 Address of periodicity or magnitude parameters
  87 0a-0b Address of attack and fade parameters, or ffff if none.
  88 *or*
  89 08-09 Address of interactive parameters for X-axis, or ffff if not applicable
  90 0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
  91
  92 0c-0d Delay before execution of effect (little endian encoding, in ms)
  93
  94
  95 ** Time based parameters **
  96
  97 *** Attack and fade ***
  98 OP=  02
  99 LEN= 08
 100 00-01 Address where to store the parameteres
 101 02-03 Duration of attack (little endian encoding, in ms)
 102 04 Level at end of attack. Signed byte.
 103 05-06 Duration of fade.
 104 07 Level at end of fade.
 105
 106 *** Magnitude ***
 107 OP=  03
 108 LEN= 03
 109 00-01 Address
 110 02 Level. Signed byte.
 111
 112 *** Periodicity ***
 113 OP=  04
 114 LEN= 07
 115 00-01 Address
 116 02 Magnitude. Signed byte.
 117 03 Offset. Signed byte.
 118 04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
 119 05-06 Period (little endian encoding, in ms)
 120
 121 ** Interactive parameters **
 122 OP=  05
 123 LEN= 0a
 124 00-01 Address
 125 02 Positive Coeff
 126 03 Negative Coeff
 127 04+05 Offset (center)
 128 06+07 Dead band (Val 01F4 = 5000 (decimal))
 129 08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
 130 09 Negative saturation
 131
 132 The encoding is a bit funny here: For coeffs, these are signed values. The
 133 maximum value is 64 (100 decimal), the min is 9c.
 134 For the offset, the minimum value is FE0C, the maximum value is 01F4.
 135 For the deadband, the minimum value is 0, the max is 03E8.
 136
 137 ** Controls **
 138 OP=  41
 139 LEN= 03
 140 00 Channel
 141 01 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)
 145 02 Number of iterations n.
 146
 147 ** Init **
 148
 149 *** Querying features ***
 150 OP=  ff
 151 Query command. Length varies according to the query type.
 152 The general format of this packet is:
 153 ff 01 QUERY [INDEX] CHECKSUM
 154 responses are of the same form:
 155 FF LEN QUERY VALUE_QUERIED CHECKSUM2
 156 where LEN = 1 + length(VALUE_QUERIED)
 157
 158 **** Query ram size ****
 159 QUERY = 42 ('B'uffer size)
 160 The device should reply with the same packet plus two additional bytes
 161 containing the size of the memory:
 162 ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
 163
 164 **** Query number of effects ****
 165 QUERY = 4e ('N'umber of effects)
 166 The device should respond by sending the number of effects that can be played
 167 at the same time (one byte)
 168 ff 02 4e 14 CS would stand for 20 effects.
 169
 170 **** Vendor's id ****
 171 QUERY = 4d ('M'anufacturer)
 172 Query the vendors'id (2 bytes)
 173
 174 **** Product id *****
 175 QUERY = 50 ('P'roduct)
 176 Query the product id (2 bytes)
 177
 178 **** Open device ****
 179 QUERY = 4f ('O'pen)
 180 No data returned.
 181
 182 **** Close device *****
 183 QUERY = 43 ('C')lose
 184 No data returned.
 185
 186 **** Query effect ****
 187 QUERY = 45 ('E')
 188 Send effect type.
 189 Returns nonzero if supported (2 bytes)
 190
 191 **** Firmware Version ****
 192 QUERY = 56 ('V'ersion)
 193 Sends 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 !!!
 199 OP=  40 <idx> <val> [<val>]
 200 LEN= 2 or 3
 201 00 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 ****
 210 OP=  42 <val>
 211 LEN= 1
 212 00 State
 213    Bit 3 Pause force feedback
 214    Bit 2 Enable force feedback
 215    Bit 0 Stop all effects
 216
 217 **** Set overall gain ****
 218 OP=  43 <val>
 219 LEN= 1
 220 00 Gain
 221    Val 00 = 0%
 222    Val 40 = 50%
 223    Val 80 = 100%
 224
 225 ** Parameter memory **
 226
 227 Each device has a certain amount of memory to store parameters of effects.
 228 The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
 229 is 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
 237 1. Generate effects using the force editor provided with the DirectX SDK, or
 238 use Immersion Studio (freely available at their web site in the developer section:
 239 www.immersion.com)
 240 2. Start a soft spying RS232 or USB (depending on where you connected your
 241 joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
 242 3. Play the effect, and watch what happens on the spy screen.
 243
 244 A few words about ComPortSpy:
 245 At first glance, this software seems, hum, well... buggy. In fact, data appear with a
 246 few seconds latency. Personally, I restart it every time I play an effect.
 247 Remember it's free (as in free beer) and alpha!
 248
 249 ** URLS **
 250 Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
 251
 252 ** Author of this document **
 253 Johann Deneux <johann.deneux@gmail.com>
 254 Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/
 255
 256 Additions by Vojtech Pavlik.
 257
 258 I-Force is trademark of Immersion Corp.