Annotation of src/usr.bin/usbhidaction/usbhidaction.1, Revision 1.1
1.1 ! nate 1: .\" $OpenBSD$
! 2: .\" $NetBSD: usbhidaction.1,v 1.6 2002/01/18 14:38:59 augustss 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 December 29, 2000
! 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: .Fl c Ar config-file
! 47: .Op Fl d
! 48: .Op Fl i
! 49: .Fl f Ar device
! 50: .Op Fl v
! 51: .Ar arg ...
! 52: .Sh DESCRIPTION
! 53: .Nm
! 54: can be used to execute commands when certain values appear on HID controls.
! 55: The normal operation for this program is to read the configuration file
! 56: and then become a daemon and execute commands as the HID items specify.
! 57: If a read from the HID device fails the program dies; this will make it
! 58: die when the USB device is unplugged.
! 59: .Pp
! 60: The options are as follows:
! 61: .Bl -tag -width Ds
! 62: .It Fl c Ar config-file
! 63: Specify a path name for the config file.
! 64: .It Fl d
! 65: Toggle the daemon flag.
! 66: .It Fl i
! 67: Ignore HID items in the config file that does not exist in the device.
! 68: .It Fl f Ar device
! 69: Specify a path name for the device to operate on. If
! 70: .Ar device
! 71: is numeric, it is taken to be the USB HID device number. If it is a relative
! 72: path, it is taken to be the name of the device under
! 73: .Pa /dev .
! 74: An absolute path is taken to be the literal device pathname.
! 75: .It Fl v
! 76: Be verbose, and do not become a daemon.
! 77: .El
! 78: .Pp
! 79: The config file will be re-read if the process gets a HUP signal.
! 80: .Sh CONFIGURATION
! 81: The configuration file has a very simple format. Each line describes an
! 82: action; if a line begins with a whitespace it is considered a continuation
! 83: of the previous line. Lines beginning with `#' are considered as comments.
! 84: .Pp
! 85: Each line has three parts: a name of a USB HID item, a value for that item,
! 86: and an action. There must be whitespace between the parts.
! 87: .Pp
! 88: The item names are similar to those used by
! 89: .Xr usbhidctl 1 ,
! 90: but each part must be prefixed by its page name.
! 91: .Pp
! 92: The value is simply a numeric value. When the item reports this value
! 93: the action will be performed.
! 94: If the value is `*' it will match any value.
! 95: .Pp
! 96: The action is a normal command that is executed with
! 97: .Xr system 3 .
! 98: Before it is executed some substitution will occur:
! 99: `$n' will be replaced by the nth argument on the
! 100: command line, `$V' will be replaced by the numeric value
! 101: of the HID item, `$N' will be replaced by the name
! 102: of the control, and `$H' will be replaced by the name
! 103: of the HID device.
! 104: .Sh FILES
! 105: .Pa /usr/share/misc/usb_hid_usages
! 106: The HID usage table.
! 107: .Sh EXAMPLES
! 108: The following configuration file can be used to control a pair
! 109: of Philips USB speakers with the HID controls on the speakers.
! 110: .Bd -literal -offset indent
! 111: # Configuration for various Philips USB speakers
! 112: Consumer:Consumer_Control.Consumer:Volume_Up 1
! 113: mixerctl -f $1 -n -w fea8-i7-master++
! 114: Consumer:Consumer_Control.Consumer:Volume_Down 1
! 115: mixerctl -f $1 -n -w fea8-i7-master--
! 116: Consumer:Consumer_Control.Consumer:Mute 1
! 117: mixerctl -f $1 -n -w fea8-i7-mute++
! 118: Consumer:Consumer_Control.Consumer:Channel_Top.Microsoft:Base_Up 1
! 119: mixerctl -f $1 -n -w fea8-i7-bass++
! 120: Consumer:Consumer_Control.Consumer:Channel_Top.Microsoft:Base_Down 1
! 121: mixerctl -f $1 -n -w fea8-i7-bass--
! 122: .Ed
! 123: .Pp
! 124: A sample invocation using this configuration would be
! 125: .Bd -literal -offset indent
! 126: usbhidaction -f /dev/uhid1 -c conf /dev/mixer1
! 127: .Ed
! 128: .Sh SEE ALSO
! 129: .Xr usbhidctl 1 ,
! 130: .Xr usbhid 3 ,
! 131: .Xr uhid 4 ,
! 132: .Xr usb 4
! 133: .Sh HISTORY
! 134: The
! 135: .Nm
! 136: command first appeared in
! 137: .Ox 3.2 .