Metadata-Version: 1.1
Name: usbrply
Version: 2.0.1
Summary: Replay captured USB packets from .pcap file.
Home-page: https://github.com/JohnDMcMaster/usbrply
Author: John McMaster
Author-email: JohnDMcMaster@gmail.com
License: BSD
Description: # usbrply
        
        Convert a .pcap file (captured USB packets) to Python or C code that replays the captured USB commands.
        
        Supported packet sources are:
        * Linux Wireshark (via usbmon)
        * Windows Wireshark (via USBPcap)
        
        Supported output formats are:
        * libusb Python (primary)
        * (libusb C: fixme)
        * (Linux Kernel C: fixme)
        * JSON
        
        Example applications:
        * Rapidly reverse engineer and re-implement USB protocols
        * Record a proprietary Windows programming sequence and replay on an embedded Linux device
        * Snoop USB-serial packets
        
        Questions? Please reach out on github or join #usbrply on Freenode IRC
        
        # Installation
        Its currenlty only tested under Ubuntu Linux, but probably works under Windows.
        If someone sends instructions I'll add them here
        
        ```
        # Do one of these
        # Easier to setup, but slower
        sudo pip install python-pcapng
        # Much faster, but no longer maintained
        sudo apt-get install -y python-libpcap
        git clone https://github.com/JohnDMcMaster/usbrply.git
        cd usbrply
        sudo python setup.py install
        ```
        
        # Sample workflows
        
        Sample workflow for capturing Windows traffic and replaying traffic in Python:
        * Install Wireshark. Make sure you install the USBPcap library
        * Start Wireshark
        * Connect USB device to computer
        * Start catpure
        * Start your application, do your thing, etc to generate packets
        * Close application
        * Stop capture
        * Save capture. Save in pcap-ng format (either should work)
        * Close Wireshark
        * Run: "usbrply --device-hi -p my.pcapng >replay.py"
        * Linux: run "python replay.py"
        * Verify expected device behavior. Did an LED blink? Did you get expected data back?
        
        Sample workflow for capturing Windows VM traffic from Linux host and replaying traffic in Python:
        * Example: program a Xilinx dev board under Linux without knowing anything about the JTAG adapter USB protocol
        * Linux: Install Wireshark
        * Linux: Enable usbmon so Wireshark can capture USB (sudo modprobe usbmon, see http://wiki.wireshark.org/CaptureSetup/USB)
        * Linux: Boot Windows VM (ie through VMWare)
        * Linux: Start Wireshark. Make sure you have USB permissions (ie you may need to sudo)
        * Connect USB device to computer
        * Linux: use lsusb to determine which device bus is on. Try to choose a bus (port) with no other devices
        * Linux: start catpure on bus from above
        * Linux: attach USB device to Windows guest
        * Windows: start your application, do your thing, etc to generate packets
        * Linux: stop capture
        * Linux: save capture. Save in pcap-ng format (either should work)
        * Linux: run: "usbrply --device-hi -p my.pcapng >replay.py"
        * Linux: detatch USB device from Windows guest
        * Linux: run "python replay.py"
        * Verify expected device behavior. Did an LED blink? Did you get expected data back?
        
        You may need to filter out USB devices. There are two ways to do this:
        * --device-hi: use the last device enumerated. This works well in most cases, including FX2 renumeration
        * --device DEVICE: manually specify the USB device used. Get this from lsusb output or Wireshark view
        
        Other useful switches:
        * --rel-pkt: intended to easier allow diffing two outputs. Ex: what changed in trace for LED on vs LED off?
        * --no-packet-numbers: alternative to above
        * --fx2: decode common FX2 commands (ex: CPU reset)
        * --range RANGE: only decode a specific packet range. Use along with Wireshark GUI or refine a previous decode
        * see --help for more
        
        
        # JSON output
        
        use -j switch to output a parsing intermediate representation that should resemble original USB requests
        along with associated metadata.
        This can be used in more advanced applications, such as if you need to decode a complicated protocol
        or convert USB output to higher level API calls.
        An example can be found here: https://github.com/ProgHQ/bpmicro/blob/master/scrape.py
        This example first aggregates USB packets into application specific packets, and then decodes these into API calls
        
        
        # USB serial decoder
        
        usbrply-serial supported adapters:
          * FT2232C: data rx/tx
        
        TODO: write doc
        
        
Keywords: libusb pcap
Platform: UNKNOWN
Classifier: License :: OSI Approved :: BSD License
