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 .\"
  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 but each part must be prefixed by its page name.
 104 .Pp
 105 The value is simply a numeric value.
 106 When the item reports this value,
 107 the action will be performed.
 108 If the value is
 109 .Ql * ,
 110 it will match any value.
 111 .Pp
 112 The debounce value is an integer not less than 0.
 113 The value of 0 indicates that no debouncing should occur.
 114 A value of 1 will only execute the action when the state changes.
 115 Values greater than one specify that an action should be performed
 116 only when the value changes by that amount.
 117 .Pp
 118 The action is a normal command that is executed with
 119 .Xr system 3 .
 120 Before it is executed some substitution will occur:
 121 .Ql $n
 122 will be replaced by the
 123 .Ar n Ns th
 124 argument on the command line,
 125 .Ql $V
 126 will be replaced by the numeric value of the HID item,
 127 .Ql $N
 128 will be replaced by the name of the control, and
 129 .Ql $H
 130 will be replaced by the name of the HID device.
 131 .Sh FILES
 132 .Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages"
 133 .It Pa /usr/share/misc/usb_hid_usages
 134 The HID usage table.
 135 .It Pa /var/run/usbaction.pid
 136 The default location of the PID file.
 137 .El
 138 .Sh EXAMPLES
 139 The following configuration file can be used to control a pair
 140 of Philips USB speakers with the HID controls on the speakers.
 141 .Bd -literal -offset indent
 142 # Configuration for various Philips USB speakers
 143 Consumer:Volume_Up                       1 0 mixer -f $1 vol +1
 144 Consumer:Volume_Down                     1 0 mixer -f $1 vol -1
 145 # mute not supported
 146 #Consumer:Mute                           1 0 mixer -f $1 mute
 147 Consumer:Channel_Top.Microsoft:Base_Up   1 0 mixer -f $1 bass +1
 148 Consumer:Channel_Top.Microsoft:Base_Down 1 0 mixer -f $1 bass -1
 149 .Ed
 150 .Pp
 151 A sample invocation using this configuration would be
 152 .Pp
 153 .Dl "usbhidaction -f /dev/uhid1 -c conf /dev/mixer1"
 154 .Pp
 155 The following example controls the mixer volume using a Logitech Wingman.
 156 Notice the debounce of 1 for buttons and 5 for the slider.
 157 .Bd -literal -offset indent
 158 Button:Button_1   1 1   mixer vol +10
 159 Button:Button_2   1 1   mixer vol -10
 160 Generic_Desktop:Z * 5   mixer vol `echo $V | awk '{print int($$1/255*100)}'`
 161 .Ed
 162 .Sh SEE ALSO
 163 .Xr usbhidctl 1 ,
 164 .Xr usbhid 3 ,
 165 .Xr uhid 4 ,
 166 .Xr usb 4
 167 .Sh HISTORY
 168 The
 169 .Nm
 170 command first appeared in
 171 .Nx 1.6 .
 172 The
 173 .Nm
 174 command appeared in
 175 .Fx 5.1 .