Export and Integration Tools

Overview

The PyWellen MCP server includes tools for exporting waveform data and integrating with external tools and workflows. These tools enable:

Exporting signal data to CSV and JSON formats
Exporting design hierarchy to structured formats
Loading and saving signal configuration files
Launching external waveform viewers
Monitoring files for changes
Generating viewer-specific configuration files

These tools bridge the gap between PyWellen and external analysis tools, viewers, and workflows.

Export Tools

export_to_csv

Purpose: Export signal data to CSV format for analysis in spreadsheets or data science tools.

Parameters:

session_id (string, required): Active waveform session ID
signal_paths (array, required): List of signal paths to export
output_path (string, required): Path to output CSV file
start_time (integer, optional): Start time for export range
end_time (integer, optional): End time for export range
include_header (boolean, optional): Include column headers (default: true)
time_format (string, optional): “absolute” or “relative” (default: absolute)

Returns:

output_file: Path to created CSV file
signals_exported: Number of signals exported
rows_written: Number of data rows written
time_range: Actual time range exported
format: CSV format details

Example Usage:

{
    "session_id": "abc123",
    "signal_paths": ["top.clk", "top.data", "top.valid"],
    "output_path": "/tmp/signals.csv",
    "time_format": "relative"
}

Output Format:

Time,top.clk,top.data,top.valid
0,0,0x00,0
5,0,0x00,1
10,1,0xff,1
15,1,0xff,0

Use Cases:

Statistical analysis in R, Python (pandas), or Excel
Plotting signal waveforms
Correlation analysis between signals
Export for regression testing

export_hierarchy_tree

Purpose: Export design hierarchy as structured tree for visualization or processing.

Parameters:

session_id (string, required): Active session ID
output_path (string, required): Path to output file
format (string, optional): “json”, “yaml”, or “text” (default: json)
include_variables (boolean, optional): Include variable details (default: true)
include_metadata (boolean, optional): Include scope metadata (default: true)
max_depth (integer, optional): Maximum tree depth (null = unlimited)

Returns:

output_file: Path to created file
format: Format used
total_scopes: Number of scopes exported
total_variables: Number of variables exported
max_depth_reached: Maximum depth in hierarchy

Example - JSON Output:

{
    "design": "test.vcd",
    "scopes": [
        {
            "name": "top",
            "type": "Module",
            "metadata": {
                "num_children": 2,
                "num_variables": 3,
                "depth": 0
            },
            "variables": [
                {
                    "name": "clk",
                    "type": "Wire",
                    "direction": "Input",
                    "length": 1
                }
            ],
            "children": [...]
        }
    ]
}

Example - Text Output:

Design: test.vcd

├─ top (Module)
  │  clk : Wire
  │  data : Reg
  ├─ cpu (Module)
    │  alu_out : Wire

Use Cases:

Design visualization tools
Documentation generation
Hierarchy analysis
Module extraction

export_signal_data

Purpose: Export single signal’s complete data to JSON or CSV.

Parameters:

session_id (string, required): Active session ID
signal_path (string, required): Signal to export
output_path (string, required): Path to output file
format (string, optional): “json” or “csv” (default: json)
start_time (integer, optional): Start time for export range
end_time (integer, optional): End time for export range

Returns:

output_file: Path to created file
signal_path: Signal that was exported
format: Format used
changes_exported: Number of changes written
time_range: Time range exported
file_size: Size of created file

JSON Output Example:

{
    "signal": "top.clk",
    "changes": [
        {"time": 0, "value": "0"},
        {"time": 10, "value": "1"},
        {"time": 20, "value": "0"}
    ],
    "metadata": {
        "total_changes": 3,
        "time_range": {"start": 0, "end": 20}
    }
}

Configuration Tools

load_signal_list

Purpose: Load signal lists and configurations from JSON/YAML files.

Parameters:

session_id (string, required): Active session ID
config_path (string, required): Path to configuration file

Returns:

config_file: Path to loaded file
signals: List of loaded signal paths
groups: Signal groups from config
filters: Filters from config
metadata: Configuration metadata
validation: Validation results (valid/invalid signals)

Configuration File Format:

{
    "signals": [
        "top.clk",
        "top.data"
    ],
    "groups": {
        "control": ["top.valid", "top.ready", "top.enable"],
        "data": ["top.data", "top.addr"]
    },
    "filters": {
        "scope": "top.cpu",
        "types": ["Wire", "Reg"],
        "min_bitwidth": 8
    },
    "metadata": {
        "description": "Main control signals",
        "author": "user@example.com",
        "date": "2024-01-15"
    }
}

Use Cases:

Reusable signal selection for common debug scenarios
Team-shared signal lists
Workflow automation
Regression test configurations

save_signal_list

Purpose: Save signal lists to configuration files for reuse.

Parameters:

session_id (string, required): Active session ID
output_path (string, required): Path to output file
signal_paths (array, required): Signals to save
groups (object, optional): Signal groups
filters (object, optional): Filter configuration
metadata (object, optional): Metadata
format (string, optional): “json” or “yaml” (default: json)

Returns:

output_file: Path to created file
format: Format used
signals_saved: Number of signals saved
groups_saved: Number of groups saved
file_size: Size of created file

Integration Tools

integration_launch_viewer

Purpose: Launch external waveform viewer with waveform file.

Supported Viewers:

GTKWave: Open-source waveform viewer
Verdi: Synopsys Verdi
Simvision: Cadence Simvision
DVE: Synopsys DVE
Wave: Generic wave viewer
Custom: User-defined viewer command

Parameters:

viewer (string, required): Viewer name or “custom”
file_path (string, required): Path to waveform file
save_file (string, optional): Optional save/config file
additional_args (array, optional): Additional command arguments
wait (boolean, optional): Wait for viewer to exit (default: false)

Returns:

viewer: Viewer launched
command: Full command executed
pid: Process ID (if not waiting)
exit_code: Exit code (if waiting)
status: “launched” or “completed”

Example Usage:

{
    "viewer": "gtkwave",
    "file_path": "/path/to/waveform.vcd",
    "save_file": "/path/to/signals.gtkw"
}

Viewer-Specific Arguments:

GTKWave: Save file loaded with -a flag
Simvision: Save file loaded with -input flag
Verdi: Save file loaded with -sswr flag

Custom Viewer Example:

{
    "viewer": "custom",
    "file_path": "/path/to/wave.vcd",
    "additional_args": ["my_viewer", "--fullscreen", "{file}"]
}

integration_watch_file

Purpose: Monitor waveform file for changes (useful for live simulation).

Parameters:

file_path (string, required): Path to file to monitor
interval (integer, optional): Check interval in seconds (default: 5)
max_checks (integer, optional): Maximum checks (default: 60)

Returns:

file_path: File being monitored
status: “unchanged”, “modified”, “created”, “deleted”, or “not_found”
last_modified: Last modification timestamp
file_size: Current file size
size_change: Size difference (if modified)
checks_performed: Number of checks performed

Example Usage:

{
    "file_path": "/sim/output/waves.vcd",
    "interval": 5,
    "max_checks": 120
}

Use Cases:

Live simulation monitoring
Auto-reload workflows
Simulation completion detection
File update notifications

integration_generate_gtkwave_save

Purpose: Generate GTKWave save file (.gtkw) for quick signal viewing.

Parameters:

session_id (string, required): Active session ID
output_path (string, required): Path to .gtkw file
signal_paths (array, required): Signals to include
time_range (object, optional): Time range dict with start/end
group_signals (boolean, optional): Group by hierarchy (default: true)

Returns:

output_file: Path to created save file
format: “gtkwave_save”
signals_included: Number of signals included
groups_created: Number of signal groups
file_size: Size of created file

Generated Save File:

[*]
[*] GTKWave Save File
[*] Generated by PyWellen MCP
[*]

[dumpfile] "(null)"
[timestart] 0
[timeend] 1000

@top.cpu
top.cpu.clk
top.cpu.data
top.cpu.valid
@-

@top.mem
top.mem.addr
top.mem.data
@-

Use Cases:

Pre-configured waveform views
Team-shared debug setups
Automated test result viewing
Quick signal inspection

Common Workflows

Workflow 1: Export for Analysis

Export signals to CSV for analysis in Python/R/Excel:

Open waveform with waveform_open
Find signals of interest with hierarchy_search
Export to CSV with export_to_csv
Analyze in external tool (pandas, Excel, etc.)

Workflow 3: Launch Viewer with Pre-configured Signals

Quick waveform viewing with pre-loaded signals:

Open waveform session
Generate GTKWave save with integration_generate_gtkwave_save
Launch viewer with integration_launch_viewer
Signals are pre-loaded and grouped

Workflow 4: Live Simulation Monitoring

Monitor ongoing simulation:

Start simulation (generates waveform file)
Use integration_watch_file to monitor for updates
When modified, open new session with waveform_open
Analyze latest data
Repeat until simulation completes

Best Practices

File Paths

Always use absolute paths for reliability
Check directory permissions before export
Use temporary directories for throwaway exports
Organize exports by date/session for tracking

Configuration Files

Use JSON for simple configs
Use YAML for complex, human-editable configs
Include metadata (author, date, description)
Version control configuration files
Document signal groupings and filters

External Tool Integration

Check viewer availability before launching
Use save files for consistent viewer configuration
Launch viewers in background (wait=false) for responsiveness
Provide additional_args for custom options

Performance

Limit time ranges for large exports
Use signal_summarize before full export
Export only needed signals
Consider batch operations for multiple exports

File Format Recommendations

CSV Export

Pros: * Universal compatibility * Easy to parse * Works with spreadsheets

Cons: * Large file sizes * No hierarchy information * Text-based (slower for large data)

Best For: * Spreadsheet analysis * Statistical processing * Quick data inspection

JSON Export

Pros: * Structured format * Supports metadata * Easy to parse programmatically

Cons: * Larger than binary formats * Slower for huge datasets

Best For: * Tool integration * Configuration files * Hierarchical data

YAML Export

Pros: * Human-readable * Supports comments * Good for configuration

Cons: * Requires pyyaml package * Slower parsing than JSON

Best For: * Configuration files * Human-edited files * Documentation

Limitations

File watching is polling-based (not event-driven)
Large CSV exports may consume significant memory
Viewer integration requires viewer to be installed
YAML support requires optional pyyaml package
Custom viewer commands are platform-dependent

Export and Integration Tools

Overview

Export Tools

export_to_csv

export_hierarchy_tree

export_signal_data

Configuration Tools

load_signal_list

save_signal_list

Integration Tools

integration_launch_viewer

integration_watch_file

integration_generate_gtkwave_save

Common Workflows

Workflow 1: Export for Analysis

Workflow 2: Save and Share Signal Lists

Workflow 3: Launch Viewer with Pre-configured Signals

Workflow 4: Live Simulation Monitoring

Best Practices

File Paths

Configuration Files

External Tool Integration

Performance

File Format Recommendations

CSV Export

JSON Export

YAML Export

Limitations

See Also