Packetry Documentation

What is Packetry?

Packetry is a fast, intuitive USB 2.0 protocol analysis application for use with Cynthion or for exploring previously captured USB traffic. Designed from the ground up to handle the challenges of USB analysis, Packetry enables live capture and visual representation of physical layer packet data for High Speed (480 Mbps), Full Speed (12 Mbps), and Low Speed (1.5 Mbps) USB.

User Interface

Action Bar

Across the top of the Packetry window is the Action Bar used to control Packetry.

• Open Button: Clears Traffic Pane and Device Pane and loads a .pcap file with the LINKTYPE_USB_2_0 link-layer header type.

• Save Button: Saves a .pcap file with the LINKTYPE_USB_2_0 link-layer header type.

• Capture Button: Clears Traffic Pane and Device Pane and starts capturing USB data with the connected capture device.

• Stop Button: Stops capturing USB data. Stops reading USB data from file.

• Device Drop-down: Selects a capture device. This list is updated automatically as devices are attached or unplugged.

• Speed Drop-down: Selects the target device speed for live capture.

• Target Power Switch: Turns on or off power to the target device (requires a Cynthion analyzer and suitable gateware).

• Power Menu: Where target power control is available, opens a menu for additional power control settings.

Traffic Pane

Beneath the Action Bar is the Traffic Pane. This is Packetry’s main view of captured USB data. At the top of the Traffic Pane there are buttons to switch between different views of the captured data.

Each packet is displayed with a precise time stamp relative to the start of capture. Higher level groups have a time stamp matching the first packet that is a part of the group.

The Traffic Pane is cleared at the start of each capture or when a file is loaded.

Hierarchical View

This displays an interactive hierarchical view, allowing you to expand high level events to explore their constituent low level transactions and packets.

Note

Since multiple high level events can be happening at the same time, this view may show packets out of chronological order. An interleaved view that still shows packets in order is in progress, tracked here: https://github.com/greatscottgadgets/packetry/pull/150

Transactions View

This combines packets into expandable groups for each USB transaction. It is more verbose than the hierarchical view, but guarantees that all items are shown in chronological order.

Packets View

This shows all packets captured on the wire in order, with no grouping.

Device Pane

To the right of the Traffic Pane is the Device Pane. The Device Pane summarizes information about observed USB devices on the target bus.

Much of the information that can be displayed in the Device Pane is discovered only if Packetry observes the initial enumeration of a USB device by the target host. To allow this to take place in a live capture, connect the target device after starting a capture, not before.

The Device Pane is cleared at the start of each capture or when a file is loaded.

Detail Pane

The Detail Pane is located below the Traffic Pane. It provides a detailed view of an item selected in the Traffic Pane and allows copying of data from that item.

Depending on the item selected, the Detail Pane may provide different information. For example, when a string descriptor request transfer is selected, the Detail Pane summarizes the request including the actual string as text. By expanding that transfer in the Traffic Pane you can select a transaction or packet within the transfer to view packet data in hexadecimal in the Detail Pane.

Status Bar

At the bottom of the Packetry window is the Status Bar.

The Status Bar tells you what Packetry is doing.

Keyboard Shortcuts - Linux & Windows

General

Keypress	Command
Ctrl + O	Open capture file
Ctrl + E	Interrupt loading of a large capture file
Ctrl + S	Save current capture to file

Live Capture

Keypress	Command
Ctrl + B	Begin live capture
Ctrl + E	End live capture

Keyboard Shortcuts - macOS

General

Keypress	Command
⌘ + O	Open capture file
⌘ + E	Interrupt loading of a large capture file
⌘ + S	Save current capture to file

Live Capture

Keypress	Command
⌘ + B	Begin live capture
⌘ + E	End live capture

Getting Started with Packetry

Follow these steps to start analyzing live USB traffic with Packetry and Cynthion. If you want to use Packetry only to view existing capture files, you can skip the Cynthion steps.

Install Cynthion

Before installing Packetry, follow the instructions to install Cynthion host software and then ensure that your Cynthion is up to date by running:

cynthion update

Install Packetry

Linux

Pre-built

Download packetry-x86_64.AppImage from the latest release. Follow the AppImage Quickstart instructions to make the file executable.

From source code

Install Prerequisites

Install the Rust build tools, other essential build tools, and GTK 4 headers:

Debian/Ubuntu

apt install rustc cargo build-essential libgtk-4-dev git

Fedora

yum install rust cargo make gcc gcc-c++ gtk4-devel pango-devel git

Note that Packetry requires a minimum Rust version of 1.85.1. If your distribution’s packages are older than this, use rustup to get the latest Rust toolchain and manage your Rust installation.

Download Packetry Source Code

Clone the Packetry repository:

git clone https://github.com/greatscottgadgets/packetry.git

Build and Install Packetry

cd packetry
cargo build --release
sudo cp target/release/packetry /usr/local/bin

Hint: You can copy the packetry executable to any directory in your PATH instead of /usr/local/bin. If you’ve used rustup and have ~/.cargo/bin in your PATH, ~/.cargo/bin is a great choice!

Note: Do not build with --all-features. All the optional features currently in the package are for debug/test purposes only, and will prevent or degrade normal use of the application if enabled. See Cargo.toml for details.

macOS

Pre-built

Use Homebrew to install Packetry:

brew install packetry

From source code

Install Prerequisites

Use rustup to install the latest Rust toolchain and manage your Rust installation.

Use Homebrew to install GTK 4:

brew install gtk4

Download Packetry Source Code

Clone the Packetry repository:

git clone https://github.com/greatscottgadgets/packetry.git

Build and Install Packetry

cd packetry
cargo build --release
cp target/release/packetry ~/.cargo/bin

Hint: You can copy the packetry executable to any directory in your PATH instead of ~/.cargo/bin. If you’ve used rustup, ~/.cargo/bin should be in your PATH. Otherwise /usr/local/bin is a great choice!

Note: Do not build with --all-features. All the optional features currently in the package are for debug/test purposes only, and will prevent or degrade normal use of the application if enabled. See Cargo.toml for details.

Windows

Pre-built

Download and run the Windows installer from the latest release.

From source code

Install Prerequisites

Building Packetry requires that the GTK 4 libraries and header files are available and discoverable via the pkg-config mechanism. There are several ways you can arrange this; if in doubt we suggest using vcpkg:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
bootstrap-vcpkg.bat

This next step will take a while. It builds and installs GTK and all its dependencies from source:

vcpkg install gtk pkgconf

Set environment variables so that Packetry can find its dependencies:

set PKG_CONFIG=%CD%\installed\x64-windows\tools\pkgconf\pkgconf.exe
set PKG_CONFIG_PATH=%CD%\installed\x64-windows\lib\pkgconfig
set PATH=%PATH%;%CD%\installed\x64-windows\bin
cd ..

These environment variables will only persist for the lifetime of the current command window, so you may want to set them up elsewhere for future use.

Download Packetry Source Code

Clone the Packetry repository:

git clone https://github.com/greatscottgadgets/packetry.git

Build and Install Packetry

cd packetry
cargo build --release
set PATH=%PATH%;%CD%\target\release

This PATH modification will only persist for the lifetime of the current command window, so you may want to set it up elsewhere for future use. Alternatively you can copy target\release\packetry to a location already in your PATH.

Note: Do not build with --all-features. All the optional features currently in the package are for debug/test purposes only, and will prevent or degrade normal use of the application if enabled. See Cargo.toml for details.

Connect Cynthion

Cynthion enables analysis of a USB connection between a target host and a target device. This connection passes through Cynthion’s TARGET A and TARGET C ports. Cynthion watches the traffic on this connection and sends the observed packet data over the CONTROL port for analysis in Packetry.

Connect Cynthion’s CONTROL port to your analysis host computer running Packetry. Connect TARGET C to your target host computer. If your target host and analysis host are the same computer, please be aware of this issue.

You can connect Cynthion’s TARGET A port to your target device at this time, but you may wish to delay this connection until after Packetry is capturing. This will ensure that Packetry can observe the entire device enumeration process and is able to provide detailed information in the Device Pane.

Launch Packetry

Run the Packetry executable. The Packetry window should appear.

Start Capturing USB Traffic

Make sure that “Cynthion” is selected in the Device Drop-down. If this list is empty, check that your Cynthion is connected via its CONTROL port and is running the USB analyzer gateware.

Click the Capture Button.

If the target device is not already connected to TARGET A, connect it now.