G2G / Setup

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

ZIP · 2.9 MB

NandTier source code

The Verilog, the firmware, the games, the tests and the setup scripts. Unpack it, then run the setup below.

ZIP · measuring…

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.

TOOLS · about 1 GB

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

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

ToolVersionDownloadWhat for
OSS CAD Suite2026-11-01600–720 MBYosys, nextpnr-himbaechel, Apicula (gowin_pack), openFPGALoader, Icarus Verilog, GTKWave
xPack RISC-V GCC14.2.0-3about 330 MBthe boot ROM, the launcher and the games
pyserial3.50.1 MBthe flash programmer and the keyboard controller in sw/
Windows Build Tools4.4.1-32.6 MBWindows only: GNU make and the shell the Makefiles use
Python 33.1211 MBWindows only, and only when none is installed; the OSS CAD Suite brings one too

What the script does

  1. Downloads each archive onceinto setup/cache/, and checks the SHA-256 that xPack and PyPI publish.
  2. Unpacks it into tools/inside the project. Nothing goes into system folders and no administrator rights are needed.
  3. Writes local.mkEvery Makefile reads it first, so plain make finds the tools. env.sh, env.ps1 and env.bat put them on your PATH too.
  4. Sets up USB on LinuxIt asks before installing /etc/udev/rules.d/99-nandtier.rules, so openFPGALoader and the UART work without sudo.
  5. 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.

GitHub · PyPI tools, once Teacher's PC setup.sh --bundle --platform win32-x64 USB stick 1 archive no network past this line Lab PC 1 setup.bat -Offline Lab PC 2 setup.bat -Offline Lab PC 30 setup.bat -Offline
# 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
OptionWhat it does
--download-onlyfill setup/cache/, install nothing (Windows: -DownloadOnly)
--offlineinstall from the cache only, never touch the network (Windows: -Offline)
--bundledownload, then pack the repository and the cache into one archive
--platform Plinux-x64, linux-arm64, darwin-x64, darwin-arm64 or win32-x64, to prepare another system
--no-cad, --no-gccfirmware only, or bitstreams only
--gcc DIRuse a RISC-V GCC that is already installed
--checkcheck 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.

SystemStart it
Windowsdouble-click start.bat. It uses Python when it is installed, and PowerShell's own web server when it is not.
Linux, macOSdouble-click start.sh, or run ./start.sh in a terminal
Anything with Pythonpython3 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.