Annotation of src/usr.bin/usbhidaction/usbhidaction.1, Revision 1.4
1.4 ! jmc 1: .\" $OpenBSD: usbhidaction.1,v 1.3 2003/01/11 11:07:50 hugh Exp $
1.1 nate 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
1.3 hugh 67: Ignore HID items in the config file that do not exist in the device.
1.1 nate 68: .It Fl f Ar device
1.4 ! jmc 69: Specify a path name for the device to operate on.
! 70: If
1.1 nate 71: .Ar device
1.4 ! jmc 72: is numeric, it is taken to be the USB HID device number.
! 73: If it is a relative path, it is taken to be the name of the device under
1.1 nate 74: .Pa /dev .
75: An absolute path is taken to be the literal device pathname.
76: .It Fl v
77: Be verbose, and do not become a daemon.
78: .El
79: .Pp
80: The config file will be re-read if the process gets a HUP signal.
81: .Sh CONFIGURATION
1.4 ! jmc 82: The configuration file has a very simple format.
! 83: Each line describes an action; if a line begins with a whitespace
! 84: it is considered a continuation of the previous line.
! 85: Lines beginning with `#' are considered as comments.
1.1 nate 86: .Pp
87: Each line has three parts: a name of a USB HID item, a value for that item,
1.4 ! jmc 88: and an action.
! 89: There must be whitespace between the parts.
1.1 nate 90: .Pp
91: The item names are similar to those used by
92: .Xr usbhidctl 1 ,
93: but each part must be prefixed by its page name.
94: .Pp
1.4 ! jmc 95: The value is simply a numeric value.
! 96: When the item reports this value the action will be performed.
1.1 nate 97: If the value is `*' it will match any value.
98: .Pp
99: The action is a normal command that is executed with
100: .Xr system 3 .
101: Before it is executed some substitution will occur:
102: `$n' will be replaced by the nth argument on the
103: command line, `$V' will be replaced by the numeric value
104: of the HID item, `$N' will be replaced by the name
105: of the control, and `$H' will be replaced by the name
106: of the HID device.
107: .Sh FILES
108: .Pa /usr/share/misc/usb_hid_usages
109: The HID usage table.
110: .Sh EXAMPLES
111: The following configuration file can be used to control a pair
112: of Philips USB speakers with the HID controls on the speakers.
113: .Bd -literal -offset indent
114: # Configuration for various Philips USB speakers
115: Consumer:Consumer_Control.Consumer:Volume_Up 1
116: mixerctl -f $1 -n -w fea8-i7-master++
117: Consumer:Consumer_Control.Consumer:Volume_Down 1
118: mixerctl -f $1 -n -w fea8-i7-master--
119: Consumer:Consumer_Control.Consumer:Mute 1
120: mixerctl -f $1 -n -w fea8-i7-mute++
121: Consumer:Consumer_Control.Consumer:Channel_Top.Microsoft:Base_Up 1
122: mixerctl -f $1 -n -w fea8-i7-bass++
123: Consumer:Consumer_Control.Consumer:Channel_Top.Microsoft:Base_Down 1
124: mixerctl -f $1 -n -w fea8-i7-bass--
125: .Ed
126: .Pp
127: A sample invocation using this configuration would be
128: .Bd -literal -offset indent
1.2 deraadt 129: $ usbhidaction -f /dev/uhid1 -c conf /dev/mixer1
1.1 nate 130: .Ed
131: .Sh SEE ALSO
132: .Xr usbhidctl 1 ,
133: .Xr usbhid 3 ,
134: .Xr uhid 4 ,
135: .Xr usb 4
136: .Sh HISTORY
137: The
138: .Nm
139: command first appeared in
140: .Ox 3.2 .