RouteRTL

Command-line SDK for FPGA projects: simulation, linting, IP packages and vendor builds from one project.yml.

---

RouteRTL is a command-line SDK for FPGA development. A project is described in project.yml. RouteRTL reads the HDL sources, works out the compile order from the code, and drives the simulators, linters and vendor tools. The CLI command is rr.

Main functions:

• Source discovery and dependency resolution for VHDL, Verilog and SystemVerilog. File lists and compile order are derived from the sources.
• An IP package manager (rr pkg) backed by a public registry. Package dependencies are resolved across languages, and each package carries a license classification.
• cocotb 2.1+ simulation (rr sim run) with shipped bus-functional models.
• Linting (rr lint) with configurable profiles.
• Synthesis, implementation and bitstream generation for AMD/Xilinx, Altera, Lattice and Microchip devices, plus an open-source Yosys/nextpnr flow.
• An MCP server and agent skills for use with AI coding agents.

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install routertl

Release wheels are built for Python 3.10 to 3.14.

On Ubuntu 24.04+, Debian 12+ and other systems with an externally managed Python, a plain pip install routertl outside a virtual environment fails with error: externally-managed-environment. Use the virtual environment above, or pipx install routertl for a global CLI. Not recommended: --break-system-packages. It installs into the system Python and can break system packages.

Optional extras: routertl[mcp] (MCP server), routertl[docker] (Docker tool images) and routertl[web] (web services). The base install does not include them.

Platform notes for Linux, WSL2 and macOS are in the Installation Guide.

Quick start

This example uses the uart_loopback template. It installs the open-logic/olo_intf_uart package from the registry, lints the design and runs two cocotb tests on NVC.

mkdir my_uart && cd my_uart
rr init --template uart_loopback --name my_uart
rr lint
rr sim run

rr init --template creates the project in the current directory. The template declares the UART package, so rr init installs it. To add a package to any project, run rr pkg add <vendor>/<package>.

rr init --list-templates lists the other templates. first_success uses only open-source tools (Icarus Verilog and Yosys) and needs no vendor license.

To create an empty project for a specific device:

rr init --name my_project --vendor xilinx --part xc7z020clg400-1

To import an existing Vivado (.xpr) or Quartus (.qpf / .qsf) project, use rr migrate run <project>.

IP packages

rr pkg search ethernet
rr pkg add open-logic/olo_base_fifo_async
rr pkg add fpganinja/taxi::taxi_eth_mac_1g
rr hierarchy --forest

rr pkg add resolves the package's HDL dependencies, including dependencies between VHDL and Verilog sources. rr hierarchy --forest prints the resolved design hierarchy. The registry is at registry.routertl.dev.

Commands

Area	Commands
Project	rr init, rr migrate run, rr status, rr doctor, rr hierarchy
Packages	rr pkg search, rr pkg add, rr pkg update, rr deps graph
Lint	rr lint
Simulation	rr sim run, rr sim list, rr sim scaffold, rr testgen, rr watch
Build	rr synth run, rr implementation run, rr bitstream run, rr report
Hardware	rr program run
Tools	rr eda install <tool>, rr docker install <env>
Waveforms	rr routewave
AI agents	rr mcp install, rr skills install, rr skills search

rr --help --all lists every command. rr help <command> shows the manual page for one command.

Supported tools

Function	Tools
Simulation	NVC, GHDL, Verilator, Icarus Verilog. Questa, Riviera-PRO, Active-HDL and Xcelium when installed.
Synthesis and implementation	Vivado, Quartus Pro and Standard, Lattice Radiant and Diamond, Microchip Libero, Yosys with nextpnr
Waveforms	RouteWave (rr routewave), GTKWave

rr eda install builds NVC, GHDL, Verilator, Icarus Verilog and Yosys from pinned sources. rr docker install provides container images for vendor tools.

Simulation API

import cocotb
from routertl.sim import Tb

@cocotb.test()
async def test_my_module(dut):
    tb = Tb(dut)
    await tb.start_clock()
    await tb.reset()

Each test file ends with a call to run_simulation(...) and runs with rr sim run <test>. rr sim bfms lists the shipped bus-functional models. They include AXI4, AXI4-Lite, AXI4-Stream, APB, Avalon-MM, Avalon-ST, Wishbone, UART, SPI, I2C and GMII.

Use with AI agents

RouteRTL includes an MCP server (rr_* tools for schema lookup, lint, simulation and diagnosis) and a set of agent skills. In the project directory:

pip install 'routertl[mcp]'   # MCP server dependencies (not in the base install)
rr mcp install                # registers the routertl server in ./.mcp.json
rr skills install             # copies the agent skills into ./.claude/skills

rr skills install --scope user installs the skills for all projects. rr skills search <words> finds a skill. Details are in MCP Server.

Documentation

Topic	Link
First project	First Steps Tutorial
Writing simulations	Cocotb Quickstart
Protocol drivers	Driver Cookbook
project.yml fields	project.yml Reference
Existing projects	Existing Project Migration
Errors	Troubleshooting
All documents	Documentation Index

Requirements

Tool	Required	Notes
Python 3.10 to 3.14	Yes	CLI and simulation framework
Git	Yes	Version control and dependency tracking
NVC	Recommended	Default VHDL simulator. rr eda install nvc builds the pinned release. Ubuntu 24.04 has no nvc apt package. The release .deb also works.
GHDL >= 6.0	Recommended	VHDL analysis for rr lint. rr eda install ghdl builds the pinned release. Ubuntu 24.04 apt provides 4.1.0, which rr lint does not accept.
Vendor tools	Optional	Vivado, Quartus, Radiant, Diamond or Libero, installed locally or with rr docker install

Acknowledgments

RouteRTL uses the following open-source projects:

Project	Use in RouteRTL
NVC	Default VHDL simulator
GHDL	VHDL analysis, linting and simulation
cocotb	Python verification framework used by rr sim
Verilator	Verilog/SystemVerilog simulation and linting
Icarus Verilog	Verilog simulation
xpm_vhdl	VHDL models of Xilinx XPM macros
Rich	Terminal output
Jinja2	Code generation templates

Support

Bug reports and feature requests: support@routertl.dev. Please include the output of rr doctor. See CONTRIBUTING.md for contributions.

RouteRTL is developed and maintained by Daniel J. Mazure (routertl.dev).

Licensing

RouteRTL is distributed under two licenses:

Component	License	Terms
CLI, build system, cocotb drivers, hooks, documentation, examples	MIT	Use, modification and redistribution with attribution
Compiled core (routertl_core/*.so)	RouteRTL Core License 1.0	30-day evaluation; then free for registered individuals; a commercial license for organizations of any size; no competing product
Compiled core, academic use	RouteRTL Academic License 1.0	Teaching and published non-commercial research at accredited institutions and non-profit public research institutes

The RouteRTL Core License 1.0 applies from release 5.1.0. Releases before 5.1.0 remain under the PolyForm Shield License 1.0.0 they were published with.

Licensing questions

Question	Answer
Evaluation?	Anyone may use RouteRTL, including its paid features, for 30 days.
Individual use after the evaluation?	Free of charge for an individual's own benefit, after free registration. Paid features need a seat.
Use in a company?	After the 30-day evaluation, an organization of any size needs a commercial license: a named seat per engineer or a company-wide Enterprise license. See routertl.dev/pricing.
Open-hardware project?	Free for a hardware design whose sources are published under an open license. This covers the project, not other use by the organization that runs it.
Commercial products?	Permitted under a commercial license. RouteRTL places no claim on the designs built with it.
Modification of the CLI or build system?	Permitted under the MIT license.
Working around the licence key check?	Not permitted under the RouteRTL Core License.
Redistribution of the PyPI wheel?	Permitted, unmodified.
What counts as competing?	Distributing an FPGA SDK that replaces RouteRTL. Using RouteRTL to build an FPGA product is not competing.

Copyright 2024-2026 Daniel J. Mazure