Input: iforce - convert documentation into ReST format (f8639952) · Commits · e / devices / android_kernel_oneplus_sm8150

Documentation/input/iforce-protocol.txt

+309 −186

Original line number	Original line	Diff line number	Diff line
	** Introduction		===============
			Iforce Protocol
			===============

			:Author: Johann Deneux <johann.deneux@gmail.com>

			Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_

			:Additions: by Vojtech Pavlik.


			Introduction
			============

	This document describes what I managed to discover about the protocol used to		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		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		from Immerse. That's why you should not trust what is written in this
	@@ -6,30 +19,46 @@ document. This document is intended to help understanding the protocol.
	This is not a reference. Comments and corrections are welcome. To contact me,		This is not a reference. Comments and corrections are welcome. To contact me,
	send an email to: johann.deneux@gmail.com		send an email to: johann.deneux@gmail.com

	WARNING		.. warning::

	I shall not be held responsible for any damage or harm caused if you try to		I shall not be held responsible for any damage or harm caused if you try to
	send data to your I-Force device based on what you read in this document.		send data to your I-Force device based on what you read in this document.

	** Preliminary Notes:		Preliminary Notes
			=================

	All values are hexadecimal with big-endian encoding (msb on the left). Beware,		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		values inside packets are encoded using little-endian. Bytes whose roles are
	unknown are marked ??? Information that needs deeper inspection is marked (?)		unknown are marked ??? Information that needs deeper inspection is marked (?)

	General form of a packet		General form of a packet
			------------------------

	This is how packets look when the device uses the rs232 to communicate.		This is how packets look when the device uses the rs232 to communicate.

			== == === ==== ==
	2B OP LEN DATA CS		2B OP LEN DATA CS
			== == === ==== ==

	CS is the checksum. It is equal to the exclusive or of all bytes.		CS is the checksum. It is equal to the exclusive or of all bytes.

	When using USB:		When using USB:

			== ====
	OP DATA		OP DATA
	The 2B, LEN and CS fields have disappeared, probably because USB handles frames and		== ====
	data corruption is handled or unsignificant.
			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		First, I describe effects that are sent by the device to the computer

	** Device input state		Device input state
			==================

	This packet is used to indicate the state of each button and the value of each		This packet is used to indicate the state of each button and the value of each
	axis		axis::

	OP= 01 for a joystick, 03 for a wheel		OP= 01 for a joystick, 03 for a wheel
	LEN= Varies from device to device		LEN= Varies from device to device
	00 X-Axis lsb		00 X-Axis lsb
	@@ -42,7 +71,11 @@ LEN= Varies from device to device
	Upper 4 bits: Hat		Upper 4 bits: Hat
	07 Rudder		07 Rudder

	** Device effects states		Device effects states
			=====================

			::

	OP= 02		OP= 02
	LEN= Varies		LEN= Varies
	00 ? Bit 1 (Value 2) is the value of the deadman switch		00 ? Bit 1 (Value 2) is the value of the deadman switch
	@@ -53,10 +86,15 @@ LEN= Varies
	05 Address of second parameter block changed (lsb)		05 Address of second parameter block changed (lsb)
	... depending on the number of parameter blocks updated		... depending on the number of parameter blocks updated

	Force effect		Force effect
			------------

			::

	OP= 01		OP= 01
	LEN= 0e		LEN= 0e
	00 Channel (when playing several effects at the same time, each must be assigned a channel)		00 Channel (when playing several effects at the same time, each must
			be assigned a channel)
	01 Wave form		01 Wave form
	Val 00 Constant		Val 00 Constant
	Val 20 Square		Val 20 Square
	@@ -65,7 +103,8 @@ LEN= 0e
	Val 23 Sawtooth up		Val 23 Sawtooth up
	Val 24 Sawtooth down		Val 24 Sawtooth down
	Val 40 Spring (Force = f(pos))		Val 40 Spring (Force = f(pos))
	Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))		Val 41 Friction (Force = f(velocity)) and Inertia
			(Force = f(acceleration))


	02 Axes affected and trigger		02 Axes affected and trigger
	@@ -86,15 +125,22 @@ LEN= 0e
	08-09 Address of periodicity or magnitude parameters		08-09 Address of periodicity or magnitude parameters
	0a-0b Address of attack and fade parameters, or ffff if none.		0a-0b Address of attack and fade parameters, or ffff if none.
	or		or
	08-09 Address of interactive parameters for X-axis, or ffff if not applicable		08-09 Address of interactive parameters for X-axis,
	0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable		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)		0c-0d Delay before execution of effect (little endian encoding, in ms)


	Time based parameters		Time based parameters
			---------------------

			Attack and fade
			^^^^^^^^^^^^^^^

			::

	* Attack and fade *
	OP= 02		OP= 02
	LEN= 08		LEN= 08
	00-01 Address where to store the parameters		00-01 Address where to store the parameters
	@@ -103,13 +149,21 @@ LEN= 08
	05-06 Duration of fade.		05-06 Duration of fade.
	07 Level at end of fade.		07 Level at end of fade.

	* Magnitude *		Magnitude
			^^^^^^^^^

			::

	OP= 03		OP= 03
	LEN= 03		LEN= 03
	00-01 Address		00-01 Address
	02 Level. Signed byte.		02 Level. Signed byte.

	* Periodicity *		Periodicity
			^^^^^^^^^^^

			::

	OP= 04		OP= 04
	LEN= 07		LEN= 07
	00-01 Address		00-01 Address
	@@ -118,7 +172,11 @@ LEN= 07
	04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.		04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
	05-06 Period (little endian encoding, in ms)		05-06 Period (little endian encoding, in ms)

	Interactive parameters		Interactive parameters
			----------------------

			::

	OP= 05		OP= 05
	LEN= 0a		LEN= 0a
	00-01 Address		00-01 Address
	@@ -134,7 +192,11 @@ 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 offset, the minimum value is FE0C, the maximum value is 01F4.
	For the deadband, the minimum value is 0, the max is 03E8.		For the deadband, the minimum value is 0, the max is 03E8.

	Controls		Controls
			--------

			::

	OP= 41		OP= 41
	LEN= 03		LEN= 03
	00 Channel		00 Channel
	@@ -144,9 +206,14 @@ LEN= 03
	Val 41: Start and play n times (See byte 02 below)		Val 41: Start and play n times (See byte 02 below)
	02 Number of iterations n.		02 Number of iterations n.

	Init		Init
			----


			Querying features
			^^^^^^^^^^^^^^^^^
			::

	* Querying features *
	OP= ff		OP= ff
	Query command. Length varies according to the query type.		Query command. Length varies according to the query type.
	The general format of this packet is:		The general format of this packet is:
	@@ -155,47 +222,94 @@ responses are of the same form:
	FF LEN QUERY VALUE_QUERIED CHECKSUM2		FF LEN QUERY VALUE_QUERIED CHECKSUM2
	where LEN = 1 + length(VALUE_QUERIED)		where LEN = 1 + length(VALUE_QUERIED)

	** Query ram size **		Query ram size
			~~~~~~~~~~~~~~

			::

	QUERY = 42 ('B'uffer size)		QUERY = 42 ('B'uffer size)

	The device should reply with the same packet plus two additional bytes		The device should reply with the same packet plus two additional bytes
	containing the size of the memory:		containing the size of the memory:
	ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.		ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.

	** Query number of effects **		Query number of effects
			~~~~~~~~~~~~~~~~~~~~~~~

			::

	QUERY = 4e ('N'umber of effects)		QUERY = 4e ('N'umber of effects)

	The device should respond by sending the number of effects that can be played		The device should respond by sending the number of effects that can be played
	at the same time (one byte)		at the same time (one byte)
	ff 02 4e 14 CS would stand for 20 effects.		ff 02 4e 14 CS would stand for 20 effects.

	** Vendor's id **		Vendor's id
			~~~~~~~~~~~

			::

	QUERY = 4d ('M'anufacturer)		QUERY = 4d ('M'anufacturer)

	Query the vendors'id (2 bytes)		Query the vendors'id (2 bytes)

	** Product id ***		Product id
			~~~~~~~~~~

			::

	QUERY = 50 ('P'roduct)		QUERY = 50 ('P'roduct)

	Query the product id (2 bytes)		Query the product id (2 bytes)

	** Open device **		Open device
			~~~~~~~~~~~

			::

	QUERY = 4f ('O'pen)		QUERY = 4f ('O'pen)

	No data returned.		No data returned.

	** Close device ***		Close device
			~~~~~~~~~~~~

			::

	QUERY = 43 ('C')lose		QUERY = 43 ('C')lose

	No data returned.		No data returned.

	** Query effect **		Query effect
			~~~~~~~~~~~~

			::

	QUERY = 45 ('E')		QUERY = 45 ('E')

	Send effect type.		Send effect type.
	Returns nonzero if supported (2 bytes)		Returns nonzero if supported (2 bytes)

	** Firmware Version **		Firmware Version
			~~~~~~~~~~~~~~~~

			::

	QUERY = 56 ('V'ersion)		QUERY = 56 ('V'ersion)

	Sends back 3 bytes - major, minor, subminor		Sends back 3 bytes - major, minor, subminor

	* Initialisation of the device *		Initialisation of the device
			^^^^^^^^^^^^^^^^^^^^^^^^^^^^

			Set Control
			~~~~~~~~~~~

			.. note::
			Device dependent, can be different on different models!

			::

	** Set Control **
	!!! Device dependent, can be different on different models !!!
	OP= 40 <idx> <val> [<val>]		OP= 40 <idx> <val> [<val>]
	LEN= 2 or 3		LEN= 2 or 3
	00 Idx		00 Idx
	@@ -206,7 +320,11 @@ LEN= 2 or 3
	Idx 04 Enable or disable the spring (0/1)		Idx 04 Enable or disable the spring (0/1)
	Idx 05 Set axis saturation threshold (0..2048)		Idx 05 Set axis saturation threshold (0..2048)

	** Set Effect State **		Set Effect State
			~~~~~~~~~~~~~~~~

			::

	OP= 42 <val>		OP= 42 <val>
	LEN= 1		LEN= 1
	00 State		00 State
	@@ -214,7 +332,11 @@ LEN= 1
	Bit 2 Enable force feedback		Bit 2 Enable force feedback
	Bit 0 Stop all effects		Bit 0 Stop all effects

	** Set overall gain **		Set overall
			~~~~~~~~~~~

			::

	OP= 43 <val>		OP= 43 <val>
	LEN= 1		LEN= 1
	00 Gain		00 Gain
	@@ -222,17 +344,20 @@ LEN= 1
	Val 40 = 50%		Val 40 = 50%
	Val 80 = 100%		Val 80 = 100%

	Parameter memory		Parameter memory
			----------------

	Each device has a certain amount of memory to store parameters of effects.		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		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:		is the amount of memory apparently needed for every set of parameters:

	- period : 0c		- period : 0c
	- magnitude : 02		- magnitude : 02
	- attack and fade : 0e		- attack and fade : 0e
	- interactive : 08		- interactive : 08

	Appendix: How to study the protocol ?		Appendix: How to study the protocol?
			====================================

	1. Generate effects using the force editor provided with the DirectX SDK, or		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:		use Immersion Studio (freely available at their web site in the developer section:
	@@ -246,13 +371,11 @@ At first glance, this software seems, hum, well... buggy. In fact, data appear w
	few seconds latency. Personally, I restart it every time I play an effect.		few seconds latency. Personally, I restart it every time I play an effect.
	Remember it's free (as in free beer) and alpha!		Remember it's free (as in free beer) and alpha!

	URLS		URLS
	Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.		====

	Author of this document		Check http://www.immerse.com for Immersion Studio,
	Johann Deneux <johann.deneux@gmail.com>		and http://www.fcoder.com for ComPortSpy.
	Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr

	Additions by Vojtech Pavlik.

	I-Force is trademark of Immersion Corp.		I-Force is trademark of Immersion Corp.