/ README.md
README.md
1 # M.CU.M.E = Multi CompUter Machine Emulator 2 <p align="center"> 3 <img width="320" height="140" src="/images/logo.png"> 4 </p> 5 6 # News 7 Mai 2023: add multi display support to T-COMPUTER and PICOZX platforms 8 - You can now configure at boot the display to use for each emulator (Teensy41 or PICO) 9 - No need for different binaries depending on the display (VGA,ILI and ST displays are all suported) 10 - Config is stored on the SDCARD 11 - Press Up while booting to force VGA output at startup (will erase display config => default VGA) 12 - Press Left while booting to force ST7789 output at startup (will write config) 13 - Press Right while booting to force ILI9341 output at startup (will write config) 14 - When configured for non VGA display, you can always push to VGA by pressing ALT iso TAB key to start (on T-COMPUTER) 15 - Add FMSX and SNES emulators to T-COMPUTER. 16 - Port of all PICO emulators to the new PICOZX platform of BOBRICIUS 17 <br> 18 19 February 2022: introducing T(TEE)-COMPUTER platform based on Teensy41 MCU:<br> 20 - T-COMPUTER has VGA and TFT video out, Audio out, USB input, embedded 42 keys keyboard and a DB9 joystick input! 21 - now supported on T-COMPUTER: Apple2, Vic20, C64, Atari800, ZX81, ZXSpectrum, Atari ST, Amiga, Colecovision, Odyssey, NES, SMS, Genesis and Doom. 22 - new emus for Teensy41: Vic20 and Apple2 based on aiie! 23 - add AUTORUN feature to Teensy and PICO platforms 24 - add Floppy write support to Castaway ST emulator 25 - improved USB keyboard support for existing Teensy41 emus 26 <br> 27 28 December 2021:<br> 29 - Add vic20 emulation to the PICO 30 <br> 31 32 October 2021: yet more PICO platforms improvements<br> 33 - MCUME_REV2 has now dual screen support (TFT+VGA binaries where TFT can be used for keyboard control, or VGA only binaries wo keyboard control) 34 - Fix keyboard scan for PICOMPUTERMAX (C64,ZX81,ZX Spectrum and Atari800 have now usable keyboard for basic program typing) 35 <br> 36 37 September 2021: More PICO platforms improvements<br> 38 - MCUME_REV2 has now digital inputs for UP/DOWN/LEFT/RIGHT so external C64 joystick can be connected (VGA & TFT binaries) 39 - PICOMPUTERMAX now supporting ALT and FN(long press on ALT) so more C64 keys can be mapped (FN for Function keys for e.g.) 40 <br> 41 42 43 <details> 44 <summary>Click for more news</summary> 45 46 <br> 47 August 2021: Add support for PICOMPUTERMAX on PICO<br> 48 - TFT 7789 320x240 49 <br> 50 51 July 2021: Add support for TFT dispays on PICO<br> 52 - MCUME_REV2 supports VGA and TFT (ST or ILI) on same layout 53 - Add specific support for PICOMPUTER (TFT and full keyboard microswitch)<br> 54 https://www.youtube.com/watch?v=4tL9K5tXZtY 55 <br> 56 57 May 13th 2021: C64 emulator improvement for PICO<br> 58 - Overclocked to 250MHz for better speed 59 - Add on screen keyboard for text input 60 <br> 61 62 May 2021: few improvements for raspberry pi PICO<br> 63 - VGA driver stripped down for 8bits RRRGGGBB (red lines bug fixed)... 64 - Improved PWM audio... 65 - Add sound to C64 emulator but still running far too slow 66 - Add SID player application (picosnd) 67 <br> 68 69 April 2021: Add initial support for raspberry PICO<br> 70 - adapted pico scanline library for VGA 8 bits mode (RRRGGGBB), sorry adapted code is embedded... 71 - SD support from https://github.com/carlk3/no-OS-FatFS-SD-SPI-RPi-Pico (fixed IRQ to 1) 72 - rudimentary PWM IRQ based audio (https://gregchadwick.co.uk/blog/playing-with-the-pico-pt3/) 73 74 Far from perfect, lot of bugs, and ... unfortunately C64 emulator has no sound for performance reason!<br> 75 All what you need is in MCUME_pico. Precompiled binaries in MCUME_pico/bin.<br> 76 To recompile, look at MCUME_pico/readme.txt<br> 77 78 https://www.youtube.com/watch?v=MUpwlZXheb8<br> 79 https://www.youtube.com/watch?v=_WL_KGkxZ88 80 <br><br> 81 82 November 2020 UPDATE: Atari ST emulation now supporting MIDI output!<br> 83 https://www.youtube.com/watch?v=H-TlCDBwdak<br> 84 https://www.youtube.com/watch?v=fzoTYUpEOKs 85 86 87 November 2020: move to latest VGA_t4 library for stable HIRES support<br> 88 - USB mouse added to Amiga/Atari ST emulation 89 - Amiga sound improved (freq drifting less audible) 90 - Atari ST now support 640x200 and 640x400 (B/W) modes with double buffering!!! 91 - Amiga now support 640x240 mode for cleaner workbench!!!<br> 92 https://www.youtube.com/watch?v=vex335vHc68<br> 93 https://www.youtube.com/watch?v=LKdcduVwwGQ 94 95 96 Mid October 2020: Most emulators are now supporing VGA with sound on the Teensy4.1<br> 97 Experimental I2S sound driver has been added to the VGA_t4 library with minimal DMA disturbances.<br><br> 98 If you are experimenting issues (e.g. image flashing out, crash after few minutes): 99 - try compiling for smallest code iso faster 100 <br> 101 e.g.:<br> 102 - ST emu: compile for "smallest code"<br> 103 - Amiga emu: compile for "smallest code"<br> 104 - Doom: compile for "faster"<br> 105 106 Atari ST emu has now better sound support!<br> 107 <br> 108 109 October 2020: DOOM ported to the Teensy4.1 (for VGA and LCD displays)<br> 110 No sound yet but with USB keyboard support (see VGA prototype PCB below).<br> 111 https://www.youtube.com/watch?v=adYwnctiKsg 112 <br> 113 <p align="center"> 114 <img src="/images/T41VGA.jpg" width="640" /> 115 <br> 116 117 June 2020: Update of UAE (Amiga emulator) on Teensy4.1<br> 118 Now with HDD support, better sound and 68020 emulation.<br> 119 All for better compatibility...<br> 120 https://youtu.be/Ho8qZSCKdLg<br> 121 https://youtu.be/vuMYwylYqYs 122 123 May 2020: Amiga emulation on Teensy4.1 (with PSRAM) !!!<br> 124 Here is a video of the emulator running on my prototype board.<br> 125 https://youtu.be/LE4IWPG5z6g 126 127 March 2020: MSX1/2 emulation on Teensy4.0 (no SDRAM required)<br> 128 Mini-console prototype with 40 keys keyboard, keypad and 320x240 ST7789 display. 129 The prototype supports of course all systems below where keyboard is supported!<br> 130 https://youtu.be/YZGbGKmeb6I<br> 131 <br> 132 <p align="center"> 133 <img src="/images/msx.png" width="640" /> 134 <br> 135 136 137 Nov 2019: Gameboy, Sega Master System/ GameGear and Megadrive/Genesis emulator running with extra 8MB SPI RAM (PSRAM) <br> 138 https://youtu.be/j2sKw7KYpEo <br> 139 140 Oct 2019: PC-Engine 'tiny' emulator running on Teensy 4.0 using an extra 8MB SPI RAM (PSRAM) <br> 141 https://youtu.be/Ot9RgDMqdF4<br> 142 GFX bug due to objs cache limitation is now fixed! 143 <br> 144 <p align="center"> 145 <img src="/images/t4piggy.png" width="240" /> 146 <img src="/images/pcbT4.png" width="480" /> 147 <br> 148 T4 with PSRAM piggy back and latest T4 pcb! 149 </p> 150 151 <br> 152 <br> 153 154 Sep 2019: Teensy 4.0 now running Atari 520ST emulator (68k core based)!!! <br> 155 https://youtu.be/UCOaOGmYYso<br> 156 https://youtu.be/6rr2hMqprO0<br> 157 <br> 158 159 </details> 160 161 162 163 <p align="center"> 164 <img src="/images/teensy4SD.png" width="200" /> 165 </p> 166 167 <p align="center"> 168 <img src="/images/stdesktop.png" width="200" /> 169 <img src="/images/strobocop.png" width="200" /> 170 </p> 171 172 <p align="center"> 173 <img src="/images/teensybread.jpg" width="200" /> 174 <img src="/images/teensy362.jpg" width="200" /> 175 </p> 176 177 <p align="center"> 178 <img src="/images/esp321.jpg" width="200" /> 179 <img src="/images/esp322.jpg" width="200" /> 180 </p> 181 A collection of 80th game Console and Computer emulators ported to Teensy, raspberry PICO and ESP32 MCUs.<br> 182 Have a look at the video: 183 https://youtu.be/jlqoWH2X6gk<br><br> 184 This project is a spin-off of the TeensyCEC project https://github.com/Jean-MarcHarvengt/TeensyCEC<br> 185 Now ported to much more MCUs! <br> 186 187 # Featuring 188 189 Computer systems supported and status on various MCU platforms<br> 190 191 | System | Teensy3.6 | Teensy 4.0 | Teensy4.0 +PSRAM | Teensy4.1 +PSRAM | ESP32 | ESP32-Wrover | Pico | 192 | --- | --- | --- | --- | --- | --- | --- | --- | 193 | Zx81 | X | X | X | X | X | X | X | 194 | Zx spectrum | X | X | X | X | X | X | X | 195 | Atari 800 | X | X | X | X | X | X | X | 196 | C64 | X | X | X | X | X | X | X | 197 | VIC20 | | | | X | | | X | 198 | Apple2 | | | | X | | | | 199 | Atari 520ST | - | full speed! | X | X (640x400!) | - | slow | - | 200 | 8086 XT PC | - | full speed! | X | X | - | slow | - | 201 | MSX1/2 | - | full speed! | X | X | - | - | - | 202 | Amiga | - | - | exp only! | X (640x240!) | - | - | - | 203 | Doom | - | - | - | x | - | - | - | 204 205 Please compile for smallest code on the Teensy4.0 else you will run out of memory<br><br> 206 For Teensy 4.1 with PSRAM try compiling for smallest code (unless it complains at compilation).<br> 207 Doom for example only works if compiled for smallest code! 208 209 Game console systems supported and status on various MCU platforms<br> 210 211 | System | Teensy3.6 | Teensy 4.0 | Teensy4 +PSRAM | Teensy4.1 +PSRAM | ESP32 | ESP32-Wrover | Pico | 212 | --- | --- | --- | --- | --- | --- | --- | --- | 213 | Atari 2600 | X | X | X | X | X | X | X | 214 | Odyssey/Videopac | X | X | X | X | X | X | X | 215 | Colecovision | X | X | X | X | X | X | X | 216 | Atari 5200 | X | X | X | X | X | X | X | 217 | Nintendo NES | X | 384KB roms! | X | X | X | X | - | 218 | Vectrex | - | full speed! | X | X | - | slow | - | 219 | PC Engine | - | - | X | X | - | - | - | 220 | Gameboy/GBColor | - | 490KB roms| X | X | - | - | - | 221 | Sega Master System/Game Gear | - | - | X | X | - | - | - | 222 | Sega Genesis/Megadrive | - | - | X | X | - | - | - | 223 224 # Minimal requirements: 225 - Teensy3.6/Teensy4.0, ESP32 Node32S/Wrover SDK chip or Raspberry PICO 226 - ILI9341 (Teensy/ESP32) or ST7789 (Teensy only) SPI display 227 - SD card (Teensy uses built-in uSD, ESP32 uses external one connected over SPI, e.g. ILI9341 integrated one) 228 - Analog joypad (Arduino or PSP like) 229 - 3 buttons (FIRE, USER1 and USER2) 230 231 # Optional requirements: 232 - I2C custom keyboard or integrated one (for computers emulators) 233 - Sound (DAC for ESP and Teensy3.6, MQS for Teensy4.0, I2S for Teensy4.1, PWM for PICO) 234 - VGA output (Teensy 3.6, Teensy 4.1 and Raspberry PICO only) 235 - 2 extra buttons (USER3 and USER4) mostly for NES emu 236 237 # Wiring 238 - see pinout.txt file in the respective project (ESP32 or Teensy) 239 - Some KICAD image also available for ESP32 240 241 # I2C keyboard (for computer emus on Teensy 3.6 only) 242 - see i2ckeyboard sub-directory 243 - the I2C keyboard is using a separate atmega328p MCU handling the keys matrix 244 - with 10x4 or 10x5 keys 245 246 # Embedded 42 keys keyboard (on T-COMPUTER and PICOMPUTER) 247 248 # USB keyboard (on T-COMPUTER and other Teensy 4.1 platforms) 249 250 # Installation 251 - Format the SD card as FAT32 252 - extract the content of SD.zip in the root directory 253 - there must be a sub-directorie for each emulator 254 - "2600" => for atarivcs, put your Atari 2600 roms here (.bin), with sub-dirs or not 255 - "5200" => for atari5200, put your Atari 5200 roms here (.bin) 256 - "800" => for atari800, put your Atari 800 cartridges here (.rom) 257 - 'c64" => for c64, put your C64 programs here (.prg), with sub-dirs or not 258 - "vic20" => for VIC20, put your V20 programs (.prg), with sub-dirs or not 259 - "apple2" => for Apple2 disks, put your ".dsk" files here, with sub-dirs or not 260 - "o2em" => for odyssey/videopac, put your Videopac/Odysssey roms here (.bin) 261 - "coleco" => for colem, put your Colecovision roms here (.rom, including coleco.rom) 262 - "nes" => for nes/nofrendo, put your .nes files here (e.g. galaga,xevious,mario1...) 263 - "spec" => for spectrum, put your ".z80" or ".sna" files here into sub-dirs or not ( max 48K ) 264 - "z81" => for zx81, put your ".p", ".81"(, ".56") ".80" or ".o" files here ( max 56K ) 265 - "st" => for AtariST, put your floppis ".st" files here 266 - "pc" => for 8086, put your HDD image ".img" 267 - "vectrex" => for Vectrex, put your ".gam" files here 268 - "pce" => for PC Engine, put your ".pce" files here 269 - "gameboy" => for Gameboy and GBColor, put your ".gb"/"gbc" files here 270 - "sms" => for Sega Master System/Game Gear, put your ".sms"/"gg" files here 271 - "gen" => for Sega Genesis/Megadrive, put your ".smd"/"bin" files here 272 - "msx" => for MSX roms, put your ".rom"/".msx2" files here. MSX system roms in msx/roms 273 - "amiga" => for Amiga floppies, put your ".adf" and ".hdf" files here. 274 - "data" => for Doom, put your WAD files there (doom1,doom2,plutonia or tnt) 275 276 - insert the card into the SD slot 277 278 # Compilation/flashing (Teensy) 279 - open the respective ino file with Arduino SDK 280 - select DISPLAY MODULE in platform_config.h (ST7789 or ILI9341)!!!! 281 - select VGA or not in platform_config.h (T4.1 using vgat4 lib, T3.6 using uvga lib) 282 - double check iopins.h for pins configuration!!!! 283 - compile and install from there. 284 285 # Compilation/flashing (ESP32) 286 - go to espboot directory first: 287 - make, make flash => this will install custom partition table, bootloader and app selector 288 - go to any other directory (one by one!): 289 - Adapt ./flashapp.sh according your OS (I use OSX) 290 - make, ./flashapp.sh 291 292 # Compilation (PICO) 293 - git clone -b master https://github.com/raspberrypi/pico-sdk.git 294 - cd pico-sdk/ 295 - git submodule update --init 296 - export PICO_SDK_PATH=path-to-pico-sdk 297 - Insure MCUME_pico is NEXT to pico-sdk directory 298 - go to MCUME_pico/build 299 - select emulator to compile in CMakeLists.txt (uncomment ${XXX_SOURCES} and comment out the rest) 300 - select platform options in config/platform_confih.h (e.g. PICOMPUTER, default is MCUME_REV1) 301 - cmake .. 302 - make 303 - drag and drop mcume.uf2 after having boouted the PICO os mass storage mode 304 305 # Status and known issues 306 - 64 (C64): 307 - Full speed with sound 308 - I2C custom keyboard support! 309 - (only few games working) 310 - colem (Colecovision): 311 - Full speed with sound 312 - vcs (Atari 2600): 313 - no sound yet 314 - limited cartridge size support (due to ram constraint) 315 - o2em (Videopac/Odyssey): 316 - no sound 317 - only videopac G7000 games supported (due to ram constraint) 318 - nofrendo (Nintendo NES): 319 - Full speed with sound 320 - 32k roms only supported except on Teensy 4.0 321 - 5200 (Atari 5200): 322 - Full speed with sound 323 - 16 and 32k roms 324 - speccy (Zx spectrum): 325 - SNA support (Z80 to be fixed) 326 - YM and preliminary buzz sound support 327 - 48k games only supported 328 - kempston joystick supported but on screen keyboard may not answer in some games 329 - I2C custom keyboard support! 330 - 81 (Zx81): 331 - zx80 and zx81 332 - .P, .81 and .80 format support (rename .56 for Zx81 hires game that requires 48k or more) 333 - I2C custom keyboard support! 334 - HIRES support for zx81 335 - zx80 support 336 - YM sound support for zx81 337 - 800 (Atari 400/800/XE/XL): 338 - .rom support (no floppy yet) 339 - I2C custom keyboard support! 340 - Full speed with sound 341 - Castaway (AtariST): 342 - floppy support now with Read and Write access 343 - I2C or integrated (TEECOMPUTER) keyboard support! 344 - USB mouse and keyboard support (T4.1) 345 - with sound 346 - full speed on Teensy4.0 only!! 347 - 8086 (XT PC): 348 - HDD image support 349 - I2C custom keyboard support! 350 - no sound 351 - full speed on Teensy4.0 only!! 352 - Vectrex (MB Vectrex): 353 - .gam roms support 354 - no sound 355 - full speed on Teensy4.0 only!! 356 - PCE (PC Engine): 357 - .pce roms support 358 - Nearly full speed with sound 359 - Some games hang or do not start as Outrun, Powerdrift... 360 - SMS/GG (Sega Master System/Game Gear): 361 - Full speed with sound 362 - Gameboy (and Game Boy Color): 363 - Full speed with sound 364 - Major missing background issue 365 - Genesis (Sega Megadrive): 366 - Nearly Full speed with rarely sound 367 - Some background rotation issue 368 - Some games do not start 369 - MSX1/2: 370 - Full speed with sound 371 - up to 256KB roms 372 - some games are not working as uridium2 373 - Amiga: 374 - Full speed with sound 375 - up to 2MB chip RAM + 4MB expand fast RAM roms 376 - HDF (Hard Disk) and adf support 377 - USB mouse and keyboard support (T4.1) 378 - Improved compatibility (still no AGA support!) 379 - Doom: 380 - Full speed without sound 381 - Vic20: 382 - Initial Audio 383 - Compatibility issues (dont expect to run mario and other demos!) 384 - Apple2: 385 - No Audio 386 - Compatibility issues 387 388 # Running 389 - ESP32 only: Select the emulator from the app selector screen and press FIRE (wait a bit that the SD get mounted) 390 - For the launched emulator you should see the roms of the SD card being listed 391 - you can select the rom with up/down 392 - you can start the game by pressing the FIRE key 393 - while the game is running, you might have to press USER1 or USER2 keys to start the game 394 - some emulators requires the I2Ckeyboard 395 - You can then play the game with the analog joystick and the FIRE/USER1 keys 396 - press the USER1+USER2 to reboot the emulator and load another ROM 397 - USER2 can be used to swap joystick 1/2 in some emulators 398 399 # Running on the PICOMPUTER/T-COMPUTER 400 - Fire button is mapped to key 'TAB' 401 - USER2 is mapped to key "fn" 402 - USER1 is mapped to "fn+DEL" 403 - for PICO64, fb+DEL can be used to load selected game 404 - AUTORUN: keep fn key pressed until LED flashes. Launch game with fire. (to remove AUTORUN, press down key at reset) 405 406 # Credits 407 I mostly ported the emulators from existing projects, all the credit goes to the authors of 408 colem, o2em , x2600, moarnes, mc-4u, sz81, atari800, Vice, Nofrendo, jun52, dcastaway, vectrexemu (sorry if I don't mention their name), Charles Macdonald (TGemu), Bernd Schmidt (UAE), Author of Aiie, Vic20 emu and Mike Chambers for his 8086 Arduino project!<br> 409 Doom is based on the ST32 port of chocolate doom so thanks for initial porting effort.<br> 410 Thanks a lot also to Frank Boesing for his ILI DMA library from which I started from and his great Teensy64 project https://github.com/FrankBoesing/Teensy64 411