path: root/README

Synaptics TouchPad driver for XOrg/XFree86
------------------------------------------

Introduction
------------

This is a driver for the Synaptics TouchPad for XOrg/XFree86 4.x. A
Synaptics touchpad by default operates in compatibility mode by
emulating a standard mouse. However, by using a dedicated driver, more
advance features of the touchpad becomes available, such as:

- Movement with adjustable, non-linear acceleration and speed.
- Button events through short touching of the touchpad.
- Double-Button events through double short touching of the touchpad.
- Dragging through short touching and holding down the finger on the
  touchpad.
- Middle and right button events on the upper and lower corner of
  the touchpad.
- Vertical scrolling (button four and five events) through moving
  the finger on the right side of the touchpad.
- The up/down button sends button four/five events.
- Horizontal scrolling (button six and seven events) through moving
  the finger on the lower side of the touchpad.
- The multi-buttons send button four/five events, and six/seven
  events for horizontal scrolling.
- Adjustable finger detection.
- Multifinger taps: two finger for middle button and three finger
  for right button events. (Needs hardware support. Not all models
  implement this feature.)
- Run-time configuration using shared memory. This means you can
  change parameter settings without restarting the X server.

Note that depending on the touchpad firmware, some of these features
might be available even without using the synaptics driver. Note also
that some functions are not available on all touchpad models, because
they need support from the touchpad hardware/firmware. (Multifinger
taps for example.)


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

See the INSTALL file for detailed installation instructions.


Compatibility
-------------

The driver has been reported to work on a number of different laptop
computers. See the COMPATIBILITY file for the list. If your computer
is not listed, please let me (petero2@telia.com) know if the driver
works on your computer.


Parameters
----------

The driver behavior can be configured with parameters. These
parameters are options in the InputDevice section in the XFree86
config file. See the INSTALL file for a working example. If you have
the SHMConfig parameter enabled, these parameters can also be changed
at runtime with the synclient program.

Parameter:		Type:   Description:

Device			String	Synaptics device
Protocol		String	"auto-dev" (automatic, default), "psaux" (raw) or
				"event" (linux 2.5 kernel events)
SHMConfig		Bool	switch on/off shared memory for configuration
LeftEdge		Int	coordinates for left edge
RightEdge		Int	coordinates for right edge
TopEdge			Int	coordinates for top edge
BottomEdge		Int	coordinates for bottom edge
FingerLow		Int	When finger pressure drops below this value, the
				driver counts it as a release.
FingerHigh		Int	When finger pressure goes above this value, the
				driver counts it as a touch.
MaxTapTime		Int	max. time (in milliseconds) for detecting a tap
MaxTapMove		Int	max. movement of the finger for detecting a tap
MaxDoubleTapTime	Int	max. time (in milliseconds) for detecting a double tap
ClickTime		Int	the duration of the mouse click generated by tapping
FastTaps		Bool	Makes the driver react faster to a single tap, but
				also makes double clicks caused by double tapping slower.
VertScrollDelta		Int	move distance of the finger for a scroll event
HorizScrollDelta	Int	move distance of the finger for a scroll event
EdgeMotionMinZ		Int	finger pressure at which minimum edge motion speed is set
EdgeMotionMaxZ		Int	finger pressure at which maximum edge motion speed is set
EdgeMotionMinSpeed	Int	slowest setting for edge motion speed
EdgeMotionMaxSpeed	Int	fastest setting for edge motion speed
EdgeMotionUseAlways	Bool	If on, edge motion is also used for normal movements,
				if off, egde motion is used only when dragging
Repeater		String	repeater device
MinSpeed		Float	min. Speed factor
MaxSpeed		Float	max. Speed factor
AccelFactor		Float	acceleration factor
UpDownScrolling		Bool	If on, the up/down buttons generate button 4/5 events.
				If off, the up button generates a double click and
				the down button generates a button 2 event.
EmulateMidButtonTime	Int	max time (in milliseconds) for middle button emulation.
TouchpadOff		Int	Switch off the touchpad. Valid values are:
				0 : Touchpad is enabled
				1 : Touchpad is switched off
				2 : Only tapping is switched off
GuestMouseOff		Bool	switch on/off guest mouse (often a stick)
LockedDrags		Bool	If off, a tap and drag gesture ends when you release
				the finger. If on, the gesture is active until you
				tap a second time.
RTCornerButton		Int	Which mouse button is reported on a right top corner tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
RBCornerButton		Int	Which mouse button is reported on a right bottom corner tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
LTCornerButton		Int	Which mouse button is reported on a left top corner tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
LBCornerButton		Int	Which mouse button is reported on a left bottom corner tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
TapButton1		Int	Which mouse button is reported on a non-corner one-finger tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
TapButton2		Int	Which mouse button is reported on a non-corner two-finger tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
TapButton3		Int	Which mouse button is reported on a non-corner three-finger tap
				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
CircularScrolling	Bool	If on, circular scrolling is used (see below)
CircScrollDelta		Float	Move angle (radians) of finger to generate a scroll event
CircScrollTrigger	Int	Trigger region on the touchpad to start circular scrolling
				0=All Edges, 1=Top Edge, 2=Top Right Corner, 3=Right Edge,
				4=Bottom Right Corner, 5=Bottom Edge, 6=Bottom Left Corner,
				7=Left Edge, 8=Top Left Corner
CircularPad	        Bool	Instead of being a rectangle, the edge is the ellipse
				enclosed by the Left/Right/Top/BottomEdge parameters.
				For circular touchpads.
PalmDetect		Bool	If palm detection should be enabled
PalmMinWidth		Int	Minimum width at which touch is considered a palm
PalmMinZ		Int	Minimum finger pressure at which touch is considered a palm
CoastingSpeed		Float	Coasting threshold scrolling speed. 0 disables coasting.

The LeftEdge, RightEdge, TopEdge and BottomEdge parameters are used to
define the edge and corner areas of the touchpad. The parameters split
the touchpad area in 9 pieces, like this:

        LeftEdge  RightEdge
            v         v
            |         |       Physical top edge
          1 |    2    | 3
        -------------------   TopEdge
            |         |
         4  |    5    | 6
            |         |
        -------------------   BottomEdge
         7  |    8    | 9
            |         |       Physical bottom edge
        ^                 ^
     Physical          Physical
     left edge        right edge

Coordinates to the left of LeftEdge are part of the left edge (areas
1, 4 and 7), coordinates to the left of LeftEdge and above TopEdge
(area 1) are part of the upper left corner, etc. A good way to find
appropriate edge parameters is to enable the SHMConfig option and run
"synclient -m 1" to see the x/y coordinates corresponding to different
positions on the touchpad.

A tap event happens when the finger is touched and released in a time
interval shorter than MaxTapTime, and the touch and release
coordinates are less than MaxTapMove units apart. A "touch" event
happens when the Z value goes above FingerHigh, and an "untouch" event
happens when the Z value goes below FingerLow.

The MaxDoubleTapTime parameter has the same function as the MaxTapTime
parameter, but for the second, third, etc tap in a tap sequence. If
you can't perform double clicks fast enough (for example, xmms depends
on fast double clicks), try reducing this parameter. If you can't get
word selection to work in xterm (ie button down, button up, button
down, move mouse), try increasing this parameter.

The ClickTime parameter controls the delay between the button down and
button up X events generated in response to a tap event. A too long
value can cause undesirable autorepeat in scroll bars and a too small
value means that visual feedback from the gui application you are
interacting with is harder to see.

The MinSpeed, MaxSpeed and AccelFactor parameters control the pointer
motion speed. The speed value defines the scaling between touchpad
coordinates and screen coordinates. When moving the finger very
slowly, the MinSpeed value is used, when moving very fast the MaxSpeed
value is used. When moving the finger at moderate speed, you get a
pointer motion speed somewhere between MinSpeed and MaxSpeed. If you
don't want any acceleration, set MinSpeed and MaxSpeed to the same
value.

The MinSpeed, MaxSpeed and AccelFactor parameters don't have any
effect on scrolling speed. Scrolling speed is determined solely from
the VertScrollDelta and HorizScrollDelta parameters. To disable
vertical or horizontal scrolling, set VertScrollDelta or
HorizScrollDelta to zero.

When hitting an egde, movement can be automatically continued.
If EdgeMotionUseAlways is false, edge motion is only used when
dragging. With EdgeMotionUseAlways set to true, it is also used for
normal cursor movements.

Edge motion speed is calculated by taking into account the amount of
pressure applied to the touchpad. The sensitivity can be adjusted
using the EdgeMotion parameters. If the pressure is below
EdgeMotionMinZ, EdgeMotionMinSpeed is used, and if the pressure is
greater than EdgeMotionMaxZ, EdgeMotionMaxSpeed is used. For a
pressure value between EdgeMotionMinZ and EdgeMotionMaxZ, the speed is
increased linearly.

Since most synaptics touchpad models don't have a button that
corresponds to the middle button on a mouse, the driver can emulate
middle mouse button events. If you press both the left and right mouse
buttons at almost the same time (no more than EmulateMidButtonTime
milliseconds apart) the driver generates a middle mouse button event.

Circular scrolling acts like a scrolling wheel on the trackpad.
Scrolling is engaged when a drag starts in the given CircScrollTrigger
region, which can be all edges, a particular side, or a particular
corner. Once scrolling is engaged, moving your finger in clockwise
circles around the trackpad will generate scroll down events and
counter clockwise scroll up events. Lifting your finger will disengage
circular scrolling. Use tight circles near the center of the pad for
fast scrolling and large circles for better control. When used
together with vertical scrolling, hitting the upper or lower right
corner will seamlessly switch over from vertical to circular
scrolling.

Coasting is enabled by setting the CoastingSpeed parameter to a
non-zero value. When coasting is enabled, horizontal/vertical
scrolling can continue after the finger is released from the
lower/right edge of the touchpad. The driver computes the scrolling
speed corresponding to the finger speed immediately before the finger
leaves the touchpad. If this scrolling speed is larger than the
CoastingSpeed parameter (measured in scroll events per second), the
scrolling will continue with the same speed in the same direction
until the finger touches the touchpad again.


FAQ
---

* Is this free software?

    Yes, the source code is released under the GNU General Public
    License.

* When will the driver be included in the XOrg distribution?

    This is unlikely to happen because of copyright issues. Although
    the GPL license is compatible with the license used by the XOrg X
    server, the XOrg project doesn't want to include GPL code in their
    source code, because it would effectively make the whole XOrg
    project GPL. The synaptics license can't be changed unless all
    copyright holders agree to change the license, but previous
    attempts to find all copyright holders for the synaptics source
    code have failed.

    So unfortunately, the best we can currently hope for is that the
    synaptics driver is included as a separate package by the major
    distributions.

* How do I use this driver with Linux kernel 2.6.x?

    You need to have the "evdev" driver loaded or compiled into the
    kernel (CONFIG_INPUT_EVDEV). Set the "Protocol" parameter in the X
    configuration file to "auto-dev". Also, if you set the "Device"
    parameter to "/dev/psaux", the same X configuration file should
    work for a 2.4.x kernel.

    When configuring the kernel, enable PS/2 mouse support
    (CONFIG_MOUSE_PS2).

* It still doesn't work with a 2.6 kernel.

    Some distributions come with an incomplete /dev directory. The
    driver needs the /dev/input/eventX device nodes. Try to create
    them manually if they don't exist already. (Look at
    /proc/bus/input/devices to figure out how many nodes you need.)

	     # mknod /dev/input/event0 c 13 64
	     # mknod /dev/input/event1 c 13 65
	     # mknod /dev/input/event2 c 13 66
	     ...

* How can I configure tap-to-click behavior?

    If you set MaxTapTime=0 in the X config file then the touchpad
    will not use tapping at all, i.e. touching/tapping will not be
    taken as a mouse click.

    If, instead, you set MaxTapMove=0 in the X config file, then the
    touchpad will not use tapping for a single finger tap (left mouse
    button click) but will for the two and three finger tap (middle
    and right button click).

* Why did tap-to-click stop working after I upgraded from an old version?

    Time is now measured in milliseconds instead of "number of
    packets". In practice, this means that if you are upgrading from
    an old version, you need to change MaxTapTime and
    EmulateMidButtonTime to make "tap to click" work. Good values are
    180 and 75 respectively.

* Gnome scrollbars scroll too much when using tap-to-click. Why?

    The ClickTime parameter is probably too big. Try setting it to
    100. Gnome scrollbars use auto repeat, ie if you press the left
    mouse button and keep it pressed, the scroll bar will move until
    you release the button. This will lead to problems if the tap time
    is longer than the delay before auto repeat starts.

* Vertical and horizontal scrolling events are mixed up. How come?

    Probably because some X startup/login script uses xmodmap to remap
    the mouse buttons. Correct settings for the touchpad are:

	xmodmap -e 'pointer = 1 2 3 4 5 6 7'

    You can check the current settings by running:

	xmodmap -pp

* Horizontal scrolling doesn't work in some programs. Is it a driver
  bug?

    No, probably not. Support for horizontal scroll events must be
    handled by the application programs. Not all programs do that
    yet. Ask the authors of the application in question to implement
    support for horizontal scroll events.

    You can use the "xev" program to check if the synaptics driver
    generates the horizontal scroll events.

* Can the driver be used together with gpm?

    No, not reliably, if you are using a 2.4.x kernel. The gpm driver
    and the X driver both try to read data from the touchpad, and if
    they try to read at the same time, both drivers see incomplete
    data and don't know how to interpret it.

    If you are running a 2.6.x kernel though, there should be no
    conflict, because the kernel driver will make sure both user space
    drivers receive all events from the touchpad.

* How do I compile the driver?

    Beginning with version 0.11.8, it should be possible to compile
    the driver by simply running "make". This will compile a driver
    for XFree86 4.2.x, which will also work for 4.3.x versions of
    XFree86.

    If you have an older version of XFree86, you will need an
    installed X source tree. On an RPM based distribution, you can
    build a suitable source tree by installing the XFree86 source RPM
    and compile it. For example, in RedHat 9, use the following
    commands:

      # rpm -vU XFree86-4.3.0-2.src.rpm
      # cd /usr/src/redhat/SPECS
      # rpmbuild -bb XFree86.spec

    Then change the TOP variable in the Makefile to match the version
    of XFree86 you are using. In the example above, set

      TOP = /usr/src/redhat/BUILD/XFree86-4.3.0/xc

* Can I use this driver with an ALPS Glidepoint device?

    Yes, see the README.alps file for more information.

* The driver says "reset failed" and the touchpad doesn't work. What
  can I do?

    This problem has been reported for some Compaq models. It's
    currently not known why it happens, but removing the reset command
    from the driver appears to make it work. If you use a 2.4 linux
    kernel, replace the contents of the ps2_synaptics_reset() function
    in ps2comm.c with a "return TRUE;" statement. If you use a 2.6
    linux kernel, remove the while loop in synaptics_query_hardware()
    in the file drivers/input/mouse/synaptics.c in the linux kernel
    source code.


Authors
-------

Many people have contributed to this driver. Look at the top of
synaptics.c and ps2comm.c for details.

The current maintainer is Peter Osterlund <petero2@telia.com>.