Every tool in one step, then no internet at all
One script installs the whole toolchain for NandTier: synthesis, place and route, the RISC-V compiler, the simulator and the board programmer. Everything goes into one folder inside the project, with no administrator rights. Once that folder is there, nothing needs the network again, and this website runs from your own disk as well.
Downloads
NandTier source code
The Verilog, the firmware, the games, the tests and the setup scripts. Unpack it, then run the setup below.
This website, offline
The course with every video, the blog and the emulator, with a tiny local server. Double-click start.bat or start.sh to open it.
The tools, for a lab without internet
Not hosted here: the script fetches them once from GitHub and PyPI, then packs repository and tools into one archive to copy to every PC. See Without internet.
Install the tools
Unpack nandtier.zip (or clone the repository), open a terminal in that folder and run the script for your system. The first run downloads about 1 GB and needs about 4 GB of disk.
$ cd nandtier $ setup/setup.sh ==> NandTier setup on linux-x64 ==> downloading oss-cad-suite-linux-x64-20261101.tgz ==> downloading xpack-riscv-none-elf-gcc-14.2.0-3-linux-x64.tar.gz Install USB rules so the boards work without sudo (needs sudo)? [y/N] y ==> checking ok riscv-none-elf-gcc 14.2.0 · yosys 0.70 · nextpnr 0.11.1 · iverilog 14.0 ==> building the boot ROM, the launcher and the games (make) ==> ready $ make fpga # the bitstream (Tang Nano 9K) $ make program COMx=/dev/ttyUSB1 # launcher into the flash, games onto the SD card
rem double-click setup\setup.bat, or in a terminal: > cd nandtier > setup\setup.bat ==> NandTier setup on Windows ==> downloading oss-cad-suite-windows-x64-20261101.tgz ==> downloading xpack-riscv-none-elf-gcc-14.2.0-3-win32-x64.zip ==> downloading xpack-windows-build-tools-4.4.1-3-win32-x64.zip ==> ready rem then, in every new PowerShell window: > . .\env.ps1 > make > make program COMx=COM5
# in Ubuntu under WSL, exactly as on Linux: $ sudo apt install make $ setup/setup.sh # the board's USB reaches Linux through usbipd-win, in Windows PowerShell (admin): > usbipd list > usbipd bind --busid 2-3 > usbipd attach --wsl --busid 2-3
Run it again at any time: it only does what is missing. To remove everything, delete the tools folder and local.mk.
What it installs
| Tool | Version | Download | What for |
|---|---|---|---|
| OSS CAD Suite | 2026-11-01 | 600–720 MB | Yosys, nextpnr-himbaechel, Apicula (gowin_pack), openFPGALoader, Icarus Verilog, GTKWave |
| xPack RISC-V GCC | 14.2.0-3 | about 330 MB | the boot ROM, the launcher and the games |
| pyserial | 3.5 | 0.1 MB | the flash programmer and the keyboard controller in sw/ |
| Windows Build Tools | 4.4.1-3 | 2.6 MB | Windows only: GNU make and the shell the Makefiles use |
| Python 3 | 3.12 | 11 MB | Windows only, and only when none is installed; the OSS CAD Suite brings one too |
What the script does
- Downloads each archive onceinto
setup/cache/, and checks the SHA-256 that xPack and PyPI publish. - Unpacks it into
tools/inside the project. Nothing goes into system folders and no administrator rights are needed. - Writes
local.mkEvery Makefile reads it first, so plainmakefinds the tools.env.sh,env.ps1andenv.batput them on yourPATHtoo. - Sets up USB on LinuxIt asks before installing
/etc/udev/rules.d/99-nandtier.rules, so openFPGALoader and the UART work without sudo. - Checks and buildsIt prints every tool's version and builds the firmware once, so you know the whole chain works.
Without internet
The tools come from GitHub and PyPI exactly once. For a classroom, one machine with internet makes a bundle: the repository plus every download, for the operating system of the lab PCs. The lab PCs never go online.
# on the machine with internet (Linux, macOS or WSL) $ setup/setup.sh --bundle # for this OS: nandtier-offline-linux-x64.tar.gz $ setup/setup.sh --bundle --platform win32-x64 # for Windows PCs: nandtier-offline-win32-x64.zip # on each lab PC, after unpacking the archive $ setup/setup.sh --offline # Linux / macOS > setup\setup.bat -Offline # Windows
| Option | What it does |
|---|---|
--download-only | fill setup/cache/, install nothing (Windows: -DownloadOnly) |
--offline | install from the cache only, never touch the network (Windows: -Offline) |
--bundle | download, then pack the repository and the cache into one archive |
--platform P | linux-x64, linux-arm64, darwin-x64, darwin-arm64 or win32-x64, to prepare another system |
--no-cad, --no-gcc | firmware only, or bitstreams only |
--gcc DIR | use a RISC-V GCC that is already installed |
--check | check what is installed and build the firmware |
This website on your own computer
The offline download is the same site as here: the course, all lesson videos, the blog with its benches, and the SoC Lab running the real firmware. It needs a small local web server, because the emulator loads its programs with fetch() and the videos seek by byte ranges. The server is included.
| System | Start it |
|---|---|
| Windows | double-click start.bat. It uses Python when it is installed, and PowerShell's own web server when it is not. |
| Linux, macOS | double-click start.sh, or run ./start.sh in a terminal |
| Anything with Python | python3 serve.py, then open http://localhost:8080 |
Your progress in the course and the light or dark choice are kept in that browser.
When something does not work
openFPGALoader cannot find the board on Linux
Let the script install the USB rules (it asks), or run setup/setup.sh --udev, then unplug the board and plug it in again. The Tang Nano's debugger appears as an FT2232 (0403:6010): interface 0 is JTAG, interface 1 is the UART, usually /dev/ttyUSB1.
openFPGALoader cannot find the board on Windows
It needs the WinUSB driver on the debugger's interface 0. Install it once with Zadig (Options → List All Devices, pick interface 0, WinUSB). Leave interface 1 alone: it is the serial port, COMx=COM5 or similar. The Gowin IDE's programmer works without this step.
make fpga fails, or timing is not met
All three boards build with the open tools: the Tang Nano 9K at 65% of its LUTs and 42.9 MHz, the 20K at 82.2 MHz, the ULX3S at 57.5 MHz, against the 25 MHz needed. If yours stops, read oss/build/<board>/nextpnr.log from the end: "Unable to find legal placement" means the design no longer fits (compare stat.txt with these numbers), and a red "FAIL" on a clock means timing. An older checkout of NandTier, from before the logic analyzer's flags moved into block RAM, did not fit the 9K: update it, or build the 9K with the Gowin IDE project in project/.
I already have a RISC-V compiler
Run setup/setup.sh --gcc /path/to/toolchain, or edit local.mk: RISCV_PATH ?= … and RISCV_NAME ?= riscv-none-embed. Old 8.x and current compilers both work: the Makefiles ask the compiler whether it needs the Zicsr name for rdcycle.
The GitHub download fails or hits a limit
The versions are pinned in setup/versions.txt, so the script downloads release files directly and does not need the GitHub API. Only a version set to latest asks the API, which allows 60 requests an hour per address. A school proxy can block GitHub; then make a bundle at home and bring it in.