usr.bin/usbhidctl/usbhidctl.1

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