File	Date	Author	Commit
app-patches	2007-04-08	James Simmons	[b5561f] cleanup our tree
docs	2019-10-05	Stephen Kitt	[cb22fb] Update the inputattach documentation
ruby-2.6	2007-04-09	James Simmons	[1334e4] no longer needed
utils	2020-02-22	Tillmann Karras	[33ce9c] inputattach: add Gunze protocol
web	2007-04-08	James Simmons	[b5561f] cleanup our tree
xfree86	2007-04-08	James Simmons	[b5561f] cleanup our tree
COPYING	2011-03-30	Stephen Kitt	[1c2943] Add licenses and documentation.
COPYING-1	2011-03-30	Stephen Kitt	[1c2943] Add licenses and documentation.
Makefile	2019-10-06	Stephen Kitt	[c4c80f] Release 1.7.0
NEWS	2019-10-06	Stephen Kitt	[c4c80f] Release 1.7.0
README	2019-10-06	Stephen Kitt	[c4c80f] Release 1.7.0

Read Me

			  linuxconsole tools
			    Release 1.7.0
		 http://sf.net/projects/linuxconsole/


This package contains the following utilities and associated
documentation:
* inputattach - connects legacy serial devices to the input layer
* joystick utilities - calibrate and test joysticks and joypads

The evtest tool, which used to be part of this package, is now
maintained separately at http://cgit.freedesktop.org/evtest/ and
https://bugzilla.freedesktop.org/enter_bug.cgi?product=evtest


Joystick utilities
------------------

The following utilities are provided to calibrate and test joysticks:
* evdev-joystick - calibrate joystick devices (including dead zones
  and fuzz)
* ffcfstress, ffmvforce, fftest - test force-feedback devices
* ffset - set force-feedback device parameters
* jscal - calibrate joystick devices, reconfigure the axes and buttons
* jscal-store, jscal-restore - store and retrieve joystick device
  settings as configured using jscal
* jstest - test joystick devices

The typical scenario when configuring a new device is as follows:
1. Check the basic functions using jstest (number of buttons, axes,
   etc.).
2. Calibrate the joystick using jscal (this can be useful even if the
   device functions correctly, if only to configure the dead-zone at
   the centre).
3. Repeat steps 1 and 2 until the joystick is configured to the user's
   satisfaction.
4. Store the device's setup using jscal-store.


Installation
------------

Most of the utilities have no particular requirement beyond a libc and
the Linux input layer headers (normally part of your libc
installation). ffmvforce requires SDL (libsdl1.2-dev on Debian
derivatives).

To install the utilities and their manpages, run
	make
or
	make SYSTEMD_SUPPORT=1
and then as root
	make install
from the distribution's top directory. This will install everything
into /usr/local. Should you wish to install the tools elsewhere, you
can use the PREFIX variable:
	PREFIX=/usr make install
The Makefiles also recognise the DESTDIR variable which can be used to
install into a temporary directory (this is useful mainly for
distribution packagers).


Auto-loading inputattach and jscal-restore
------------------------------------------

udev can be used to start inputattach and jscal-restore when the
appropriate device is connected to the system (or detected when the
system is booting up).

The following rule restores the stored calibration and axis/button
mappings whenever a joystick device is connected:
	KERNEL=="js*", ACTION=="add", RUN+="/usr/bin/jscal-restore %E{DEVNAME}"
(change the path as appropriate). This rule needs /usr to be
available, which can cause issues on systems where udev is run from
the initramfs or where /usr is a separate partition. To work around
this, the Debian package uses a script provided by Debian's udev
package to wait for jscal-restore to become available. Should you wish
to reproduce this, you need to create a udev agent
(/lib/udev/jscal-restore) containing the following:

#!/bin/sh -e
# udev agent for jscal-restore

wait_for_file() {
	local file=$1
	local count=120
	while [ $count != 0 ]; do
		[ -e "$file" ] && return 0
		sleep 1
		count=$(($count - 1))
	done
	exit 1
}

(
	wait_for_file /usr/bin/jscal-restore
	exec /usr/bin/jscal-restore $1
) &

and change the udev rule to
	KERNEL=="js*", ACTION=="add", RUN+="/lib/udev/jscal-restore %E{DEVNAME}"

The following rule forces flaky Acrux gamepads to stay awake:
	KERNEL=="js*", ACTION=="add", ATTRS{name}=="ACRUX USB GAMEPAD 8116", RUN+="/bin/sleep 5000 < /dev/%k"
(This should only be necessary on kernels older than 2.6.39-rc1.)

The following rule configures a Mouse Systems mouse on the first
serial port:
	KERNEL=="ttyS0", ACTION=="add", RUN+="/usr/bin/inputattach --daemon -msc /dev/%k"
If you need to wait for /usr you can adapt the recipe above.

The following rules configures a Wacom W8001 devices on a Fujitsu
T2010[2] or on Lenovo X200-series laptops and tablets:
	SUBSYSTEM=="tty", KERNEL=="ttyS[0-9]*", ATTRS{id}=="FUJ02e5", ACTION=="add|change", RUN+="/usr/bin/inputattach --daemon --baud 19200 --w8001 /dev/%k"
	SUBSYSTEM=="tty", KERNEL=="ttyS[0-9]*", ATTRS{id}=="WACf00c", ACTION=="add|change", RUN+="/usr/bin/inputattach --daemon --baud 38400 --w8001 /dev/%k"

These rules are liable to cause conflicts with the X.org wacom
driver. For example, on some Debian-based systems the
/usr/share/X11/xorg.conf.d/50-wacom.conf configuration file needs to
be amended so that the "MatchProduct" line matching one of the
identifiers used above ("FUJ02e5" or "WACf00c", the latter being
matched by "WACf") no longer contains the matching identifier. The
appropriate X.org driver when using inputattach in this way is evdev.

A udev rule, especially shipped in a custom OS package is not
always applicable because it cannot handle the conflict presented
by the fact that not all computers are built the same and on one
computer, e.g ttyS1 can be attached to a specific touchscreen,
in another computer it can be attached to a different kind of
touchscreen or a different device or connected at all.
For this case, a wrapper script started from sysvinit, upstart, or
systemd is better suited. systemd needs special treatment inside
inputattach: a notification must be sent to it when inputattach
becomes "ready". To achieve this, the previously mentioned
"make SYSTEMD_SUPPORT=1" must be used to include this support.
Then a systemd unit file and the wrapper script can be added, similar
to the following:

----8<---- inputattach-wrapper.sh ----8<----
#!/bin/sh

SYSTEM=`detect_computer_type`
case $SYSTEM in
type1)
    inputattach --daemon -pm9k /dev/ttyS2
    ;;
type2)
    inputattach --daemon -mtouch /dev/ttyS2
    ;;
# and so on
*)
    # do nothing for other computers
    ;;
esac

# Exit without errors, so systemd won't try to
# restart our script for the "do nothing" case.
exit 0
----8<- end of inputattach-wrapper.sh-8<----

----8<---- inputattach.service    ----8<----
[Unit]
Description=inputattach helper service

[Service]
Type=forking
NotifyAccess=all
ExecStart=/usr/sbin/inputattach-wrapper.sh

[Install]
WantedBy=multi-user.target
----8<- end of inputattach.service----8<----

Configuring PS3 controller LEDs
-------------------------------

The js-set-enum-leds can be used with udev to ensure that the
controller LEDs on PS3 controllers match their identifiers as set by
Bluetooth host software. This ensures that if the controllers are
plugged in before the Bluetooth daemon starts, the LEDs still match
the identifier assigned once the daemon has initialised.

The following udev rule achieves this:

	# Set PS3 controller leds to the same value bluez will choose for it.
	# IMPORT{parent} used because $parent did not appear to be working; we
	# don't need the devpath of the js device for this so it is OK to overwrite.
	ACTION=="add", KERNEL=="js*", IMPORT{parent}="DEVPATH", ATTRS{name}=="Sony PLAYSTATION(R)3 Controller", RUN+="/lib/udev/js-set-enum-leds /sys/%E{DEVPATH}/device/leds/ $number"


Contributors
------------

The following people have contributed to this release:
* Johann Walles: jscal jitter tolerance.
* Dr. László Kaján: button and axis remapping.
* Sebastian Siewior: EVIOCGBIT correction.
* Krzysztof A. Sobiecki: improvements to the button and axis remapping
  functions.
* Claudio Nieder: Sahara Touch-iT213 support.
* Florian Fainelli: evtest fixes.
* Alexander Clouter: W8001 support and error-handling fixes.
* Roberto Neri: much discussion, and fixes and improvements to
  jscal-store/jscal-restore and the udev rules given above.
* Jean Delvare: inputattach improvements, TAOS support.
* Brian Murray and Kees Cook: Lenovo W8001 support.
* Raoul Bönish: fixes for the udev rules.
* John Sung: PenMount 3000, 6000 and 6250 support.
* Christian Gmeiner: TSC-40 support.
* Kyle Manna: various build fixes.
* Denis Gonsiorovsky: Genius EasyPen 3x4 tablet support.
* Jaromir Capik: 64-bit fixes and changes from ff-utils (based on a
  patch originally by Jean-Philippe Meure).
* Ralf Jung: fixes for long device names.
* Andrew Basterfield: fix for Spaceball 4000FLX support.
* bri: PS3 controller LED configuration
* Julian Squires: Wacom IV support.
* Jamie Lentin: mouseman4 mode.
* Böszörményi Zoltán: eGalaxTouch support, Hampshire support, systemd
  notification, multiple device initialisation, CRTSCTS control.
* Stephen Anthony: evdev-joystick (based on G25manage).
* Hans Verkuil: Pulse-Eight and RainShadow HDMI CEC dongle support.
* Jon Sangster: min/max axis control in evdev-joystick.
* Markus Koch: FlySky FS-iA6B RC support.
* Stefan Brüns: SDL2 port of ffmvforce.


License
-------

The linuxconsole tools are
	Copyright © 1996-2005 Vojtech Pavlik
	Copyright © 2001 Oliver Hamann
	Copyright © 2001-2002 Johann Deneux
	Copyright © 2001 Arndt Schoenewald
	Copyright © 2008-2019 Stephen Kitt
	Copyright © 2016 Stephen Anthony


This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301,
USA.


The GNU General Public License version 2 is provided in the COPYING
file.