1 files changed, 254 insertions, 0 deletions
diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt
new file mode 100644
index 000000000000..95df4ca70e71
--- /dev/null
+++ b/Documentation/input/iforce-protocol.txt
@@ -0,0 +1,254 @@
+** Introduction
+This document describes what I managed to discover about the protocol used to
+specify force effects to I-Force 2.0 devices.  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 understanding the protocol.
+This is not a reference. Comments and corrections are welcome.  To contact me,
+send an email to: deneux@ifrance.com
+** WARNING **
+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.
+** Preliminary Notes:
+All values are hexadecimal with big-endian encoding (msb on the left). Beware,
+values inside packets are encoded using little-endian.  Bytes whose roles are
+unknown are marked ???  Information that needs deeper inspection is marked (?)
+** General form of a packet **
+This is how packets look when the device uses the rs232 to communicate.
+2B OP LEN DATA CS
+CS is the checksum. It is equal to the exclusive or of all bytes.
+When using USB:
+OP DATA
+The 2B, LEN and CS fields have disappeared, probably because USB handles frames and
+data corruption is handled or unsignificant.
+First, I describe effects that are sent by the device to the computer
+** Device input state
+This packet is used to indicate the state of each button and the value of each
+axis
+OP= 01 for a joystick, 03 for a wheel
+LEN= Varies from device to device
+00 X-Axis lsb
+01 X-Axis msb
+02 Y-Axis lsb, or gas pedal for a wheel
+03 Y-Axis msb, or brake pedal for a wheel
+04 Throttle
+05 Buttons
+06 Lower 4 bits: Buttons
+   Upper 4 bits: Hat
+07 Rudder
+** Device effects states
+OP= 02
+LEN= Varies
+00 ? Bit 1 (Value 2) is the value of the deadman switch
+01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
+02 ??
+03 Address of parameter block changed (lsb)
+04 Address of parameter block changed (msb)
+05 Address of second parameter block changed (lsb)
+... depending on the number of parameter blocks updated
+** Force effect **
+OP=  01
+LEN= 0e
+00 Channel (when playing several effects at the same time, each must be assigned a channel)
+01 Wave form
+        Val 00 Constant
+        Val 20 Square
+        Val 21 Triangle
+        Val 22 Sine
+        Val 23 Sawtooth up
+        Val 24 Sawtooth down
+        Val 40 Spring (Force = f(pos))
+        Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
+        
+02 Axes affected and trigger
+        Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
+                  Val 4 = X axis only. Byte 05 must contain 5a
+                  Val 8 = Y axis only. Byte 05 must contain b4
+                  Val c = X and Y axes. Bytes 05 must contain 60
+        Bits 0-3: Val 0 = No trigger
+                  Val x+1 = Button x triggers the effect
+        When the whole byte is 0, cancel the previously set trigger
+03-04 Duration of effect (little endian encoding, in ms)
+05 Direction of effect, if applicable. Else, see 02 for value to assign.
+06-07 Minimum time between triggering.
+08-09 Address of periodicity or magnitude parameters
+0a-0b Address of attack and fade parameters, or ffff if none.
+*or*
+08-09 Address of interactive parameters for X-axis, or ffff if not applicable
+0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
+0c-0d Delay before execution of effect (little endian encoding, in ms)
+** Time based parameters **
+*** Attack and fade ***
+OP=  02
+LEN= 08
+00-01 Address where to store the parameteres
+02-03 Duration of attack (little endian encoding, in ms)
+04 Level at end of attack. Signed byte.
+05-06 Duration of fade.
+07 Level at end of fade.
+*** Magnitude ***
+OP=  03
+LEN= 03
+00-01 Address
+02 Level. Signed byte.
+*** Periodicity ***
+OP=  04
+LEN= 07
+00-01 Address
+02 Magnitude. Signed byte.
+03 Offset. Signed byte.
+04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
+05-06 Period (little endian encoding, in ms)
+** Interactive parameters **
+OP=  05
+LEN= 0a
+00-01 Address
+02 Positive Coeff
+03 Negative Coeff
+04+05 Offset (center)
+06+07 Dead band (Val 01F4 = 5000 (decimal))
+08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
+09 Negative saturation
+The encoding is a bit funny here: For coeffs, these are signed values. The
+maximum value is 64 (100 decimal), the min is 9c.
+For the offset, the minimum value is FE0C, the maximum value is 01F4.
+For the deadband, the minimum value is 0, the max is 03E8.
+** Controls **
+OP=  41
+LEN= 03
+00 Channel
+01 Start/Stop
+        Val 00: Stop
+        Val 01: Start and play once.
+        Val 41: Start and play n times (See byte 02 below)
+02 Number of iterations n.
+** Init **
+*** Querying features ***
+OP=  ff
+Query command. Length varies according to the query type.
+The general format of this packet is:
+ff 01 QUERY [INDEX] CHECKSUM
+reponses are of the same form:
+FF LEN QUERY VALUE_QUERIED CHECKSUM2
+where LEN = 1 + length(VALUE_QUERIED)
+**** Query ram size ****
+QUERY = 42 ('B'uffer size)
+The device should reply with the same packet plus two additionnal bytes
+containing the size of the memory:
+ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
+**** Query number of effects ****
+QUERY = 4e ('N'umber of effects)
+The device should respond by sending the number of effects that can be played
+at the same time (one byte)
+ff 02 4e 14 CS would stand for 20 effects.
+**** Vendor's id ****
+QUERY = 4d ('M'anufacturer)
+Query the vendors'id (2 bytes)
+**** Product id *****
+QUERY = 50 ('P'roduct)
+Query the product id (2 bytes)
+**** Open device ****
+QUERY = 4f ('O'pen) 
+No data returned.
+**** Close device *****
+QUERY = 43 ('C')lose
+No data returned.
+**** Query effect ****
+QUERY = 45 ('E') 
+Send effect type.
+Returns nonzero if supported (2 bytes)
+**** Firmware Version ****
+QUERY = 56 ('V'ersion)
+Sends back 3 bytes - major, minor, subminor
+*** Initialisation of the device ***
+**** Set Control ****
+!!! Device dependent, can be different on different models !!!
+OP=  40 <idx> <val> [<val>]
+LEN= 2 or 3
+00 Idx
+   Idx 00 Set dead zone (0..2048) 
+   Idx 01 Ignore Deadman sensor (0..1)     
+   Idx 02 Enable comm watchdog (0..1)     
+   Idx 03 Set the strength of the spring (0..100)   
+   Idx 04 Enable or disable the spring (0/1)
+   Idx 05 Set axis saturation threshold (0..2048) 
+**** Set Effect State ****
+OP=  42 <val>
+LEN= 1
+00 State
+   Bit 3 Pause force feedback
+   Bit 2 Enable force feedback
+   Bit 0 Stop all effects
+**** Set overall gain ****
+OP=  43 <val>
+LEN= 1
+00 Gain
+   Val 00 = 0%
+   Val 40 = 50%
+   Val 80 = 100%
+** Parameter memory **
+Each device has a certain amount of memory to store parameters of effects.
+The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
+is the amount of memory apparently needed for every set of parameters:
+ - period : 0c
+ - magnitude : 02
+ - attack and fade : 0e
+ - interactive : 08
+** Appendix: How to study the protocol ? **
+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)
+2. Start a soft spying RS232 or USB (depending on where you connected your joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
+3. Play the effect, and watch what happens on the spy screen.
+A few words about ComPortSpy:
+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.
+Remember it's free (as in free beer) and alpha!
+** URLS **
+Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
+** Author of this document **
+Johann Deneux <deneux@ifrance.com>
+Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/
+Additions by Vojtech Pavlik.
+I-Force is trademark of Immersion Corp.

diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt new file mode 100644 index 000000000000..95df4ca70e71 --- /dev/null +++ b/Documentation/input/iforce-protocol.txt
@@ -0,0 +1,254 @@
	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: deneux@ifrance.com
	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
	249	Johann Deneux <deneux@ifrance.com>
	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.