🎮 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)

---

🚀 Schnellstart - Build & Flash

Voraussetzungen

• ESP-IDF v4.4 installiert
• Python 3.10 (NICHT 3.12!)
• Git
• pyenv (für Python-Version Management)

⚙️ Installation & Build

1️⃣ Original GNUBoy Repository klonen

# Erstelle Arbeitsverzeichnis
mkdir -p ~/Arduino/gameboy
cd ~/Arduino/gameboy

# Clone das Original MCH2022 GNUBoy Projekt
git clone -b v4.4 --recursive https://github.com/badgeteam/mch2022-esp32-app-gnuboy.git gnuboy
cd gnuboy

2️⃣ Unser angepasstes Projekt darüber kopieren

# Clone unser LEGO GameBoy Projekt
cd ~/Arduino/gameboy
git clone https://git.hacker-net.de/Hacker-Software/lego-esp32s3-gameboy.git

# Kopiere alle Dateien über das Original-Projekt
cp -r lego-esp32s3-gameboy/* gnuboy/
cd gnuboy

3️⃣ ESP-IDF v4.4 Setup

# Abhängigkeiten installieren
sudo apt install python3-gevent python3-virtualenv git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 curl
sudo apt-get install -y \
    build-essential \
    libssl-dev \
    zlib1g-dev \
    libbz2-dev \
    libreadline-dev \
    libsqlite3-dev \
    wget \
    curl \
    llvm \
    libncurses5-dev \
    libncursesw5-dev \
    xz-utils \
    tk-dev \
    libffi-dev \
    liblzma-dev \
    python3-openssl \
    git


# pyenv installieren (falls noch nicht vorhanden)
curl https://pyenv.run | bash

# Zu ~/.bashrc hinzufügen:
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Python 3.10 installieren und aktivieren
pyenv install 3.10.13
pyenv local 3.10.13

# ESP-IDF v4.4 installieren
git clone -b v4.4 --recursive https://github.com/espressif/esp-idf.git ~/esp-idf
cd ~/esp-idf
./install.sh esp32s3
source ./export.sh

4️⃣ WICHTIG: Fix-Scripts ausführen!

⚠️ Vor dem Kompilieren müssen zwingend diese beiden Scripts ausgeführt werden:

cd ~/Arduino/gameboy/gnuboy

# 1. PSRAM-Kompatibilität für ESP-IDF v4.4 herstellen
chmod +x fix_psram.sh
./fix_psram.sh

# 2. Komponenten-Abhängigkeiten fixen (Potentiometer, NFC, JSON)
chmod +x fix_poti_manager_nfc_json.sh
./fix_poti_manager_nfc_json.sh

Was machen diese Scripts?

• fix_psram.sh: Ersetzt esp_psram mit esp_hw_support (ESP-IDF v4.4 API-Änderung)
• fix_poti_manager_nfc_json.sh:
  • Fügt fehlende Komponenten-Abhängigkeiten hinzu (json, fatfs, st7789)
  • Kopiert hardware_config.h an die richtigen Stellen
  • Passt ADC-API für Potentiometer an (entfernt deprecated esp_adc_cal)

5️⃣ Projekt konfigurieren & bauen

cd ~/Arduino/gameboy/gnuboy

# ESP-IDF Environment laden
source ~/esp-idf/export.sh

# Target setzen
idf.py set-target esp32s3

# (Optional) Konfiguration anpassen, wird schon durch script fix_psram.sh gemacht
idf.py menuconfig
# → Component config → ESP32S3-Specific → PSRAM auf "Octal Mode" setzen

# Projekt bauen
idf.py build

6️⃣ Flashen

# USB-Port finden (meist /dev/ttyUSB0 oder /dev/ttyACM0)
ls /dev/ttyUSB* /dev/ttyACM*

# Flashen (ggf. BOOT-Button beim Verbinden gedrückt halten)
idf.py -p /dev/ttyUSB0 flash

# Mit Monitor (zum Debuggen)
idf.py -p /dev/ttyUSB0 flash monitor

# Monitor beenden: Ctrl + ]
#Einfach nur monitor
#idf.py -p /dev/ttyUSB0 monitor

🐛 Troubleshooting

Python 3.12 Fehler?

# Python 3.10 installieren:
siehe anfang 3️⃣ ESP-IDF v4.4 Setup

Build Fehler?

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

PSRAM nicht erkannt?

# Octal PSRAM aktivieren:
idf.py menuconfig
# → Component config → ESP32S3-Specific
# → [*] Support for external, SPI-connected RAM
# → SPI RAM config → Mode: Octal Mode PSRAM

Board kommt nicht in Flash-Modus?

1. BOOT-Button gedrückt halten
2. RESET-Button kurz drücken
3. BOOT-Button loslassen
4. Flash-Befehl ausführen

---

🛠️ 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 35
• LRC: GPIO 36
• DIN: GPIO 37

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
├── fix_psram.sh                   # ⚠️ WICHTIG: Vor Build ausführen!
├── fix_poti_manager_nfc_json.sh   # ⚠️ WICHTIG: Vor Build ausführen!
│
├── main/
│   ├── CMakeLists.txt
│   ├── main.c                     # Hauptprogramm
│   └── include/
│       └── 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
    │
    └── potentiometer_manager/     # Volume/Brightness Control
        ├── CMakeLists.txt
        ├── include/potentiometer_manager.h
        └── potentiometer_manager.c

---

🎮 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

• NFC Tags programmieren mit ROM-Namen
• Tag scannen → ROM startet automatisch!
• 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

• Zwei GameBoys bauen
• Link Cable verbinden:
  • SCLK ↔ SCLK
  • SOUT ↔ SIN (gekreuzt!)
  • SIN ↔ SOUT (gekreuzt!)
  • GND ↔ GND
• Gleiches ROM laden auf beiden
• Im Spiel: 2-Player Mode wählen
• 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

Aktueller Status

• ✅ Projekt-Struktur fertig
• ✅ CMake Build System
• ✅ Pin-Konfiguration
• ✅ Component-Grundstruktur
• ✅ ESP-IDF v4.4 Kompatibilität
• ✅ PSRAM Support (8MB Octal)
• ⏳ 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
• MCH2022 Badge Team: ESP32 GNUBoy App
• 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
5. Fix-Scripts ausgeführt? (fix_psram.sh & fix_poti_manager_nfc_json.sh)

---

🎯 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! ❤️