# 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.