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