# HDLBoard: A Virtual DE1-SoC That Runs Your Actual VHDL

Learning VHDL usually starts with a detour. You install a vendor toolchain, find a free board, and wait for synthesis, all to find out whether `LEDR <= SW;` lights an LED. That's a lot of ceremony for one line of code.

I built **HDLBoard** for my intro FPGA course at USN (PB1180 Programmerbare logiske kretser). The goal is simple: write VHDL, press Start, flip a switch, see an LED. Learn the language first. Timing analysis can wait for the next chapter.

## What I Wanted

### "Is It Actually Simulating?"

Board simulators have a sneaky failure mode. If you wire the LEDs straight to the switches for a demo, everything looks perfect, as long as the design happens to be `LEDR <= SW;`. HDLBoard never does that. Only GHDL writes to the outputs, so the board stays dark until your VHDL drives something. The first LED that lights up actually means something.

### Timing That Doesn't Lie

Simulated time is paced to wall-clock time. A blinker designed for 2 Hz blinks at 2 Hz, both on screen and on the real board. One honest caveat: dividing a genuine 50 MHz clock down to 1 Hz takes millions of simulated cycles. For interactive designs there's an optional `CLOCK_500Hz` port. Just remove it before synthesizing for real hardware.

### Looks Like the Board on the Desk

Every part was measured pixel by pixel from reference renders and built in pure CSS, with no bitmaps. The switch knobs slide rather than change colour. `KEY` is active low, so it reads `1111` at rest. The signal names match the entity ports, and `LEDR3` sits directly above `SW3`, just like on the real board.

## The Specifics

| Feature | What You Get |
|---|---|
| **Simulation** | Real GHDL: analyse → elaborate → run, errors with file:line |
| **Board** | `SW[9:0]`, `KEY[3:0]`, `LEDR[9:0]`, `HEX0`–`HEX5` |
| **Editor** | Tabs, VHDL highlighting, file explorer with drag-and-drop upload |
| **Testbenches** | `report`/`assert` streams live; portless testbenches run at full GHDL speed |
| **Timing** | Real-time pacing, so on-screen timing predicts the hardware |
| **Install** | Windows installer (GHDL bundled), or self-host on Linux/macOS/WSL and the whole lab connects over the LAN |

## Under the Hood

The front end is React, TypeScript and Vite, with Node.js behind it. Each session runs one continuous GHDL process instead of restarting on every switch flip. LEDR and HEX updates are pushed over a WebSocket. The Windows build wraps everything in Electron and serves itself on localhost, so nothing is exposed to the network. It's licensed under GPL-2.0.

It supports VHDL only for now. There's no persistence either: reload and you're back to the starter project.

## Try It

**Source:**
**Windows installer:** (unsigned, so SmartScreen will grumble: *More info → Run anyway*)

It's not a replacement for the real board. It's the step before it, where a student's first LED lights up in seconds instead of after a synthesis run.