Synaptics Touchpad

The Synaptics Touchpad is a pointing device, found on many laptops for instance. First, we discuss the problems with the current driver. Then we talk about a replacement driver to improve the quality and extend features.

Support for this device is already included in FreeBSD and can be enabled with the hw.psm.synaptics_support tunable. Without this, the touchpad is recognized as a standard 3-buttons mouse.

The current implementation provides the following features:

• movement smoothing
• tap detection with one finger
• palm detection
• support for extra buttons
• support for guest devices

However it lacks several useful features:

• precision with slow movements
• tap detection with two or three fingers
• tap-hold (to simulate a button kept pressed)
• virtual scrolling (to simulate a wheel)
• movement continuation (to continue a movement when the finger reaches a border)

An X.Org driver providing some of the missing features is available in the Ports tree but it requires further setup and its features are obviously unavailable for the console.

The development of the new driver will go through two phases:

1. Bring the quality of the movement smoothing and tap-hold support on par with what is done internaly by the touchpad, when hw.psm.synaptics_support is not set.
2. Add more features such as virtual scrolling.

The latest patch is available for:

• 8-CURRENT (as of 2008-10-14)

To apply it:

# cd /usr/src
# patch < psm-synaptics-8-CURRENT-m.patch

To be able to use horizontal scrolling with this new driver under X.Org (through sysmouse), you'll need a patch against xf86-input-mouse.

To apply it:

# cd /usr/ports/x11-drivers/xf86-input-mouse
# make patch
# cd work
# patch -p1 < xf86-input-mouse-sysmouse-horizontal-scrolling.patch
# cd ..
# make

• better movement smoothing. It's comparable to the Microsoft Windows driver from Synaptics, except when the finger reaches touchpad borders where the movement becomes chaotic.
• tap detection with one (left click), two (right click) or three (middle click) fingers.
• tap-hold detection with one, two or three fingers.
• virtual scrolling. For now, an area must be dedicated to virtual scrolling; typically, one on the right (vertical scrolling) and one at the bottom (horizontal scrolling). Also, a patch must be applied to xf86-input-mouse to handle horizontal scrolling from sysmouse. Later, virtual scrolling with two fingers will be re-added, as found on Apple MacBook.

hw.psm.synaptics.min_pressure: 16
hw.psm.synaptics.max_pressure: 220

If the pressure is less than min_pressure of above max_pressure, the packet is ignored but the current action isn't terminated. The pressure is comprised between 0 and 255. Here are some meaningful values, as stated by Synaptics specifications:

• z = 0: no finger contact
• z = 10: finger hovering near the pad
• z = 30: very light finger contact
• z = 80: normal finger contact
• z = 110: very heavy finger contact
• z = 200: finger lying flat on pad surface
• z = 255: maximum reportable Z

hw.psm.synaptics.max_width: 10

If the finger width is above max_width, the packet is ignored but the current action isn't terminated. The width is comprised between 4 and 15. Here are some meningful values, as stated by Synaptics specifications:

• w = 4-7: finger of normal width (capPalmDetect needed)
• w = 8-14: very wide finger or palm (capPalmDetect needed)
• w = 15: maximum reportable width (capPalmDetect needed

To smooth the movement, we use a weighted average then a division where both the weight and the divisor vary, depending on the movement speed. See “How it works”.

hw.psm.synaptics.weight_current: 3
hw.psm.synaptics.weight_previous: 6
hw.psm.synaptics.weight_previous_na: 20
hw.psm.synaptics.weight_len_squared: 2000

weight_current and weight_previous define the range of weights to use when calculating the average. weight_previous_na is used instead of weight_previous when the finger is inside the noisy area (see “Touchpad borders”).

TODO: explain weight_len_squared.

hw.psm.synaptics.div_min: 9
hw.psm.synaptics.div_max: 17
hw.psm.synaptics.div_max_na: 30
hw.psm.synaptics.div_len: 100

div_min and div_max define the range of divisors to when calculating the final delta for x & y. div_max_na is used instead of div_max when the finger is inside the noisy area (see “Touchpad borders”).

TODO: explain div_len.

hw.psm.synaptics.multiplicator: 10000

This multiplicator is used during averages and divisions to increase the precision.

The touchpad borders generate a lot of noise in the reported coordinates. There are two sets of sysctl to control this area.

hw.psm.synaptics.margin_top: 200
hw.psm.synaptics.margin_right: 200
hw.psm.synaptics.margin_bottom: 200
hw.psm.synaptics.margin_left: 200

These margins act as a high-pass filter: for instance, the point [50; 170] will be reported as [200;200].

hw.psm.synaptics.na_top: 1783
hw.psm.synaptics.na_right: 563
hw.psm.synaptics.na_bottom: 1408
hw.psm.synaptics.na_left: 1600

na stands for noisy area. Movements inside these larger margins will be smoothed using different max weight and divisor. See “Movement smoothing”.

hw.psm.synaptics.window_min: 4
hw.psm.synaptics.window_max: 10

window_min indicates the minimum number of packets to receive before an action is considered to be real and wanted. window_max is the maximum number of packets to use in calculations.

hw.psm.synaptics.tap_max_delta: 80
hw.psm.synaptics.tap_min_queue: 2

tap_max_delta is the maximum delta between points to treat the action as a tap. This is to prevent any unwanted click. tap_min_queue is the minimum number of packets needed to consider a tap.

hw.psm.synaptics.taphold_timeout: 125000

taphold_timeout is the time (in microseconds) between two taps to consider a tap-hols action.

hw.psm.synaptics.vscroll_hor_area: 1300
hw.psm.synaptics.vscroll_ver_area: -600
hw.psm.synaptics.vscroll_min_delta: 50
hw.psm.synaptics.vscroll_div_min: 100
hw.psm.synaptics.vscroll_div_max: 150

An area must be dedicated to virtual scrolling for now. This area is defined by vscroll_hor_area (positive for an area at the bottom, negative for an area at the top) for horizontal scrolling and vscroll_ver_area (positive for an area on the left, negative for an area on the right) for vertical scrolling. vscroll_min_delta is the minimum delta between points to consider a scrolling action. This is to prevent unwanted scrolling when tapping for instance. vscroll_div_min and vscroll_div_max are the divisors used instead of div_min and div_max respectively.

The smoothing is based on a weighted average:

average = (weight_current * delta + weight_previous * average) / (weight_current + weight_preivous)

where :

• average is the previous average, which is kept between each packet.
• delta is the relative movement.
• weight_current and weight_previous are configurable weights.

This average is calculated for each axis (x & y) separately.

The problem with a simple weighted average as above is that the user has to choose between a smooth but laggy movement (weight_previous greater then weight_current) or a sharp but imprecise movement at slow speed (weight_previous smaller or equal to weight_current).

The idea is then to change weight_previous based on the last packets:

• If the movement is slow, we keep weight_previous at its original value.
• If the movement is fast, weight_previous decreases and may reach 0 for the fastest movements.

Internaly, the driver keeps the last 10 packets. Here is the simplified algorithm:

dx = abs(new_x - older_x) + 1; /* +1: to avoid a division by zero below. */
dy = abs(new_y - older_y) + 1;
 
/* "len" is really the length squared. */
len = (dx * dx) + (dy * dy);
 
/* "sysctl_weight_len_squared" is the length squared at which the
 * "weight_previous" will start to decrease. */
weight_previous = sysctl_weight_len_squared * weight_previous / len;
weight_previous = imin(weight_previous, sysctl_weight_previous);

The driver will do almost the same with the divisor to calculate the acceleration. The rest of the division is also kept between each packet; otherwise, with slow movements, the pointer doesn't reproduce well what the finger is doing.