About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / input / iforce-protocol.txt


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

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: johann.deneux@gmail.com
8	
9	** WARNING **
10	I shall not be held responsible for any damage 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 parameters
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	responses 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 additional 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 
238	use Immersion Studio (freely available at their web site in the developer section: 
239	www.immersion.com)
240	2. Start a soft spying RS232 or USB (depending on where you connected your 
241	joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
242	3. Play the effect, and watch what happens on the spy screen.
243	
244	A few words about ComPortSpy:
245	At first glance, this software seems, hum, well... buggy. In fact, data appear with a
246	few seconds latency. Personally, I restart it every time I play an effect.
247	Remember it's free (as in free beer) and alpha!
248	
249	** URLS **
250	Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
251	
252	** Author of this document **
253	Johann Deneux <johann.deneux@gmail.com>
254	Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr
255	
256	Additions by Vojtech Pavlik.
257	
258	I-Force is trademark of Immersion Corp.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog