Tang Nano 20K Unbox

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.

unbox_nano_20k_led_water_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.

unbox_device_manager_serial_port

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

unbox_uart_litex_terminal

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

unbox_uart_litex_command_list

Here we take leds as example, type leds command.

unbox_uart_litex_leds_command_help

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.

unbox_uart_litex_leds_command_control

There is only one led on.

unbox_uart_litex_leds_command

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

unbox_uart_litex_leds_max_value

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.

unbox_uart_bl616_terminal

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

unbox_uart_bl616_command_list

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.

unbox_uart_bl616_pllclk_command

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

unbox_uart_bl616_ms351_clk_pin

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

  • Set CLK1 output 50M clock

pll_clk O1=50M

unbox_uart_bl616_ms351_set_o1_clk_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

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

pll_clk -s

unbox_uart_bl616_ms351_save

  • Set CLK2 output 100M clock and save configuration

pll_clk O2=100M -s

unbox_uart_bl616_ms351_clk2_100m

choose

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

unbox_uart_bl616_choose_list

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.

unbox_uart_bl616_choose_uart

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.

unbox_uart_bl616_quit_uart_mode

  • 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

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.

unbox_burn_nestang_firmware_into_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

unbox_burn_nestang_game_image_select_file unbox_burn_nestang_game_image_choose_game_image

A warning comes out, but we click Continue.

unbox_burn_nestang_game_warn_no_partition_table

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

unbox_burn_nestang_game_change_tfcard_select unbox_burn_nestang_game_select_tf_card

Click Flash.

unbox_burn_nestang_game_burn_game_image unbox_burn_nestang_game_finish_burn_game_image

Assemble board

  • Insert TF card into board.

unbox_burn_nestang_game_tf_card_onsert

  • Tie joystick convertor board and FPGA board on breadboard.

unbox_burn_nestang_game_breadboard_connecting

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

unbox_burn_nestang_game_connect_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.

unbox_burn_nestang_power_game

  • 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