greatscottgadgets · martinling · Jul 15, 2024 · Jul 12, 2024 · Jul 13, 2024 · Jul 13, 2024
diff --git a/README.md b/README.md
@@ -2,10 +2,12 @@
 
 A fast, intuitive USB 2.0 protocol analysis application for use with [Cynthion](https://greatscottgadgets.com/cynthion/).
 
-Packetry is currently in active development and not yet ready for initial release.
-
 ![Screenshot of Packetry](screenshot.png)
 
+## Documentation
+
+Read the latest [Packetry Documentation](https://packetry.readthedocs.io/).
+
 ## Development
 
 Packetry is written in [Rust](https://rust-lang.org/), with its GUI using [GTK 4](https://gtk.org) via the [gtk-rs](https://gtk-rs.org/) bindings.

diff --git a/docs/images/action-bar.png b/docs/images/action-bar.png
diff --git a/docs/images/cynthion-connections-packetry.svg b/docs/images/cynthion-connections-packetry.svg
diff --git a/docs/images/device-pane.png b/docs/images/device-pane.png
diff --git a/docs/images/status-bar.png b/docs/images/status-bar.png
diff --git a/docs/images/traffic-pane.png b/docs/images/traffic-pane.png
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
 sphinx==7.2.6
-sphinx_rtd_theme==1.3.0
+sphinx_rtd_theme==2.0.0
 readthedocs-sphinx-search==0.3.2
+sphinx-inline-tabs==2023.4.21
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -7,7 +7,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Packetry'
-copyright = '2023, Great Scott Gadgets'
+copyright = '2023-2024, Great Scott Gadgets'
 author = 'Great Scott Gadgets'
 
 version = ''
@@ -17,14 +17,15 @@
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-  'sphinx.ext.autodoc'
+    'sphinx.ext.autodoc',
+    'sphinx_inline_tabs',
 ]
 
 templates_path = ['_templates']
 exclude_patterns = ['_build']
 source_suffix = '.rst'
 master_doc = 'index'
-language = None
+language = 'en'
 exclude_patterns = []
 pygments_style = None
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,9 +1,16 @@
 ======================
-Documentation
+Packetry Documentation
 ======================
 
 .. toctree::
   :maxdepth: 2
-  :caption: User Documentation
+  :caption: Introduction
 
-  introToPacketry
+  what_is_packetry
+  user_interface
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Quick Start
+
+  quick_start
diff --git a/docs/source/introToPacketry.rst b/docs/source/introToPacketry.rst
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst
@@ -0,0 +1,193 @@
+=============================
+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 <https://cynthion.readthedocs.io/en/latest/getting_started.html>`__ and then ensure that your Cynthion is up to date by running:
+
+.. code::
+
+   cynthion update
+
+
+Install Packetry
+----------------
+
+.. tab:: Linux
+
+    .. tab:: Pre-built
+
+        AppImage coming soon! For now you can build and install from source code.
+
+    .. tab:: From source code
+
+        **Install Prerequisites**
+
+        Install the Rust build tools, other essential build tools, and GTK 4 headers:
+
+        .. tab:: Debian/Ubuntu
+
+            .. code::
+
+                apt install rustc cargo build-essential libgtk-4-dev git
+
+        .. tab:: Fedora
+
+            .. code::
+
+                yum install rust cargo make gcc gcc-c++ gtk4-devel pango-devel git
+
+        Note that Packetry requires a minimum Rust version of 1.74. If your distribution's packages are older than this, use `rustup <https://rustup.rs/>`__ to get the latest Rust toolchain and manage your Rust installation.
+
+        **Download Packetry Source Code**
+
+        Clone the Packetry repository:
+
+        .. code::
+
+            git clone https://github.com/greatscottgadgets/packetry.git
+
+        **Build and Install Packetry**
+
+        .. code::
+
+            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.
+
+.. tab:: macOS
+
+    .. tab:: Pre-built
+
+        Homebrew installation coming soon! For now you can build and install from source code.
+
+    .. tab:: From source code
+
+        **Install Prerequisites**
+
+        Use `rustup <https://rustup.rs/>`__ to install the latest Rust toolchain and manage your Rust installation.
+
+        Use `Homebrew <https://brew.sh/>`__ to install GTK 4:
+
+        .. code::
+
+            brew install gtk4
+
+        **Download Packetry Source Code**
+
+        Clone the Packetry repository:
+
+        .. code::
+
+            git clone https://github.com/greatscottgadgets/packetry.git
+
+        **Build and Install Packetry**
+
+        .. code::
+
+            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.
+
+.. tab:: Windows
+
+    .. tab:: Pre-built
+
+        Download and run the Windows installer from the `latest release <https://github.com/greatscottgadgets/packetry/releases/latest>`__.
+
+    .. tab:: 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 <https://vcpkg.io/en/>`__:
+
+        .. code:: bat
+
+            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:
+
+        .. code:: bat
+
+            vcpkg install gtk pkgconf
+
+        Set environment variables so that Packetry can find its dependencies:
+
+        .. code:: bat
+
+            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:
+
+        .. code:: bat
+
+            git clone https://github.com/greatscottgadgets/packetry.git
+
+        **Build and Install Packetry**
+
+        .. code:: bat
+
+            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
+----------------
+
+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 <https://github.com/greatscottgadgets/packetry/issues/122>`__.
+
+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.
+
+.. image:: ../images/cynthion-connections-packetry.svg
+  :width: 800
+  :alt: Connection diagram for using Cynthion with Packetry.
+
+
+Launch Packetry
+---------------
+
+Run the Packetry executable:
+
+.. code::
+
+    packetry
+
+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, use the Scan Button to search for a capture device.
+
+Select the target device speed from the Speed Drop-down. If you don't know the target speed, try each speed until you find the one that works for your device. (Automatic speed detection coming soon!)
+
+Click the Capture Button.
+
+If the target device is not already connected to TARGET A, connect it now.
diff --git a/docs/source/user_interface.rst b/docs/source/user_interface.rst
@@ -0,0 +1,54 @@
+==============
+User Interface
+==============
+
+Action Bar
+----------
+
+Across the top of the Packetry window is the Action Bar used to control Packetry.
+
+.. image:: ../images/action-bar.png
+  :alt: Action Bar
+
+- **Open Button**: 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.
+- **Scan Button**: Searches for a capture device such as a Cynthion running analyzer gateware.
+- **Capture Button**: Starts capturing USB data with the connected capture device.
+- **Stop Button**: Stops capturing USB data.
+- **Device Drop-down**: Selects a capture device. If you don't see a device listed here, try using the Scan button.
+- **Speed Drop-down**: Selects the target device speed for live capture.
+
+
+Traffic Pane
+------------
+
+Beneath the Action Bar is the Traffic Pane. This is Packetry's main view of captured USB data.
+
+.. image:: ../images/traffic-pane.png
+  :alt: Traffic Pane
+
+The Traffic Pane displays packets in an interactive hierarchical view, allowing you to expand high level events to explore their constituent low level transactions and packets.
+
+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.
+
+
+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.
+
+.. image:: ../images/device-pane.png
+  :alt: Device Pane
+
+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.
+
+
+Status Bar
+----------
+
+At the bottom of the Packetry window is the Status Bar.
+
+.. image:: ../images/status-bar.png
+  :alt: Status Bar
+
+The Status Bar tells you what Packetry is doing.
diff --git a/docs/source/what_is_packetry.rst b/docs/source/what_is_packetry.rst
@@ -0,0 +1,5 @@
+=================
+What is Packetry?
+=================
+
+Packetry is a fast, intuitive USB 2.0 protocol analysis application for use with `Cynthion <https://greatscottgadgets.com/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.