usr.bin/usbhidaction/usbhidaction.1

   1 .\" $FreeBSD$
   2 .\" $NetBSD: usbhidaction.1,v 1.8 2003/02/25 10:35:59 wiz Exp $
   3 .\"
   4 .\" Copyright (c) 2000 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to The NetBSD Foundation
   8 .\" by Lennart Augustsson (lennart@augustsson.net).
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"        This product includes software developed by the NetBSD
  21 .\"        Foundation, Inc. and its contributors.
  22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  23 .\"    contributors may be used to endorse or promote products derived
  24 .\"    from this software without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .Dd April 9, 2003
  39 .Dt USBHIDACTION 1
  40 .Os
  41 .Sh NAME
  42 .Nm usbhidaction
  43 .Nd perform actions according to USB HID controls
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Op Fl diev
  47 .Fl c Ar config-file
  48 .Fl f Ar device
  49 .Op Fl p Ar pidfile
  50 .Op Fl t Ar tablefile
  51 .Ar arg ...
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 utility
  56 can be used to execute commands when certain values appear on HID controls.
  57 The normal operation for this program is to read the configuration file
  58 and then become a daemon and execute commands as the HID items specify.
  59 If a read from the HID device fails, the program dies; this will make it
  60 die when the USB device is unplugged.
  61 .Pp
  62 The options are as follows:
  63 .Bl -tag -width indent
  64 .It Fl d
  65 Toggle the daemon flag.
  66 .It Fl e
  67 Instruct
  68 .Nm
  69 to die early.
  70 Useful when specified with multiple verbose options to see how files are parsed.
  71 .It Fl i
  72 Ignore HID items in the configuration file that do not exist in the device.
  73 .It Fl v
  74 Be verbose, and do not become a daemon.
  75 .It Fl c Ar config-file
  76 Specify a path name for the configuration file.
  77 .It Fl t Ar tablefile
  78 Specify a path name for the HID usage table file.
  79 .It Fl f Ar device
  80 Specify a path name for the device to operate on.
  81 If
  82 .Ar device
  83 is numeric, it is taken to be the USB HID device number.
  84 If it is a relative
  85 path, it is taken to be the name of the device under
  86 .Pa /dev .
  87 An absolute path is taken to be the literal device pathname.
  88 .It Fl p Ar pidfile
  89 Specify an alternate file in which to store the process ID.
  90 .El
  91 .Pp
  92 The configuration file will be re-read if the process gets a
  93 .Dv SIGHUP
  94 signal.
  95 .Sh CONFIGURATION
  96 The configuration file has a very simple format.
  97 Each line describes an
  98 action; if a line begins with a whitespace, it is considered a continuation
  99 of the previous line.
 100 Lines beginning with
 101 .Ql #
 102 are considered as comments.
 103 .Pp
 104 Each line has four parts: a name of a USB HID item, a value for that item,
 105 a debounce value, and an action.
 106 There must be whitespace between the parts.
 107 .Pp
 108 The item names are similar to those used by
 109 .Xr usbhidctl 1 ,
 110 but each part must be prefixed by its page name.
 111 .Pp
 112 The value is simply a numeric value.
 113 When the item reports this value,
 114 the action will be performed.
 115 If the value is
 116 .Ql * ,
 117 it will match any value.
 118 .Pp
 119 The debounce value is an integer not less than 0.
 120 The value of 0 indicates that no debouncing should occur.
 121 A value of 1 will only execute the action when the state changes.
 122 Values greater than one specify that an action should be performed
 123 only when the value changes by that amount.
 124 .Pp
 125 The action is a normal command that is executed with
 126 .Xr system 3 .
 127 Before it is executed some substitution will occur:
 128 .Ql $n
 129 will be replaced by the
 130 .Ar n Ns th
 131 argument on the command line,
 132 .Ql $V
 133 will be replaced by the numeric value of the HID item,
 134 .Ql $N
 135 will be replaced by the name of the control, and
 136 .Ql $H
 137 will be replaced by the name of the HID device.
 138 .Sh FILES
 139 .Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages"
 140 .It Pa /usr/share/misc/usb_hid_usages
 141 The HID usage table.
 142 .It Pa /var/run/usbaction.pid
 143 The default location of the PID file.
 144 .El
 145 .Sh EXAMPLES
 146 The following configuration file can be used to control a pair
 147 of Philips USB speakers with the HID controls on the speakers.
 148 .Bd -literal -offset indent
 149 # Configuration for various Philips USB speakers
 150 Consumer:Volume_Up                       1 0 mixer -f $1 vol +1
 151 Consumer:Volume_Down                     1 0 mixer -f $1 vol -1
 152 # mute not supported
 153 #Consumer:Mute                           1 0 mixer -f $1 mute
 154 Consumer:Channel_Top.Microsoft:Base_Up   1 0 mixer -f $1 bass +1
 155 Consumer:Channel_Top.Microsoft:Base_Down 1 0 mixer -f $1 bass -1
 156 .Ed
 157 .Pp
 158 A sample invocation using this configuration would be
 159 .Pp
 160 .Dl "usbhidaction -f /dev/uhid1 -c conf /dev/mixer1"
 161 .Pp
 162 The following example controls the mixer volume using a Logitech Wingman.
 163 Notice the debounce of 1 for buttons and 5 for the slider.
 164 .Bd -literal -offset indent
 165 Button:Button_1   1 1   mixer vol +10
 166 Button:Button_2   1 1   mixer vol -10
 167 Generic_Desktop:Z * 5   mixer vol `echo $V | awk '{print int($$1/255*100)}'`
 168 .Ed
 169 .Sh SEE ALSO
 170 .Xr usbhidctl 1 ,
 171 .Xr usbhid 3 ,
 172 .Xr uhid 4 ,
 173 .Xr usb 4
 174 .Sh HISTORY
 175 The
 176 .Nm
 177 command first appeared in
 178 .Nx 1.6 .
 179 The
 180 .Nm
 181 command appeared in
 182 .Fx 5.1 .