🎮 ESP32-S3 GNUBoy - LEGO GameBoy Emulator

GameBoy/GameBoy Color Emulator für Waveshare ESP32-S3-Touch-LCD-2

---

📋 Projekt-Übersicht

Dieses Projekt ist ein kompletter GameBoy Emulator für das Waveshare ESP32-S3-Touch-LCD-2 Board.

✨ Features

• ✅ GameBoy & GameBoy Color Emulation (GNUBoy Core)
• ✅ ST7789 Display (2.0", 240x320, optimiert)
• ✅ NFC ROM-Auswahl (PN532, einfach Tag scannen!)
• ✅ Potentiometer Controls (Volume & Brightness)
• ✅ Link Cable 2-Player (Tetris, Pokemon, etc.)
• ✅ SD Card ROM Loading (alle deine ROMs)
• ✅ I2S Audio (MAX98357A, klarer Sound)
• ✅ 8 GameBoy Buttons (Original Layout)

---

🛠️ Hardware

Hauptkomponenten

Component	Model	Notes
MCU Board	Waveshare ESP32-S3-Touch-LCD-2	16MB Flash, 8MB PSRAM
Display	ST7789 2.0"	240x320, integriert
Audio	MAX98357A	I2S Amplifier
NFC Reader	PN532	I2C mode
Storage	MicroSD Card	FAT32, via SPI

Pin-Belegung

Siehe main/hardware_config.h für alle Pin-Definitionen!

Wichtigste Pins:

Display (ST7789):
- MOSI: GPIO 11
- SCLK: GPIO 12
- CS:   GPIO 10
- DC:   GPIO 8
- RST:  GPIO 14
- BL:   GPIO 9

Audio (I2S):
- BCLK: GPIO 41
- LRC:  GPIO 42
- DIN:  GPIO 40

NFC (PN532):
- SCL:  GPIO 16
- SDA:  GPIO 15

Buttons:
- UP:    GPIO 1
- DOWN:  GPIO 2
- LEFT:  GPIO 42
- RIGHT: GPIO 41
- A:     GPIO 21
- B:     GPIO 47
- START: GPIO 48
- SELECT:GPIO 45

Link Cable:
- SCLK: GPIO 17
- SOUT: GPIO 18
- SIN:  GPIO 38

---

📦 Projekt-Struktur

esp32-s3-gnuboy/
├── CMakeLists.txt           # Root CMake
├── sdkconfig.defaults       # ESP-IDF config
├── partitions.csv           # Flash partitions
├── README.md                # Diese Datei
│
├── main/
│   ├── CMakeLists.txt
│   ├── main.c               # Hauptprogramm
│   └── hardware_config.h    # Pin-Definitionen
│
└── components/
    ├── gnuboy/              # GNUBoy Emulator Core
    │   ├── CMakeLists.txt
    │   ├── include/gnuboy.h
    │   └── gnuboy_placeholder.c
    │
    ├── st7789/              # Display Driver
    │   ├── CMakeLists.txt
    │   ├── include/st7789.h
    │   └── st7789.c
    │
    ├── nfc_manager/         # NFC ROM Selection
    │   ├── CMakeLists.txt
    │   ├── include/nfc_manager.h
    │   └── nfc_manager.c
    │
    └── link_cable/          # 2-Player Support
        ├── CMakeLists.txt
        ├── include/link_cable.h
        └── link_cable.c

---

🚀 Build & Flash

Voraussetzungen

1. ESP-IDF v4.4 installiert
2. Python 3.10 (NICHT 3.12!)
3. Git

Installation

# 1. Repository klonen
git clone <dein-repo>
cd esp32-s3-gnuboy

# 2. ESP-IDF aktivieren
source ~/esp-idf/export.sh

# 3. Target setzen
idf.py set-target esp32s3

# 4. (Optional) Konfiguration anpassen
idf.py menuconfig

# 5. Bauen
idf.py build

# 6. Flashen
idf.py -p /dev/ttyUSB0 flash

# 7. Monitor
idf.py monitor

Troubleshooting

Python 3.12 Fehler?

# Python 3.10 installieren:
sudo apt-get install python3.10 python3.10-venv
cd ~/esp-idf
python3.10 ./install.sh esp32s3

Build Fehler?

# Clean & rebuild:
idf.py fullclean
idf.py build

---

🎮 Benutzung

ROMs laden

1. SD-Karte formatieren (FAT32)
2. Verzeichnis erstellen: /roms/gb/
3. ROMs kopieren (.gb oder .gbc Dateien)
4. SD-Karte einlegen

NFC ROM-Auswahl

1. NFC Tags programmieren mit ROM-Namen
2. Tag scannen → ROM startet automatisch!
3. Mapping-File: /sd/nfc_roms.json

Beispiel nfc_roms.json:

{
  "mappings": [
    {
      "tag_uid": "04:12:34:56:78:9A:B0",
      "rom_path": "/roms/gb/tetris.gb"
    },
    {
      "tag_uid": "04:AB:CD:EF:12:34:56",
      "rom_path": "/roms/gb/pokemon_red.gb"
    }
  ]
}

Link Cable 2-Player

1. Zwei GameBoys bauen
2. Link Cable verbinden:
   • SCLK ↔ SCLK
   • SOUT ↔ SIN (gekreuzt!)
   • SIN ↔ SOUT (gekreuzt!)
   • GND ↔ GND
3. Gleiches ROM laden auf beiden
4. Im Spiel: 2-Player Mode wählen
5. Spielen! 🎮🔗🎮

Buttons

GameBoy Layout:
    ┌─────┐
 ←→↑↓  B A
    SELECT START

• D-Pad: Bewegung
• A/B: Aktion
• START: Menü/Start
• SELECT: Auswahl

Potentiometer

• Links: Volume (0-100%)
• Rechts: Brightness (10-100%)

---

🔧 Entwicklung

Nächste Schritte

Aktueller Status:

• ✅ Projekt-Struktur fertig
• ✅ CMake Build System
• ✅ Pin-Konfiguration
• ✅ Component-Grundstruktur
• ⏳ GNUBoy Core Integration
• ⏳ ST7789 Driver fertigstellen
• ⏳ NFC Implementation
• ⏳ Link Cable Implementation

TODO:

1. GNUBoy Core integrieren:

   • Quellcode von esplay-gb portieren
   • Für ESP32-S3 anpassen
   • Serial/Link Interface implementieren

2. ST7789 Driver fertigstellen:

   • Init-Sequenz ergänzen
   • Framebuffer-Rendering optimieren
   • GameBoy→Display Mapping

3. NFC Manager implementieren:

   • PN532 I2C Treiber
   • Tag UID auslesen
   • JSON Mapping parsen

4. Link Cable fertigstellen:

   • GPIO Bit-Transfer
   • Master/Slave Negotiation
   • GNUBoy Serial Hook

5. Audio implementieren:

   • I2S Konfiguration
   • GameBoy→I2S Buffer
   • Volume Control

Code-Richtlinien

• Zentralisierte Konfiguration: Alle Pins in hardware_config.h
• ESP-IDF Stil: ESP_LOG statt printf
• Fehlerbehandlung: Immer ESP_ERROR_CHECK nutzen
• Dokumentation: Doxygen-Kommentare

---

📝 Lizenz

• GNUBoy: GPL v2.0
• Projekt-spezifischer Code: MIT (oder nach Wahl)

---

🙏 Credits

• GNUBoy: Original GameBoy Emulator
• esplay-gb: ESP32 Port von pebri86
• Waveshare: Hardware Board
• Stefan: LEGO GameBoy Projekt! 🎮

---

📞 Support

Bei Fragen oder Problemen:

1. Hardware-Config prüfen (hardware_config.h)
2. Serial Monitor checken (idf.py monitor)
3. Build-Log lesen
4. Pin-Konflikte überprüfen

---

🎯 Vision

Ziel: Der ultimative LEGO GameBoy Emulator!

• Zwei baugleiche Geräte
• Link Cable Multiplayer
• NFC ROM-Auswahl
• Professionelle Qualität
• Open Source

Let's build it! 🚀🎮

---

Erstellt für Stefan's LEGO GameBoy Projekt
Hardware: Waveshare ESP32-S3-Touch-LCD-2
Mit Liebe zum Detail gebaut! ❤️