Learning track: Tang Nano 20K from blinking an LED to HDMI

Summary A beginner route for the Tang Nano 20K from the first LED example to HDMI, built from vendor and open-source documentation. Overview Step 1. Hardware and board resources. The Sipeed wiki parameter table lists GW2AR-LV18QN88C8/I7: 20736 LUT4, 15552 flip-flops, 828K bits of block SRAM in 46 blocks, a 32-bit SDR SDRAM of 64M bits, 48 18x18 multipliers, 2 PLLs and 8 I/O banks. The board also has an onboard BL616 debugger (JTAG, USB-to-UART, USB-to-SPI, control of the MS5351 clock generator), 6 LEDs, one WS2812 RGB LED, 2 user keys, a TF card slot, a 40-pin RGB LCD connector, an HDMI interface and 64 Mbit flash for the bitstream. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html Step 2. First power-on. The default firmware is LiteX: after power-up the LEDs flow, and the serial port at 115200 baud opens a LiteX terminal. A command such as "leds 62" changes the LEDs. This is a quick check that the board, the cable and the driver are alive before any EDA is installed. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/unbox.html Step 3. Gowin IDE. According to the Sipeed install page the IDE comes in two editions: Standard needs a license, Education is free but supports fewer devices; GW2AR-LV18QN88C8/I7 from the Tang Nano 20K is in the Education edition table. The download is on the vendor GOWIN EDA page (after logging in), which lists GOWIN EDA (Standard) and GOWIN EDA (Education). On Linux the gw_ide executable is in the IDE/bin folder of the unpacked archive. The Sipeed table is dated 2023-05-29, so check the edition contents on the Gowin site. Sources: https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-Doc/install-the-ide.html and https://www.gowinsemi.com/en/support/download_eda/ Step 4. First project: LEDs and keys. The Hackaday article walks through a minimal Verilog example: two switch inputs and two LED outputs, with the logic written as two assign statements (inverted OR and inverted AND). The author notes that the LEDs on the board are active low and the switches are pulled down, and shows a constraint file with the pin numbers. The Sipeed LED page shows the Gowin IDE steps (new project for GW2AR-LV18QN88C8/I7, Verilog file, Synthesize, FloorPlanner, Place and Route). Sources: https://hackaday.com/2026/09/28/the-fpga-chronicles-exploring-the-tang-nano-20k/ and https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/led.html Step 5. Loading the bitstream. In Gowin Programmer there is an SRAM mode (fast, but the content is lost at power-off) and an External Flash mode (the design starts at power-up). On Linux Sipeed suggests openFPGALoader; its Gowin documentation gives the SRAM command openFPGALoader -m -b tangnano20k impl/pnr/*.fs, and openFPGALoader --list-boards prints the board names. Sources: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/led.html, https://trabucayre.github.io/openFPGALoader/vendors/gowin.html and https://trabucayre.github.io/openFPGALoader/guide/first-steps.html Step 6. Open-source path: Yosys, nextpnr-himbaechel, Apicula. Project Apicula lists the Tang Nano 20K among supported boards and asks for recent Yosys, nextpnr-himbaechel, openFPGALoader and Python 3.9 or newer; the Apicula tools install with pip install apycula. In the examples Makefile for the Tang Nano 20K, synthesis uses synth_gowin with -family gw2a, place and route uses nextpnr-himbaechel with --device GW2AR-LV18QN88C8/I7, --vopt family=GW2A-18C and --vopt cst=tangnano20k.cst, packing uses gowin_pack -d GW2A-18C, and loading uses openFPGALoader -b tangnano20k. The Yosys documentation marks synth_gowin as experimental. nextpnr for Gowin is built with -DARCH="himbaechel" -DHIMBAECHEL_UARCH="gowin". Run the commands in the examples folder of the Apicula repository. Sources: https://github.com/YosysHQ/apicula, https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile, https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/index_techlibs_gowin.html and https://github.com/YosysHQ/nextpnr Step 7. UART. The Sipeed example repository has a uart folder: the example prints two messages; open the port at 115200 baud. The board cannot be programmed while the serial port is open, so close the terminal before loading. Source: https://github.com/sipeed/TangNano-20K-example Step 8. Sipeed examples. The official TangNano-20K-example repository has the folders audio, hdmi, led, linux, litex, nestang, picorv32, riscv_core, rgb_lcd, uart and ws2812. For a first pass take led and uart and leave the rest for later. Source: https://github.com/sipeed/TangNano-20K-example Step 9. Next step: HDMI or SDRAM. The hdmi example in the Sipeed repository drives a 1280x720 screen. In the open-source flow, the Apicula Makefile has a dvi-example target for tangnano20k built from DVI/dvi-example.v, DVI/pll480.v and DVI/tmds-channel.v. The board SDRAM (32-bit, 64M bits) is reached through logic in the FPGA; the Hackaday article notes that talking to it takes some FPGA resources. The checked sources contain no ready-made SDRAM example. Sources: https://github.com/sipeed/TangNano-20K-example, https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile, https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html and https://hackaday.com/2026/09/28/the-fpga-chronicles-exploring-the-tang-nano-20k/ Step 10. After that. Hackaday promises open-source tools, IP, synchronous logic and the built-in logic analyzer; add those parts to the route as they appear. Series page: https://hackaday.com/series_of_posts/fpga-chronicles Commands from the documentation (Linux). Check board names: openFPGALoader --list-boards. Load to SRAM from a Gowin project folder: openFPGALoader -m -b tangnano20k impl/pnr/*.fs. Install Apicula: pip install apycula. Synthesis: yosys -D LEDS_NR=6 -D OSC_TYPE_OSC -D INV_BTN=1 -D CPU_FREQ=27 -D BAUD_RATE=115200 -D NUM_HCLK=5 -D RISCV_MEM_88K -p "read_verilog blinky.v; synth_gowin -json blinky-tangnano20k-synth.json -family gw2a -setundef". Place and route: nextpnr-himbaechel --timing-allow-fail -r --json blinky-tangnano20k-synth.json --write blinky-tangnano20k.json --device GW2AR-LV18QN88C8/I7 --vopt family=GW2A-18C --vopt cst=tangnano20k.cst. Pack: gowin_pack -c -d GW2A-18C -o blinky-tangnano20k.fs blinky-tangnano20k.json. Load: openFPGALoader -b tangnano20k blinky-tangnano20k.fs. DVI example synthesis (the other steps are the same): yosys -D INV_BTN=1 -D IS_ELVDS=0 -p "read_verilog -sv DVI/dvi-example.v DVI/pll480.v DVI/tmds-channel.v; synth_gowin -json dvi-example-tangnano20k-synth.json -family gw2a -setundef". Build nextpnr for Gowin: cmake .. -DARCH="himbaechel" -DHIMBAECHEL_UARCH="gowin". Sources: https://trabucayre.github.io/openFPGALoader/guide/first-steps.html, https://trabucayre.github.io/openFPGALoader/vendors/gowin.html, https://github.com/YosysHQ/apicula, https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile, https://github.com/YosysHQ/nextpnr Pitfalls confirmed by the sources. The onboard debugger is not recognized: connect the board directly to the computer, not through a USB hub, try another cable and another computer, update the debugger firmware (Sipeed wiki, https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html). UART output is garbled or the speed is four times the set one: update the debugger firmware, reinstall the FTDI drivers (Sipeed wiki, https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html). The board cannot be programmed while the serial port is open (Sipeed repository, https://github.com/sipeed/TangNano-20K-example). A load to SRAM is lost at power-off; for start-up use external flash (https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/led.html). For C devices Apicula needs --vopt family in nextpnr and the family name in gowin_pack (https://github.com/YosysHQ/apicula). The Sipeed LED page was partly carried over from the Tang Primer 20K (its text mentions the Primer 20K and a "core board"), so check the pin numbers against the Tang Nano 20K schematic (https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/led.html). The Gowin IDE on an unsupported Linux distribution needed manual fixes in the Hackaday author's setup: replacing libfreetype.so.6, setting LD_LIBRARY_PATH and a udev rule for the ftdi_sio driver; the author writes that these may not help others (https://hackaday.com/2026/09/28/the-fpga-chronicles-exploring-the-tang-nano-20k/). In the openFPGALoader Gowin notes the -f list of boards does not include tangnano20k, while the boards table gives external flash (EF) for it: check the documentation when writing to flash (https://trabucayre.github.io/openFPGALoader/vendors/gowin.html). Verified facts Apicula supports Tang Nano 20K (GW2AR-LV18QN88C8/I7) with Yosys, nextpnr-himbaechel and openFPGALoader. Source: https://github.com/YosysHQ/apicula. Checked: 2026-10-02. Confidence: 5/5. The Makefile commands for tangnano20k use synth_gowin -family gw2a, --vopt family=GW2A-18C and gowin_pack -d GW2A-18C. Source: https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile. Checked: 2026-10-02. Confidence: 5/5. openFPGALoader accepts the board name tangnano20k and loads .fs files to SRAM with -m. Source: https://trabucayre.github.io/openFPGALoader/vendors/gowin.html. Checked: 2026-10-02. Confidence: 5/5. The Sipeed uart example runs at 115200 baud and the FPGA cannot be burned while the serial port is open. Source: https://github.com/sipeed/TangNano-20K-example. Checked: 2026-10-02. Confidence: 5/5. Engineering benefit The route covers both the vendor flow (Gowin IDE) and the open-source flow (Yosys, nextpnr-himbaechel, Apicula, openFPGALoader) for the same chip, so the same LED example can be built either way. Source: https://github.com/YosysHQ/apicula. Checked: 2026-10-02. Confidence: 4/5. Apicula's examples Makefile has Tang Nano 20K targets for LED, memory, DSP, RISC-V and DVI designs, which gives follow-up exercises after the first LED. Source: https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile. Checked: 2026-10-02. Confidence: 5/5. Commercial benefit The Gowin Education edition is free to use and includes the Tang Nano 20K chip, so a learner can start without buying a license; it supports fewer devices and fewer IP cores than Standard. Edition contents may have changed since the page table of 2023-05-29. Source: https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-Doc/install-the-ide.html. Checked: 2026-10-02. Confidence: 5/5. Community benefit Sipeed lists support channels for the board (Reddit r/GowinFPGA, Telegram, a forum), and the Hackaday author invites discussion of the series on Discord. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html. Checked: 2026-10-02. Confidence: 4/5. Critical review The Sipeed wiki pages carry 2023 dates, and the LED page was partly adapted from the Tang Primer 20K, so details such as IDE screenshots and pin hints can be out of date. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/led.html. Checked: 2026-10-02. Confidence: 4/5. The Yosys documentation calls synth_gowin experimental, and the Apicula readme describes a project that parses vendor data and fuzzes the bitstream, so the open-source flow carries more risk than the vendor flow. Source: https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/index_techlibs_gowin.html. Checked: 2026-10-02. Confidence: 4/5. The commands were not run on a board by the editors; they are taken from the documentation and the Apicula Makefile, and the Makefile comes from the master branch, which changes. Source: https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile. Checked: 2026-10-02. Confidence: 5/5. Each step links to a primary source, so a reader can check any command against the current documentation before running it. Source: https://github.com/YosysHQ/apicula. Checked: 2026-10-02. Confidence: 5/5. Practical recommendations Related pages on this site: the board card /boards/sipeed/tang-nano-20k and the news item /news/izuchenie-fpga-tang-nano-20k about the Hackaday series. Pick one flow per evening: the Gowin IDE and the open-source tools both build the same LED example, but mixing their project folders in one directory is a good way to meet new error messages. Official links Hackaday: The FPGA Chronicles: Exploring The Tang Nano 20K Hackaday: FPGA Chronicles series Sipeed wiki: Tang Nano 20K Sipeed wiki: first power-on Sipeed wiki: install the Gowin IDE Sipeed wiki: blink an LED GOWIN EDA download Project Apicula Apicula examples Makefile Yosys: synth_gowin nextpnr (himbaechel, Gowin) openFPGALoader: Gowin notes openFPGALoader: first steps openFPGALoader: boards Sipeed TangNano-20K-example on GitHub Evidence The Sipeed wiki parameter table for Tang Nano 20K lists FPGA GW2AR-LV18QN88C8/I7, 20736 LUT4, 15552 flip-flops, 828K bits of block SRAM in 46 blocks, a 32-bit SDR SDRAM of 64M bits, 48 18x18 multipliers, 2 PLLs and 8 I/O banks. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html. Checked: 2026-10-02. The board has an onboard BL616 debugger (JTAG, USB-to-UART, USB-to-SPI, control of the MS5351 clock generator), a 40-pin RGB LCD connector, an HDMI interface, 6 LEDs, 1 WS2812 RGB LED, 2 user keys, a TF card slot and 64 Mbit flash for the bitstream. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html. Checked: 2026-10-02. The default firmware in the Tang Nano 20K is LiteX; after power-on the LEDs flow, and the serial port at 115200 baud opens a LiteX terminal where a command such as "leds 62" sets the LEDs. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/unbox.html. Checked: 2026-10-02. The Sipeed install page says the GOWIN IDE comes in a Standard edition that needs a license and a free Education edition that supports fewer devices; GW2AR-LV18QN88C8/I7 (Nano 20K) is in the Education edition table. Source: https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-Doc/install-the-ide.html. Checked: 2026-10-02. The GOWIN download page lists GOWIN EDA (Standard) and GOWIN EDA (Education) and a Register / Member Login link; the Sipeed page says the IDE is downloaded after logging in. Source: https://www.gowinsemi.com/en/support/download_eda/. Checked: 2026-10-02. The Sipeed LED page walks through a new project for GW2AR-LV18QN88C8/I7, a Verilog file, synthesis, FloorPlanner constraints, place and route, and programming to SRAM or to external flash. Source: https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/example/led.html. Checked: 2026-10-02. The Hackaday article shows a two-switch, two-LED Verilog example for the Tang Nano 20K, a constraint file with pin locations, and notes that the LEDs are active low and the switches are pulled down. Source: https://hackaday.com/2026/09/28/the-fpga-chronicles-exploring-the-tang-nano-20k/. Checked: 2026-10-02. Project Apicula lists Sipeed Tang Nano 20K (GW2AR-LV18QN88C8/I7) as a supported board and asks for Yosys, nextpnr-himbaechel, openFPGALoader and Python 3.9 or newer; the tools install with "pip install apycula". Source: https://github.com/YosysHQ/apicula. Checked: 2026-10-02. For the Tang Nano 20K the Apicula Makefile calls Yosys with synth_gowin -family gw2a, nextpnr-himbaechel with --device GW2AR-LV18QN88C8/I7 --vopt family=GW2A-18C --vopt cst=tangnano20k.cst, and gowin_pack with -d GW2A-18C. Source: https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile. Checked: 2026-10-02. The Yosys documentation describes synth_gowin with -json, -family (gw1n, gw2a, gw5a) and marks the command as experimental. Source: https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/index_techlibs_gowin.html. Checked: 2026-10-02. The nextpnr README builds the Gowin target with -DARCH="himbaechel" -DHIMBAECHEL_UARCH="gowin" and points to the Apicula examples for Gowin boards. Source: https://github.com/YosysHQ/nextpnr. Checked: 2026-10-02. The openFPGALoader Gowin notes list tangnano20k among the board names usable with "openFPGALoader -m -b BOARD_NAME impl/pnr/*.fs" for SRAM loading; its boards table gives tangnano20k as Sipeed Tang Nano 20k with FPGA Gowin Arora GW2A(R)-18(C) and flash mode EF (external flash). Source: https://trabucayre.github.io/openFPGALoader/vendors/gowin.html. Checked: 2026-10-02. The openFPGALoader first-steps page gives "openFPGALoader -b my_fpga_board my_bitstream.bit" (SRAM) and "-f" (flash) and mentions "openFPGALoader --list-boards". Source: https://trabucayre.github.io/openFPGALoader/guide/first-steps.html. Checked: 2026-10-02. The Sipeed example repository TangNano-20K-example has directories audio, hdmi, led, linux, litex, nestang, picorv32, riscv_core, rgb_lcd, uart and ws2812; the hdmi demo drives a 1280x720 screen, the uart example prints two messages at 115200 baud, and the FPGA cannot be programmed while the serial port is open. Source: https://github.com/sipeed/TangNano-20K-example. Checked: 2026-10-02. The Apicula Makefile has a dvi-example target for the tangnano20k board built from DVI/dvi-example.v, DVI/pll480.v and DVI/tmds-channel.v. Source: https://raw.githubusercontent.com/YosysHQ/apicula/master/examples/Makefile. Checked: 2026-10-02. The Hackaday article says the first part of the series uses the GOWIN IDE and that later parts cover open-source tools, IP, synchronous logic and the built-in logic analyzer. Source: https://hackaday.com/2026/09/28/the-fpga-chronicles-exploring-the-tang-nano-20k/. Checked: 2026-10-02.