1 files changed, 209 insertions, 0 deletions

diff --git a/lib/vusb/examples/usbtool/Readme.txt b/lib/vusb/examples/usbtool/Readme.txt
new file mode 100644
index 000000000..33f527cc4
--- /dev/null
+++ b/lib/vusb/examples/usbtool/Readme.txt
@@ -0,0 +1,209 @@
+This is the Readme file for usbtool, a general purpose command line utility
+which can send USB requests to arbitrary devices. Usbtool is based on libusb.
+
+
+WHAT IS USBTOOL GOOD FOR?
+=========================
+When you implement a communication protocol like USB, you must usually write
+two programs: one on each end of the communication. For USB, this means that
+you must write a firmware for the device and driver software for the host.
+
+Usbtool can save you the work of writing the host software, at least during
+firmware development and testing. Usbtool can send control-in and -out
+requests to arbitrary devices and send and receive data on interrupt- and
+bulk-endpoints.
+
+Usbtool is not only a useful developer tool, it's also an example for using
+libusb for communication with the device.
+
+
+SYNOPSIS
+========
+  usbtool [options] <command>
+
+
+COMMANDS
+========
+  list
+    This command prints a list of devices found on all available USB busses.
+    Options -v, -V, -p and -P can be used to filter the list.
+
+  control in|out <type> <recipient> <request> <value> <index>
+    Sends a control-in or control-out request to the device. The request
+    parameters are:
+      type ........ Type of request, can be "standard", "class", "vendor" or
+                    "reserved". The type determines which software module in
+                    the device is responsible for answering the request:
+                    Standard requests are answered by the driver, class
+                    requests by the class implementation (e.g. HID, CDC) and
+                    vendor requests by custom code.
+      recipient ... Recipient of the request in the device. Can be "device",
+                    "interface", "endpoint" or "other". For standard and
+                    class requests, the specification defines a recipient for
+                    each request. For vendor requests, choose whatever your
+                    code expects.
+      request ..... 8 bit numeric value identifying the request.
+      value ....... 16 bit numeric value passed to the device.
+      index ....... another 16 bit numeric value passed to the device.
+    Use options -v, -V, -p and -P to single out a particular device. Use
+    options -d or -D to to send data in an OUT request. Use options -n, -O
+    and -b to determine what to do with data received in an IN request.
+
+  interrupt in|out
+    Sends or receives data on an interrupt-out resp. -in endpoint.
+    Use options -v, -V, -p and -P to single out a particular device. Use
+    options -d or -D to to send data to an OUT endpoint. Use options -n, -O
+    and -b to determine what to do with data received from an IN endpoint.
+    Use option -e to set the endpoint number, -c to choose a configuration
+    -i to claim a particular interface.
+
+  bulk in|out
+    Same as "interrupt in" and "interrupt out", but for bulk endpoints.
+
+
+OPTIONS
+=======
+Most options have already been mentioned at the commands which use them.
+here is a complete list:
+
+  -h or -?
+    Prints a short help.
+
+  -v <vendor-id>
+    Numeric vendor ID, can be "*" to allow any VID. Take only devices with
+    matching vendor ID into account.
+
+  -p <product-id>
+    Numeric product ID, can be "*" to allow any PID. Take only devices with
+    matching product ID into account.
+
+  -V <vendor-name-pattern>
+    Shell style matching pattern for vendor name. Take only devices into
+    account which have a vendor name that matches this pattern.
+
+  -P <product-name-pattern>
+    Shell style matching pattern for product name. Take only devices into
+    account which have a product name that matches this pattern.
+
+  -S <serial-pattern>
+    Shell style matching pattern for serial number. Take only devices into
+    account which have a serial number that matches this pattern.
+
+  -d <databytes>
+    Data bytes to send to the device, comma separated list of numeric values.
+    E.g.: "1,2,3,4,5".
+
+  -D <file>
+    Binary data sent to the device should be taken from this file.
+
+  -O <file>
+    Write received data bytes to the given file. Format is either hex or
+    binary, depending on the -b flag. By default, received data is printed
+    to standard output.
+
+  -b
+    Request binary output format for files and standard output. Default is
+    a hexadecimal listing.
+
+  -n <count>
+    Numeric value: Maximum number of bytes to receive. This value is passed
+    directly to the libusb API functions.
+
+  -e <endpoint>
+    Numeric value: Endpoint number for interrupt and bulk commands.
+
+  -t <timeout>
+    Numeric value: Timeout in milliseconds for the request. This value is
+    passed directly to the libusb API functions.
+
+  -c <configuration>
+    Numeric value: Interrupt and bulk endpoints can usually only be used if
+    a configuration and an interface has been chosen. Use -c and -i to
+    specify configuration and interface values.
+
+  -i <interface>
+    Numeric value: Interrupt and bulk endpoints can usually only be used if
+    a configuration and an interface has been chosen. Use -c and -i to
+    specify configuration and interface values.
+
+  -w
+    Usbtool may be too verbose with warnings for some applications. Use this
+    option to suppress USB warnings.
+
+
+NUMERIC VALUES
+==============
+All numeric values can be given in hexadecimal, decimal or octal. Hex values
+are identified by their 0x or 0X prefix, octal values by a leading "0" (the
+digit zero) and decimal values because they start with a non-zero digit. An
+optional sign character is allowed. The special value "*" is translated to
+zero and stands for "any value" in some contexts.
+
+
+SHELL STYLE MATCHING PATTERNS
+=============================
+Some options take shell style matching patterns as an argument. This refers
+to Unix shells and their file wildcard operations:
+  + "*" (asterisk character) matches any number (0 to infinite) of any
+    characters.
+  + "?" matches exactly one arbitrary character.
+  + A list of characters in square brackets (e.g. "[abc]") matches any of the
+    characters in the list. If a dash ("-") is in the list, it must be the
+    first or the last character. If a caret ("^") is in the list, it must
+    not be the first character. A closing square bracket ("]") must be the
+    first character in the list. A range of characters can be specified in
+    the way "[a-z]". This matches all characters with numeric representation
+    (usually ASCII) starting with "a" and ending with "z". The entire
+    construct matches only one character.
+  + A list of characters in square brackets starting with a caret ("^"), e.g.
+    ("[^abc]") matches any character NOT in the list. The other rules are as
+    above.
+  + "\" (backslash) followed by any character matches that following
+    character. This can be used to escape "*", "?", "[" and "\".
+
+
+BUILDING USBTOOL
+================
+Usbtool uses libusb on Unix and libusb-win32 on Windows. These libraries can
+be obtained from http://libusb.sourceforge.net/ and
+http://libusb-win32.sourceforge.net/ respectively. On Unix, a simple "make"
+should compile the sources (although you may have to edit Makefile to
+include or remove additional libraries). On Windows, we recommend that you
+use MinGW and MSYS. See the top level Readme file for details. Edit
+Makefile.windows according to your library installation paths and build with
+"make -f Makefile.windows".
+
+
+EXAMPLES
+========
+To list all devices connected to your computer, do
+
+    usbtool -w list
+
+To check whether our selection options single out the desired device, use eg.
+
+    usbtool -w -P LEDControl list
+
+This command shows all LEDControl devices connected or prints nothing if
+none is found. LEDControl is the device from the "custom-class" example.
+
+You can also send commands to the LEDControl device using usbtool. From
+the file requests.h in custom-class/firmware, we know that the set-status
+request has numeric value 1 and the get-status request is 2. See this file
+for details of the protocol used. We can therefore query the status with
+
+    usbtool -w -P LEDControl control in vendor device 2 0 0
+
+This command prints 0x00 if the LED is off or 0x01 if it is on. To turn the
+LED on, use
+
+    usbtool -w -P LEDControl control out vendor device 1 1 0
+
+and to turn it off, use
+
+    usbtool -w -P LEDControl control out vendor device 1 0 0
+
+
+----------------------------------------------------------------------------
+(c) 2008 by OBJECTIVE DEVELOPMENT Software GmbH.
+http://www.obdev.at/