Commit | Line | Data |
---|---|---|
6d0b842d LT |
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, | |
118e78d1 | 7 | send an email to: johann.deneux@gmail.com |
6d0b842d LT |
8 | |
9 | ** WARNING ** | |
10 | I may not be held responsible for any dammage 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 | reponses 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 additionnal 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 use Immersion Studio (freely available at their web site in the developer section: www.immersion.com) | |
238 | 2. Start a soft spying RS232 or USB (depending on where you connected your joystick/wheel). I used ComPortSpy from fCoder (alpha version!) | |
239 | 3. Play the effect, and watch what happens on the spy screen. | |
240 | ||
241 | A few words about ComPortSpy: | |
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. | |
243 | Remember it's free (as in free beer) and alpha! | |
244 | ||
245 | ** URLS ** | |
246 | Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy. | |
247 | ||
248 | ** Author of this document ** | |
118e78d1 | 249 | Johann Deneux <johann.deneux@gmail.com> |
6d0b842d LT |
250 | Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/ |
251 | ||
252 | Additions by Vojtech Pavlik. | |
253 | ||
254 | I-Force is trademark of Immersion Corp. |