160 lines
6.3 KiB
Groff
160 lines
6.3 KiB
Groff
.TH HAL_INPUT "1" "2007-02-25" "LinuxCNC Documentation" "HAL User's Manual"
|
|
.de TQ
|
|
.br
|
|
.ns
|
|
.TP \\$1
|
|
..
|
|
.SH NAME
|
|
hal_input \- control HAL pins with any Linux input device, including USB HID devices
|
|
.SH SYNOPSIS
|
|
\fIloadusr\fR \fBhal_input\fR \fI[\-KRAL] inputspec ...\fR
|
|
.SH DESCRIPTION
|
|
hal_input is an interface between HAL and any Linux input device, including USB
|
|
HID devices. For each device named, \fBhal_input\fR creates pins corresponding
|
|
to its keys, absolute axes, and LEDs. At a fixed rate of approximately 10ms,
|
|
it synchronizes the device and the HAL pins.
|
|
.SH INPUT SPECIFICATION
|
|
The \fIinputspec\fR may be in one of several forms:
|
|
.TP
|
|
A string \fIS\fR
|
|
A substring or shell-style pattern match will be tested against the "name"
|
|
of the device, the "phys" (which gives information about how it is connected),
|
|
and the "id", which is a string of the form "Bus=... Vendor=... Product=...
|
|
Version=...". You can view the name, phys, and id of attached devices by executing \fBless /proc/bus/input/devices\fR. Examples:
|
|
.RS 12
|
|
.PD 0
|
|
SpaceBall
|
|
.PP
|
|
"Vendor=001f Product=0001"
|
|
.PP
|
|
serio*/input0
|
|
.RE
|
|
.PD
|
|
.TP
|
|
A number \fIN\fR
|
|
This opens \fB/dev/input/event\fIN\fR. Except for devices that are always
|
|
attached to the system, this number may change over reboots or when the device
|
|
is removed. For this reason, using an integer is not recommended.
|
|
.PP
|
|
When several devices are identified by the same string, add "\fB:\fIN\fR" where
|
|
\fIN\fR is the index of the desired device. For example, if \fBMouse\fR
|
|
matches \fBinput3\fR and \fBinput10\fR, then \fBMouse\fR and \fBMouse:0\fR
|
|
select \fBinput3\fR. Specifying \fBmouse:1\fR selects \fRinput10\fR.
|
|
.PP
|
|
For devices that appear as multiple entries in /dev/input, these indices are
|
|
likely to stay the same every time. For multiple identical devices, these
|
|
indices are likely to depend on the insertion order, but stay the same across
|
|
reboots as long as the devices are not moved to different ports or unplugged
|
|
while the machine is booted.
|
|
.PP
|
|
If the first character of the \fIinputspec\fR is a "+", then \fBhal_input\fR
|
|
requests exclusive access to the device. The first device matching an
|
|
\fIinputspec\fR is used. Any number of \fIinputspec\fRs may be used.
|
|
.PP
|
|
A \fIsubset option\fI may precede each \fIinputspec\fR. The subset option
|
|
begins with a dash. Each letter in the subset option specifies a device
|
|
feature to \fBinclude\fR. Features that are not specified are excluded.
|
|
For instance, to export keyboard LEDs to HAL without exporting keys, use
|
|
.RS 12
|
|
hal_input \-L \fIkeyboard\fR ...
|
|
.RE
|
|
|
|
.SH DEVICE FEATURES SUPPORTED
|
|
.IP \(bu 4
|
|
EV_KEY (buttons and keys). Subset \-K
|
|
.IP \(bu 4
|
|
EV_ABS (absolute analog inputs). Subset \-A
|
|
.IP \(bu 4
|
|
EV_REL (relative analog inputs). Subset \-R
|
|
.IP \(bu 4
|
|
EV_LED (LED outputs). Subset \-L
|
|
.SH HAL PINS AND PARAMETERS
|
|
.SS For buttons
|
|
.TP
|
|
.B input.\fIN\fB.btn\-\fIname\fR bit out
|
|
.TQ
|
|
.B input.\fIN\fB.btn\-\fIname\fB\-not\fR bit out
|
|
Created for each button on the device.
|
|
.SS For keys
|
|
.TP
|
|
.B input.\fIN\fB.key\-\fIname\fB
|
|
.TQ
|
|
.B input.\fIN\fB.key\-\fIname\fB\-not
|
|
Created for each key on the device.
|
|
.SS For absolute axes
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-counts\fR s32 out
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-position\fR float out
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-scale\fR parameter float rw
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-offset\fR parameter float rw
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-fuzz\fR parameter s32 rw
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-flat\fR parameter s32 rw
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-min\fR parameter s32 r
|
|
.TQ
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-max\fR parameter s32 r
|
|
Created for each absolute axis on the device. Device positions closer than
|
|
\fBflat\fR to \fBoffset\fR are reported as \fBoffset\fR in \fBcounts\fR, and
|
|
\fBcounts\fR does not change until the device position changes by at least
|
|
\fBfuzz\fR. The position is computed as \fBposition\fR = (\fBcounts\fR \-
|
|
\fBoffset\fR) / \fBscale\fR. The default value of \fBscale\fR and \fBoffset\fR
|
|
map the range of the axis reported by the operating system to [\-1,1]. The
|
|
default values of \fBfuzz\fR and \fBflat\fR are those reported by the operating
|
|
system. The values of \fBmin\fR and \fBmax\fR are those reported by the
|
|
operating system.
|
|
.SS For relative axes
|
|
.TP
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-counts\fR s32 out
|
|
.TQ
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-position\fR float out
|
|
.TQ
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-reset\fR bit in
|
|
.TQ
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-scale\fR parameter float rw
|
|
.TQ
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-absolute\fR parameter s32 rw
|
|
.TQ
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-precision\fR parameter s32 rw
|
|
.TQ
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-last\fR parameter s32 rw
|
|
Created for each relative axis on the device. As long as \fBreset\fR is true,
|
|
\fBcounts\fR is reset to zero regardless of any past or current axis movement.
|
|
Otherwise, \fBcounts\fR increases or decreases according to the motion of the
|
|
axis. \fBcounts\fR is divided by \fRposition\-scale\fR to give \fBposition\fR.
|
|
The default value of \fBposition\fR is 1. There are some devices, notably
|
|
scroll wheels, which return signed values with less resolution than 32 bits.
|
|
The default value of \fBprecision\fR is 32. \fBprecision\fR can be set to 8
|
|
for a device that returns signed 8 bit values, or any other value from 1 to 32.
|
|
\fBabsolute\fR, when set true, ignores duplicate events with the same value.
|
|
This allows for devices that repeat events without any user action to work
|
|
correctly. \fBlast\fR shows the most recent count value returned by the
|
|
device, and is used in the implementation of \fBabsolute\fR.
|
|
.SS For LEDs
|
|
.TP
|
|
.B input.\fIN\fB.led\-\fIname\fR bit out
|
|
.TQ
|
|
.B input.\fIN\fB.led\-\fIname\fB\-invert\fR parameter bit rw
|
|
Created for each LED on the device.
|
|
.SH PERMISSIONS AND UDEV
|
|
By default, the input devices may not be accessible to regular
|
|
users--\fBhal_input\fR requires read-write access, even if the device has no
|
|
outputs.
|
|
|
|
Different versions of udev have slightly different, incompatible syntaxes. For
|
|
this reason, it is not possible for this manual page to give an accurate
|
|
example. The
|
|
.B udev(7)
|
|
manual page documents the syntax used on your Linux distribution.
|
|
To view it in a terminal, the command is
|
|
.BR "man 7 udev" .
|
|
|
|
.SH BUGS
|
|
The initial state of keys, buttons, and absolute axes are erroneously reported
|
|
as FALSE or 0 until an event is received for that key, button, or axis.
|
|
.SH SEE ALSO
|
|
\fBudev(8)\fR, \fBudev(7)\fR
|