iforce-protocol.txt 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254
  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: deneux@ifrance.com
  8. ** WARNING **
  9. I may not be held responsible for any dammage or harm caused if you try to
  10. send data to your I-Force device based on what you read in this document.
  11. ** Preliminary Notes:
  12. All values are hexadecimal with big-endian encoding (msb on the left). Beware,
  13. values inside packets are encoded using little-endian. Bytes whose roles are
  14. unknown are marked ??? Information that needs deeper inspection is marked (?)
  15. ** General form of a packet **
  16. This is how packets look when the device uses the rs232 to communicate.
  17. 2B OP LEN DATA CS
  18. CS is the checksum. It is equal to the exclusive or of all bytes.
  19. When using USB:
  20. OP DATA
  21. The 2B, LEN and CS fields have disappeared, probably because USB handles frames and
  22. data corruption is handled or unsignificant.
  23. First, I describe effects that are sent by the device to the computer
  24. ** Device input state
  25. This packet is used to indicate the state of each button and the value of each
  26. axis
  27. OP= 01 for a joystick, 03 for a wheel
  28. LEN= Varies from device to device
  29. 00 X-Axis lsb
  30. 01 X-Axis msb
  31. 02 Y-Axis lsb, or gas pedal for a wheel
  32. 03 Y-Axis msb, or brake pedal for a wheel
  33. 04 Throttle
  34. 05 Buttons
  35. 06 Lower 4 bits: Buttons
  36. Upper 4 bits: Hat
  37. 07 Rudder
  38. ** Device effects states
  39. OP= 02
  40. LEN= Varies
  41. 00 ? Bit 1 (Value 2) is the value of the deadman switch
  42. 01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
  43. 02 ??
  44. 03 Address of parameter block changed (lsb)
  45. 04 Address of parameter block changed (msb)
  46. 05 Address of second parameter block changed (lsb)
  47. ... depending on the number of parameter blocks updated
  48. ** Force effect **
  49. OP= 01
  50. LEN= 0e
  51. 00 Channel (when playing several effects at the same time, each must be assigned a channel)
  52. 01 Wave form
  53. Val 00 Constant
  54. Val 20 Square
  55. Val 21 Triangle
  56. Val 22 Sine
  57. Val 23 Sawtooth up
  58. Val 24 Sawtooth down
  59. Val 40 Spring (Force = f(pos))
  60. Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
  61. 02 Axes affected and trigger
  62. Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
  63. Val 4 = X axis only. Byte 05 must contain 5a
  64. Val 8 = Y axis only. Byte 05 must contain b4
  65. Val c = X and Y axes. Bytes 05 must contain 60
  66. Bits 0-3: Val 0 = No trigger
  67. Val x+1 = Button x triggers the effect
  68. When the whole byte is 0, cancel the previously set trigger
  69. 03-04 Duration of effect (little endian encoding, in ms)
  70. 05 Direction of effect, if applicable. Else, see 02 for value to assign.
  71. 06-07 Minimum time between triggering.
  72. 08-09 Address of periodicity or magnitude parameters
  73. 0a-0b Address of attack and fade parameters, or ffff if none.
  74. *or*
  75. 08-09 Address of interactive parameters for X-axis, or ffff if not applicable
  76. 0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
  77. 0c-0d Delay before execution of effect (little endian encoding, in ms)
  78. ** Time based parameters **
  79. *** Attack and fade ***
  80. OP= 02
  81. LEN= 08
  82. 00-01 Address where to store the parameteres
  83. 02-03 Duration of attack (little endian encoding, in ms)
  84. 04 Level at end of attack. Signed byte.
  85. 05-06 Duration of fade.
  86. 07 Level at end of fade.
  87. *** Magnitude ***
  88. OP= 03
  89. LEN= 03
  90. 00-01 Address
  91. 02 Level. Signed byte.
  92. *** Periodicity ***
  93. OP= 04
  94. LEN= 07
  95. 00-01 Address
  96. 02 Magnitude. Signed byte.
  97. 03 Offset. Signed byte.
  98. 04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
  99. 05-06 Period (little endian encoding, in ms)
  100. ** Interactive parameters **
  101. OP= 05
  102. LEN= 0a
  103. 00-01 Address
  104. 02 Positive Coeff
  105. 03 Negative Coeff
  106. 04+05 Offset (center)
  107. 06+07 Dead band (Val 01F4 = 5000 (decimal))
  108. 08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
  109. 09 Negative saturation
  110. The encoding is a bit funny here: For coeffs, these are signed values. The
  111. maximum value is 64 (100 decimal), the min is 9c.
  112. For the offset, the minimum value is FE0C, the maximum value is 01F4.
  113. For the deadband, the minimum value is 0, the max is 03E8.
  114. ** Controls **
  115. OP= 41
  116. LEN= 03
  117. 00 Channel
  118. 01 Start/Stop
  119. Val 00: Stop
  120. Val 01: Start and play once.
  121. Val 41: Start and play n times (See byte 02 below)
  122. 02 Number of iterations n.
  123. ** Init **
  124. *** Querying features ***
  125. OP= ff
  126. Query command. Length varies according to the query type.
  127. The general format of this packet is:
  128. ff 01 QUERY [INDEX] CHECKSUM
  129. reponses are of the same form:
  130. FF LEN QUERY VALUE_QUERIED CHECKSUM2
  131. where LEN = 1 + length(VALUE_QUERIED)
  132. **** Query ram size ****
  133. QUERY = 42 ('B'uffer size)
  134. The device should reply with the same packet plus two additionnal bytes
  135. containing the size of the memory:
  136. ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
  137. **** Query number of effects ****
  138. QUERY = 4e ('N'umber of effects)
  139. The device should respond by sending the number of effects that can be played
  140. at the same time (one byte)
  141. ff 02 4e 14 CS would stand for 20 effects.
  142. **** Vendor's id ****
  143. QUERY = 4d ('M'anufacturer)
  144. Query the vendors'id (2 bytes)
  145. **** Product id *****
  146. QUERY = 50 ('P'roduct)
  147. Query the product id (2 bytes)
  148. **** Open device ****
  149. QUERY = 4f ('O'pen)
  150. No data returned.
  151. **** Close device *****
  152. QUERY = 43 ('C')lose
  153. No data returned.
  154. **** Query effect ****
  155. QUERY = 45 ('E')
  156. Send effect type.
  157. Returns nonzero if supported (2 bytes)
  158. **** Firmware Version ****
  159. QUERY = 56 ('V'ersion)
  160. Sends back 3 bytes - major, minor, subminor
  161. *** Initialisation of the device ***
  162. **** Set Control ****
  163. !!! Device dependent, can be different on different models !!!
  164. OP= 40 <idx> <val> [<val>]
  165. LEN= 2 or 3
  166. 00 Idx
  167. Idx 00 Set dead zone (0..2048)
  168. Idx 01 Ignore Deadman sensor (0..1)
  169. Idx 02 Enable comm watchdog (0..1)
  170. Idx 03 Set the strength of the spring (0..100)
  171. Idx 04 Enable or disable the spring (0/1)
  172. Idx 05 Set axis saturation threshold (0..2048)
  173. **** Set Effect State ****
  174. OP= 42 <val>
  175. LEN= 1
  176. 00 State
  177. Bit 3 Pause force feedback
  178. Bit 2 Enable force feedback
  179. Bit 0 Stop all effects
  180. **** Set overall gain ****
  181. OP= 43 <val>
  182. LEN= 1
  183. 00 Gain
  184. Val 00 = 0%
  185. Val 40 = 50%
  186. Val 80 = 100%
  187. ** Parameter memory **
  188. Each device has a certain amount of memory to store parameters of effects.
  189. The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
  190. is the amount of memory apparently needed for every set of parameters:
  191. - period : 0c
  192. - magnitude : 02
  193. - attack and fade : 0e
  194. - interactive : 08
  195. ** Appendix: How to study the protocol ? **
  196. 1. Generate effects using the force editor provided with the DirectX SDK, or use Immersion Studio (freely available at their web site in the developer section: www.immersion.com)
  197. 2. Start a soft spying RS232 or USB (depending on where you connected your joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
  198. 3. Play the effect, and watch what happens on the spy screen.
  199. A few words about ComPortSpy:
  200. At first glance, this soft seems, hum, well... buggy. In fact, data appear with a few seconds latency. Personnaly, I restart it every time I play an effect.
  201. Remember it's free (as in free beer) and alpha!
  202. ** URLS **
  203. Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
  204. ** Author of this document **
  205. Johann Deneux <deneux@ifrance.com>
  206. Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/
  207. Additions by Vojtech Pavlik.
  208. I-Force is trademark of Immersion Corp.