291 lines
4.6 KiB
Markdown
291 lines
4.6 KiB
Markdown
# 🚀 Quickstart Guide - ESP32-S3 GNUBoy
|
||
|
||
**Von 0 zu einem laufenden GameBoy Emulator in 10 Minuten!**
|
||
|
||
---
|
||
|
||
## ⚡ Schnellstart
|
||
|
||
### 1️⃣ Voraussetzungen prüfen
|
||
|
||
```bash
|
||
# ESP-IDF installiert?
|
||
idf.py --version
|
||
|
||
# Python Version (sollte 3.10 sein)?
|
||
python --version
|
||
|
||
# Git installiert?
|
||
git --version
|
||
```
|
||
|
||
**Wenn etwas fehlt, siehe weiter unten!**
|
||
|
||
---
|
||
|
||
### 2️⃣ Projekt klonen
|
||
|
||
```bash
|
||
cd ~/Arduino/gameboy/
|
||
git clone <dein-repo> esp32-s3-gnuboy
|
||
cd esp32-s3-gnuboy
|
||
```
|
||
|
||
---
|
||
|
||
### 3️⃣ ESP-IDF aktivieren
|
||
|
||
```bash
|
||
source ~/esp-idf/export.sh
|
||
```
|
||
|
||
**Wichtig:** Das musst du **jedes Mal** machen wenn du ein neues Terminal öffnest!
|
||
|
||
---
|
||
|
||
### 4️⃣ Target setzen
|
||
|
||
```bash
|
||
idf.py set-target esp32s3
|
||
```
|
||
|
||
---
|
||
|
||
### 5️⃣ Bauen
|
||
|
||
```bash
|
||
idf.py build
|
||
```
|
||
|
||
**Dauer:** ~2-5 Minuten beim ersten Build
|
||
|
||
---
|
||
|
||
### 6️⃣ Flashen
|
||
|
||
```bash
|
||
# Board anschließen via USB
|
||
# Dann:
|
||
idf.py -p /dev/ttyUSB0 flash
|
||
```
|
||
|
||
**Port finden:**
|
||
```bash
|
||
ls /dev/ttyUSB*
|
||
# oder
|
||
ls /dev/ttyACM*
|
||
```
|
||
|
||
---
|
||
|
||
### 7️⃣ Monitor starten
|
||
|
||
```bash
|
||
idf.py monitor
|
||
```
|
||
|
||
**Beenden:** `Ctrl+]`
|
||
|
||
---
|
||
|
||
## ✅ Fertig!
|
||
|
||
Du solltest jetzt sehen:
|
||
|
||
```
|
||
╔════════════════════════════════════════════════════════╗
|
||
║ ║
|
||
║ ESP32-S3 GNUBoy LEGO GameBoy Emulator ║
|
||
║ ║
|
||
╚════════════════════════════════════════════════════════╝
|
||
|
||
Hardware: Waveshare ESP32-S3-Touch-LCD-2
|
||
Display: ST7789 2.0" 240x320
|
||
Flash: 16 MB
|
||
PSRAM: 8 MB
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Fehlerbehebung
|
||
|
||
### Problem: Python 3.12 Fehler
|
||
|
||
```bash
|
||
# Python 3.10 installieren:
|
||
sudo apt-get install python3.10 python3.10-venv python3.10-dev
|
||
|
||
# Alte ESP-IDF Umgebung löschen:
|
||
rm -rf ~/.espressif/python_env/idf4.4_py3.12_env
|
||
|
||
# ESP-IDF neu installieren:
|
||
cd ~/esp-idf
|
||
python3.10 ./install.sh esp32s3
|
||
```
|
||
|
||
---
|
||
|
||
### Problem: Port nicht gefunden
|
||
|
||
```bash
|
||
# USB Ports checken:
|
||
ls -la /dev/ttyUSB*
|
||
ls -la /dev/ttyACM*
|
||
|
||
# Berechtigungen setzen:
|
||
sudo usermod -a -G dialout $USER
|
||
# Dann neu einloggen!
|
||
```
|
||
|
||
---
|
||
|
||
### Problem: Build Fehler
|
||
|
||
```bash
|
||
# Alles löschen und neu:
|
||
idf.py fullclean
|
||
idf.py build
|
||
```
|
||
|
||
---
|
||
|
||
### Problem: Flash Fehler
|
||
|
||
```bash
|
||
# Board in Download Mode bringen:
|
||
# 1. BOOT Button drücken und halten
|
||
# 2. RESET Button kurz drücken
|
||
# 3. BOOT loslassen
|
||
# 4. Nochmal flashen versuchen
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 Nächste Schritte
|
||
|
||
### SD-Karte vorbereiten
|
||
|
||
1. **Formatieren:** FAT32
|
||
2. **Verzeichnis:** `/roms/gb/`
|
||
3. **ROMs kopieren:** `tetris.gb`, etc.
|
||
|
||
### Hardware verbinden
|
||
|
||
- **Display:** Sollte schon integriert sein!
|
||
- **Buttons:** Nach Pin-Plan verlöten
|
||
- **Audio:** MAX98357A anschließen
|
||
- **NFC:** PN532 via I2C
|
||
- **SD-Karte:** Einlegen
|
||
|
||
### Code anpassen
|
||
|
||
1. **Pins prüfen:** `main/hardware_config.h`
|
||
2. **Features aktivieren:** `main/main.c`
|
||
|
||
---
|
||
|
||
## 🎮 Test-Workflow
|
||
|
||
### Minimaler Test (ohne ROMs):
|
||
|
||
```bash
|
||
# Build & Flash
|
||
idf.py build flash monitor
|
||
|
||
# Erwartung:
|
||
# - System startet
|
||
# - PSRAM erkannt
|
||
# - Display initialisiert
|
||
# - Keine Errors
|
||
```
|
||
|
||
### Mit ROM testen:
|
||
|
||
```bash
|
||
# 1. ROM auf SD-Karte: /roms/gb/tetris.gb
|
||
# 2. SD-Karte einlegen
|
||
# 3. Neustarten
|
||
# 4. ROM sollte laden
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 Tipps
|
||
|
||
### Schneller entwickeln:
|
||
|
||
```bash
|
||
# Nur App flashen (schneller):
|
||
idf.py app-flash
|
||
|
||
# Monitor ohne Flash:
|
||
idf.py monitor
|
||
|
||
# Build + Flash + Monitor in einem:
|
||
idf.py build flash monitor
|
||
```
|
||
|
||
### Debug aktivieren:
|
||
|
||
```bash
|
||
idf.py menuconfig
|
||
|
||
# Dann:
|
||
# Component config → Log output
|
||
# → Default log verbosity → Verbose
|
||
```
|
||
|
||
### Pin-Check:
|
||
|
||
Alle Pins sind in **einer** Datei:
|
||
```bash
|
||
cat main/hardware_config.h
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Checkliste
|
||
|
||
Nach erfolgreichem Build solltest du haben:
|
||
|
||
- ✅ ESP-IDF v4.4 aktiv
|
||
- ✅ Python 3.10 (nicht 3.12!)
|
||
- ✅ Projekt kompiliert ohne Fehler
|
||
- ✅ Board erkannt auf `/dev/ttyUSB0`
|
||
- ✅ Flash erfolgreich
|
||
- ✅ Serial Monitor zeigt Boot-Messages
|
||
- ✅ PSRAM wird erkannt (8 MB)
|
||
- ✅ Display wird initialisiert
|
||
|
||
---
|
||
|
||
## 🎯 Wenn alles läuft:
|
||
|
||
**Glückwunsch!** 🎉
|
||
|
||
Jetzt kannst du:
|
||
1. Hardware zusammenbauen
|
||
2. GNUBoy Core integrieren
|
||
3. ROMs testen
|
||
4. NFC implementieren
|
||
5. Link Cable bauen
|
||
|
||
---
|
||
|
||
## 📞 Hilfe
|
||
|
||
**Serial Monitor zeigt nichts?**
|
||
→ Richtigen Port? Richtige Baud-Rate (115200)?
|
||
|
||
**Build dauert ewig?**
|
||
→ Beim ersten Mal normal (5-10 Min), danach schneller
|
||
|
||
**Flash schlägt fehl?**
|
||
→ Boot Mode? USB-Kabel OK? Treiber installiert?
|
||
|
||
---
|
||
|
||
**Viel Erfolg!** 🚀
|
||
|
||
*Für Stefan's LEGO GameBoy Projekt*
|