Ubuntu Manpage: hal_input - control HAL pins with any Linux input device, including USB HID devices

Provided by: linuxcnc-uspace_2.9.0~pre0+git20220402.2500863908-4build1_amd64

NAME

       hal_input - control HAL pins with any Linux input device, including USB HID devices

SYNOPSIS

       loadusr hal_input [-KRAL] inputspec ...

DESCRIPTION

       hal_input  is  an  interface  between  HAL  and  any Linux input device, including USB HID
       devices.  For each device  named,  hal_input  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.

INPUT SPECIFICATION

The inputspec may be in one of several forms:

A string S
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 less
/proc/bus/input/devices. Examples:
SpaceBall
"Vendor=001f Product=0001"
serio*/input0

A number N
This opens /dev/input/eventN. 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.

When several devices are identified by the same string, add ":N" where N is the index of
the desired device. For example, if Mouse matches input3 and input10, then Mouse and
Mouse:0 select input3. Specifying mouse:1 selects input10.

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.

If the first character of the inputspec is a "+", then hal_input requests exclusive access
to the device. The first device matching an inputspec is used. Any number of inputspecs
may be used.

A subset option may precede each inputspec. The subset option begins with a dash. Each
letter in the subset option specifies a device feature to include. Features that are not
specified are excluded. For instance, to export keyboard LEDs to HAL without exporting
keys, use
hal_input -L keyboard ...

DEVICE FEATURES SUPPORTED

       •   EV_KEY (buttons and keys).  Subset -K

       •   EV_ABS (absolute analog inputs).  Subset -A

       •   EV_REL (relative analog inputs).  Subset -R

       •   EV_LED (LED outputs).  Subset -L

HAL PINS AND PARAMETERS

For buttons
input.N.btn-name bit out
input.N.btn-name-not bit out
Created for each button on the device.

For keys
input.N.key-name
input.N.key-name-not
Created for each key on the device.

For absolute axes
input.N.abs-name-counts s32 out
input.N.abs-name-position float out
input.N.abs-name-scale parameter float rw
input.N.abs-name-offset parameter float rw
input.N.abs-name-fuzz parameter s32 rw
input.N.abs-name-flat parameter s32 rw
input.N.abs-name-min parameter s32 r
input.N.abs-name-max parameter s32 r
Created for each absolute axis on the device. Device positions closer than flat to
offset are reported as offset in counts, and counts does not change until the
device position changes by at least fuzz. The position is computed as position =
(counts - offset) / scale. The default value of scale and offset map the range of
the axis reported by the operating system to [-1,1]. The default values of fuzz
and flat are those reported by the operating system. The values of min and max are
those reported by the operating system.

For relative axes
input.N.rel-name-counts s32 out
input.N.rel-name-position float out
input.N.rel-name-reset bit in
input.N.rel-name-scale parameter float rw
input.N.rel-name-absolute parameter s32 rw
input.N.rel-name-precision parameter s32 rw
input.N.rel-name-last parameter s32 rw
Created for each relative axis on the device. As long as reset is true, counts is
reset to zero regardless of any past or current axis movement. Otherwise, counts
increases or decreases according to the motion of the axis. counts is divided by
position-scale to give position. The default value of position is 1. There are
some devices, notably scroll wheels, which return signed values with less
resolution than 32 bits. The default value of precision is 32. precision can be
set to 8 for a device that returns signed 8 bit values, or any other value from 1
to 32. absolute, when set true, ignores duplicate events with the same value.
This allows for devices that repeat events without any user action to work
correctly. last shows the most recent count value returned by the device, and is
used in the implementation of absolute.

For LEDs
input.N.led-name bit out
input.N.led-name-invert parameter bit rw
Created for each LED on the device.

PERMISSIONS AND UDEV

       By default, the input devices may not be accessible to regular  users--hal_input  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  udev(7)
       manual  page  documents  the  syntax  used  on  your  Linux distribution.  To view it in a
       terminal, the command is man 7 udev.

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.