1.\" $NetBSD: usbhidaction.1,v 1.15 2008/04/30 13:11:01 martin Exp $ 2.\" 3.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson (lennart@augustsson.net). 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 20, 2004 31.Dt USBHIDACTION 1 32.Os 33.Sh NAME 34.Nm usbhidaction 35.Nd perform actions according to USB HID controls 36.Sh SYNOPSIS 37.Nm 38.Fl c Ar config-file 39.Op Fl d 40.Op Fl i 41.Fl f Ar device 42.Op Fl t Ar table 43.Op Fl v 44.Op Ar arg ... 45.Sh DESCRIPTION 46.Nm 47can be used to execute commands when certain values appear on HID controls. 48The normal operation for this program is to read the configuration file 49and then become a daemon and execute commands as the HID items specify. 50If a read from the HID device fails the program dies; this will make it 51die when the USB device is unplugged. 52.Pp 53The options are as follows: 54.Bl -tag -width Ds 55.It Fl c Ar config-file 56Specify a path name for the config file. 57When running as a daemon this needs to be an absolute path for the HUP 58signal to work. 59.It Fl d 60Toggle the daemon flag. 61.It Fl i 62Ignore HID items in the config file that do not exist in the device. 63.It Fl f Ar device 64Specify a path name for the device to operate on. 65If 66.Ar device 67is numeric, it is taken to be the USB HID device number. 68If it is a relative 69path, it is taken to be the name of the device under 70.Pa /dev . 71An absolute path is taken to be the literal device pathname. 72.It Fl t Ar table 73Specify a path name for the HID usage table file. 74.It Fl v 75Be verbose, and do not become a daemon. 76.El 77.Pp 78The config file will be re-read if the process gets a HUP signal. 79.Sh CONFIGURATION 80The configuration file has a very simple format. 81Each line describes an 82action; if a line begins with a whitespace it is considered a continuation 83of the previous line. 84Lines beginning with `#' are considered as comments. 85.Pp 86Each line has three parts: a name of a USB HID item, a value for that item, 87and an action. 88There must be whitespace between the parts. 89.Pp 90The item names are similar to those used by 91.Xr usbhidctl 1 , 92but each part must be prefixed by its page name 93(use the 94.Fl v 95flag to 96.Xr usbhidctl 1 97to see the page name). 98Replace spaces in the item name by underscores. 99.Pp 100The value is simply a numeric value. 101When the item reports this value 102the action will be performed. 103If the value is `*' it will match any value. 104.Pp 105The action is a normal command that is executed with 106.Xr system 3 . 107Before it is executed some substitution will occur: 108`$n' will be replaced by the nth argument on the 109command line, `$V' will be replaced by the numeric value 110of the HID item, `$N' will be replaced by the name 111of the control, and `$H' will be replaced by the name 112of the HID device. 113.Sh FILES 114.Pa /usr/share/misc/usb_hid_usages 115The HID usage table. 116.Sh EXAMPLES 117The following configuration file can be used to control a pair 118of Philips USB speakers with the HID controls on the speakers. 119.Bd -literal -offset indent 120# Configuration for various Philips USB speakers 121Consumer:Consumer_Control.Consumer:Volume_Up 1 122 mixerctl -f $1 -n -w outputs.master++ 123Consumer:Consumer_Control.Consumer:Volume_Down 1 124 mixerctl -f $1 -n -w outputs.master-- 125Consumer:Consumer_Control.Consumer:Mute 1 126 mixerctl -f $1 -n -w outputs.mute++ 127Consumer:Consumer_Control.Consumer:Channel_Top.Microsoft:Base_Up 1 128 mixerctl -f $1 -n -w outputs.bass++ 129Consumer:Consumer_Control.Consumer:Channel_Top.Microsoft:Base_Down 1 130 mixerctl -f $1 -n -w outputs.bass-- 131.Ed 132.Pp 133A sample invocation using this configuration would be 134.Bd -literal -offset indent 135usbhidaction -f /dev/uhid1 -c conf /dev/mixer1 136.Ed 137.Pp 138This configuration file can be used for various keyboards with extra keys: 139.Bd -literal -offset indent 140# Configuration for extra keyboard keys 141Consumer:Consumer_Control.Consumer:Volume_Up 1 142 mixerctl -n -w outputs.master++ 143Consumer:Consumer_Control.Consumer:Volume_Down 1 144 mixerctl -n -w outputs.master-- 145Consumer:Consumer_Control.Consumer:Mute 1 146 mixerctl -n -w outputs.mute++ 147Consumer:Consumer_Control.Consumer:Pause/Play 1 148 xmms -p 149Consumer:Consumer_Control.Consumer:Stop 1 150 xmms -s 151Consumer:Consumer_Control.Consumer:Scan_Previous_Track 1 152 xmms -r 153Consumer:Consumer_Control.Consumer:Scan_Next_Track 1 154 xmms -f 155.Ed 156.Pp 157And this configuration can be used with, e.g., 158.Bd -literal -offset indent 159usbhidaction -f /dev/uhid0 -c conf -i 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 167The 168.Nm 169command first appeared in 170.Nx 1.6 . 171