Documentation

1. Getting Started

1.1 Installation

Windows users can install directly from the Microsoft Store. macOS, Linux, iOS, and Android currently require building from source with the Flutter SDK. See the Download page for platform-specific instructions and prerequisites.

1.2 Your First Flow

On launch, PingRoute opens with an empty flow tab. Type a hostname or IP into the Target Name/IP field, set a ping interval, and press the play button (or Cmd/Ctrl + R) to start probing. Hops populate as traceroute discovers them, and telemetry begins streaming immediately.

1.3 Interface Tour

• Toolbar: play/pause, target field, ping interval, latency threshold legend, and quick-access icons for diagnostics, screenshot, share, and settings.
• Stat cards: hop count, max latency, average latency, last-hop jitter, and packet loss, updated live.
• Hop table: every hop with IP, resolved name, min/max/avg/last latency, and packet loss percentage.
• Live chart: switchable between latency, jitter, packet loss, and average latency.
• Hop Inspector: click any hop number for its full metric breakdown and a dedicated trend chart.

2. Core Concepts

2.1 Flows & Tabs

A flow is a single traceroute + ping session against one target. Each flow lives in its own tab — open a new one with Cmd/Ctrl + T, close the active one with Cmd/Ctrl + W, or jump directly to tab 1–9 with Cmd/Ctrl + 1–9.

2.2 Split & Grid Views

Switch between three layouts from the toolbar at the top of the window:

• Tabs — one flow visible at a time, full detail.
• 2-Flow Split — two flows side by side for direct comparison.
• 4-Flow Grid — a 2x2 matrix. Each pane has a dropdown to assign any open tab to that slot.

2.3 Hop Table

Click any column header (IP, Hop, Name, Min, Max, Avg, Last, PL%) to sort ascending, then descending, then reset. IPv4 addresses sort numerically by octet rather than as strings, so 10.0.0.1 correctly sorts before 172.16.0.1. Right-click a header for quick filter/search and sort controls, or right-click a hop row to copy its IP, bookmark it as a target, or launch a new flow probing that specific hop.

2.4 Hop Inspector

Selecting a hop opens the Hop Inspector: jitter, latency, min/max, domain name, and packets sent/received for that hop specifically, with its own trend chart. Use the Timeframe Timeline to scrub through a flow's history, or the Incident Log to review automatically tracked packet loss and latency spike events.

2.5 IP Geolocation

Open the IP Info card on any hop to resolve it further: a map of the approximate location, ASN, ISP/organization, anycast status, and city, region, and country. Useful for spotting which network operator a slow hop belongs to without leaving the app.

2.6 Charts & Timeline

The live chart panel switches between latency, packet loss, jitter, and average latency per flow. Charts update in real time as new ping results arrive at the configured interval.

3. Advanced Usage

3.1 Target Directory

Press Cmd/Ctrl + D to open the Target Directory. Save frequently tested hosts with custom labels and favorite pins; PingRoute tracks ping counters and last-tested timestamps automatically. A LIFO history dropdown in the target bar gives instant access to recent targets without saving them permanently.

3.2 Exporting Data

Press Cmd/Ctrl + E to open the export dialog. Three formats are available:

• MTR ASCII — clean terminal-style formatted traceroute tables.
• CSV — ready for spreadsheet analysis and time-series logging.
• JSON — structured telemetry for automated pipelines.

You can also capture and share a snapshot of any flow directly from the toolbar's share icon.

3.3 System Diagnostics

Press Cmd/Ctrl + Shift + N to open System Network Diagnostics: active network interfaces, default gateway, DNS servers, and overall connectivity — useful context before you even start a trace.

4. Troubleshooting

For anything not covered here, search existing GitHub issues before filing a new one.