trellis-logic/pyusb_pcap_replay

A python project to replay USB scripts captured by wireshark and usbpcap

Pyusb Pcap Replay Overview and Purpose

This repository contains scripts originally written for bare metal programming of the TI AM3517, a replacement for the TI's FLASHTOOL. The TI FLASHTOOL only supports specific host platforms (XP and Windows 7 32 bit). The scripts allow you to perform the same functions on any system with support for python and pyusb. See this thread for more information about the motivation and usage with the TI AM3517

Although it was originally intended for replacing the TI flash tool, this repository will be useful in any case that you'd like to replay a USB sequence captured from another device with usbpcap, possibly useful for other obsolete and no longer supported manufacturing tools. You just need to set the VID and PID appropriately in usb_replay.py to correspond to other devices

Installing

Windows

1. Install Python and ensure it is in your PATH
2. Open a git command prompt as Administrator (Git Bash, right click->Open as Administrator) and cd to the scripts directory
3. Run ./install_windows.sh
4. Download the zadig tool.
5. Open Zadig and select Device->Load Preset Device
6. Select the zadig.cfg file in the "config" directory of this repo
7. Click "Install Driver"

Windows 8.1 or later instructions

1. On Windows 8.1 or later, you will need to disable the BOS descriptor enumeration using a special registry key. This is only necessary for the TI AM3517 bootloader, which doesn't support this descriptor.

• Open regedit and go to HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\usbflags\0451D0090000 (create this key if it doesn't exist).
• Add a Binary value with name "SkipBOSDescriptorQuery" and value 01 00 00 00
• On Windows 8.1 you may also need to install KB 2967917. This is not needed on Windows 10.
• See the video at this link for details.

Setup Capture

• Start by capturing a sequence of the programming operations performed by TIs FLASHTOOL. Install this tool on a Windows XP or Windows 7 32 bit system.
• Download and install wireshark and usbpcap. Use the instructions on the usbpcap site to configure usbpcap settings.

Run Capture

1. Start the capture on the usbpcap endpoint configured in the previous step.
2. Run the TI Flash utility to capture the event you'd like to replay.
3. Filter the trace to only contain data for the specified device if more than one device is included on the root hub. Use a filter like:

usb.src == "2.3.0" || usb.src == "2.3.1" || usb.dst == "2.3.0" || usb.dst == "2.3.1"

Where 2.3.0 and 2.3.1 are the endpoints shown in the wireshark "Source" and "Destination" columns for the device you want to capture. 4. Use File->Export Specified Packets to export the filtered data to a .pcap file. 5. Open the pcap file with filtered content 6. Export to the PDML format in wireshark using File->Export Packet Dissections->as XML - "PDML" packet details file rt to this format using File->Export Packet Dissections->as XML - "PDML" packet details file

• Make sure "Packet Details" include "All expanded"
• Make sure "Packet Bytes" checkbox is checked.
• Make sure "Packet Details" include "All expanded"
• Make sure "Packet Bytes" checkbox is checked.

Replay capture file

Once you've captured the file on the XP or Windows 7 32 bit machine, you can replay the trace on any system supporting python and pyusb

1. Connect the usb otg port to the PC
2. Run python usb_replay.py <path_to_pdml_file> where <path_to_pdml_file> is the path to the file captured using pcap and expored to PDML as described above.
3. Connect the device when prompted by the script.
4. When using the development board, ensure the dip switches are set such that USB boot attempts will occur early in the boot sequence. Switch setting 1 and 4 on puts USB boot first in the boot sequence.

Troubleshooting/Known Issues

• On my Windows 10 system, approximately 1 in 10 attempts I see a USBError during initial enumeration. Errors are "Access denied (insufficient permissions)"
• If you see "Entity Not Found" continuously, retry the Zadig driver install steps.

pyusb_pcap_replay's Issues

usb.core.USBError: [Errno 110] Operation timed out

Hi, thanks for writing this! I had generated a pcap file (generated by usbpcap) from sniffing this USB development board that only supports Windows currently. I converted the PCAP to PDML using Wireshark on Windows. I'm trying to reverse engineer the protocol so it can work on Raspbian.

However I get this error while I try to replay the file on Raspberry Pi running Raspbian,

pi@sdpcontrol:~/Downloads/pyusb_pcap_replay-master/scripts $ sudo python usb_replay.py sdph11.pdml 
Please power down device to start
Please power on device with USB connected
Found device with VID 1110 and PID 46635
Traceback (most recent call last):
  File "usb_replay.py", line 129, in <module>
    USBReplay(VID,PID).replay(PDMLParse(sys.argv[1]))
  File "usb_replay.py", line 116, in replay
    self.do_replay_sequence(pdml)
  File "usb_replay.py", line 97, in do_replay_sequence
    buffer=dev_dict['dev'].read(dev_dict['epin'],len_bytes,DEFAULT_TIMEOUT_MS)
  File "/usr/local/lib/python2.7/dist-packages/usb/core.py", line 988, in read
    self.__get_timeout(timeout))
  File "/usr/local/lib/python2.7/dist-packages/usb/backend/libusb1.py", line 833, in bulk_read
    timeout)
  File "/usr/local/lib/python2.7/dist-packages/usb/backend/libusb1.py", line 936, in __read
    _check(retval)
  File "/usr/local/lib/python2.7/dist-packages/usb/backend/libusb1.py", line 595, in _check
    raise USBError(_strerror(ret), ret, _libusb_errno[ret])
usb.core.USBError: [Errno 110] Operation timed out

After this I made a slight modification to line 97,

try:
    buffer=dev_dict['dev'].read(dev_dict['epin'],len_bytes,DEFAULT_TIMEOUT_MS)
except:
    print "timeout probably with ", packet
    pass

and similar change in the next occurrence of DEFAULT_TIMEOUT_MS

Running the program now gives me a different error,

pi@sdpcontrol:~/Downloads/pyusb_pcap_replay-master/scripts $ sudo python usb_replay.py sdph11.pdml 
Please power down device to start
Please power on device with USB connected
Found device with VID 1110 and PID 46635
timeout probably with  {'data': '0800', 'direction': 'in', 'type': 'bulk'}
Traceback (most recent call last):
  File "usb_replay.py", line 137, in <module>
    USBReplay(VID,PID).replay(PDMLParse(sys.argv[1]))
  File "usb_replay.py", line 124, in replay
    self.do_replay_sequence(pdml)
  File "usb_replay.py", line 104, in do_replay_sequence
    raise USBReplayException("Expected data " + packet['data'].upper() + " with length " + str(len(packet['data'])/2) + " bytes but found " + asciibuffer.upper() + " at packet " + str(packet_count))
__main__.USBReplayException: Expected data 0800 with length 2 bytes but found 01500080000101000001000800F60107194B328CCE416E616C6F672044657669636573C6414437363236C0CF4556414C2D414437363236464D435AC0020030C100000000009201020DFDF30300000000000000000000000001020DFCF40400000000000000000000000001020DFBF50500000000000000000000000002020D0CE300FA0000004A0100000000A00F02020D5B94014A0129016B0100000000B80B02020DF6F902B0043804280500000000E803FA020B3FBAA21200000C010000000000FA82043C44A2120010FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 at packet 13

If you need the device descriptors for the device, here they are.