.\" $NetBSD: uatp.4,v 1.4 2014/03/18 18:20:39 riastradh Exp $
.\"
.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Taylor R. Campbell.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 4, 2012
.Dt UATP 4
.Os
.Sh NAME
.Nm uatp
.Nd USB Apple trackpad driver
.Sh SYNOPSIS
.Cd "uatp* at uhidev? reportid ?"
.Cd "wsmouse* at uatp? mux 0"
.Sh DESCRIPTION
The
.Nm
driver provides support for the USB trackpads found in Apple laptops
since 2005, exposed through
.Xr wsmouse 4 .
Some USB Apple trackpads are standard USB HID mice supported by
.Xr ums 4 ,
but
.Nm
supports more features.
The following
.Xr sysctl 8
variables control behavior of USB Apple trackpads:
.Bl -tag -width hw.uatpN.tap_track_distance_limit
.It Dv hw.uatpN.two_finger_buttons
Bit mask of buttons to emulate when two fingers are on the trackpad
while the button is pressed.
.It Dv hw.uatpN.three_finger_buttons
Bit mask of buttons to emulate when three fingers are on the trackpad
while the button is pressed.
.It Dv hw.uatpN.multifinger_track
What to do when multiple fingers are moved on the trackpad.
If set to 0, ignore the input.
If set to 1, move as if a single finger were at the mean position of
the fingers.
If set to 2, scroll.
Note that scrolling is currently broken.
.It Dv hw.uatpN.x_sensors
Number of sensor columns detecting the x positions of fingers on the
trackpad.
The driver should detect this based on the model of hardware, so you
should not have to set this, and likewise for the x ratio and y
sensors and ratio.
.It Dv hw.uatpN.x_ratio
Ratio of the number of sensor columns in the trackpad to the number of
distinct cursor x positions.
.It Dv hw.uatpN.y_sensors
Number of sensor rows detecting the y positions of fingers on the
trackpad.
.It Dv hw.uatpN.y_ratio
Ratio of the number of sensor rows in the trackpad to the number of
distinct cursor y positions.
.It Dv hw.uatpN.sensor_threshold
Nonnegative integer giving a lower bound on the
.Dq pressure
a sensor must report for the driver to recognize input from it.
.It Dv hw.uatpN.sensor_normalizer
Nonnegative integer to subtract from the
.Dq pressure
reported by a sensor when averaging them to estimate the pressure of a
single finger.
.It Dv hw.uatpN.palm_width
If zero, palm detection is disabled.
Otherwise, a positive integer giving the number of consecutive sensors
wide or high that will be interpreted as a palm instead of a finger and
therefore ignored.
.It Dv hw.uatpN.old_raw_weight
.It Dv hw.uatpN.old_smoothed_weight
.It Dv hw.uatpN.new_raw_weight
When a finger moves on the trackpad, the new smoothed (cursor) position
is computed as a positive linear combination of the old raw (trackpad)
position, the old smoothed position, and the new raw position.
The weights of the linear combination are given by these sysctl knobs.
.It Dv hw.uatpN.motion_threshold
Threshold below which a difference in smoothed position will not be
reported as an input event to userland.
.It Dv hw.uatpN.motion_multiplier
Positive integer by which a difference in smoothed position will be
multiplied before passing it as an input event to userland.
.It Dv hw.uatpN.motion_divisor
Positive integer by which a difference in smoothed position will be
divided, after multiplying it by the motion multiplier, before passing
it as an input event to userland.
.It Dv hw.uatpN.fast_motion_threshold
Threshold above which to use the fast motion factors below.
.It Dv hw.uatpN.fast_motion_multiplier
Positive integer by which to multiply a large difference in smoothed
position.
.It Dv hw.uatpN.fast_motion_divisor
Positive integer by which to divide a large difference in smoothed
position, after multiplying it by the fast motion multiplier.
.It Dv hw.uatpN.motion_delay
Number of input packets before
.Nm
reports motion to userland.
.It Dv hw.uatpN.tap_limit_msec
Positive integer giving the number of milliseconds of a finger's
contact with the trackpad before it will not be considered a tap.
.It Dv hw.uatpN.double_tap_limit_msec
Positive integer giving the maximum number of milliseconds after a tap
before a second tap will keep the button down.
.It Dv hw.uatpN.one_finger_tap_buttons
Bit mask of buttons that a one-finger tap will press.
.It Dv hw.uatpN.two_finger_tap_buttons
Bit mask of buttons that a two-finger tap will press.
.It Dv hw.uatpN.three_finger_tap_buttons
Bit mask of buttons that a three-finger tap will press.
.It Dv hw.uatpN.tap_track_distance_limit
Maximum distance in smoothed position that will be interpreted as a tap
instead of motion.
.El
.Sh SEE ALSO
.Xr ums 4 ,
.Xr wsmouse 4
.Sh HISTORY
The
.Nm
driver first appeared in
.Nx 7.0 .
.Sh AUTHORS
The
.Nm
driver was originally written by
.An Taylor R. Campbell Aq Mt riastradh@NetBSD.org .
.Sh BUGS
Sometimes, particularly when X starts up, the driver gets wedged in an
interrupt storm and does not reset the device.
Setting
.Li hw.uatpN.sensor_threshold
to a large number, say 1000, and then back to its original value, can
fix this.
.Pp
Palm detection is not very robust.
.Pp
Multi-touch scrolling is currently broken.
.Pp
Pinch-to-zoom and other fancy multi-touch input is not implemented.
.Pp
On suspending and resuming,
.Nm
detaches and reattaches, and loses all sysctl settings in the process.
.Pp
Do not submerge your
.Nm
devices in water: USB adenosine triphosphate is unstable in water, and
will hydrolyze to USB adenosine diphosphate and phosphate, which is a
lower energy state that makes your mouse narcoleptic in X.