Readme.txt 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209
  1. This is the Readme file for usbtool, a general purpose command line utility
  2. which can send USB requests to arbitrary devices. Usbtool is based on libusb.
  3. WHAT IS USBTOOL GOOD FOR?
  4. =========================
  5. When you implement a communication protocol like USB, you must usually write
  6. two programs: one on each end of the communication. For USB, this means that
  7. you must write a firmware for the device and driver software for the host.
  8. Usbtool can save you the work of writing the host software, at least during
  9. firmware development and testing. Usbtool can send control-in and -out
  10. requests to arbitrary devices and send and receive data on interrupt- and
  11. bulk-endpoints.
  12. Usbtool is not only a useful developer tool, it's also an example for using
  13. libusb for communication with the device.
  14. SYNOPSIS
  15. ========
  16. usbtool [options] <command>
  17. COMMANDS
  18. ========
  19. list
  20. This command prints a list of devices found on all available USB busses.
  21. Options -v, -V, -p and -P can be used to filter the list.
  22. control in|out <type> <recipient> <request> <value> <index>
  23. Sends a control-in or control-out request to the device. The request
  24. parameters are:
  25. type ........ Type of request, can be "standard", "class", "vendor" or
  26. "reserved". The type determines which software module in
  27. the device is responsible for answering the request:
  28. Standard requests are answered by the driver, class
  29. requests by the class implementation (e.g. HID, CDC) and
  30. vendor requests by custom code.
  31. recipient ... Recipient of the request in the device. Can be "device",
  32. "interface", "endpoint" or "other". For standard and
  33. class requests, the specification defines a recipient for
  34. each request. For vendor requests, choose whatever your
  35. code expects.
  36. request ..... 8 bit numeric value identifying the request.
  37. value ....... 16 bit numeric value passed to the device.
  38. index ....... another 16 bit numeric value passed to the device.
  39. Use options -v, -V, -p and -P to single out a particular device. Use
  40. options -d or -D to to send data in an OUT request. Use options -n, -O
  41. and -b to determine what to do with data received in an IN request.
  42. interrupt in|out
  43. Sends or receives data on an interrupt-out resp. -in endpoint.
  44. Use options -v, -V, -p and -P to single out a particular device. Use
  45. options -d or -D to to send data to an OUT endpoint. Use options -n, -O
  46. and -b to determine what to do with data received from an IN endpoint.
  47. Use option -e to set the endpoint number, -c to choose a configuration
  48. -i to claim a particular interface.
  49. bulk in|out
  50. Same as "interrupt in" and "interrupt out", but for bulk endpoints.
  51. OPTIONS
  52. =======
  53. Most options have already been mentioned at the commands which use them.
  54. here is a complete list:
  55. -h or -?
  56. Prints a short help.
  57. -v <vendor-id>
  58. Numeric vendor ID, can be "*" to allow any VID. Take only devices with
  59. matching vendor ID into account.
  60. -p <product-id>
  61. Numeric product ID, can be "*" to allow any PID. Take only devices with
  62. matching product ID into account.
  63. -V <vendor-name-pattern>
  64. Shell style matching pattern for vendor name. Take only devices into
  65. account which have a vendor name that matches this pattern.
  66. -P <product-name-pattern>
  67. Shell style matching pattern for product name. Take only devices into
  68. account which have a product name that matches this pattern.
  69. -S <serial-pattern>
  70. Shell style matching pattern for serial number. Take only devices into
  71. account which have a serial number that matches this pattern.
  72. -d <databytes>
  73. Data bytes to send to the device, comma separated list of numeric values.
  74. E.g.: "1,2,3,4,5".
  75. -D <file>
  76. Binary data sent to the device should be taken from this file.
  77. -O <file>
  78. Write received data bytes to the given file. Format is either hex or
  79. binary, depending on the -b flag. By default, received data is printed
  80. to standard output.
  81. -b
  82. Request binary output format for files and standard output. Default is
  83. a hexadecimal listing.
  84. -n <count>
  85. Numeric value: Maximum number of bytes to receive. This value is passed
  86. directly to the libusb API functions.
  87. -e <endpoint>
  88. Numeric value: Endpoint number for interrupt and bulk commands.
  89. -t <timeout>
  90. Numeric value: Timeout in milliseconds for the request. This value is
  91. passed directly to the libusb API functions.
  92. -c <configuration>
  93. Numeric value: Interrupt and bulk endpoints can usually only be used if
  94. a configuration and an interface has been chosen. Use -c and -i to
  95. specify configuration and interface values.
  96. -i <interface>
  97. Numeric value: Interrupt and bulk endpoints can usually only be used if
  98. a configuration and an interface has been chosen. Use -c and -i to
  99. specify configuration and interface values.
  100. -w
  101. Usbtool may be too verbose with warnings for some applications. Use this
  102. option to suppress USB warnings.
  103. NUMERIC VALUES
  104. ==============
  105. All numeric values can be given in hexadecimal, decimal or octal. Hex values
  106. are identified by their 0x or 0X prefix, octal values by a leading "0" (the
  107. digit zero) and decimal values because they start with a non-zero digit. An
  108. optional sign character is allowed. The special value "*" is translated to
  109. zero and stands for "any value" in some contexts.
  110. SHELL STYLE MATCHING PATTERNS
  111. =============================
  112. Some options take shell style matching patterns as an argument. This refers
  113. to Unix shells and their file wildcard operations:
  114. + "*" (asterisk character) matches any number (0 to infinite) of any
  115. characters.
  116. + "?" matches exactly one arbitrary character.
  117. + A list of characters in square brackets (e.g. "[abc]") matches any of the
  118. characters in the list. If a dash ("-") is in the list, it must be the
  119. first or the last character. If a caret ("^") is in the list, it must
  120. not be the first character. A closing square bracket ("]") must be the
  121. first character in the list. A range of characters can be specified in
  122. the way "[a-z]". This matches all characters with numeric representation
  123. (usually ASCII) starting with "a" and ending with "z". The entire
  124. construct matches only one character.
  125. + A list of characters in square brackets starting with a caret ("^"), e.g.
  126. ("[^abc]") matches any character NOT in the list. The other rules are as
  127. above.
  128. + "\" (backslash) followed by any character matches that following
  129. character. This can be used to escape "*", "?", "[" and "\".
  130. BUILDING USBTOOL
  131. ================
  132. Usbtool uses libusb on Unix and libusb-win32 on Windows. These libraries can
  133. be obtained from http://libusb.sourceforge.net/ and
  134. http://libusb-win32.sourceforge.net/ respectively. On Unix, a simple "make"
  135. should compile the sources (although you may have to edit Makefile to
  136. include or remove additional libraries). On Windows, we recommend that you
  137. use MinGW and MSYS. See the top level Readme file for details. Edit
  138. Makefile.windows according to your library installation paths and build with
  139. "make -f Makefile.windows".
  140. EXAMPLES
  141. ========
  142. To list all devices connected to your computer, do
  143. usbtool -w list
  144. To check whether our selection options single out the desired device, use eg.
  145. usbtool -w -P LEDControl list
  146. This command shows all LEDControl devices connected or prints nothing if
  147. none is found. LEDControl is the device from the "custom-class" example.
  148. You can also send commands to the LEDControl device using usbtool. From
  149. the file requests.h in custom-class/firmware, we know that the set-status
  150. request has numeric value 1 and the get-status request is 2. See this file
  151. for details of the protocol used. We can therefore query the status with
  152. usbtool -w -P LEDControl control in vendor device 2 0 0
  153. This command prints 0x00 if the LED is off or 0x01 if it is on. To turn the
  154. LED on, use
  155. usbtool -w -P LEDControl control out vendor device 1 1 0
  156. and to turn it off, use
  157. usbtool -w -P LEDControl control out vendor device 1 0 0
  158. ----------------------------------------------------------------------------
  159. (c) 2008 by OBJECTIVE DEVELOPMENT Software GmbH.
  160. http://www.obdev.at/