README.md hinzugefügt

README.md

@@ -0,0 +1,187 @@
+# Hirnfrei Floppinator
+
+USB-Floppy-Emulator auf Basis eines Raspberry Pi Pico. Zeigt `.img`- und
+`.adf`-Dateien von einer SD-Karte als USB-Massenspeicher an, Auswahl über
+Display + 3 Taster, Oberfläche mit LVGL.
+
+## Features
+
+- Erscheint am Host als normales USB-Massenspeichergerät (kein Treiber nötig)
+- Unterstützt `.img` (PC/generisch) und `.adf` (Amiga) — Kapazität wird
+  automatisch aus der Dateigröße ermittelt, kein festes Format nötig
+- 160×128-TFT-Display mit LVGL-Oberfläche (Liste, Statuszeile, Aktivitätsanzeige)
+- Alphabetisch sortierte Image-Liste
+- Manuelles Neuladen der Liste per Tastenkombination (z.B. nach SD-Kartenwechsel)
+- Aktivitäts-LED (Onboard-LED) leuchtet bei Lese-/Schreibzugriffen
+- Debug-Ausgaben über USB-Seriell, zentral abschaltbar
+
+## Hardware
+
+- Raspberry Pi Pico (RP2040)
+  ([Berrybase Pico Light Starter Kit](https://www.berrybase.de/raspberry-pi-pico-light-starter-kit-bestehend-aus-pico-offiziellem-kabel-und-stiftleisten))
+- 1,8" SPI-TFT-Display, 160×128, ST7735S-Controller
+  ([Berrybase 1,8" LCD-Anzeigemodul](https://www.berrybase.de/1-8-zoll-lcd-anzeigemodul-fuer-raspberry-pi-pico-65k-farben-160x128-spi))
+- Micro-SD-Kartenmodul, SPI, 3,3V (6-Pin: 3V3/CS/MOSI/CLK/MISO/GND)
+  ([Berrybase Micro-SD-Card-Reader-Modul, kompakt](https://www.berrybase.de/micro-sd-card-reader-modul-mit-spi-schnittstelle-kompakt))
+- 3× Kurzhubtaster, 6×6mm, vertikale Printmontage, H=5,0mm
+  ([Berrybase Kurzhubtaster](https://www.berrybase.de/kurzhubtaster-vertikale-printmontage-6x6mm-h-5-0mm))
+- microSD-Karte (FAT16/FAT32 formatiert)
+
+### Schaltplan / Verkabelung
+
+```
+                         Raspberry Pi Pico
+                       ┌──────────────────┐
+   TFT-Display         │                  │
+   ──────────          │                  │
+   CS   ───────────────┤ GP9              │
+   DC   ───────────────┤ GP8              │
+   RST  ───────────────┤ GP12             │
+   BL   ───────────────┤ GP13             │
+   SCK  ───────────────┤ GP10  (SPI1 SCK) │
+   MOSI ───────────────┤ GP11  (SPI1 TX)  │
+   MISO ───────────────┤ GP28  (SPI1 RX)  │
+   VCC  ───────────────┤ 3V3(OUT)         │
+   GND  ───────────────┤ GND              │
+                        │                  │
+   SD-Kartenmodul       │                  │
+   ──────────────       │                  │
+   CS   ───────────────┤ GP5              │
+   MOSI ───────────────┤ GP7   (SPI0 TX)  │
+   CLK  ───────────────┤ GP6   (SPI0 SCK) │
+   MISO ───────────────┤ GP4   (SPI0 RX)  │
+   3V3  ───────────────┤ 3V3(OUT)         │
+   GND  ───────────────┤ GND              │
+                        │                  │
+   Taster                │                  │
+   ──────                │                  │
+   Zurück ───────────────┤ GP14 (INPUT_PULLUP, gegen GND) │
+   Weiter ───────────────┤ GP15 (INPUT_PULLUP, gegen GND) │
+   Auswahl ──────────────┤ GP20 (INPUT_PULLUP, gegen GND) │
+                        │                  │
+   Aktivitäts-LED        │  Onboard-LED     │
+   (keine Verkabelung    │  (LED_BUILTIN)   │
+    nötig)                │                  │
+                        └──────────────────┘
+```
+
+Alle Taster schalten gegen GND (interner Pull-Up wird im Code aktiviert,
+kein externer Widerstand nötig).
+
+**Wichtig:** SD-Modul und Display hängen an unterschiedlichen SPI-Bussen
+(SD an SPI0, Display an SPI1) und benutzen absichtlich *nicht* die
+RP2040-Standard-SPI0-Pins (GP16-19), da diese im ursprünglichen
+Prototyp-Aufbau elektrisch beansprucht waren. Bei einem Neuaufbau von
+Grund auf können auch die Standard-Pins verwendet werden — einfach die
+`#define SD_*_PIN`-Zeilen im Sketch anpassen.
+
+### Pin-Übersicht
+
+| Funktion         | Pico-Pin | Bus/Modus         |
+|-------------------|----------|-------------------|
+| TFT CS            | GP9      | SPI1              |
+| TFT DC            | GP8      | SPI1              |
+| TFT RST           | GP12     | SPI1              |
+| TFT Backlight     | GP13     | digital OUT       |
+| TFT SCK           | GP10     | SPI1              |
+| TFT MOSI          | GP11     | SPI1              |
+| TFT MISO          | GP28     | SPI1              |
+| SD CS             | GP5      | SPI0              |
+| SD MOSI           | GP7      | SPI0              |
+| SD CLK            | GP6      | SPI0              |
+| SD MISO           | GP4      | SPI0              |
+| Taster Zurück     | GP14     | INPUT_PULLUP      |
+| Taster Weiter     | GP15     | INPUT_PULLUP      |
+| Taster Auswahl    | GP20     | INPUT_PULLUP      |
+| Aktivitäts-LED    | LED_BUILTIN (GP25) | digital OUT |
+
+## Abhängigkeiten (Arduino Libraries)
+
+Über den Arduino Library Manager installieren:
+
+| Library                  | Autor         | Version | Zweck                          |
+|---------------------------|---------------|---------|----------------------------------|
+| Adafruit GFX Library       | Adafruit      | aktuell | Basis-Grafikbibliothek           |
+| Adafruit ST7735 and ST7789 Library | Adafruit | aktuell | Display-Treiber                 |
+| SdFat                      | Bill Greiman  | 2.x     | SD-Karten-/FAT-Dateisystemzugriff |
+| Adafruit TinyUSB Library   | Adafruit      | aktuell | USB-Massenspeicher-Gerät (MSC)   |
+| lvgl                       | kisvegabor    | 9.x     | Grafische Oberfläche             |
+
+## Arduino IDE Einstellungen
+
+Board-Paket: **Raspberry Pi Pico/RP2040** (von Earle Philhower,
+`arduino-pico`) über den Boardverwalter installieren.
+
+Unter `Werkzeuge`:
+
+| Einstellung        | Wert                          |
+|---------------------|-------------------------------|
+| Board               | Raspberry Pi Pico              |
+| Flash Size          | 2MB (no FS)                    |
+| CPU Speed           | 200 MHz (oder Standard 133 MHz) |
+| Optimize            | Small (-Os) (Standard)          |
+| **USB Stack**       | **Adafruit TinyUSB**  ⚠️ zwingend erforderlich |
+| Upload Method       | Default (UF2)                   |
+
+**Wichtig:** Ohne `USB Stack: Adafruit TinyUSB` funktioniert weder die
+USB-Massenspeicher-Funktion noch `Serial` (da beides über TinyUSB läuft).
+Reine Test-/Diagnose-Sketches ohne TinyUSB (z.B. isolierte SPI-Tests)
+brauchen stattdessen `USB Stack: Pico SDK`, damit `Serial` ohne
+`Adafruit_TinyUSB.h`-Include funktioniert.
+
+## LVGL-Konfiguration (`lv_conf.h`)
+
+LVGL benötigt eine aktive `lv_conf.h`. Vorgehen:
+
+1. Die Vorlage `lv_conf_template.h` aus dem `lvgl`-Bibliotheksordner
+   eine Ebene höher kopieren, z.B. nach:
+   ```
+   Arduino/libraries/lv_conf.h      (Ebene über .../libraries/lvgl/)
+   ```
+2. In der kopierten Datei ganz oben `#if 0` zu `#if 1` ändern, damit sie
+   aktiv ist.
+3. Ansonsten reicht die Standard-Vorlage unverändert — Farbformat
+   (RGB565) und Schriftgröße (Montserrat 14, in der Vorlage standardmäßig
+   aktiv) werden bereits im Sketch selbst passend gesetzt/verwendet.
+
+## Display-Kalibrierung
+
+Das verwendete ST7735S-Panel benötigt einen manuellen Adressierungs-Offset
+(`tft.setColRowStart(2, 1)`), der empirisch für das konkret verbaute
+Panel-Exemplar ermittelt wurde. Bei einem anderen Panel/Batch kann dieser
+Wert leicht abweichen. Symptom bei falschem Offset: ein bunter,
+"verrauschter" Rand am Bildschirmrand (Zeilen-/Spaltenversatz zwischen
+GRAM und sichtbarem Glas). Falls das auftritt: Werte wie `(0, 0)`,
+`(1, 2)` oder `(0, 32)` ausprobieren.
+
+## Bedienung
+
+| Aktion                          | Tasten                      |
+|-----------------------------------|------------------------------|
+| In der Liste navigieren           | Zurück / Weiter               |
+| Fokussiertes Image mounten        | Auswahl                       |
+| Image-Liste neu laden (z.B. nach SD-Kartenwechsel) | Zurück + Weiter gleichzeitig |
+
+Das SD-Modul hat keinen Card-Detect-Pin — ein Kartenwechsel im laufenden
+Betrieb wird daher **nicht automatisch** erkannt (frühere Versuche mit
+automatischer Erkennung per periodischem Polling haben sich als
+unzuverlässig erwiesen). Nach einem Kartenwechsel einfach kurz
+Zurück+Weiter drücken.
+
+## Bekannte Einschränkungen
+
+- Kein automatisches Remounten des zuletzt gewählten Images nach einem
+  Kartenwechsel (bewusst, um kein Image von einer inzwischen anderen
+  Karte "weiterlaufen" zu lassen)
+- Debounce-basierte Tastenerkennung, kein Auto-Repeat bei gehaltener Taste
+- `MAX_IMAGES` ist aktuell auf 16 begrenzt (Konstante im Sketch anpassbar)
+
+## Debug-Ausgaben
+
+Über `Serial` (115200 Baud), zentral steuerbar über die Konstante
+`DEBUG_ENABLED` im Sketch (`true`/`false`). Bei `false` entfällt auch der
+Start-Delay auf den seriellen Monitor.
+
+## Kontakt
+
+Fragen, Anregungen oder Bugs? Discord: https://discord.projekt-hirnfrei.de