CHIRP

h1. DevelopersUSB Sniffing in Linux

In a nutshell:

* Run the Windows program to be sniffed under Wine

* use Tshark (or Wireshark) to capture the USB protocol interactions

* Use Tshark (or Wireshark) to filter the captured data

* Use a small program to post-process the data into an easily-read form.

h2. The Problem

To write a driver, we need to first analyze the radio's serial communications protocol. Simple methods such as interposing a sniffer system may work, but some protocols have timing constraints that cause these methods to fail. We avoid this by intercepting the communications inside of the OS. There are ways to do this inside the Windows OS, but you may prefer to use a Linux system.

h2. Approach

We will use the Wine suite in Linux to provide a Windows API environment, and then run the manufacturer's software under Wine. Wine permits the application to use the USB cable connected to Linux. Linux has a facility called usbmon that permits capture of the USB protocol as the program reads and writes the serial port. The Wireshark application (and the batch-mode Tshark application) run under linux and interact with usbmon and actually capture the data. Finally, a small port-processing application can extract the actual serial data and present it in an easily-usable fashion. 

h2. Prerequisites

* a Linux system that has usbmon support

* root login privileges

* Wine installed

* USB programming cable

* Manufacturer's radio programming application

* wireshark/tshark installed

h2. Initial setup

* Determine the Linux name of the serial cable USB device (e.g., /dev/ttyUSB0) Wine makes the Linux serial ports available as COM ports. To see the mapping, use 

<pre>

   ls -l ~/.wine/dosdevices/

</pre>

*Run the application under Wine and configure it to use the correct "Windows" COM port as supplied by Wine.

*Use the application to program your radio, to verify that everything works.

*Determine the cable's device ID. Use

<pre>

   lsusb -l

</pre>

*Exit the application

*Set up an empty directory for your capture work. Download and copy the two script files and the "tidy.c" program into your directory.

*if you only have one cable, you may choose to modify the start_trace.sh script to replace the commandline param ($1) with the device ID

*compile tidy:

<pre>

   gcc tidy.c -o tidy

</pre>

h2. Perform a capture

To perform the capture, we must start the capture program, then start the communications interaction and wait for it to finish, then stop the capture, and finally post-process the captured data.  Unfortunately, there is no obvious way to automate the timing of these steps, so you must do them manually. The capture script is capturing everything on the USB bus shared by the cable, so don't wander away to take a coffee break between the time you start the capture and the time you stop it. You can probably capture more than 30 minutes without straining your system unless the same bus is supporting HDMI, disk, or GigE.

*Open a console, navigate to your trace directory, login as root.

*run the application under Wine. Do any preliminary setup in the application, but do not communicate with the radio yet

*in the console, start the capture on your device. if the device id is 067b:

<pre>

   ./start_trace.sh 067b

</pre>

*in the application, initiate the serial data interaction

* wait for the interaction to finish

*in the console, kill the capture program. (use a ^C. Yes, it's ugly)

*note the USB device number printed by the capture script. (Yes. it's not the device ID)

*log out as root.

*(optional) exit the apllication

*run The cleanup script using the USB device nuber. If the device number is 11:

<pre>

   ./clean.sh 11

</pre>

*The captured data is in a file named "radiotrace."

h2. Other considerations

Some protocols may have tight timing constraints. While the raw capture data contains precision timestamps, the three provided scripts do not retain them. If you need this data, you must read the Tshark documentation and modify the scripts. The documentation is opaque. You may find it easier to start by using Wireshark.

Some protocols may use serial dataset signals, or change the serial I/O speed, or perform other unusual functions. These functions occurs on subdevices of the USB cable device other than the data device. the three scripts ignore these subdevices. Again, if you think you need to see this, modify the scripts and/ or use Wireshark.