2
This document describes what I managed to discover about the protocole used to specify force effects to I-Force 2.0 devices.
3
None of this information comes from Immerse. That's why you should not trust what is written in this document. This document is intended to help undertstanding the protocole.
4
This is not a reference. Comments and corrections are welcome. I made all these tests on my Boeder I-Force ForceFeedback Wheel. Please note I haven't made any test on joysticks.
5
To contact me, send email to: deneux@ifrance.com
8
I may not be held responsible for any dammage or harm caused if you try to send data to your I-Force device based on what you read in this document.
11
All values are hexadecimal with big-endian encoding (msb on the left). Beware, values inside packets are encoded using little-endian.
12
Bytes whose roles are unknown are marked ???
13
Information that needs deeper inspection is marked (?)
15
** General form of a packet **
17
CS is the checksum. It is equal to the exclusive or of all bytes.
22
00 Channel (when playing several effects at the same time, each must be assigned a channel)
30
Val 40 Spring (Force = f(pos))
31
Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
34
02 Axes affected and trigger
35
Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
36
Val 4 = X axis only. Byte 05 must contain 5a
37
Val 8 = Y axis only. Byte 05 must contain b4
38
Val c = X and Y axes. Bytes 05 must contain 60
39
Bits 0-3: Val 0 = No trigger
40
Val x+1 = Button x triggers the effect
41
When the whole byte is 0, cancel the previously set trigger
43
03-04 Duration of effect (little endian encoding, in ms)
45
05 Direction of effect, if applicable. Else, see 02 for value to assign.
47
06-07 Minimum time between triggering.
49
08-09 Address of periodicity or magnitude parameters
50
0a-0b Address of attack and fade parameters, or ffff if none.
52
08-09 Address of interactive parameters for X-axis, or ffff if not applicable
53
0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
55
0c-0d Delay before execution of effect (little endian encoding, in ms)
58
** Time based parameters **
60
*** Attack and fade ***
63
00-01 Address where to store the parameteres
64
02-03 Duration of attack (little endian encoding, in ms)
65
04 Level at end of attack. Signed byte.
66
05-06 Duration of fade.
67
07 Level at end of fade.
73
02 Level. Signed byte.
79
02 Magnitude. Signed byte.
80
03 Offset. Signed byte.
81
04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
82
05-06 Period (little endian encoding, in ms)
84
** Interactive parameters **
89
03 Negative Coeff (Val 14 = 2000 (decimal))
90
04 Offset (Val 64 = 2000 (decimal)) | center ?
92
06+07 Dead band (Val 01F4 = 5000 (decimal))
93
08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
94
09 Negative saturation
102
Val 01: Start and play once.
103
Val 41: Start and play n times (See byte 02 below)
104
02 Number of iterations n.
108
*** Querying features ***
110
Query command. Length varies according to the query type.
111
The general format of this packet is:
112
ff 01 QUERY [INDEX] CHECKSUM
113
reponses are of the same form:
114
FF LEN QUERY VALUE_QUERIED CHECKSUM2
115
where LEN = 1 + length(VALUE_QUERIED)
117
**** Query ram size ****
118
QUERY = 42 ('B'uffer size)
119
The device should reply with the same packet plus two additionnal bytes
120
containing the size of the memory:
121
ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
123
**** Query number of effects ****
124
QUERY = 4e ('N'umber of effects)
125
The device should respond by sending the number of effects that can be played
126
at the same time (one byte)
127
ff 02 4e 14 CS would stand for 20 effects.
129
**** Vendor's id ****
130
QUERY = 4d ('M'anufacturer)
131
Query the vendors'id (2 bytes)
133
**** Product id *****
134
QUERY = 50 ('P'roduct)
135
Query the product id (2 bytes)
137
**** Open device ****
141
**** Close device *****
145
**** Query effect ****
148
Returns nonzero if supported (2 bytes)
150
**** Firmware Version ****
151
QUERY = 56 ('V'ersion)
152
Sends back 3 bytes - major, minor, subminor
154
*** Initialisation of the device ***
156
**** Set Control ****
157
!!! Device dependent, can be different on different models !!!
158
OP= 40 <idx> <val> [<val>]
161
Idx 00 Set dead zone (0..2048)
162
Idx 01 Ignore Deadman sensor (0..1)
163
Idx 02 Enable comm watchdog (0..1)
164
Idx 03 Set the strength of the spring (0..100)
165
Idx 04 Enable or disable the spring (0/1)
166
Idx 05 Set axis saturation threshold (0..2048)
168
**** Set Effect State ****
172
Bit 3 Pause force feedback
173
Bit 2 Enable force feedback
174
Bit 0 Stop all effects
176
**** Set overall gain ****
184
** Parameter memory **
186
Each device has a certain amount of memory to store parameters of effects.
187
The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
188
is the amount of memory apparently needed for every set of parameters:
191
- attack and fade : 0e
194
** 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.
200
A few words about ComPortSpy:
201
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.
202
Remember it's free (as in free beer) and alpha!
205
Well, I don't have them at hand (unluckyly, I do not have internet at home).
206
Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
208
** Author of this document **
209
Johann Deneux <deneux@ifrance.com>
210
Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/
212
Additions by Vojtech Pavlik.
214
I-Force is trademark of Immersion Corp.
added
removed
linux/Documentation/input/iforce-protocol.txt
