Annotation of src/usr.bin/usbhidaction/usbhidaction.1, Revision 1.12
1.12 ! bentley 1: .\" $OpenBSD: usbhidaction.1,v 1.11 2011/03/07 14:59:06 jasper 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: .\"
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: .\"
1.12 ! bentley 31: .Dd $Mdocdate: March 7 2011 $
1.1 nate 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
1.5 jmc 39: .Op Fl div
1.1 nate 40: .Fl c Ar config-file
41: .Fl f Ar device
42: .Ar arg ...
43: .Sh DESCRIPTION
44: .Nm
45: can be used to execute commands when certain values appear on HID controls.
46: The normal operation for this program is to read the configuration file
47: and then become a daemon and execute commands as the HID items specify.
48: If a read from the HID device fails the program dies; this will make it
49: die when the USB device is unplugged.
50: .Pp
51: The options are as follows:
52: .Bl -tag -width Ds
53: .It Fl c Ar config-file
54: Specify a path name for the config file.
55: .It Fl d
56: Toggle the daemon flag.
57: .It Fl f Ar device
1.4 jmc 58: Specify a path name for the device to operate on.
59: If
1.1 nate 60: .Ar device
1.4 jmc 61: is numeric, it is taken to be the USB HID device number.
62: If it is a relative path, it is taken to be the name of the device under
1.1 nate 63: .Pa /dev .
64: An absolute path is taken to be the literal device pathname.
1.5 jmc 65: .It Fl i
66: Ignore HID items in the config file that do not exist in the device.
1.1 nate 67: .It Fl v
68: Be verbose, and do not become a daemon.
69: .El
70: .Pp
71: The config file will be re-read if the process gets a HUP signal.
72: .Sh CONFIGURATION
1.4 jmc 73: The configuration file has a very simple format.
74: Each line describes an action; if a line begins with a whitespace
75: it is considered a continuation of the previous line.
76: Lines beginning with `#' are considered as comments.
1.1 nate 77: .Pp
78: Each line has three parts: a name of a USB HID item, a value for that item,
1.4 jmc 79: and an action.
80: There must be whitespace between the parts.
1.1 nate 81: .Pp
82: The item names are similar to those used by
83: .Xr usbhidctl 1 ,
84: but each part must be prefixed by its page name.
85: .Pp
1.4 jmc 86: The value is simply a numeric value.
87: When the item reports this value the action will be performed.
1.1 nate 88: If the value is `*' it will match any value.
89: .Pp
1.11 jasper 90: The action is a normal command that is executed by using
91: .Xr fork 2 .
1.1 nate 92: Before it is executed some substitution will occur:
93: `$n' will be replaced by the nth argument on the
94: command line, `$V' will be replaced by the numeric value
95: of the HID item, `$N' will be replaced by the name
96: of the control, and `$H' will be replaced by the name
97: of the HID device.
98: .Sh FILES
99: .Pa /usr/share/misc/usb_hid_usages
100: The HID usage table.
101: .Sh EXAMPLES
1.10 jakemsr 102: The following configuration file can be used to control the
103: master volume and muting of an
104: .Xr azalia 4
105: device using the multimedia keys on a Belkin USB keyboard.
1.1 nate 106: .Bd -literal -offset indent
1.10 jakemsr 107: # The volume range is 0..255. Moving 8 volume steps each keypress
108: # moves quickly through the volume range but still has decent
109: # granularity.
1.12 ! bentley 110: Consumer:Volume_Increment 1
1.10 jakemsr 111: mixerctl -f $1 outputs.master=+8
1.12 ! bentley 112: Consumer:Volume_Decrement 1
1.10 jakemsr 113: mixerctl -f $1 outputs.master=-8
114: Consumer:Mute 1
115: mixerctl -f $1 outputs.master.mute=toggle
1.1 nate 116: .Ed
117: .Pp
118: A sample invocation using this configuration would be
119: .Bd -literal -offset indent
1.10 jakemsr 120: $ usbhidaction -f /dev/uhid1 -c conf /dev/mixer0
1.1 nate 121: .Ed
122: .Sh SEE ALSO
123: .Xr usbhidctl 1 ,
124: .Xr usbhid 3 ,
125: .Xr uhid 4 ,
126: .Xr usb 4
127: .Sh HISTORY
128: The
129: .Nm
130: command first appeared in
131: .Ox 3.2 .
![[BACK]](/icons/back.gif){kind=icon}
Return to usbhidaction.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / usbhidaction