hal_input.1

CNC 的开放码,EMC2 V2.2.8版

.TH HAL_INPUT "1" "2007-02-25" "EMC 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
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 preceed 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
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.
.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.  To change the default permission of a device, add a new file to
/etc/udev/rules.d to set the device's GROUP to "plugdev".  You can do this for
all input devices with this rule:
.RS
SUBSYSTEM=="input", mode="0660", group="plugdev"
.RE
You can also make more specific rules for particular devices.  For instance, a
SpaceBall input device uses the 'spaceball' kernel module, so a udev entry for
it would read:
.RS
DRIVER=="spaceball", MODE="0660", GROUP="plugdev"
.RE
the next time the device is attached to the system, it will be accessible
to the "plugdev" group.

For USB devices, the udev line would refer to the device's Vendor and Product
values, such as 
.RS
SYSFS{idProduct}=="c00e", SYSFS{idVendor}=="046d", MODE="0660", GROUP="plugdev"
.RE
for a particular logictech-brand mouse.

For more information on writing udev rules, see \fBudev(8)\fR.
.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
\fBhal_joystick(1)\fR, \fBudev(8)\fR