{"id":24283078,"url":"https://github.com/vossstef/vic20nano","last_synced_at":"2025-03-05T15:25:31.756Z","repository":{"id":227160960,"uuid":"770613159","full_name":"vossstef/VIC20Nano","owner":"vossstef","description":"Commodore VIC20 core for the Tang Nano 9k Nano 20k Primer 20k Primer 25k Mega 60k Mega138k Pro FPGA","archived":false,"fork":false,"pushed_at":"2025-02-04T22:08:32.000Z","size":38347,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-04T23:19:53.633Z","etag":null,"topics":["commodore","fpga","gowin","mist","sipeed","sipeed-","sipeed-tang-138k-pro","sipeed-tang-nano-20k","sipeed-tang-nano-9k","tang-nano","tang-primer","tang-primer-25k","tangnano20k","tangnano9k","vic20"],"latest_commit_sha":null,"homepage":"","language":"VHDL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vossstef.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-11T21:09:50.000Z","updated_at":"2025-02-01T08:32:13.000Z","dependencies_parsed_at":"2024-03-16T19:58:35.675Z","dependency_job_id":"d7b83e6b-39c2-48bc-a051-169ee298f3d5","html_url":"https://github.com/vossstef/VIC20Nano","commit_stats":null,"previous_names":["vossstef/vic20nano"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vossstef%2FVIC20Nano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vossstef%2FVIC20Nano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vossstef%2FVIC20Nano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vossstef%2FVIC20Nano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vossstef","download_url":"https://codeload.github.com/vossstef/VIC20Nano/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242050449,"owners_count":20063773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commodore","fpga","gowin","mist","sipeed","sipeed-","sipeed-tang-138k-pro","sipeed-tang-nano-20k","sipeed-tang-nano-9k","tang-nano","tang-primer","tang-primer-25k","tangnano20k","tangnano9k","vic20"],"created_at":"2025-01-16T03:56:17.037Z","updated_at":"2025-03-05T15:25:31.745Z","avatar_url":"https://github.com/vossstef.png","language":"VHDL","readme":"# VIC20Nano\n\nThe VIC20Nano is a port of some [MiST](https://github.com/mist-devel/mist-board/wiki) and\n[MiSTer](https://mister-devel.github.io/MkDocs_MiSTer/) components of the\n[VIC20](https://en.wikipedia.org/wiki/VIC-20) for the :\n\n| Board      | FPGA       | support |Note|\n| ---        |        -   | -     |-|\n| [Tang Nano 9k](https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-9K/Nano-9K.html)       | [GW1NR](https://www.gowinsemi.com/en/product/detail/38/)  |HDMI / LCD|no C1541, Tape Mega-Cart.  Only 8k or 16k memory expansion. micro SD card [HW modification](TANG_NANO_9K.md#hw-modification) needed|\n| [Tang Nano 20k](https://wiki.sipeed.com/nano20k)     | [GW2AR](https://www.gowinsemi.com/en/product/detail/38/)  |HDMI / LCD|- |\n| [Tang Primer 20K Dock ext Board](https://wiki.sipeed.com/hardware/en/tang/tang-primer-20k/primer-20k.html)| [GW2A](https://www.gowinsemi.com/en/product/detail/46/)|HDMI / LCD|- |\n| [Tang Primer 25K](https://wiki.sipeed.com/hardware/en/tang/tang-primer-25k/primer-25k.html) | [GW5A-25](https://www.gowinsemi.com/en/product/detail/60/)  |HDMI|no Dualshock, no Retro D9 Joystick |\n| [Tang Mega 60k NEO](https://wiki.sipeed.com/hardware/en/tang/tang-mega-60k/mega-60k.html)|[GW5AT-60](https://www.gowinsemi.com/en/product/detail/60/)|HDMI / LCD|two Dualshock, selectable |\n| [Tang Mega 138k Pro](https://wiki.sipeed.com/hardware/en/tang/tang-mega-138k/mega-138k-pro.html)|[GW5AST-138](https://www.gowinsemi.com/en/product/detail/60/) |HDMI / LCD|two Dualshock, selectable |\n\nBe aware that the [C64](https://en.wikipedia.org/wiki/Commodore_64) had been ported too in similar manner ([C64Nano](https://github.com/vossstef/tang_nano_20k_c64)).\nAlso the [Atari 2600 VCS](https://en.wikipedia.org/wiki/Atari_2600) had been ported ([A2600Nano](https://github.com/vossstef/A2600Nano)).\n\nOriginal VIC-20 core by [MikeJ (Mike Johnson)](https://www.fpgaarcade.com/author/mikej/) and [WoS (Wolfgang Scherr)](https://www.researchgate.net/profile/Wolfgang_Scherr2), C1541 by [darfpga](https://github.com/darfpga).  \nAll HID components and µC firmware by Till Harbaum\n\nThis project relies on an external µC being connected to the Tang Nano 20K. You can use a [M0S Dock BL616](https://wiki.sipeed.com/hardware/en/maixzero/m0s/m0s.html), [Raspberry Pi Pico (W)](https://www.raspberrypi.com/documentation/microcontrollers/pico-series.html) or [esp32-s2](https://www.espressif.com/en/products/socs/esp32-s2)/[s3](https://www.espressif.com/en/products/socs/esp32-s3) and use the [FPGA companion firmware](http://github.com/harbaum/FPGA-Companion). Basically a µC acts as USB host for USB devices and as an OSD controller using a [SPI communication protocol](https://github.com/harbaum/MiSTeryNano/blob/main/SPI.md).\n\nFor the [M0S Dock BL616](https://wiki.sipeed.com/hardware/en/maixzero/m0s/m0s.html) there is a:\n\n* [Optional custom carrier board MiSTeryShield20k](https://github.com/harbaum/MiSTeryNano/tree/main/board/misteryshield20k/README.md)\n* [Optional case](https://github.com/prcoder-1/MiSTeryNano-Case)\n* [Dualshock Adapter / Cable](/board/misteryshield20k_ds2_adapter/misteryshield20k_ds2_adapter_cable.md)\n\nand for the Raspberry PiPico (RP2040 µC) there is a:\n\n* [Optional custom carrier board MiSTeryShield20k Raspberry PiPico](/board/misteryshield20k_rpipico/README.md)\n\nFeatures:\n\n* PAL 832x576p@50Hz or NTSC 800x480p@60Hz HDMI Video and Audio Output\n* TFT-LCD module 800x600 [SH500Q01Z](https://dl.sipeed.com/Accessories/LCD/500Q01Z-00%20spec.pdf) + Speaker support\n* USB Keyboard via µC (Sipeed M0S Dock BL616 / Raspberry Pi Pico RP2040 / ESP32 S2/S3)\n* [USB Joystick](https://en.wikipedia.org/wiki/Joystick) via µC\n* [USB Mouse](https://en.wikipedia.org/wiki/Computer_mouse) via µC as [c1351](https://en.wikipedia.org/wiki/Commodore_1351) Mouse emulation\n* [USB Gamepad](https://en.wikipedia.org/wiki/Gamepad) Stick via µC as [Paddle](https://www.c64-wiki.com/wiki/Paddle) Emulation\n* [legacy D9 Joystick](https://en.wikipedia.org/wiki/Atari_CX40_joystick) (Atari / Commodore digital type) [MiSTeryNano shield](https://github.com/harbaum/MiSTeryNano/tree/main/board/misteryshield20k/README.md)\n* Joystick emulation on Keyboard [Numpad](https://en.wikipedia.org/wiki/Numeric_keypad)\n* [Dualshock 2 Controller Gamepad](https://en.wikipedia.org/wiki/DualShock) Keys \u0026 Stick as Joystick\n* [Dualshock 2 Controller Gamepad](https://en.wikipedia.org/wiki/DualShock) Sticks as [Paddle](https://www.c64-wiki.com/wiki/Paddle) Emulation (analog mode)\n* emulated [1541 Diskdrive](https://en.wikipedia.org/wiki/Commodore_1541) on FAT/extFAT microSD card\n* C1541 DOS ROM selection\n* Cartridge ROM (*.PRG) loader\n* Direct BASIC program file (*.PRG) injection loader\n* Tape (*.TAP) image loader [C1530 Datasette](https://en.wikipedia.org/wiki/Commodore_Datasette)\n* Loadable 8K Kernal ROM (*.BIN)\n* Mega-Cart (*.ROM) loader\n* On Screen Display (OSD) for configuration and D64 image selection\n* 3K, 8K, 16K, 24K, 32K RAM Expansion (35k with cardtridge RAM)\n* 8K RAM at $A000 as loadable Cartridge Slot\n* RS232 Serial Interface [VIC-1011](http://www.zimmers.net/cbmpics/xother.html) to Tang onboard USB-C serial port or external hw pin.\n\n\u003cimg src=\"./.assets/vic20nano.png\" alt=\"image\" width=\"80%\" height=\"auto\"\u003e\n\n## Installation\n\nThe installation of VIC20 Nano on the Tang Nano 20k board can be done using a Linux PC or a Windows PC\n[Instruction](INSTALLATION_WINDOWS.md).\n\n## VIC20Nano on Tang Nano 9K\n\nSee [Tang Primer 9K](TANG_NANO_9K.md)\n\n## VIC20Nano on Tang Primer 20K (Dock ext board)\n\nSee [Tang Primer 20K](TANG_PRIMER_20K.md)\nThe DDR3 memory controller is a slight modified copy of [nestang](https://github.com/nand2mario/nestang). It had been tested on a board eqipped with a SKHynix DDR3 memory and is used as a buffer for the TAP Tape loading.\n\n## VIC20Nano on Tang Primer 25K\n\nSee [Tang Primer 25K](TANG_PRIMER_25K.md). PMOD TF-CARD V2 is required !\n\n## VIC20Nano on Tang Mega 60k NEO\n\nSee [Tang Mega 60K NEO](TANG_MEGA_60K.md)\n\n## VIC20Nano on Tang Mega 138K Pro\n\nSee [Tang Mega 138K Pro](TANG_MEGA_138K.md)\n\n## VIC20Nano with LCD and Speaker\n\nSee [Tang Nano LCD](TANG_LCD.md)\n\n## emulated Diskdrive c1541\n\nEmulated 1541 on a regular FAT/exFAT formatted microSD card.\nCopy a D64 Disk image to your sdcard and rename it to **disk8.d64** as default boot image.\nAdd further D64 images as you like and insert card in TN/TP slot. LED 0 acts as Drive activity indicator.\n\u003e [!TIP]\nDisk directory listing: [or F1 keypress in JiffyDOS]  \ncommand:  \nLOAD\"$\",8  \nLIST  \nLoad first program from Disk: (or just LOAD if Dolphin Kernal active)  \nLOAD\"*\",8  \nRUN  \nJiffyDOS can be used as well known Speedloader. Change in OSD the c1541 DOS to Jiffy too.\n\n## RAM Expansion\n\nSize and Region can be activated in several steps. A change takes effect immediately.\nTake care to activate the correct size of needed expansion before you load .PRG and .TAP !\n\n|Expansion| $0400 3k | $2000 8k |$4000 8k |$6000 8k |$A000 8k |\n| - | - | - |- |- |- |\n| Block | 0 | 1 |2 |3 |Cartridge|\n| 3k | x | - |- |- | |\n| 8k | -  | x  |- |- | |\n| 16k | -  | x |x |- | |\n| 24k | -  | x  |x |x | |\n| 35k | x  | x  |x |x |x|\n\n## Cartridge ROM Loader (.PRG/.CRT)\n\nCartrige ROM can be loaded via OSD file selection.\nBe aware that the core doesn't support the [VICE EMU](https://vice-emu.sourceforge.io/vice_16.html) file format.\nTypical VIC20 Cartridge ROMS with ending .PRG have a two byte header indicating the loading location.\n8k Cartridges to be loadeded directly as such. 16k or larger Cartridges have to be loaded in several steps and the file with ending xyz-a000.prg have to be loaded last. First load xyz-2000.prg, xyz-4000.prg or xyz-6000.prg and then xyz-a000.prg at last. The Cartridge will start after that last step automatically.\nCopy a 8K xyz-a000.prg ROM to your sdcard and rename it to **vic20crt.crt** as default boot cartridge.\n\u003e [!TIP]\n**Detach Cartridge** by OSD :\n```temporary``` **Cartridge unload \u0026 Reset**. ```permanent``` **No Disk**, **Save settings** and System **Cold Boot**\n\n## BASIC Program Loader (.PRG)\n\nA BASIC Program .PRG file can be loaded via OSD file selection.\nCopy a .PRG to your sdcard and rename it to **vic20prg.prg** as default boot basic program.\nPrevent PRG load by OSD PRG selection **No Disk** , **Save settings** and **Reset**.\n\u003e [!TIP]\n\u003e Check loaded file by command: **LIST**\n\n\u003e [!IMPORTANT]\n\u003e command: **RUN**\n\n## Tape Image Loader (*.TAP)\n\nA [Tape](https://en.wikipedia.org/wiki/Commodore_Datasette) *.TAP file can be loaded via OSD file selection\nIn order to start a tape download choose VIC20 CBM Kernal (mandatory as JiffyDOS doesn't support Tape). Best to save Kernal OSD selection via **Save settings**.\n\u003e [!IMPORTANT]\n\u003e command: **LOAD**\n\nThe file is loaded automatically as soon as TAP file selected via OSD (no need to press PLAY TAPE button) in case ***no** TAP had been previously selected*.\nAfter some seconds the filename of the to be loaded file will be shown and it will take time...\nCopy a *.TAP to your sdcard and rename it to **vic20tap.tap** as default tape mountpoint.\nFor **Tape unload** use OSD TAP selection **No Disk** and **Reset** or System **Cold Boot**.\n\u003e [!WARNING]\n\u003e After board power-up or coldboot a TAP file will **not autoloaded** even if TAP file selection had been saved or c64tap.tap mountpoint available !\n\u003e Unblock loader by OSD TAP selection **No Disk** or simply select again the desired TAP file to be loaded after you typed **LOAD**\n\n\u003e [!TIP]\n\u003e Check loaded file by command: **LIST**\n\n\u003e [!IMPORTANT]\n\u003e command: **RUN**\n\n\u003e [!NOTE]\n\u003e The available (muffled) Tape Sound audio can be disabled from OSD.\n\n## Kernal Loader (.BIN)\n\nThe CBM factory PAL type is the power-up default Kernal.\n\u003e [!TIP]\n\u003e If you are fine with that then there is no need to load another Kernal via OSD and just select OSD Kernal BIN selection **No Disk** and **Save settings**!\n\nKernal ROM files *.BIN can be loaded via OSD selection (e.g. JiffyDOS VIC20).\nCopy a 8K VIC20 Kernal ROM .BIN to your sdcard and rename it to **vic20kernal.bin** as default boot Kernal.\nPrevent Kernal load by OSD Kernal BIN selection **No Disk** and **Save settings** and do a **power-cyle** of the board.\n\n## loadable Cartridge RAM Slot\n\nSome Cartridge based games can be be simply loaded from a [VIC20](https://vic20reloaded.com) D64 Disk Image.\nExample: 16 k Cartridge Game\nEnable RAM Expansion at $2000 (or $6000) and Cartridge region $A000\nLeave OSD setting CRT writeable setting as enabled as first approach.\nSave setting and do a Cold Boot Reset.\n``` LOAD \"xyz.200\",8,1```   (Block 1)\n``` or LOAD \"xyz.600\",8,1```   (Block 3)\n``` LOAD \"xyz.A00\",8,1```   (Block 5)\nStart Game by command: SYS40960 (general start Address for Cartridge Slot) or better perform a Reset via OSD.\nThere are also some cartridge games on D64 Image with a loader that themselves further reload the needed RAM regions and autostart (you have to activate RAM regions beforhand). A loaded Cartridge can be exited by disabling memory region $A000 + Cold Reset via OSD. In order to trial another game just activate again (after reset !) the $A000 memory and load another game.\n\n## Mega-Cart (.ROM)\n\nThe 2MB [Mega-Cart](https://www.retroisle.com/commodore/vic20/Articles/megacart.php) *.ROM can be loaded via OSD file selection.\nIf the Mega-Cart is used, then managing the RAM expansion configuration is done in its menu. NVRAM is not supported.\n\n## Core Loader Sequencing\n\nThe core will after power cycle/ cold-boot start downloading the images on the sdcard in the following order:\n\u003e [!NOTE]\n(1) BIN Kernal, (2) CRT ROM, (3) PRG Basic.\n\n## Push Button / DIP Switch utilization\n\n* Nano 20k S2 keep pressed during power-up for FLASH programming of FPGA bitstream\n* Primer 20k: There is by default unfortunately no Button/Switch to prevent FPGA bitstream load from FLASH (see rework how to add).\n* Mega 60k NEO ```SW1 ON``` ```SW6 ON``` + Press \u0026 **Hold** ```RECONFIG``` + Power the Board + release ```RECONFIG``` and perform programming.\n\n\u003e [!CAUTION]\nA FLASH programm attempt without keeping the board in reset may lead to corruption of the C1541 DOS images stored in FLASH requiring re-programming.\n\n* **S1** reserved\n\n## OSD\n\ninvoke by F12 keypress\n\n* Reset\n* Cold Reset\n* Audio Volume + / -\n* Scanlines effect %\n* Widescreen activation\n* Screen centering\n* PAL / NTSC Video mode\n* HID device selection for Joystick Port\n* RAM Expansion $A000(8k), $6000(8k), $4000(8k), $2000(8k), $0400(3k)\n* Cartridge Write protection\n* c1541 Drive disk image selection\n* c1541 Disk write protetcion\n* c1541 Reset\n* c1541 DOS ROM selection\n* Loader (CRT/PRG/BIN/TAP/ROM) file selection\n* Cartridge unload\n\n## Gamecontrol support\n\nlegacy single D9 Digital Joystick. OSD: **Retro D9**  \n\nUSB Joystick(s). OSD: **USB #1 Joy** or **USB #2 Joy**  \n\nGamepad Stick as Joystick. OSD: **DualShock2**  \n**stick digital** for Move and Left **L1** or Right **R1** shoulder Button for Trigger or following **Pad** controls:\n\n| Buttons | - | - |\n| - | - | -  |\n| Left L1/R1Trigger | triangle buttonUp  | .  |\n| square buttonLeft | - | circle buttonRight |\n| - | cross buttonDown | - |\n\nKeyboard Numpad. OSD: **Numpad**  \n\n|- | | |\n|-|-|-|\n|0 Trigger|8 Up|-|\n|4 Left|-|6 Right|\n|-|2 Down|-|\n\nMouse. OSD: **Mouse**  \nUSB Mouse as c1351 Mouse emulation.\n\nDualshock2 Gamepad as Paddle. OSD: **DS2 Paddle**  \nDualshock 2 Sticks in analog mode as VC-1312 Paddle emulation.\nLeft **L1 / L2**  and Right **R1 / R2** shoulder Button as Trigger\nYou have first to set the DS2 Sticks into analog mode by pressing the DS2 ANALOG button. Mode indicated by red light indicator.Configure DIGITAL mode (press ANALOG button again) when using the **Joystick** mode again and set OSD: **DualShock**\n\nUSB Paddle. OSD: **USB #1 Padd** or **USB #2 Padd**  \nLeft Stick in X / Y analog mode as VC-1312 Paddle emulation.\nButton **1 / 2** as Trigger\n\n## Keyboard\n\n![Layout](\\.assets/keymap.gif)\nTape Play not implemented.\n\n## LED UI\n\n| LED | function        | TN20K | TP20K | TP25K |TM60k     |TM138K Pro |TN9k|\n| -   |        -        | -     |-      | -     |-         |-          |-   |\n| 0   | c1541 activity  | x     |x      |  x    |x (done)  |x          |N/A |\n| 1   | D64 selected    | x     |x      |  x    |x (ready) |x          |N/A |\n| 2   | CRT seleced     | x     |x      | -     |-         |x          |x   |\n| 3   | PRG selected    | x     |x      | -     |-         |x          |x   |\n| 4   | Kernal selected | x     |x      | -     |-         |x          |x   |\n| 5   | TAP selected    | x     |x      | -     |-         |x          |N/A |\n\nSolid **\u003cfont color=\"red\"\u003ered\u003c/font\u003e** of the c1541 led after power-up indicates a missing DOS in Flash\n\n## Multicolor RGB LED\n\n* **\u003cfont color=\"green\"\u003egreen\u003c/font\u003e**\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;all fine and ready to go\n* **\u003cfont color=\"red\"\u003ered\u003c/font\u003e**\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;something wrong with SDcard / default boot image\n* **\u003cfont color=\"blue\"\u003eblue\u003c/font\u003e**\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;µC firmware detected valid FPGA core\n* **\u003cfont color=\"yellow\"\u003eyellow\u003c/font\u003e**\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;FPGA core can't detect valid firmware\n* **white**\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;\u0026ensp;\u0026thinsp;-\n\n## RS232 Serial Interface\n\nThe Tang onboard USB-C serial port can be used for communication with the Userport Serial port [VIC-1011](http://www.zimmers.net/cbmpics/xother.html).\nTerminal programs need the Kernal serial routines therefore select via OSD the CBM Kernal. For a first start use 1200Baud and a Terminal program like [VIC term](https://github.com/sblendorio/victerm300) and on the PC side [Putty](https://www.putty.org).\nOSD selection allows to change in between TANG USB-C port or external HW pin interface.\n\n| Board      |RX (I) FPGA |TX (O) FPGA|Note|\n|  -         |   -    |   -  | -   |\n| TN20k      |31      | 77   |[pinmap](https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html#Pin-diagram), misterynano io(6) / io(7)|\n| TP25k      |K5      | L5   | J4-6  J4-5, share M0S Dock PMOD|\n| TM60k NEO  |AB20    | AA19 | J24-6 J24-5, share M0S Dock PMOD |\n| TM138k Pro |H15     | H14  | J24-6 J24-5, share M0S Dock PMOD |\n\nRemember that in + out to be crossed to connect to external device. Level are 3V3 tolerant.\n\n## Powering\n\nPrototype circuit with Keyboard can be powered by Tang USB-C connector from PC or a Power Supply Adapter.\n\n## Synthesis\n\nSource code can be synthesized, fitted and programmed with GOWIN IDE Windows or Linux.\nAlternatively use the command line build script **gw_sh.exe** build_tn20k.tcl, build_tp20k.tcl or build_tp25k.tcl\n\n## Pin mapping\n\nsee pin configuration in .cst configuration file\n\n## HW circuit considerations\n\n* Pinmap TN20k Interfaces\n Sipeed M0S Dock, digital Joystick D9 and DualShock Gamepad connection.\n ![wiring](\\.assets/wiring_spi_irq.png)\n\n### Pinmap D-SUB 9 Joystick Interface\n\nJoystick interface is 3.3V tolerant. Joystick 5V supply pin has to be left floating !\n\n![pinmap](\\.assets/vic20-Joystick.png)\n\n| Joystick pin |IO| Tang Nano pin | FPGA pin | Joystick Function |\n| ----------- |-----| ---   | --------  | ----- |\n| 1 |2| J6 10  | 25   | UP |\n| 2 |1| J6 9  | 28 | DOWN |\n| 3 |4| J6 12 | 29 | LEFT |\n| 4 |3| J5 11 | 26 | RIGHT |\n| 5 |-| - | - | POT Y |\n| 6 |0| J5 8 | 27 | TRIGGER|\n| 7 |-| n.c | n.c | 5V |\n| 8 |-| J5 20 | - | GND |\n| 9 |-| - | - | POT X |\n\n### Pinmap Dualshock 2 Controller Interface\n\n\u003cimg src=\"./.assets/controller-pinout.jpg\" alt=\"image\" width=\"30%\" height=\"auto\"\u003e\n\n| DS pin | Tang Nano pin | FPGA pin | DS Function |\n| ----------- | ---   | --------  | ----- |\n| 1 | J5 18 | 71 MISO | JOYDAT  |\n| 2 | J5 19 | 53 MOSI  | JOYCMD |\n| 3 | n.c. | - | 7V5 |\n| 4 | J5 15 | - | GND |\n| 5 | J5 16| - | 3V3 |\n| 6 | J5 17 | 72 CS | JOYATN|\n| 7 | J5 20 | 52 MCLK | JOYCLK |\n| 8 | n.c. | - | JOYIRQ |\n| 9 | n.c. | - | JOYACK |\n\n## Getting started\n\nIn order to use this Design the following things are needed:\n\n[Sipeed M0S Dock](https://wiki.sipeed.com/hardware/en/maixzero/m0s/m0s.html) or Raspberry Pi Pico RP2040 or ESP32-S2/S3  \n[Sipeed Tang Nano 20k](https://wiki.sipeed.com/nano20k)  \nor [Sipeed Tang Primer 25k](https://wiki.sipeed.com/hardware/en/tang/tang-primer-25k/primer-25k.html)  \nand [PMOD DVI](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#PMOD_DVI)  \nand [PMOD TF-CARD V2](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#PMOD_TF-CARD)  \nand [SDRAM](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#TANG_SDRAM)  \nand [M0S PMOD adapter](https://github.com/harbaum/MiSTeryNano/tree/main/board/m0s_pmod/README.md)  \n or ad hoc wiring + soldering.\nor [Tang Primer 20K with Dock ext Board](https://wiki.sipeed.com/hardware/en/tang/tang-primer-20k/primer-20k.html)  \nand [M0S PMOD adapter](https://github.com/harbaum/MiSTeryNano/tree/main/board/m0s_pmod/README.md)  \nand [PMOD DS2x2](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#PMOD_DS2x2)  \nor [Tang Nano 9K](https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-9K/Nano-9K.html)  \nor [Sipeed Tang Mega 138k Pro](https://wiki.sipeed.com/hardware/en/tang/tang-mega-138k/mega-138k-pro.html)  \nand [SDRAM](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#TANG_SDRAM)  \nand [PMOD DS2x2](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#PMOD_DS2x2)  \nand [M0S PMOD adapter](https://github.com/harbaum/MiSTeryNano/tree/main/board/m0s_pmod/README.md)  \nor [Tang Mega 60K NEO](https://wiki.sipeed.com/hardware/en/tang/tang-mega-60k/mega-60k.html)  \nand [SDRAM](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#TANG_SDRAM)  \nand [PMOD DS2x2](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html#PMOD_DS2x2)  \nand [M0S PMOD adapter](https://github.com/harbaum/MiSTeryNano/tree/main/board/m0s_pmod/README.md)  \n\nmicroSD or microSDHC card FAT/exFAT formatted  \nTFT Monitor with HDMI Input and Speaker\n\n| HID and Gamecontrol Hardware option | TN20k needs | alternative option |Primer 25K|Mega 60K|Mega 138K|\n| -----------                         | ---         | ---                | ---      | -      | -       |\n| USB Keyboard | [USB-C to USB-A adapter](https://www.aliexpress.us/item/3256805563910755.html) |mini USB-C hub |x|x|x|\n| [USB Joystick(s)](https://www.speedlink.com/en/COMPETITION-PRO-EXTRA-USB-Joystick-black-red/SL-650212-BKRD)|mini USB-C hub | - |x|x|x|\n| USB Mouse   |mini USB-C hub  | -  |x|x|x|\n| USB Gamepad |mini USB-C hub  | -  |x|x|x|\n| Commodore/[Atari](https://en.wikipedia.org/wiki/Atari_CX40_joystick) compatible retro D9 Joystick| [MiSTeryNano shield](https://github.com/harbaum/MiSTeryNano/tree/main/board/misteryshield20k/README.md)|D-SUB 9 M connector, breadboard to wire everything up, some jumper wires|-|adhoc SDRAM1 Joy D9|adhoc PMOD Joy D9|\n| [Dualshock 2 Controller Gamepad](https://en.wikipedia.org/wiki/DualShock) | Gamepad Adapter Board (Sipeed Joystick to DIP) respectively PMOD DS2x2 | breadboard to wire everything up and some jumper wires |-|PMOD DS2x2|PMOD DS2x2|\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvossstef%2Fvic20nano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvossstef%2Fvic20nano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvossstef%2Fvic20nano/lists"}