FPGA AI Assistant

Host-side application for AI-driven FPGA and ZedBoard debugging over USB (JTAG + UART).
Author: Reza Mirfayzi.

Features

• Desktop GUI (PySide6): Quick Actions, FPGA Editor (tabbed, AI-assisted), Port Monitor (live serial/TCP + AI log analysis), Panther Export, Request Builder, Results view, AI Chat (Ollama, OpenAI, Claude, Gemini, Grok).
• CLI: Build bitstream, program FPGA, read/write registers, UART tail/read.
• Structured API: JSON request/response and optional REST API for automation and AI agents.
• Configurable: Board (UART, address ranges), tool paths, API keys via Settings or environment.

Table of contents

• Requirements
• Quick start
• Installation
• Configuration
• Usage
  • GUI
  • CLI
  • JSON request
  • REST API
• Troubleshooting
  • ZedBoard COM port (Windows)
  • Port Monitor: no ports or no activity
• Environment variables
• Project structure
• License

Requirements

• Python 3.11+
• Board: ZedBoard (Zynq-7020, 2012) or compatible
• Optional: Vivado 2020.x–2024.x (for bitstream build, program, JTAG)
• Dependencies: pyserial, pydantic, typer; for GUI: PySide6 and LLM provider packages (see Installation).

Quick start

git clone <your-repo-url>
cd FPGA_Assistant
pip install -e ".[gui]"
python -m zeddebug gui

Set your board's UART port in Settings or in config/zedboard.json if the default does not match your COM port.

Installation

From the project root:

pip install -e .
# With GUI (PySide6 + LLM providers):
pip install -e ".[gui]"
# With REST API (uvicorn):
pip install -e ".[api]"

Configuration

Config files live in config/.

File	Purpose
zedboard.json	Board UART port (e.g. COM3 or /dev/ttyUSB0), allowed address ranges
tools.json	Vivado/tool paths and timeouts; leave paths empty to use PATH

Copy or edit these as needed for your environment.

Usage

GUI

pip install -e ".[gui]"
python -m zeddebug gui

Opens the desktop app: Quick Actions, FPGA Editor, Port Monitor, Panther Export, Request Builder, Results, and AI Chat. Configure API keys and AI persona under Settings.

CLI

# Build bitstream (synthesis + implementation)
python -m zeddebug build-bitstream --board zedboard --session-id smoke

# Program bitstream
python -m zeddebug program build/top.bit

# Read / write register
python -m zeddebug read_reg 0x43C00000

# UART
python -m zeddebug uart_tail
python -m zeddebug uart_read --bytes 1024

JSON request

python -m zeddebug run-request request.json > response.json

REST API

pip install -e ".[api]"
uvicorn zeddebug.api:app --reload

Troubleshooting

ZedBoard COM port on Windows (FTDI VCP)

If the ZedBoard does not show as a COM port in the app or in Device Manager:

Step 1 — Install FTDI VCP drivers

1. Download FTDI VCP drivers.
2. Install the Windows 64-bit setup executable (Recommended).
3. Reboot Windows, then unplug and replug the ZedBoard.

You should see Ports (COM & LPT) → USB Serial Port (COMx) in Device Manager.

Step 2 — Enable VCP

If there is still no COM port: Device Manager → USB Serial Converter → Right-click Properties → Advanced → enable Load VCP → OK → unplug and replug the board.

Step 3 — Xilinx cable drivers

If you use Vivado/Vitis for JTAG, install the cable drivers from your Xilinx installation so both the tools and this app can see the board.

Port Monitor debugging

If the Port Monitor tab shows no ports or no activity:

1. Use Scan & report in the tab to see if pyserial is installed and if the OS reports any serial devices.
2. Run the standalone diagnostic (same Python as the GUI):

   python scripts/diag_ports.py

   Empty lists → pyserial or driver/VM issue; only COM1–32 in the first list → Windows fallback, no real device.
3. Run the GUI from a terminal with ZEDDEBUG_PORT_DEBUG=1 and connect; check for [DEBUG] LivePortReader raw line: and [DEBUG] GUI received line: to see where the pipeline breaks.
4. Cross-check with PuTTY or TeraTerm on the same COM port and baud; if the terminal shows output but the app does not, the issue is in the app (e.g. LivePortReader or environment).

Environment variables

• ZED_UART_PORT — Override UART port from config.
• ZED_DEBUG_CONFIG_DIR — Override config directory.
• ZEDDEBUG_PORT_DEBUG=1 — Print port/reader debug lines to the console (run the GUI from a terminal).

Project structure

• src/zeddebug/ — Main package (GUI, CLI, serial monitor, USB scan, orchestration, API).
• config/ — Board and tool configuration (e.g. zedboard.json, tools.json).
• scripts/ — TCL scripts (Vivado, xsct) and utilities (e.g. diag_ports.py).
• design/ — Example or reference design (constraints, RTL, block design).
• samples/ — Sample JSON requests.
• tests/ — Unit and integration tests.

License

MIT

---

FPGA AI Assistant — Reza Mirfayzi.