RouteWave User Guide

🚀 Get Running

One command installs the RouteRTL SDK and launches RouteWave. The binary is auto-downloaded on first use — no manual setup.

Install

# Install the RouteRTL SDK (includes RouteWave)
pip install routertl

# Launch RouteWave
rr routewave

First Launch

Open RouteWave with a waveform file to jump straight into analysis. It accepts VCD, FST, GHW, and ILA CSV formats.

# Open a VCD from simulation
rr routewave my_design.vcd

# Open an FST (GTKWave-compatible)
rr routewave capture.fst

# Run simulation and auto-open the result
rr sim my_testbench --view

# Or open the latest waveform from a previous run
rr waves

At launch, the Signal Hierarchy panel loads the full design tree. Double-click any signal to add it to the waveform view.

WSL2 (Windows)

RouteWave runs natively on WSL2. A fresh Ubuntu install needs OpenGL libraries first — one line, then you're set.

# Install OpenGL libs (required once on fresh WSL2 Ubuntu)
sudo apt install libopengl0 libgl1 libglx-mesa0 libegl1

# Windows 11 — WSLg handles display automatically
rr routewave

# Windows 10 — install VcXsrv first, then:
export DISPLAY=$(ip route list default | awk '{print $3}'):0
rr routewave

🖥 The Layout

RouteWave has four main panels. Understanding where things live will make everything else in this guide click.

RouteWave with a UART sniffer design loaded — Signal Hierarchy (left), Waveform View (center), Mission Control (right), Console (bottom-right)

Signal Hierarchy

The left panel shows your entire design tree. Modules are expandable folders; signals are leaf nodes with coloured eye badges. Double-click a signal to add it to the waveform view. The eye badge turns bright blue when a signal is currently displayed.

Waveform View

The center canvas renders your signals at 60 FPS using GPU-accelerated rendering. Each signal occupies a horizontal row with its name and current value on the left. Bus signals display as diamond-shaped lozenges with their hex value inside.

The timeline ruler at the top shows time ticks with auto-scaling units (ns, μs, ms, s). Use the unit selector in the toolbar to force a specific unit.

Mission Control

The right panel provides live context about your current view:

• Cursor State — positions and delta of all active cursors
• View Info — zoom level, time window, active channel count
• Hover Measurements — signal name, value, frequency, period, width, and duty cycle at the mouse position
• Display — rendering settings and visual options

Console

The bottom panel is a scriptable command console. Focus it with Ctrl+J. Every action in RouteWave — adding signals, changing views, attaching decoders — can be done through the console. This makes RouteWave fully automatable.

routewave> show clk
routewave> show data[7:0]
routewave> zoom 100ns 500ns
routewave> handshake tvalid tready

🧭 Navigate

Fast navigation is essential for waveform debugging. RouteWave supports mouse, keyboard, and console-based navigation — use whichever fits your flow.

Zoom & Pan

Cursors

RouteWave uses a cursor stack. Click on the waveform to place the primary cursor. Use C to push additional cursors onto the stack. The Mission Control panel shows cursor positions and the delta between them.

The delta measurement between cursors is shown in Mission Control as "Δ" with the time difference. Use this to measure clock periods, pulse widths, or protocol timing without leaving the main view.

Edge Jumping

When you're focused on a specific signal, use edge jumping to snap between transitions:

Edge jumping works on the currently selected signal. Click a signal name in the hierarchy or waveform to select it, then use N and Shift+N to walk through its transitions.

Bookmarks

Save viewport positions for quick recall during long debugging sessions:

routewave> bookmark "reset sequence"
routewave> bookmark "error condition"
routewave> bookmarks
routewave> goto "reset sequence"

Or use M to add a named marker at the current cursor position. Markers appear as labeled vertical lines on the timeline.

📊 Work with Signals

RouteWave goes beyond simple signal viewing — you can create virtual buses, search for values, and group related signals together.

Add & Remove

There are multiple ways to add signals to the waveform view:

• Double-click a signal in the hierarchy tree
• Use the console: show clk, show data[7:0]
• Use Ctrl+F to search and add

To remove a signal, right-click it in the waveform and select "Hide", or use hide signalname in the console.

Reorder & Group

Drag and drop signals in the waveform view to reorder them. You can also create visual groups to separate related signals with dividers and labels.

Change Radix

Bus signals default to hexadecimal display. Change the display radix using keyboard shortcuts or the console:

Select a signal first, then press the number key. ASCII mode is particularly useful for UART data buses where you want to see the transmitted characters directly on the waveform.

Virtual Buses

Combine individual signals into a virtual bus for grouped analysis:

# Select signals with Ctrl+Click, then create a virtual bus
routewave> makebus my_data

# Create a virtual signal using an expression
routewave> virtual handshake = valid AND ready

Virtual buses appear in the waveform just like real bus signals — with lozenges showing the combined hex value. They persist across sessions when saved in a .ltrace session file.

Find Values

Search a bus signal for a specific value — essential for tracking down a particular address access or data pattern:

# Find all occurrences of 0xDEAD on data_bus
routewave> find data_bus 0xDEAD

# Navigate through results
routewave> findnext
routewave> findprev

You can also use the Find value button in the toolbar. Search results are highlighted on the timeline with small markers.

🔬 Analyze

RouteWave includes built-in analysis tools that let you decode protocols, measure timings, and compare waveforms — without leaving the viewer.

I2C sniffer analysis — protocol decode bands (I2C Decoded, Sniffer Internals), cursor delta measurements (Δ = 52.8 μs), and console bookmark navigation

Measurements

The measure command computes timing properties of a signal:

routewave> measure sys_clk
  Period:    20.000 ns
  Frequency: 50.000 MHz
  Duty Cycle: 50.0%
  Pulse Width: 10.000 ns

For quick hover measurements, just move your mouse over any signal. Mission Control updates live with the signal name, current value, and timing properties at the cursor position.

Handshake Analyzer

Bind a valid/ready pair to visualize handshake transfers as coloured overlay bands on the waveform:

# Bind an AXI-Stream handshake
routewave> handshake tvalid tready

# The overlay shows:
#   Green bands = completed transfers
#   Red bands   = backpressure (valid HIGH, ready LOW)
#   Transfer count in the Dashboard

Or press H with two signals selected. The handshake overlay appears as semi-transparent bands across the waveform, making protocol bottlenecks immediately visible.

Protocol Decoders

RouteWave includes built-in decoders for common serial protocols:

# Attach a UART decoder (auto-detects baud rate)
routewave> translate uart_rx uart_8n1

# I2C decoder merges SDA + SCL into a decoded trace
routewave> translate sda scl i2c

# List available decoders
routewave> translators

Decoded data appears as annotated labels directly on the waveform timeline. For UART, you'll see individual bytes with their ASCII representation.

Waveform Diff

Compare two simulation runs side-by-side to find the exact point where behaviour diverges:

# Load a reference file and compare
routewave> compare load reference_run.vcd

# Show diff overlay on a specific signal
routewave> compare diff signal_name

# Differences are highlighted as coloured overlay bands

Waveform Comparison

Compare two simulation runs to find where behaviour diverges. Load a reference file and use the compare command to overlay differences on individual signals:

# Load reference waveform for comparison
routewave> compare load golden_run.vcd

# Show diff overlay on a signal
routewave> compare diff data_bus

⚡ Automate

Every action in RouteWave can be done through the console. This makes it fully scriptable — set up complex signal views once, save them as scripts, and replay instantly.

Console Commands

Open the console with Ctrl+T. Here are the most commonly used commands:

Macro Recording

Record a sequence of console commands to a .ltr file and replay them later:

# Start recording to a file
routewave> record start my_setup.ltr

# Do your setup...
routewave> show clk
routewave> show data[7:0]
routewave> handshake bind tvalid tready
routewave> zoom 0 10000

# Stop recording
routewave> record stop

# Replay the recorded macro
routewave> exec my_setup.ltr

Script Files

Save your setup as a script file (.ltr) and source it on startup. This is the power-user path to reproducible debugging sessions:

# UART debugging session setup
show clk
show rst_n
show uart_tx
show uart_rx
show data[7:0]
translate uart_tx uart_8n1
translate uart_rx uart_8n1
handshake bind tx_valid tx_ready
zoom 0 100000
bookmark "first byte"

# Execute the script at launch
routewave my_design.vcd --exec setup_uart_debug.ltr

# Or source it from the console
routewave> exec setup_uart_debug.ltr

CSV Export

Export the visible waveform data to CSV for post-processing in Python, MATLAB, or spreadsheet tools:

# Export to CSV (format chosen by file extension)
routewave> export output.csv

# Export to VCD
routewave> export output.vcd

📖 Reference

Keyboard Shortcuts

File Formats

CLI Flags

Usage: routewave [options] [file]

Options:
  -e, --exec <file.ltr>  Execute a script file on startup
  -c, --command <cmd>    Run a single command after loading
  -s, --signal <name>    Show a signal on startup
  -w, --workspace <file> Load a workspace (.ltws) file
  --port <n>             Set WCP server port

Memory Management

For large waveform files, RouteWave includes a compression engine using delta-varint timestamps and RLE values to reduce memory usage:

# Check per-channel memory usage
routewave> memstat

# Compress a specific channel
routewave> compact sys_clk

# Compress all loaded channels
routewave> compact