buttons, power button pin 18, deep sleep implementation, dokumentaion, and decription. optimzed sd card and display init, remove bloink screens at start, added color screens for error notifications

components/st7789/include/st7789.h

@@ -1,8 +1,22 @@
 /**
  * @file st7789.h
- * @brief ST7789 Display Driver for Waveshare ESP32-S3-Touch-LCD-2
- * 
- * 2.0" TFT Display, 240x320 resolution
+ * @brief ST7789 Display-Treiber für Waveshare ESP32-S3-Touch-LCD-2
+ *
+ * Dieser Treiber steuert das 2.0" TFT-Display (240×320 Pixel) über SPI.
+ *
+ * Hardware-Details:
+ * - Controller: ST7789V2
+ * - Auflösung: 320×240 Pixel (Landscape-Modus)
+ * - Farbtiefe: 16-bit RGB565
+ * - Interface: 4-Wire SPI
+ * - Maximale SPI-Frequenz: 80 MHz
+ * - DMA-Unterstützung für schnelle Framebuffer-Transfers
+ *
+ * Features:
+ * - Hardware-Reset über GPIO
+ * - PWM-Hintergrundbeleuchtung (0-100%)
+ * - Optimierte Framebuffer-Funktion (preswapped)
+ * - DMA-basierte SPI-Transfers für hohe Performance
  */
 
 #pragma once
@@ -15,53 +29,104 @@ extern "C" {
 #endif
 
 /**
- * @brief Initialize ST7789 display
- * @return ESP_OK on success
+ * @brief ST7789 Display initialisieren
+ * @return ESP_OK bei Erfolg, Fehlercode sonst
+ *
+ * Diese Funktion:
+ * - Initialisiert SPI-Bus (80 MHz)
+ * - Führt Hardware-Reset durch
+ * - Sendet Initialisierungs-Kommandos
+ * - Konfiguriert Display-Orientierung (Landscape)
+ * - Aktiviert Display
  */
 esp_err_t st7789_init(void);
 
 /**
- * @brief Set backlight brightness
- * @param brightness 0-100%
+ * @brief Hintergrundbeleuchtung einstellen
+ * @param brightness Helligkeit (0-100%)
+ *
+ * Verwendet LEDC PWM für stufenlose Helligkeitsregelung.
+ * 0 = Aus, 100 = Maximale Helligkeit
  */
 void st7789_set_backlight(uint8_t brightness);
 
 /**
- * @brief Clear screen to color
- * @param color 16-bit RGB565 color
+ * @brief Bildschirm mit Farbe füllen
+ * @param color 16-bit RGB565 Farbe
+ *
+ * Füllt den gesamten Bildschirm (320×240) mit einer Vollfarbe.
+ * Nützlich für Splash-Screens oder Hintergrund.
+ *
+ * RGB565 Format: RRRRR GGGGGG BBBBB
+ * Beispiele:
+ *   0xF800 = Rot, 0x07E0 = Grün, 0x001F = Blau
+ *   0xFFFF = Weiß, 0x0000 = Schwarz
  */
 void st7789_fill_screen(uint16_t color);
 
 /**
- * @brief Draw pixel
- * @param x X coordinate
- * @param y Y coordinate
- * @param color 16-bit RGB565 color
+ * @brief Einzelnes Pixel zeichnen
+ * @param x X-Koordinate (0-319)
+ * @param y Y-Koordinate (0-239)
+ * @param color 16-bit RGB565 Farbe
+ *
+ * Langsame Funktion! Nur für einzelne Pixel verwenden.
+ * Für größere Bereiche st7789_draw_buffer() nutzen.
  */
 void st7789_draw_pixel(int16_t x, int16_t y, uint16_t color);
 
 /**
- * @brief Draw buffer (framebuffer)
- * @param buffer Pointer to RGB565 framebuffer
- * @param x X start position
- * @param y Y start position
- * @param width Width of buffer
- * @param height Height of buffer
+ * @brief Framebuffer zeichnen (mit Byte-Swap)
+ * @param buffer Zeiger auf RGB565 Framebuffer
+ * @param x X-Startposition
+ * @param y Y-Startposition
+ * @param width Breite des Buffers (Pixel)
+ * @param height Höhe des Buffers (Pixel)
+ *
+ * Diese Funktion führt automatisches Byte-Swapping durch:
+ * RGB565 → BGR565 (ST7789 erwartet BGR-Reihenfolge)
+ *
+ * HINWEIS: Allokiert temporären Buffer! Für Performance
+ * besser st7789_draw_buffer_preswapped() verwenden.
  */
 void st7789_draw_buffer(const uint16_t *buffer, int16_t x, int16_t y,
                         int16_t width, int16_t height);
 
 /**
- * @brief Draw buffer that is already byte-swapped (optimized, no allocation)
- * @param buffer Pointer to pre-swapped BGR565 framebuffer
- * @param x X start position
- * @param y Y start position
- * @param width Width of buffer
- * @param height Height of buffer
+ * @brief Framebuffer zeichnen (OPTIMIERT, ohne Byte-Swap)
+ * @param buffer Zeiger auf vor-geswapted BGR565 Framebuffer
+ * @param x X-Startposition
+ * @param y Y-Startposition
+ * @param width Breite des Buffers (Pixel)
+ * @param height Höhe des Buffers (Pixel)
+ *
+ * OPTIMIERTE VERSION! Kein Byte-Swapping, keine Buffer-Allokation.
+ * Der Buffer MUSS bereits BGR565-formatiert sein!
+ *
+ * Verwendung:
+ *   uint16_t c_rgb = 0xF800;  // Rot in RGB565
+ *   uint16_t c_bgr = (c_rgb >> 8) | (c_rgb << 8);  // Swap zu BGR565
+ *   buffer[i] = c_bgr;  // In Buffer schreiben
+ *
+ * Dies ist die schnellste Methode für GameBoy-Emulation!
+ * Spart ~33% CPU-Zeit im Vergleich zu draw_buffer().
  */
 void st7789_draw_buffer_preswapped(const uint16_t *buffer, int16_t x, int16_t y,
                                    int16_t width, int16_t height);
 
+/**
+ * @brief Display in Sleep-Modus versetzen (für Deep Sleep)
+ *
+ * Diese Funktion:
+ * - Schaltet Hintergrundbeleuchtung aus
+ * - Sendet DISPOFF Befehl (Display aus)
+ * - Sendet SLPIN Befehl (Sleep In)
+ *
+ * WICHTIG: Diese Funktion MUSS aufgerufen werden bevor der ESP32
+ * in Deep-Sleep geht! Sonst blinkt das Display mit zufälligen Farben.
+ */
+void st7789_sleep(void);
+
 #ifdef __cplusplus
 }
 #endif