macusbdb/adb2usb/uart2usb/vusb-20100715/examples/usbtool

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/