1.\" $NetBSD: usbhidctl.1,v 1.22 2008/04/30 13:11:01 martin Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by David Sainty <David.Sainty@dtsp.co.nz> 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 26, 2006 31.Dt USBHIDCTL 1 32.Os 33.Sh NAME 34.Nm usbhidctl 35.Nd manipulate USB HID devices 36.Sh SYNOPSIS 37.Nm 38.Fl f Ar device 39.Op Fl t Ar table 40.Op Fl lv 41.Fl a 42.Nm 43.Fl f Ar device 44.Op Fl t Ar table 45.Op Fl v 46.Fl r 47.Nm 48.Fl f Ar device 49.Op Fl t Ar table 50.Op Fl lnv 51.Ar item Op ... 52.Nm 53.Fl f Ar device 54.Op Fl t Ar table 55.Op Fl z 56.Fl w 57.Ar item=value Op ... 58.Sh DESCRIPTION 59.Nm 60can be used to output or modify the state of a USB HID (Human Interface 61Device). 62If a list of items is present on the command line, then 63.Nm 64prints the current value of those items for the specified device. 65If the 66.Fl w 67flag is specified 68.Nm 69attempts to set the specified items to the given values. 70.Pp 71The options are as follows: 72.Bl -tag -width Ds 73.It Fl a 74Show all items and their current values. 75This option fails if the device does not support the 76.Dv GET_REPORT 77command. 78.It Fl f Ar device 79Specify a path name for the device to operate on. 80If 81.Ar device 82is numeric, it is taken to be the USB HID device number. 83If it is a relative 84path, it is taken to be the name of the device under 85.Pa /dev . 86An absolute path is taken to be the literal device pathname. 87.It Fl l 88Loop and dump the device data every time it changes. 89Only 'input' items are displayed in this mode. 90.It Fl n 91Suppress printing of the item name when querying specific items. 92Only output the current value. 93.It Fl r 94Dump the USB HID report descriptor. 95.It Fl t Ar table 96Specify a path name for the HID usage table file. 97.It Fl v 98Be verbose. 99Repeating this option increases verbosity. 100.It Fl w 101Change item values. 102Only 'output' and 'feature' kinds can be set with this 103option. 104.It Fl z 105Reset all feature and output flags to zero before attempting to change them. 106May be required for changing item values (via 107.Fl w ) 108on devices that don't implement 109.Dv GET_REPORT . 110.El 111.Sh FILES 112.Pa /usr/share/misc/usb_hid_usages 113The default HID usage table. 114.Sh SYNTAX 115.Nm 116parses the names of items specified on the command line against the human 117interface items reported by the USB device. 118Each human interface item is 119mapped from its native form to a human readable name, using the HID usage 120table file. 121Command line items are compared with the generated item names, 122and the USB HID device is operated on when a match is found. 123.Pp 124Each human interface item is named by the 125.Qq page 126it appears in, the 127.Qq usage 128within that page, and the list of 129.Qq collections 130containing the item. 131Each collection in turn is also identified by page, and 132the usage within that page. 133.Pp 134On the 135.Nm 136command line the page name is separated from the usage name with the character 137.Sq Cm \&: . 138The collections are separated by the character 139.Sq Cm \&. . 140.Pp 141As an alternative notation in items on the command line, the native numeric 142value for the page name or usage can be used instead of the full human 143readable page name or usage name. 144Numeric values can be specified in decimal, 145octal or hexadecimal. 146.Pp 147Some devices give the same name to more than one item. 148.Nm 149supports isolating each item by appending a 150.Sq Cm \&# . 151character and a decimal item instance number, starting at zero. 152.Sh EXAMPLES 153On a standard USB mouse the item 154.Dl Generic_Desktop:Mouse.Generic_Desktop:Pointer.Button:Button_2 155reflects the current status of button 2. 156The 157.Qq button 2 158item is encapsulated within two collections, the 159.Qq Mouse 160collection in the 161.Qq Generic Desktop 162page, and the 163.Qq Pointer 164collection in the 165.Qq Generic Desktop 166page. 167The item itself is the usage 168.Qq Button_2 169in the 170.Qq Button 171page. 172.Pp 173An item can generally be named by omitting one or more of the page names. 174For example the 175.Qq button 2 176item would usually just be referred to on the command line as: 177.Dl usbhidctl -f /dev/mouse Mouse.Pointer.Button_2 178.Pp 179Items can also be named by referring to parts of the item name with the 180numeric representation of the native HID usage identifiers. 181This is most 182useful when items are missing from the HID usage table. 183The page identifier for the 184.Qq Generic Desktop 185page is 1, and the usage identifier for the usage 186.Qq Button_2 187is 2, so the following can be used to refer to the 188.Qq button 2 189item: 190.Dl usbhidctl -f /dev/mouse 1:Mouse.1:Pointer.Button:2 191.Pp 192Devices with human interface outputs can be manipulated with the 193.Fl w 194option. 195For example, some USB mice have a Light Emitting Diode under software 196control as usage 2 under page 0xffff, in the 197.Qq Mouse 198collection. 199The following can be used to switch this LED off: 200.Dl usbhidctl -f /dev/mouse -w Mouse.0xffff:2=0 201.Pp 202The output below is from a device that uses the same name repeatedly. 203.Bd -literal -offset indent 204% usbhidctl -f /dev/uhid0 -a 205Consumer_Control.Volume_Up=0 206Consumer_Control.Volume_Down=0 207Consumer_Control.Mute=0 208Consumer_Control.Unassigned=0 209Consumer_Control.Unassigned=0 210.Ed 211.Pp 212The 213.Qq Consumer_Control.Unassigned 214name is used twice. 215Each can be individually accessed by providing an instance number. 216For example, to set the value for the first item: 217.Dl usbhidctl -f /dev/uhid0 -w 'Consumer_Control.Unassigned#0=1' 218.Sh SEE ALSO 219.Xr usbhidaction 1 , 220.Xr usbhid 3 , 221.Xr uhid 4 , 222.Xr usb 4 223.Sh HISTORY 224The 225.Nm 226command first appeared in 227.Nx 1.4 . 228.Sh AUTHORS 229.An David Sainty Aq David.Sainty@dtsp.co.nz 230