aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/input
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@woody.linux-foundation.org>2007-09-20 14:33:45 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-09-20 14:33:45 -0400
commit6d0b842d3bf0cc027dcff57a89fb8a6b1fd610e1 (patch)
treebd1842f2f3a77330c399860d6c5c25f2d6197bf9 /Documentation/input
parentbbc15f46fe4dc2862325e2b4ba474a854162e1a1 (diff)
Fix CRLF line endings in Documentation/input/iforce-protocol.txt
Emil Medve points out that this documentation file uses CRLF line endings, which means that if you use [core] autocrlf=input (which makes sense if you ever develop under Windows, for example, or if you use other broken tools) in your git config, git will always complain about the file being dirty. This removes the bogus DOS line endings, and removes whitespace at the end of line. Cc: Emil Medve <Emilian.Medve@Freescale.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/input')
-rw-r--r--Documentation/input/iforce-protocol.txt508
1 files changed, 254 insertions, 254 deletions
diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt
index 95df4ca70e71..8777d2d321e3 100644
--- a/Documentation/input/iforce-protocol.txt
+++ b/Documentation/input/iforce-protocol.txt
@@ -1,254 +1,254 @@
1** Introduction 1** Introduction
2This document describes what I managed to discover about the protocol used to 2This document describes what I managed to discover about the protocol used to
3specify force effects to I-Force 2.0 devices. None of this information comes 3specify force effects to I-Force 2.0 devices. None of this information comes
4from Immerse. That's why you should not trust what is written in this 4from Immerse. That's why you should not trust what is written in this
5document. This document is intended to help understanding the protocol. 5document. This document is intended to help understanding the protocol.
6This is not a reference. Comments and corrections are welcome. To contact me, 6This is not a reference. Comments and corrections are welcome. To contact me,
7send an email to: deneux@ifrance.com 7send an email to: deneux@ifrance.com
8 8
9** WARNING ** 9** WARNING **
10I may not be held responsible for any dammage or harm caused if you try to 10I may not be held responsible for any dammage or harm caused if you try to
11send data to your I-Force device based on what you read in this document. 11send data to your I-Force device based on what you read in this document.
12 12
13** Preliminary Notes: 13** Preliminary Notes:
14All values are hexadecimal with big-endian encoding (msb on the left). Beware, 14All values are hexadecimal with big-endian encoding (msb on the left). Beware,
15values inside packets are encoded using little-endian. Bytes whose roles are 15values inside packets are encoded using little-endian. Bytes whose roles are
16unknown are marked ??? Information that needs deeper inspection is marked (?) 16unknown are marked ??? Information that needs deeper inspection is marked (?)
17 17
18** General form of a packet ** 18** General form of a packet **
19This is how packets look when the device uses the rs232 to communicate. 19This is how packets look when the device uses the rs232 to communicate.
202B OP LEN DATA CS 202B OP LEN DATA CS
21CS is the checksum. It is equal to the exclusive or of all bytes. 21CS is the checksum. It is equal to the exclusive or of all bytes.
22 22
23When using USB: 23When using USB:
24OP DATA 24OP DATA
25The 2B, LEN and CS fields have disappeared, probably because USB handles frames and 25The 2B, LEN and CS fields have disappeared, probably because USB handles frames and
26data corruption is handled or unsignificant. 26data corruption is handled or unsignificant.
27 27
28First, I describe effects that are sent by the device to the computer 28First, I describe effects that are sent by the device to the computer
29 29
30** Device input state 30** Device input state
31This packet is used to indicate the state of each button and the value of each 31This packet is used to indicate the state of each button and the value of each
32axis 32axis
33OP= 01 for a joystick, 03 for a wheel 33OP= 01 for a joystick, 03 for a wheel
34LEN= Varies from device to device 34LEN= Varies from device to device
3500 X-Axis lsb 3500 X-Axis lsb
3601 X-Axis msb 3601 X-Axis msb
3702 Y-Axis lsb, or gas pedal for a wheel 3702 Y-Axis lsb, or gas pedal for a wheel
3803 Y-Axis msb, or brake pedal for a wheel 3803 Y-Axis msb, or brake pedal for a wheel
3904 Throttle 3904 Throttle
4005 Buttons 4005 Buttons
4106 Lower 4 bits: Buttons 4106 Lower 4 bits: Buttons
42 Upper 4 bits: Hat 42 Upper 4 bits: Hat
4307 Rudder 4307 Rudder
44 44
45** Device effects states 45** Device effects states
46OP= 02 46OP= 02
47LEN= Varies 47LEN= Varies
4800 ? Bit 1 (Value 2) is the value of the deadman switch 4800 ? Bit 1 (Value 2) is the value of the deadman switch
4901 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id. 4901 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
5002 ?? 5002 ??
5103 Address of parameter block changed (lsb) 5103 Address of parameter block changed (lsb)
5204 Address of parameter block changed (msb) 5204 Address of parameter block changed (msb)
5305 Address of second parameter block changed (lsb) 5305 Address of second parameter block changed (lsb)
54... depending on the number of parameter blocks updated 54... depending on the number of parameter blocks updated
55 55
56** Force effect ** 56** Force effect **
57OP= 01 57OP= 01
58LEN= 0e 58LEN= 0e
5900 Channel (when playing several effects at the same time, each must be assigned a channel) 5900 Channel (when playing several effects at the same time, each must be assigned a channel)
6001 Wave form 6001 Wave form
61 Val 00 Constant 61 Val 00 Constant
62 Val 20 Square 62 Val 20 Square
63 Val 21 Triangle 63 Val 21 Triangle
64 Val 22 Sine 64 Val 22 Sine
65 Val 23 Sawtooth up 65 Val 23 Sawtooth up
66 Val 24 Sawtooth down 66 Val 24 Sawtooth down
67 Val 40 Spring (Force = f(pos)) 67 Val 40 Spring (Force = f(pos))
68 Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration)) 68 Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
69 69
70 70
7102 Axes affected and trigger 7102 Axes affected and trigger
72 Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction 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 73 Val 4 = X axis only. Byte 05 must contain 5a
74 Val 8 = Y axis only. Byte 05 must contain b4 74 Val 8 = Y axis only. Byte 05 must contain b4
75 Val c = X and Y axes. Bytes 05 must contain 60 75 Val c = X and Y axes. Bytes 05 must contain 60
76 Bits 0-3: Val 0 = No trigger 76 Bits 0-3: Val 0 = No trigger
77 Val x+1 = Button x triggers the effect 77 Val x+1 = Button x triggers the effect
78 When the whole byte is 0, cancel the previously set trigger 78 When the whole byte is 0, cancel the previously set trigger
79 79
8003-04 Duration of effect (little endian encoding, in ms) 8003-04 Duration of effect (little endian encoding, in ms)
81 81
8205 Direction of effect, if applicable. Else, see 02 for value to assign. 8205 Direction of effect, if applicable. Else, see 02 for value to assign.
83 83
8406-07 Minimum time between triggering. 8406-07 Minimum time between triggering.
85 85
8608-09 Address of periodicity or magnitude parameters 8608-09 Address of periodicity or magnitude parameters
870a-0b Address of attack and fade parameters, or ffff if none. 870a-0b Address of attack and fade parameters, or ffff if none.
88*or* 88*or*
8908-09 Address of interactive parameters for X-axis, or ffff if not applicable 8908-09 Address of interactive parameters for X-axis, or ffff if not applicable
900a-0b Address of interactive parameters for Y-axis, or ffff if not applicable 900a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
91 91
920c-0d Delay before execution of effect (little endian encoding, in ms) 920c-0d Delay before execution of effect (little endian encoding, in ms)
93 93
94 94
95** Time based parameters ** 95** Time based parameters **
96 96
97*** Attack and fade *** 97*** Attack and fade ***
98OP= 02 98OP= 02
99LEN= 08 99LEN= 08
10000-01 Address where to store the parameteres 10000-01 Address where to store the parameteres
10102-03 Duration of attack (little endian encoding, in ms) 10102-03 Duration of attack (little endian encoding, in ms)
10204 Level at end of attack. Signed byte. 10204 Level at end of attack. Signed byte.
10305-06 Duration of fade. 10305-06 Duration of fade.
10407 Level at end of fade. 10407 Level at end of fade.
105 105
106*** Magnitude *** 106*** Magnitude ***
107OP= 03 107OP= 03
108LEN= 03 108LEN= 03
10900-01 Address 10900-01 Address
11002 Level. Signed byte. 11002 Level. Signed byte.
111 111
112*** Periodicity *** 112*** Periodicity ***
113OP= 04 113OP= 04
114LEN= 07 114LEN= 07
11500-01 Address 11500-01 Address
11602 Magnitude. Signed byte. 11602 Magnitude. Signed byte.
11703 Offset. Signed byte. 11703 Offset. Signed byte.
11804 Phase. Val 00 = 0 deg, Val 40 = 90 degs. 11804 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
11905-06 Period (little endian encoding, in ms) 11905-06 Period (little endian encoding, in ms)
120 120
121** Interactive parameters ** 121** Interactive parameters **
122OP= 05 122OP= 05
123LEN= 0a 123LEN= 0a
12400-01 Address 12400-01 Address
12502 Positive Coeff 12502 Positive Coeff
12603 Negative Coeff 12603 Negative Coeff
12704+05 Offset (center) 12704+05 Offset (center)
12806+07 Dead band (Val 01F4 = 5000 (decimal)) 12806+07 Dead band (Val 01F4 = 5000 (decimal))
12908 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal)) 12908 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
13009 Negative saturation 13009 Negative saturation
131 131
132The encoding is a bit funny here: For coeffs, these are signed values. The 132The encoding is a bit funny here: For coeffs, these are signed values. The
133maximum value is 64 (100 decimal), the min is 9c. 133maximum value is 64 (100 decimal), the min is 9c.
134For the offset, the minimum value is FE0C, the maximum value is 01F4. 134For the offset, the minimum value is FE0C, the maximum value is 01F4.
135For the deadband, the minimum value is 0, the max is 03E8. 135For the deadband, the minimum value is 0, the max is 03E8.
136 136
137** Controls ** 137** Controls **
138OP= 41 138OP= 41
139LEN= 03 139LEN= 03
14000 Channel 14000 Channel
14101 Start/Stop 14101 Start/Stop
142 Val 00: Stop 142 Val 00: Stop
143 Val 01: Start and play once. 143 Val 01: Start and play once.
144 Val 41: Start and play n times (See byte 02 below) 144 Val 41: Start and play n times (See byte 02 below)
14502 Number of iterations n. 14502 Number of iterations n.
146 146
147** Init ** 147** Init **
148 148
149*** Querying features *** 149*** Querying features ***
150OP= ff 150OP= ff
151Query command. Length varies according to the query type. 151Query command. Length varies according to the query type.
152The general format of this packet is: 152The general format of this packet is:
153ff 01 QUERY [INDEX] CHECKSUM 153ff 01 QUERY [INDEX] CHECKSUM
154reponses are of the same form: 154reponses are of the same form:
155FF LEN QUERY VALUE_QUERIED CHECKSUM2 155FF LEN QUERY VALUE_QUERIED CHECKSUM2
156where LEN = 1 + length(VALUE_QUERIED) 156where LEN = 1 + length(VALUE_QUERIED)
157 157
158**** Query ram size **** 158**** Query ram size ****
159QUERY = 42 ('B'uffer size) 159QUERY = 42 ('B'uffer size)
160The device should reply with the same packet plus two additionnal bytes 160The device should reply with the same packet plus two additionnal bytes
161containing the size of the memory: 161containing the size of the memory:
162ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available. 162ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
163 163
164**** Query number of effects **** 164**** Query number of effects ****
165QUERY = 4e ('N'umber of effects) 165QUERY = 4e ('N'umber of effects)
166The device should respond by sending the number of effects that can be played 166The device should respond by sending the number of effects that can be played
167at the same time (one byte) 167at the same time (one byte)
168ff 02 4e 14 CS would stand for 20 effects. 168ff 02 4e 14 CS would stand for 20 effects.
169 169
170**** Vendor's id **** 170**** Vendor's id ****
171QUERY = 4d ('M'anufacturer) 171QUERY = 4d ('M'anufacturer)
172Query the vendors'id (2 bytes) 172Query the vendors'id (2 bytes)
173 173
174**** Product id ***** 174**** Product id *****
175QUERY = 50 ('P'roduct) 175QUERY = 50 ('P'roduct)
176Query the product id (2 bytes) 176Query the product id (2 bytes)
177 177
178**** Open device **** 178**** Open device ****
179QUERY = 4f ('O'pen) 179QUERY = 4f ('O'pen)
180No data returned. 180No data returned.
181 181
182**** Close device ***** 182**** Close device *****
183QUERY = 43 ('C')lose 183QUERY = 43 ('C')lose
184No data returned. 184No data returned.
185 185
186**** Query effect **** 186**** Query effect ****
187QUERY = 45 ('E') 187QUERY = 45 ('E')
188Send effect type. 188Send effect type.
189Returns nonzero if supported (2 bytes) 189Returns nonzero if supported (2 bytes)
190 190
191**** Firmware Version **** 191**** Firmware Version ****
192QUERY = 56 ('V'ersion) 192QUERY = 56 ('V'ersion)
193Sends back 3 bytes - major, minor, subminor 193Sends back 3 bytes - major, minor, subminor
194 194
195*** Initialisation of the device *** 195*** Initialisation of the device ***
196 196
197**** Set Control **** 197**** Set Control ****
198!!! Device dependent, can be different on different models !!! 198!!! Device dependent, can be different on different models !!!
199OP= 40 <idx> <val> [<val>] 199OP= 40 <idx> <val> [<val>]
200LEN= 2 or 3 200LEN= 2 or 3
20100 Idx 20100 Idx
202 Idx 00 Set dead zone (0..2048) 202 Idx 00 Set dead zone (0..2048)
203 Idx 01 Ignore Deadman sensor (0..1) 203 Idx 01 Ignore Deadman sensor (0..1)
204 Idx 02 Enable comm watchdog (0..1) 204 Idx 02 Enable comm watchdog (0..1)
205 Idx 03 Set the strength of the spring (0..100) 205 Idx 03 Set the strength of the spring (0..100)
206 Idx 04 Enable or disable the spring (0/1) 206 Idx 04 Enable or disable the spring (0/1)
207 Idx 05 Set axis saturation threshold (0..2048) 207 Idx 05 Set axis saturation threshold (0..2048)
208 208
209**** Set Effect State **** 209**** Set Effect State ****
210OP= 42 <val> 210OP= 42 <val>
211LEN= 1 211LEN= 1
21200 State 21200 State
213 Bit 3 Pause force feedback 213 Bit 3 Pause force feedback
214 Bit 2 Enable force feedback 214 Bit 2 Enable force feedback
215 Bit 0 Stop all effects 215 Bit 0 Stop all effects
216 216
217**** Set overall gain **** 217**** Set overall gain ****
218OP= 43 <val> 218OP= 43 <val>
219LEN= 1 219LEN= 1
22000 Gain 22000 Gain
221 Val 00 = 0% 221 Val 00 = 0%
222 Val 40 = 50% 222 Val 40 = 50%
223 Val 80 = 100% 223 Val 80 = 100%
224 224
225** Parameter memory ** 225** Parameter memory **
226 226
227Each device has a certain amount of memory to store parameters of effects. 227Each device has a certain amount of memory to store parameters of effects.
228The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below 228The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
229is the amount of memory apparently needed for every set of parameters: 229is the amount of memory apparently needed for every set of parameters:
230 - period : 0c 230 - period : 0c
231 - magnitude : 02 231 - magnitude : 02
232 - attack and fade : 0e 232 - attack and fade : 0e
233 - interactive : 08 233 - interactive : 08
234 234
235** Appendix: How to study the protocol ? ** 235** Appendix: How to study the protocol ? **
236 236
2371. 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) 2371. 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)
2382. Start a soft spying RS232 or USB (depending on where you connected your joystick/wheel). I used ComPortSpy from fCoder (alpha version!) 2382. Start a soft spying RS232 or USB (depending on where you connected your joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
2393. Play the effect, and watch what happens on the spy screen. 2393. Play the effect, and watch what happens on the spy screen.
240 240
241A few words about ComPortSpy: 241A few words about ComPortSpy:
242At 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. 242At 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.
243Remember it's free (as in free beer) and alpha! 243Remember it's free (as in free beer) and alpha!
244 244
245** URLS ** 245** URLS **
246Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy. 246Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
247 247
248** Author of this document ** 248** Author of this document **
249Johann Deneux <deneux@ifrance.com> 249Johann Deneux <deneux@ifrance.com>
250Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/ 250Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/
251 251
252Additions by Vojtech Pavlik. 252Additions by Vojtech Pavlik.
253 253
254I-Force is trademark of Immersion Corp. 254I-Force is trademark of Immersion Corp.