Update history

Date	Version	Author	Update content
2023-05-23	v0.1	wonder	Release docs

Tang Nano 20K is mainly available as two purchase options: Retro Game kits and development board kits

Primary power-on

The default firmware in Tang Nano 20K is litex, and it can be download from github.

Power on Tang Nano 20K, leds flow.

Windows 10 and Windows 11 can install the driver automatically, and there is at least one USB Serial Port in the device manager. We can open this serial port via the serial port available application like Mobaxterm.

Set baudrate 115200, open the serial port, and we succeed opening the litex terminal.

Tap the tab on your serial terminal via keyboard to see all commands we can use.

Here we take leds as example, type leds command.

We can see it requires a value with leds command.

Here we type leds 62 via serial terminal and see the state of onboard leds.

There is only one led on.

If the value we type is too big, this command will set the value to 0xffffffff.

Advanced usage

All commands above we run are on FPGA, apart from the GW2AR-18C FPGA chip, there is an onboard BL616 chip on this board, we can open its terminal and run its built-in commands.

Similar to the previous steps, open the serial port via Mobaxterm, then use shortcut key combinations Ctrl + x and Ctrl + c, then tap Enter key to open the BL616 inside terminal.

Tap Enter key to test the terminal, and it supports commands auto-completion.

Here we take pll_clk and choose these two commands as example.

pll_clk

There is a MS5351 configurable clock generator on Tang Nano 20K, it's configured by BL616 chip, and we set the generated clock via pll_clk command.

MS5351 can generate 3 clock output, we can see its clock output pin via the schematic.

The CLK0 clock is connected with the PIN10 of FPGA, and CLK1 clock is connected with the PIN11 of FPGA, CLK2 clock is connected with the PIN13 of FPGA.

• Set CLK1 output 50M clock

pll_clk O1=50M

① Type the command, we can see the log ② Type `pll_clk` again, we can see the current configuration ③ This means O1 output 50M clock ④ [EN] means O1 enabled, [DIS] means disabled.

• Disable CLK1

pll_clk O1

① View the current configuration ② CLK1 enabled ③ Run command to disable CLK1 ④ CLK1 disabled

• Save configuration

pll_clk -s

• Set CLK2 output 100M clock and save configuration

pll_clk O2=100M -s

choose

choose command is used to choose the communication methods between FPGA and BL616 Chip.

The default communication method between FPGA and BL616 Chip is uart mode.

Use shortcut key combinations Ctrl + x and Ctrl + c, then tap Enter to quit serial communication mode, and get into BL616 terminal.

• uart mode test

Run choose uart in BL616 terminal, the BL616 communicates with FPGA via serial pins.

Type Enter to test the FPGA default litex terminal if you did not flash any firmware for FPGA.

To quit serial communication mode, use command Ctrl + x and Ctrl + c, then tap Enter to open the BL616 terminal.

• spi Mode

When in SPI mode, BL616 is the SPI slave device, and receives the SPI data from FPGA. However, the default FPGA firmware does not contain the test.

Retro Game kits

Tang Nano 20K can act as NES NESTang, here we tell how to build your Tang Nano 20K a Retro Game. Visit Tang Nano 20K nestang github example or NESTang if you want to know more.

Hardware Preparation

• One Tang Nano 20K
• One or two Joystick and Joystick convertor board
• One TF card and a card reader
• One breadboard (To tie the FPGA board and Joystick)
• HDMI monitor

Software Preparation

• Windows：Gowin Programmer , balenaEtcher and python
• Linux: Openfpgaloader and python

Linux users can visit Tang Nano 20K nestang github example to see how to build this game kit, here we use Windows as the example to tell the steps of building the game kit.

Flash FPGA firmware

Run Gowin Programmer to flash this firmware into FPGA external Flash.

Make games image

Use these scripts(All scripts need downloading), to generate your NES games into the file image which can be loaded by FPGA NES Emulator.

The following command converts 1.nes 2.nes 3.nes these three NES games into the game image file(games.img).

python nes2img.py -o games.img 1.nes 2.nes 3.nes

If it tells PIL not found. Install PIL via pip manually.

Then the game image file(games.img) is generated.

Burn game image file

We need a TF card to store the game, with this we can load the game on Tang Nano 20K.

Here we use balenaEtcher to flash the game image file.

Open this program, choose Flash from file, select the generated game image file games.img

A warning comes out, but we click Continue.

Tick your TF card, make sure you choose the right TF card, not the other disk. Click Select.

Click Flash.

Assemble board

• Insert TF card into board.

• Tie joystick convertor board and FPGA board on breadboard.

Note the read line in the picture above, it shows the relative position of FPGA pin and convertor board.

• Connect the joystick and HDMI cable

When connected 2 joysticks, player ① is the right one in the picture above.

Start game

Power on Tang Nano 20K, we can see the game menu. The number of games and the name of games depends on your NES game name and quantity when generating the game image file.

• Press ② or O to start the game
• Press S1 on the FPGA board to go back to the game menu

FPGA Development guide

Blink the LED

Introduction

Install IDE