e7f312f6be
Some manual pages uses roff macros and other features not handled by po4a. Make more manual pages translatable by removing the use of such macros where it is trivial to do.
187 lines
6.4 KiB
Groff
187 lines
6.4 KiB
Groff
.TH HAL_INPUT "1" "2007-02-25" "LinuxCNC Documentation" "HAL User's Manual"
|
|
.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
|
|
.br
|
|
.ns
|
|
.TP
|
|
.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
|
|
.br
|
|
.ns
|
|
.TP
|
|
.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
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-position\fR float out
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-scale\fR parameter float rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-offset\fR parameter float rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-fuzz\fR parameter s32 rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-flat\fR parameter s32 rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.abs\-\fIname\fB\-min\fR parameter s32 r
|
|
.br
|
|
.ns
|
|
.TP
|
|
.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
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-position\fR float out
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-reset\fR bit in
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-scale\fR parameter float rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-absolute\fR parameter s32 rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B input.\fIN\fB.rel\-\fIname\fB\-precision\fR parameter s32 rw
|
|
.br
|
|
.ns
|
|
.TP
|
|
.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
|
|
.br
|
|
.ns
|
|
.TP
|
|
.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
|