Tang Nano 20K MisteryNano - Maverick-Shark/retroGuru GitHub Wiki

Tang Nano 20k Linux Debian procedure - Till Harbaum (ES)

https://www.reddit.com/r/fpgagaming/comments/1dveezs/tang_nano_20k_linux_debian_procedure_till_harbaum/?tl=es-es

TN20k 3921 PCBA NOT fused

LINK
Basically you do both ROM and FPGA bitstream programming with the TN20k factory firmware friend_20k_cfg.ini and then as last step overwrite with fpga_companion_NANO20K_unfused_cfg.ini. You will instantly loose bitstream programming capability but have FPGA-Companion running. If you want to flash a new core then first friend_20k_cfg.ini need to programmed and after that you can start with programming a new core and maybe needed ROM using Gowin/ openFPGAloader. After that once again overwrite friend_20k with fpga_companion_NANO20K_unfused_cfg.ini to get FPGA-Companion again up and running.

WARNING!!!
In you have an unfused BL616 on your TN20k (older PCBA or not even marking 3921) and program the new µC firmware you will for sure brick it. Even if you have a 3921 type it is impossible to figure out is that an unfused or fused one. In order to unbrick it you have to flash factory firmware friend_20k_cfg. The unbrick process is as such harmless but you need to be aware of it.

Check USB!!!

Windows

First Install usbipd (PowerShell):

> winget install --interactive --exact dorssel.usbipd-win

Then:

> usbipd list
BUSID  VID:PID    DEVICE                                                        STATE
4-1    0403:6010  USB Serial Converter A, USB Serial Converter B                Not shared

> usbipd bind -b 4-1
> usbipd attach -w -b 4-1

WSL:

> wsl -u root
# lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 0403:6010 Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

WSL Tips:

C:\> wsl --system -u root

C:\> wsl ~ -e bash --norc --noprofile
bash-5.0$

Linux / Ubuntu

$ lsusb

Firmware recovery

Use Bouffalo Flash Cube v1.1 and flash friend_20k_cfg.ini (friend_20k_bl616.bin)

How To Flash (openFPGAloader)

Link: https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-Doc/flash-in-linux.html

$ sudo ./openFPGALoader --detect 
$ sudo ./openFPGAloader --list-boards | grep tang
$ sudo ./openFPGALoader -b tangnano9k -f core.fs

NanoMig

NOTE: Keep 4 seconds B2 button pressed when plug!!!

$ sudo ./openFPGALoader --detect 
$ sudo ./openFPGALoader -f nanomig.fs
$ sudo ./openFPGALoader --external-flash -o 0x400000 kick13.rom
$ sudo ./openFPGALoader --external-flash -o 0x440000 kick13.rom

$ sudo ./openFPGALoader --external-flash -o 0x400000 kick31.rom

Flash m0s Dock

FPGA companion for the BL616 MCU (M0S Dock)

How To Flash Fused Firmware

For the latest version of fpga-companion to work correctly, there are two steps:

The first thing we'll do is download the original firmware for the BL616 of the Tang Nano20k; it's the first-stage loader.
https://api.dl.sipeed.com/shareURL/TANG/Debugger/onboard/BL616/2025030317

Select: bl616_fpga_partner_20kNano.bin and save it to a folder on our PC.

Now, download the BL616 programmer from:
https://dev.bouffalolab.com/download/ and select:

4 Bouffalo Lab Dev Cube Development Tool All-Platform V1.9.0 2024-06-19

Now, save it to the PC folder where we have the necessary files.

We download the three files corresponding to the second-stage firmware, the latest version of the FPGA companion, from Harbaum's GitHub:

https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.3/fpga_companion_NANO20K_cfg.ini
https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.3/bl616_fpga_partner_nano20k.bin
https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.3/fpga_companion_nano20k.bin

https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.3/friend_20k_cfg.ini
https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.3/friend_20k_bl616.bin

https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.2/fpga_companion_NANO20K_cfg.ini
https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.2/fpga_companion_NANO20K_onboard_bl616.bin
https://github.com/harbaum/FPGA-Companion/releases/download/v1.4.2/bl616_fpga_partner_20kNano.bin

We save the three files in the same folder where we will perform the update.

Now we download the programmer for the latest version of FPGA Companion:
https://github.com/bouffalolab/bouffalo_sdk/archive/refs/tags/V2.0.0.zip

We save the 2.0 version of bouffalo_sdk in the same folder. Now all that's left is to flash it.

In the first step, without the Tang20k plugged into the USB port, we will press the update button in the middle of the Tang20k without releasing the button.

Holding it, we plug the USB port into the computer, wait 4 seconds, and immediately release the update button. Now we will have the Tang20k in DFU mode.
If we run lsusb in Linux from the terminal, it will appear as bouffalo cdc demo. Well, we already have it in update mode.
We start the Bouffalolab DevCube 1.9.0 programmer and select the corresponding UART port on our PC.
If it's Windows, it will mark it as ttyusb, and if it's Linux, you'll have it as ttyacm.
We select bl616_fpga_partner_20kNano.bin from the official Sipeed website, choose Open UART, and click Flash in Download.

Once we've flashed the BL616 to OK, disconnect the USB and plug the tang20k back in without touching anything.

Run lsusb again in the Linux terminal and see if the ft232h UART port appears. If so, the flashing was successful.
If the bouffalo cdc demo appears, the board has been bricked and is an old version without eFuse, so you'll need to restore the factory firmware.

Once we see the ft232h, disconnect the USB and press the update button on the BL616 again. Now select the Bouffalo SDK 2.0 programmer.
Once executed, select the FPGA Companion ini file. Three files will appear, the ones we downloaded from GitHub with their respective memory addresses.
Select the UART port and update again.

Once the flashing is complete, disconnect the USB and reconnect the Tang20k without touching anything.
Load the Linux terminal and see if ft232h appears by running an lsusb. If so, your Tang20k is ready to use the internal BL616.
If you see Bouffalo CDC Demo, it means it has been bricked and you have an old version. You'll need to restore the firmware again.

The FPGA Companion works in two stages. In the first, it loads the original Sipeed software, which contains the encryption in the eFuse.
In the second stage the TILL loader loads the corresponding BL616 firmware modified with the CherryUSB driver so it can operate the Tang20k's USB-C port.
If the first step didn't work for you, it's because your Tang20k doesn't have eFuse built in.
This is a small 4KB memory that stores the Tang20k encryption and is what verifies the FPGA companion (modified firmware).

In that case, to restore your Tang20k, you can do so at the following address:
https://github.com/harbaum/MiSTeryNano/tree/main/firmware/friend_20k

You will be unlocked with the unencrypted version.

Tang Nano 20K - MisteryNano

Linux Debian procedure - Till Harbaum Shield - MiSTERY, NanoMIG. - Stefan Voß - C64, VIC-20...

Source: https://www.reddit.com/r/fpgagaming/comments/1dveezs/tang_nano_20k_linux_debian_procedure_till_harbaum/?rdt=63539

Thanks to all the people involved in the Tang Nano 20K!

The purpose of MisteryNANO, NanoMig, C64, VIC-20, etc is to be able to order it yourself, without having to solder and without waiting. I agree with vanfanel.

First Step:

We ordered the "motherboard" board at JLCPCB. (About 100 euros for a pack of 5 plates: the minimum order is that, 5 plates).

For it:

We are going to ORDER NOW.
We click on "Add Gerber File", and upload this ZIP with the Gerbers: https://github.com/harbaum/MiSTeryNano/blob/main/board/misteryshield20k/jlcpcb/gerber_m0s.zip
We activate "PCB Assembly", and in "ADVANCED OPTIONS" we activate "Board Cleaning", "Bake Components" and "Depanel boards"
We press "NEXT"
On the next screen, which is simply a render/preview of the board, click "NEXT"
On the next screen:
In "Add BOM File" we upload this: https://github.com/harbaum/MiSTeryNano/blob/main/board/misteryshield20k/jlcpcb/bom_m0s.csv
In "Add CPL File" we upload this: https://github.com/harbaum/MiSTeryNano/blob/main/board/misteryshield20k/jlcpcb/positions_m0s.csv
In the next two screens we also click on "NEXT", in "Product Description" we choose "Audio Equipment" and at the end we click on "SAVE TO CART".
When paying for what we have in the cart, in the shipping method, we use IOSS, which is supposed to already include taxes at the time of making the card payment.

Second Step:

On Aliexpress we ordered the TangNano 20k and the M0S Dock: (About 35 euros each TangNano 20k and about 7.5 euros each M0S Dock)

We ordered the TangNano 20K from its official store: https://es.aliexpress.com/item/1005005581148230.html
NOTE: We choose the "TangNano 20K with soldered pin header" option, which is the second from the right. Do not order the TangNano 20k without soldered pins!! Careful!!
We ordered the M0S Dock from its official store: https://es.aliexpress.com/item/1005005298084680.html

NOTE: We choose the "M0S Dock" option, which is the one on the right. DO NOT ask for the loose chip!! Careful!!

Third Step:

We could order the casing. (About 29 euros if it is printed with "high quality", that is, it does not look like that rough shit full of threads that 3D printed things usually are).

You can colsut the price at: https://innova3d.es/presupuesto-online-impresion-3d/ - spanish -

We have to upload these two models:

https://github.com/harbaum/MiSTeryNano/blob/main/board/misteryshield20k/housing3D/MiSTeryNano-lid.stl https://github.com/harbaum/MiSTeryNano/blob/main/board/misteryshield20k/housing3D/MiSTeryNano-bottom.stl

I printed it in Gray PLA, with the High Quality option and with infill at 50-60%, and it looks great.

Finally:

When we receive everything, we flash:

To flash the M0S Dock:

We download this firmware file: https://github.com/vossstef/tang_nano_20k_c64/releases/download/v1.2.2/misterynano_fw_bl616.bin
We downloaded Bouffalo Lab Dev Cube 1.9.0 from https://dev.bouffalolab.com/download
By holding down the small "BOOT" button on the M0S Dock, we connect it to the computer via USB. Once connected, we can release the button.
We open the Bouffalo Lab Dev Cube, select "BL616/618" as the chip, click "Open UART", go to the "MCU" tab and in "Image File" we select the firmware file that we just downloaded.
We click on "Create & Download" and it should flash it without problems.

To flash the TangNano 20k:

We install the OpenFPGALoader. On Debian:

sudo apt-get install openfpgaloader

I only use Debian 12.

If we want the Atari ST core, we download this bitstream:

https://github.com/harbaum/MiSTeryNano/releases/download/v1.2.4/atarist.fs

If we want the C64 core, we download this bitstream:

https://github.com/vossstef/tang_nano_20k_c64/releases/download/v1.2.3/tang_nano_20k_c64.fs

Now we flash the bitstream we want. To do this, we connect the Tang Nano20k via USB and do:

openFPGALoader -f <CORE_FILE.FS>

In the case of the AtariST core, we also have to flash the TOS:

openFPGALoader --external-flash -o 0x100000 tos104us.img
openFPGALoader --external-flash -o 0x140000 tos206us.img
openFPGALoader --external-flash -o 0x180000 tos104es.img
openFPGALoader --external-flash -o 0x1c0000 tos206es.img

Finally you have this:

Case with Shield

Thanks to vanfanel to recopile the linux procedure -