diff options
Diffstat (limited to 'examples/usbtool/Readme.txt')
| -rw-r--r-- | examples/usbtool/Readme.txt | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/examples/usbtool/Readme.txt b/examples/usbtool/Readme.txt new file mode 100644 index 0000000..33f527c --- /dev/null +++ b/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/ |