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

```bash
# 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

```bash
# 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

```bash
# 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:**

```bash
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

```bash
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

```bash
# 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?
```bash
# Python 3.10 installieren:
siehe anfang 3️⃣ ESP-IDF v4.4 Setup
```

#### Build Fehler?
```bash
# Clean & rebuild:
idf.py fullclean
idf.py build
```

#### PSRAM nicht erkannt?
```bash
# 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`:**
```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! ❤️*