usr.bin/usbhidaction/usbhidaction.1

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