Classroom Public page

CSA-101 Equipment and Setup Guide

865 words

Everything you need before week 1. Plan one weekend of preparation.

Two paths

Path A: physical kit. Buy a Sipeed Tang Primer 25K (or Tang Nano 20K as the Tier-1 alt). All labs work end-to-end; you flash bitstreams to silicon; the capstone runs on hardware you own.

Path B: browser-only. No kit. Use the academy workbench at https://virtuscyberacademy.org/workbench/. All labs except the final flash-to-silicon step work end-to-end; the capstone can be demonstrated via the workbench's simulation view.

Pick A if you want the full experience and can afford the hardware. Pick B if budget is tight or hardware shipping is a barrier. Path B students who later acquire hardware can re-do the final labs.

Path A: Physical kit

Canonical board: Sipeed Tang Primer 25K

The course's canonical target per ratification 2026-05-01.

  • Silicon: GW5A-LV25 (Gowin Arora V family); 22,800 LUT4 budget
  • Toolchain: Apicula (gowin_pack), open-source bitstream emitter; Yosys for synthesis; nextpnr-himbaechel for place-and-route
  • Order: Sipeed AliExpress shop (typically ~$75 starter kit; ~$144 full kit including HDMI cable + PMOD breakout + USB cable)
  • US distributors: as available; check the Sipeed wiki for current resellers

Tier-1 alternative: Sipeed Tang Nano 20K

  • Silicon: GW2AR-LV18 (Gowin Arora II); 20,736 LUT4 budget
  • Apicula chipdb: GW2A-18C.msgpack.xz
  • Smaller and cheaper than the Tang Primer 25K. Used in earlier course iterations and still supported for advanced-track students who want a tighter form factor
  • Reference doc: virtus-academy-support/docs/references/tang-nano-20k-board-reference.md

Required local software

Install before week 1:

  • Apicula 0.32 or newer. pip install apycula plus the chipdb file for your board
  • Yosys 0.40 or newer. Synthesis. apt install yosys on Debian/Ubuntu; build from source elsewhere
  • nextpnr-himbaechel (the Gowin variant). Build from source via the nextpnr GitHub instructions
  • openFPGALoader. Flash bitstreams to the board. apt install openfpgaloader on recent distributions
  • Verilog editor of choice. VS Code with the Verilog HDL extension is the academy default; Vim plus syntax files works fine
  • Python 3.11+. The academy toolchain (assembler, linker, VM translator, compiler) is Python
  • gdb-multiarch with RISC-V support. apt install gdb-multiarch
  • Ghidra 11.0+. For weeks 4, 6a, and 10 lab reconciliation steps

Optional but recommended

  • USB-Blaster JTAG cable (some Tang boards need this for stable flash; check your board's docs)
  • A multimeter, logic probe, and basic breadboard kit for weeks 1-3 (only required for the bench-path discrete-logic labs)
  • HDMI display or capture device for week 11+ HDMI output
  • Soldering iron for hand-modifications (advanced-track only)

Verification: post-install smoke test

After installing, run the academy's smoke-test script:

cd ~/student-repo/
./scripts/smoke-test-toolchain.sh

Expected output: 5 PASS lines (apicula, yosys, nextpnr, openFPGALoader, python). If any FAIL, debug before week 1.

Path B: Browser-only

What you need

  • A modern browser (Chrome / Firefox / Safari / Edge, 2024 or later)
  • Stable internet (the academy workbench is at https://virtuscyberacademy.org/workbench/)
  • An academy account to save your work between sessions

What works in the browser

Stages 1-4 of the FPGA pipeline run entirely client-side via WebAssembly: Yosys synthesis; nextpnr-himbaechel place-and-route; bitstream emit; simulation view. Stage 3 (the final bitstream-emit step that produces a .fs file the academy can verify on real silicon) is server-hop via the academy-bitstream-server endpoint.

The workbench supports every lab in CSA-101 through the simulation view. The flash-to-silicon step (week 5 lab 5.3+5.4 plus the capstone's hardware-verification dimension) requires either a physical board or instructor-arranged shared bench access.

What you still need to install locally

  • A text editor for offline note-taking and Toolchain Diary entries
  • Optional: Ghidra (for weeks 4, 6a, 10 reconciliation labs; Ghidra does not run in the browser as of this writing)

Folder structure recommendation

~/student-repo/
├── toolchain-diary.md         (your running tool journal)
├── lectures-notes/            (per-week)
├── labs/                      (per-week worksheet copies + your work)
├── projects/
│   ├── ch1-boolean/
│   ├── ch2-arithmetic/
│   ├── ...
│   └── ch12-virtus-os/
├── capstone/                  (week 14 deliverable assembly)
└── scratch/                   (anything experimental)

Use git from week 1. Commit often. Push to a personal GitHub or GitLab repo (or to the academy GitLab if your cohort has accounts provisioned). The git history is part of your portfolio.

Reading material to bookmark

Estimated install time

Step Time
Install apicula + chipdb ~30 min
Build nextpnr-himbaechel from source ~45 min (depends on machine)
Install yosys + openFPGALoader ~20 min
Install Python 3.11+ and pip install -r requirements.txt ~15 min
Install gdb-multiarch ~10 min
Install Ghidra ~30 min
Run smoke-test ~10 min
Total path A ~2.5 hr; one focused evening
Total path B ~30 min (browser bookmarks + academy account)

Where to get help

  • Academy Discord channel (link distributed at enrollment)
  • Instructor office hours (schedule shared at course start)
  • RISC-V community forums for ISA questions
  • The Gowin nextpnr wiki page for FPGA toolchain questions

If smoke-test fails, ask for help before week 1 starts. Setup friction at the front of the course costs every later week. Better to spend the weekend before week 1 fixing your install than to start week 5 unable to flash a bitstream.

Setup guide v0.1 prepared 2026-05-11. Updates after pilot-cohort install feedback.