MoonTANG: OPL4 y MSX-Audio en una WonderTANG · OPL4 and MSX-Audio on a WonderTANG

MoonTANG convierte un cartucho WonderTANG 2.02b en un MoonSound: un OPL4 completo, con el FM de 18 canales del OPL3 y las 24 voces de ondas (wavetable), enchufado en un slot de tu MSX de verdad. Y, si quieres, con un MSX-Audio al lado, en el mismo cartucho.

MoonTANG turns a WonderTANG 2.02b cartridge with its Sipeed Tang Nano 20K into a MoonSound: a full OPL4, with the 18-channel OPL3 FM and the 24 wavetable voices, plugged into a slot of your real MSX. And, if you want, with an MSX-Audio next to it, in the same cartridge.

Es el mismo OPL4 que lleva dentro el MSXimus, sacado aparte para que funcione solo, como cartucho. Solo hace eso: sonido.

It is the same OPL4 that lives inside the MSXimus, taken out so it runs on its own, as a cartridge. It does just that: sound. No megaROM, no RAM expansion, no Nextor; for those there is tnCart.

⚠️ MoonTANG es experimental.

⚠️ MoonTANG is experimental. If you try it, tell us how it goes —good or bad— in the comments or by opening an issue at [ENLACE REPOSITORIO].

🌙 Qué hay dentro🌙 What is inside

• MoonSound (OPL4, YMF278B), en las tres versiones:
  • FM: el OPL3, 18 canales, en los puertos C4h–C7h. Funciona sin nada más.
  • Ondas: 24 voces PCM que tocan las muestras de la ROM YRW801 de Yamaha (2 MB) y de 2 MB de RAM de samples, en los puertos 7Eh–7Fh. Necesitan tu propia YRW801 (ver más abajo).
• MSX-Audio (Y8950), en las versiones 1 y 2: FM de 9 canales (con modo ritmo) y ADPCM con 256 KB de RAM de samples, lo máximo que direcciona el chip, en los puertos C0h–C1h (la primera unidad MSX-Audio). No necesita ninguna ROM.
• El cartucho solo responde a puertos de E/S: no ocupa memoria del slot.
• Sonido por el propio MSX, en mono: sale por el amplificador de la Tang y el puente J3 hacia la línea SOUNDIN del slot. En las versiones con HDMI sale además en estéreo por el HDMI de la Tang.

• MoonSound (OPL4, YMF278B), in all three versions:
  • FM: the OPL3, 18 channels, on ports C4h–C7h. It works with nothing else.
  • Wave: 24 PCM voices playing the samples of Yamaha's YRW801 ROM (2 MB) and of 2 MB of sample RAM, on ports 7Eh–7Fh. They need your own YRW801 (see below).
• MSX-Audio (Y8950), in versions 1 and 2: 9-channel FM (rhythm mode included) and ADPCM with 256 KB of sample RAM, the most the chip can address, on ports C0h–C1h (the first MSX-Audio unit). It needs no ROM.
• The cartridge only answers I/O ports: it takes no slot memory.
• Sound through the MSX itself, in mono: it goes through the Tang's amplifier and jumper J3 into the slot's SOUNDIN line. In the HDMI versions it also comes out in stereo over the Tang's HDMI.

🎛️ Las tres versiones🎛️ The three versions

Las tres son para la WonderTANG 2.02b y se graban igual. Eliges una; para cambiar de versión basta con grabar otro .fs.

All three are for the WonderTANG 2.02b and are flashed the same way. You pick one; to switch versions you just flash another .fs.

Versión	Qué lleva	Sonido	Para quién
1 · OPL4 + MSX-Audio	MoonSound + MSX-Audio	Por el MSX (mono)	Para el día a día, escuchando por los altavoces del MSX.
2 · OPL4 + MSX-Audio + HDMI	MoonSound + MSX-Audio + pantalla HDMI con vúmetro de 7 barras	Por el MSX (mono) y por HDMI (estéreo)	Si lo quieres todo: además, ves en pantalla si la YRW801 ha cargado, si llega el reloj del MSX y qué suena.
3 · OPL4 + HDMI	MoonSound + pantalla HDMI con vúmetro de 6 barras	Por el MSX (mono) y por HDMI (estéreo)	Si ya tienes un MSX-Audio de verdad (Philips Music Module, Panasonic FS-CA1, Toshiba HX-MU900) en otro slot: los dos responderían en C0h–C1h y chocarían.

Version	What it has	Sound	Who it is for
1 · OPL4 + MSX-Audio	MoonSound + MSX-Audio	Through the MSX (mono)	Everyday use, listening through the MSX's own speakers.
2 · OPL4 + MSX-Audio + HDMI	MoonSound + MSX-Audio + HDMI screen with a 7-bar VU meter	Through the MSX (mono) and HDMI (stereo)	If you want it all: you also see on screen whether the YRW801 loaded, whether the MSX clock is there and what is playing.
3 · OPL4 + HDMI	MoonSound + HDMI screen with a 6-bar VU meter	Through the MSX (mono) and HDMI (stereo)	If you already have a real MSX-Audio (Philips Music Module, Panasonic FS-CA1, Toshiba HX-MU900) in another slot: both would answer at C0h–C1h and clash.

Visto desde el MSX, el MoonSound es exactamente el mismo en las tres. Estos ficheros son solo para la WonderTANG 2.02b: no los grabes en otra tarjeta con Tang Nano 20K, porque los pines no coinciden.

Seen from the MSX, the MoonSound is exactly the same in all three. These files are for the WonderTANG 2.02b only: do not flash them on any other Tang Nano 20K board, because the pins do not match.

📺 La pantalla HDMI📺 The HDMI screen

En las versiones 2 y 3, conecta una tele o un monitor HDMI con altavoces al conector HDMI de la Tang. Es opcional: sin nada conectado, el cartucho funciona igual.

In versions 2 and 3, plug a TV or an HDMI monitor with speakers into the Tang's HDMI connector. It is optional: with nothing connected, the cartridge works just the same.

• Barras: FM izquierda/derecha, WAVE (las ondas) izquierda/derecha y OUT, la mezcla final. En la versión 2 hay una séptima, MSX-AUDIO (mono), con lo que suma el Y8950. Cada barra tiene 28 segmentos de 1,5 dB; el segmento brillante marca el pico.
• YRW801: OK · ... (copiándose) · NO VALIDA (la copia terminó, pero lo que hay en la flash no es la YRW801: flash vacía, una megaROM de otro firmware, un fichero cortado) · ERROR (la copia no terminó: la flash o la SDRAM no responden).
• MSX: OK si llega el reloj del MSX, -- si no.
• Imagen de 720×480 a 60 Hz, marcada como 16:9; sonido estéreo a 48 kHz. Un monitor que solo acepte DVI no la mostrará.

• Bars: FM left/right, WAVE (the wavetable) left/right and OUT, the final mix. Version 2 has a seventh one, MSX-AUDIO (mono), with what the Y8950 adds. Each bar has 28 segments of 1.5 dB; the bright segment marks the peak.
• YRW801: OK · ... (being copied) · NO VALIDA (the copy finished, but what is in the flash is not the YRW801: a blank flash, a megaROM left by another firmware, a truncated file) · ERROR (the copy did not finish: the flash or the SDRAM is not answering).
• MSX: OK when the MSX clock is there, -- when it is not.
• 720×480 at 60 Hz, flagged as 16:9; stereo sound at 48 kHz. A DVI-only monitor will not show it.

🧰 Qué necesitas🧰 What you need

• Una WonderTANG 2.02b con su Tang Nano 20K.
• El puente J3 soldado a las pistas del altavoz de la Tang. Sin él no hay sonido por el MSX (por HDMI, sí).
• Tu copia de la YRW801, en un fichero yrw801.bin de 2 MB,
• Un PC con Gowin Programmer (Windows) u openFPGALoader (Linux, macOS o Windows).
• Un cable USB-C que lleve datos, no solo carga.
• Para las versiones 2 y 3, si quieres ver la pantalla: una tele o un monitor HDMI.

• A WonderTANG 2.02b with its Tang Nano 20K.
• Jumper J3 soldered to the Tang's speaker pads. Without it there is no sound through the MSX (there is over HDMI).
• Your own copy of the YRW801, as a 2 MB file yrw801.bin, for example dumped from your MoonSound. It is copyrighted: we do not include or distribute it. Without it the FM and the MSX-Audio work; only the wavetable stays silent.
• A PC with Gowin Programmer (Windows) or openFPGALoader (Linux, macOS or Windows).
• A USB-C cable that carries data, not just power.
• For versions 2 and 3, if you want to see the screen: a TV or an HDMI monitor.

⚡ Cómo flashear⚡ How to flash it

Se graban dos cosas en la flash de la Tang: el .fs de la versión elegida en 0x000000 y tu yrw801.bin en 0x200000. Hazlo con el MSX apagado (o con la tarjeta fuera del MSX): la Tang se alimenta por el USB-C.

Two things go into the Tang's flash: the .fs of the version you chose at 0x000000 and your yrw801.bin at 0x200000. Do it with the MSX switched off (or with the board out of the MSX): the Tang is powered from USB-C.

Con Gowin Programmer (Windows)With Gowin Programmer (Windows)

1. Conecta la Tang Nano 20K al PC con el cable USB-C y abre Gowin Programmer.
2. El bitstream: pulsa Add Device y elige la serie GW2AR. Haz doble clic en el dispositivo y pon Access Mode = External Flash Mode, Operation = exFlash Erase, Program thru GAO-Bridge. Elige el .fs de tu versión, Device = Generic Flash y dirección 0x000000. Save.
3. La YRW801: Add Device otra vez, serie GW2AR, Access Mode = External Flash Mode, Operation = exFlash C Bin Erase, Program thru GAO-Bridge. Elige tu yrw801.bin, Device = Generic Flash y dirección 0x200000. Save.
4. Deja activado solo el primer dispositivo de la lista y pulsa Program/Configure (menú Edit). Cuando acabe, deja activado solo el segundo y repite.
5. Desconecta el USB, pon el cartucho en el MSX (apagado) y enciéndelo.

1. Connect the Tang Nano 20K to the PC with the USB-C cable and open Gowin Programmer.
2. The bitstream: click Add Device and pick the GW2AR series. Double-click the device and set Access Mode = External Flash Mode, Operation = exFlash Erase, Program thru GAO-Bridge. Pick the .fs of your version, Device = Generic Flash and address 0x000000. Save.
3. The YRW801: Add Device again, GW2AR series, Access Mode = External Flash Mode, Operation = exFlash C Bin Erase, Program thru GAO-Bridge. Pick your yrw801.bin, Device = Generic Flash and address 0x200000. Save.
4. Leave only the first device in the list enabled and click Program/Configure (Edit menu). When it finishes, enable only the second one and repeat.
5. Unplug the USB, put the cartridge in the MSX (switched off) and power it on.

Con openFPGALoaderWith openFPGALoader

Con la Tang conectada por USB-C, primero el .fs de tu versión y después la YRW801 (2097152 es 0x200000):

With the Tang connected over USB-C, first the .fs of your version and then the YRW801 (2097152 is 0x200000):

openFPGALoader -f -b tangnano20k --external-flash moontang_version.fs
openFPGALoader -b tangnano20k --external-flash -o 2097152 yrw801.bin

Bueno saberlo.Good to know

• La YRW801 se graba una vez y vale para las tres versiones. Para cambiar de versión, graba solo el .fs.

• The YRW801 is flashed once and works for all three versions. To switch versions, flash just the .fs.
• Check the YRW801 after every flash. Some tools, when erasing the flash for the .fs, also wipe the area that comes after it. Also, 0x200000 is where other firmwares keep their own data (tnCart its megaROM, the MSXnano its BIOS pack): if you have used the Tang with another firmware, flash yrw801.bin again. The HDMI screen, the LED and the MT4YRW program tell you whether it is fine.
• Risk-free test: in Gowin Programmer you can load the .fs into SRAM instead of the flash. It is lost at power-off and the board goes back to whatever firmware it had flashed. Do it with the MSX off, or reset the MSX afterwards.
• If the Programmer does not see the Tang because it carries a firmware that uses the JTAG pins, hold the S1 button before plugging in the USB-C cable and during the whole flashing. MoonTANG does not use the JTAG pins, so once MoonTANG is flashed you should not need this.
• On Linux, Gowin's Programmer does not work well: use openFPGALoader.

✅ Cómo comprobar que funciona✅ How to check it works

Al encender el MSX, unos 3 segundos de pantalla negra son normales: la FPGA está cargando y el MSX espera. Después, durante unos 2 segundos, la tarjeta copia la YRW801 de la flash a la SDRAM; en ese rato la parte de ondas todavía no se detecta. Espera a que el LED se quede fijo.

When you power on the MSX, about 3 seconds of black screen is normal: the FPGA is loading and the MSX waits. Then, for about 2 seconds, the board copies the YRW801 from flash to SDRAM; during that time the wavetable cannot be detected yet. Wait until the LED stays on.

LED	Qué significa
Fijo	Listo y el MSX en marcha
Destello corto cada 0,6 s	Listo, pero no llega el reloj del MSX (cartucho fuera o MSX apagado)
Parpadeo lento	Copiando la YRW801 de la flash a la SDRAM (unos 2 s)
Parpadeo rápido	Arrancando la SDRAM
Ráfagas de parpadeo rápido cada 0,6 s	Copiada, pero lo que hay en la flash no es la YRW801
Doble destello	La copia no terminó (la flash o la SDRAM no responden)
Apagado	Un PLL no ha enganchado

LED	Meaning
Steady on	Ready and the MSX is running
Short flash every 0.6 s	Ready, but no clock from the MSX (cartridge out, or MSX off)
Slow blink	Copying the YRW801 from flash to SDRAM (about 2 s)
Fast blink	SDRAM starting up
Bursts of fast blinking every 0.6 s	Copied, but what is in the flash is not the YRW801
Double flash	The copy did not finish (the flash or the SDRAM is not answering)
Off	A PLL did not lock

Una pista rápida: si suena el FM pero no las ondas, mira la YRW801 (flash o SDRAM). Si no suena nada, mira el bus o la alimentación. La WonderTANG alimenta la Tang a través de un diodo: si la Tang no arranca bien, revisa primero los 5 V del slot.

A quick hint: if the FM plays but the wavetable does not, look at the YRW801 (flash or SDRAM). If nothing plays at all, look at the bus or the power. The WonderTANG powers the Tang through a diode: if the Tang does not start reliably, check the slot's 5 V first.

Use these rather than the test programs of other OPL4 FPGA projects: some of them start a timer without masking it and without an interrupt handler, and hang the MSX through /INT, just as a real MoonSound would.

🎵 Software y límites🎵 Software and limits

• MoonSound: lo que funciona en un MoonSound debería funcionar aquí: VGMPlay, MoonBlaster Wave, juegos y demos. Una buena prueba: VGMPlay dos veces seguidas saliendo a DOS sin reiniciar, MoonBlaster Wave, y un reinicio del MSX seguido de MT4YRW.
• MSX-Audio (versiones 1 y 2): debería funcionar el software que habla directamente con el chip: VGMPlay con música de MSX-Audio, MoonBlaster 1.4 (FM y samples ADPCM) y los juegos que escriben en sus puertos.
• Sin BIOS de MSX-Audio: el cartucho solo responde a los puertos. Lo que necesita esa ROM, como FAC SoundTracker, no la encuentra.
• Solo la primera unidad MSX-Audio (C0h–C1h); C2h–C3h quedan libres. No están la grabación (el ADC), los registros del DAC ni los puertos de teclado y E/S del chip.
• ¿Tienes un MSX-Audio de verdad enchufado? Usa la versión 3.
• Turbo: lo recomendado es 3,58 MHz. A partir de 5,37 MHz puede fallar la lectura de la memoria de ondas desde el MSX (tocarla no). El FM y el MSX-Audio no usan /WAIT; en simulación se leen bien hasta 7,16 MHz.
• No hay control de volumen en el cartucho. Las ondas van 6 dB por debajo del FM

• MoonSound: what works on a MoonSound should work here: VGMPlay, MoonBlaster Wave, games and demos. A good test: VGMPlay twice in a row, leaving to DOS without a reset, MoonBlaster Wave, and a reset of the MSX followed by MT4YRW.
• MSX-Audio (versions 1 and 2): software that talks to the chip directly should work: VGMPlay with MSX-Audio music, MoonBlaster 1.4 (FM and ADPCM samples) and games that write to its ports.
• No MSX-Audio BIOS: the cartridge only answers the ports. Software that needs that ROM, such as FAC SoundTracker, does not find it.
• Only the first MSX-Audio unit (C0h–C1h); C2h–C3h stay free. Recording (the ADC), the DAC registers and the chip's keyboard and I/O ports are not there.
• Do you have a real MSX-Audio plugged in? Use version 3.
• Turbo: 3.58 MHz is recommended. From 5.37 MHz on, reading the wave memory from the MSX may fail (playing it does not). The FM and the MSX-Audio do not use /WAIT; in simulation they read fine up to 7.16 MHz.
• There is no volume control on the cartridge. The wavetable sits 6 dB below the FM, as in the MSXimus; with the MSX-Audio, a limiter softens the peaks of the sum instead of clipping them.

📦 Descargas📦 Downloads

• Versión 1 · OPL4 + MSX-Audio: MoonTANG 1.0beta — OPL4 + HDMI
• Versión 2 · OPL4 + MSX-Audio + HDMI: MoonTANG 1.0beta — OPL4 + MSX-Audio + HDMI
• Versión 3 · OPL4 + HDMI: MoonTANG 1.0beta — OPL4 + MSX-Audio

Proyecto: https://github.com/Papipapito/MoonTANG

• Version 1 · OPL4 + MSX-Audio: [DESCARGA VERSIÓN 1 .fs]
• Version 2 · OPL4 + MSX-Audio + HDMI: [DESCARGA VERSIÓN 2 .fs]
• Version 3 · OPL4 + HDMI: [DESCARGA VERSIÓN 3 .fs]
• Test programs MT1DET…MT7AUD: [DESCARGA PROGRAMAS DE PRUEBA]
• Source code and documentation: [ENLACE REPOSITORIO]

The YRW801 is not in the downloads: everyone uses their own copy.

🙏 Créditos🙏 Credits

MoonTANG se apoya en el gran trabajo abierto de mucha gente. Gracias a todos:

MoonTANG stands on the great open work of many people. Thanks to all of them:

• Greg Taylor (gtaylormb): el núcleo OPL3 FPGA, la mitad FM, basado en la ingeniería inversa de Robson Cozendey, Steffen Ohrendorf y Nuke.YKT.
• Jokin Miragaia (antxiko): mangOPL4, con los ajustes para Gowin y el envoltorio de cartucho MoonSound que hemos adaptado.
• srg320: el motor PCM/wavetable del YMF278B, derivado del ymf278b.cpp de MAME (R. Belmont, Olivier Galibert y hap).
• José Tejada (jotego): JTOPL (el FM del Y8950) y el decodificador ADPCM-B de JT12.
• Shinobu Hashimoto (buppu3): tnCart, cuyo acceso al bus multiplexado usamos.
• Albert Herranz (herraa1): tnCartWonder, la adaptación a la WonderTANG y el transmisor I2S.
• luca (lfantoniosi): el cartucho WonderTANG y su asignación de pines.
• Sameer Puri: hdl-util/hdmi, el transmisor HDMI con sonido.
• Takayuki Hara (HRA!): el controlador de SDRAM de su proyecto de cartucho V9968.
• Dan Gisselquist: la FIFO asíncrona del interfaz FM.
• openMSX: su Y8950 sirvió de referencia para los registros ADPCM, y con su MoonSound y su MSX-Audio se comprobaron los valores de los programas de prueba.
• Sipeed, por la Tang Nano 20K, y Gowin, por sus primitivas de reloj y serialización.

• Greg Taylor (gtaylormb): the OPL3 FPGA core, the FM half, built on the reverse-engineering of Robson Cozendey, Steffen Ohrendorf and Nuke.YKT.
• Jokin Miragaia (antxiko): mangOPL4, with the Gowin fixes and the MoonSound cartridge wrapper we adapted.
• srg320: the YMF278B PCM/wavetable engine, derived from MAME's ymf278b.cpp (R. Belmont, Olivier Galibert and hap).
• José Tejada (jotego): JTOPL (the Y8950 FM) and the ADPCM-B decoder of JT12.
• Shinobu Hashimoto (buppu3): tnCart, whose multiplexed bus front-end we use.
• Albert Herranz (herraa1): tnCartWonder, the WonderTANG port and the I2S transmitter.
• luca (lfantoniosi): the WonderTANG cartridge and its pinout.
• Sameer Puri: hdl-util/hdmi, the HDMI transmitter with audio.
• Takayuki Hara (HRA!): the SDRAM controller from his V9968 cartridge project.
• Dan Gisselquist: the async FIFO of the FM interface.
• openMSX: its Y8950 was the reference for the ADPCM registers, and its MoonSound and MSX-Audio were used to check the values of the test programs.
• Sipeed, for the Tang Nano 20K, and Gowin, for their clock and serialiser primitives.

Cada pieza conserva su licencia original (LGPL-3.0, GPL-3.0, BSD-2/BSD-3, MIT/Apache-2.0) y sus avisos van en el repositorio.

Each part keeps its original license (LGPL-3.0, GPL-3.0, BSD-2/BSD-3, MIT/Apache-2.0), and their notices are in the repository.

MoonTANG lo ha hecho MSX barcelona programando a cuatro manos con Claude (Anthropic). Es un proyecto hobby y sin ánimo de lucro, de código abierto . Algunas piezas llevan una cláusula no comercial: no se puede vender. La lista completa de autores y licencias está en el repositorio.

MoonTANG was made by Albert (Papipapito) pair-programming with Claude (Anthropic). It is a hobby, non-commercial, open-source project [LICENCIA]. Some parts carry a non-commercial clause: it must not be sold. The full list of authors and licenses is in the repository.

MoonTANG es un proyecto de aficionados, sin relación con Yamaha. «MoonSound» y MSX se citan solo por compatibilidad.

MoonTANG is a fan project, not affiliated with Yamaha. "MoonSound" and MSX are referenced for interoperability only.