# Konfiguracja yoRadio dla ESP32-S3

## Pliki konfiguracyjne

Projekt używa trzech głównych plików konfiguracyjnych:
- `yoRadio/myoptions.h` - konfiguracja sprzętowa (piny, wyświetlacz, audio)
- `yoRadio/platformio.ini` - konfiguracja PlatformIO (board, biblioteki)
- `yoRadio/data/data/wifi.csv` i `playlist.csv` - konfiguracja WiFi i stacji radiowych

---

## 1. myoptions.h - Konfiguracja sprzętowa

Plik: `yoRadio/myoptions.h`

### Język interfejsu

```cpp
#define L10N_LANGUAGE RU
```

**Dostępne języki:**
- `EN` - English (domyślny)
- `RU` - Russian (wspiera polskie znaki: ąćęłńóśźż ĄĆĘŁŃÓŚŹŻ)

**UWAGA:** Wybierz `RU` aby wyświetlać polskie znaki na wyświetlaczu!

### Wyświetlacz

```cpp
#define DSP_MODEL DSP_ILI9341
```

**Model:** ILI9341 - kolorowy wyświetlacz TFT 320x240 pikseli, 3.2 cala

**Dostępne modele wyświetlaczy:**
- `DSP_DUMMY` - bez wyświetlacza
- `DSP_ILI9341` - 320x240, 3.2" (aktualnie używany)
- `DSP_ST7735` - 160x128, 1.8"
- `DSP_ST7789` - 320x240, 2.4"
- `DSP_SSD1306` - 128x64, 0.96" OLED
- `DSP_NEXTION` - wyświetlacz Nextion
- Więcej: https://github.com/e2002/yoradio/wiki/Available-display-models

### Piny SPI wyświetlacza (ESP32-S3)

```cpp
#define TFT_MOSI 11  /* SPI MOSI - dane do wyświetlacza */
#define TFT_SCLK 12  /* SPI CLK - zegar */
#define TFT_MISO 13  /* SPI MISO - dane z wyświetlacza */
#define TFT_CS 10    /* Chip Select */
#define TFT_RST -1   /* Reset (-1 = podłącz do EN ESP32) */
#define TFT_DC 9     /* Data/Command */
```

**WAŻNE dla ESP32-S3:**
- Standardowe piny SPI to: MOSI=11, CLK=12, MISO=13
- TFT_RST=-1 oznacza że pin RST wyświetlacza jest podłączony do pinu EN (reset) ESP32-S3
- Jeśli używasz innego pinu RST, zmień wartość (np. `#define TFT_RST 9`)

### Piny I2S audio (DAC)

```cpp
#define I2S_DOUT 16  /* DIN - dane audio */
#define I2S_BCLK 17  /* BCLK - Bit Clock */
#define I2S_LRC 15   /* LRC/WS - Left/Right Clock (Word Select) */
```

**Obsługiwane DAC I2S:**
- PCM5102 (najpopularniejszy)
- MAX98357A
- UDA1334A
- CS4344
- Wewnętrzny DAC ESP32 (gorsza jakość)

**Uwaga:** Piny I2S muszą być różne od pinów SPI!

### Encoder (pokrętło obrotowe) #1

```cpp
#define ENC_BTNL 5               /* Obrót w lewo */
#define ENC_BTNB 6               /* Przycisk (naciśnięcie) */
#define ENC_BTNR 4               /* Obrót w prawo */
#define ENC_INTERNALPULLUP true  /* Rezystory podciągające */
#define ENC_HALFQUARD true       /* Tryb czułości */
```

**Funkcje encodera:**
- Obrót lewo/prawo - zmiana stacji lub głośności
- Naciśnięcie - pauza/play

### Encoder (pokrętło obrotowe) #2

```cpp
#define ENC2_BTNL 18              /* Obrót w lewo */
#define ENC2_BTNB 8               /* Przycisk */
#define ENC2_BTNR 7               /* Obrót w prawo */
#define ENC2_INTERNALPULLUP true  /* Rezystory podciągające */
#define ENC2_HALFQUARD false      /* Tryb czułości */
```

**Uwaga:** Drugi encoder jest opcjonalny!

### Jasność wyświetlacza

```cpp
#define BRIGHTNESS_PIN 14  /* PWM pin do regulacji jasności */
```

Użyj pinu PWM ESP32-S3 do podłączenia LED backlight wyświetlacza.

### Pilot IR (podczerwień)

```cpp
#define IR_PIN 21  /* Pin odbiornika IR (np. VS1838B) */
```

**Obsługiwane protokoły:**
- NEC
- Samsung
- Sony
- RC5/RC6
- Więcej: biblioteka IRremoteESP8266

---

## 2. platformio.ini - Konfiguracja build systemu

Plik: `yoRadio/platformio.ini`

### Platforma i board

```ini
[env:esp32dev]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
```

**Uwaga:** Używamy `esp32-s3-devkitc-1` nie `esp32dev`!

### Prędkości komunikacji

```ini
monitor_speed = 115200   # Prędkość Serial Monitor
upload_speed = 921600    # Prędkość uploadu (921600 lub 460800)
```

### Partycje flash

```ini
board_build.partitions = min_spiffs.csv
board_build.flash_mode = dio
```

**min_spiffs.csv** - małe SPIFFS (system plików) dla konfiguracji i interfejsu webowego

### Flagi kompilacji (ESP32-S3)

```ini
build_flags = 
  -DCORE_DEBUG_LEVEL=4           # Poziom logowania (0-5)
  -DBOARD_HAS_PSRAM              # Board ma PSRAM
  -DARDUINO_USB_MODE=1           # Włącz USB
  -DARDUINO_USB_CDC_ON_BOOT=1    # USB CDC (Serial) od startu
```

**KRYTYCZNE dla ESP32-S3:**
- `ARDUINO_USB_CDC_ON_BOOT=1` - bez tego Serial nie będzie działał!
- `CORE_DEBUG_LEVEL=4` - logi info+warning+error+verbose

### Biblioteki

```ini
lib_deps = 
  adafruit/Adafruit GFX Library              # Grafika podstawowa
  adafruit/Adafruit ILI9341                  # Driver ILI9341
  adafruit/Adafruit ST7735 and ST7789 Library
  adafruit/Adafruit SSD1306                  # OLED
  adafruit/Adafruit PCD8544 Nokia 5110 LCD library
  adafruit/Adafruit SH110X
  adafruit/Adafruit SSD1327
  adafruit/Adafruit SSD1305
  nkawu/TFT 22 ILI9225                       # ILI9225
  mathertel/OneButton                        # Obsługa przycisków
  crankyoldgit/IRremoteESP8266              # Pilot IR
  paulstoffregen/XPT2046_Touchscreen        # Ekran dotykowy
  adafruit/RTClib                            # Zegar czasu rzeczywistego
```

---

## 3. Polskie czcionki i znaki

### Wsparcie dla polskich znaków

Plik: `yoRadio/src/displays/tools/utf8Rus.cpp`

**Zmienione znaki UTF-8:**

Polskie znaki: **ąćęłńóśźż ĄĆĘŁŃÓŚŹŻ**

Funkcja `utf8Rus()` konwertuje znaki UTF-8 na kody wyświetlacza:

```cpp
// Przykładowa konwersja:
case 0x82: {    
    if (!uppercase) { 
        strn[index] = 0xCf;  // małe ł
    } else {
        strn[index] = 0xD0;  // wielkie Ł
    }
    break;
}
```

**WAŻNE:** 
- Wybierz `L10N_LANGUAGE RU` w `myoptions.h`
- Plik `utf8Rus.cpp` został zmodyfikowany do obsługi polskich znaków
- Oryginalna wersja obsługiwała tylko cyrylicę

### Testowanie polskich znaków

W pliku `playlist.csv` możesz używać polskich nazw stacji:

```
Polskie Radio Trójka	http://...	0
TOK FM - najlepsze radio	http://...	0
```

Znaki specjalne będą poprawnie wyświetlane na ekranie ILI9341.

---

## 4. Schemat pinów ESP32-S3

### Schemat podłączenia

```
ESP32-S3 DevKit          ILI9341 Display
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GPIO 11 (MOSI)    ────►  SDI/MOSI
GPIO 12 (CLK)     ────►  SCK
GPIO 13 (MISO)    ────►  SDO/MISO
GPIO 10           ────►  CS
GPIO 9            ────►  DC/RS
EN (Reset)        ────►  RESET
3.3V              ────►  VCC/LED
GND               ────►  GND

ESP32-S3 DevKit          PCM5102 DAC
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GPIO 16           ────►  DIN
GPIO 17           ────►  BCK
GPIO 15           ────►  LCK/WS
3.3V              ────►  VIN
GND               ────►  GND
                       ─  SCK (pin nieużywany)
GND               ────►  FMT
3.3V              ────►  XMT

ESP32-S3 DevKit          Encoder
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GPIO 5            ────►  CLK (A)
GPIO 4            ────►  DT (B)
GPIO 6            ────►  SW (Button)
GND               ────►  GND
(3.3V opcjonalnie jeśli brak pullup)

ESP32-S3 DevKit          IR Receiver (VS1838B)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GPIO 21           ────►  OUT
3.3V              ────►  VCC
GND               ────►  GND
```

### Bezpieczne piny ESP32-S3

**Bezpieczne do użycia:**
- GPIO 1-18 (z wyjątkiem 15,16,17,18,19,20)
- GPIO 21
- GPIO 35-45

**Unikaj:**
- GPIO 0 - boot button
- GPIO 19, 20 - USB
- GPIO 26-32 - flash/PSRAM
- GPIO 33, 34 - nie podłączaj enkodera (tylko input)

---

## 5. Budowanie i upload

### Dostępne komendy (Taskfile)

```bash
# Budowanie
task build         # Kompiluj firmware
task clean         # Wyczyść build cache
task rebuild       # Clean + Build

# Upload
task upload        # Wgraj firmware
task upload-fs     # Wgraj pliki (SPIFFS)
task full-flash    # Firmware + pliki

# Monitoring
task monitor       # Serial monitor
task kill-monitor  # Zatrzymaj monitor

# Narzędzia
task list-ports    # Lista portów USB
task erase         # Wymaż całą pamięć flash
```

### Proces pełnego flasha

```bash
# 1. Edytuj konfigurację
nano yoRadio/myoptions.h

# 2. Edytuj WiFi i playlistę
nano yoRadio/data/data/wifi.csv
nano yoRadio/data/data/playlist.csv

# 3. Pełny flash
task full-flash

# 4. Monitor
task monitor
```

---

## 6. Debugowanie

### Logi Serial

```bash
task monitor
```

**Poziomy logów (CORE_DEBUG_LEVEL):**
- 0 - None
- 1 - Error
- 2 - Warning  
- 3 - Info
- 4 - Debug (aktualnie używany)
- 5 - Verbose

### Sprawdzanie połączenia wyświetlacza

Jeśli wyświetlacz świeci na biało:
1. Sprawdź połączenie pinów SPI
2. Sprawdź czy TFT_RST jest podłączony do EN lub do GPIO
3. Sprawdź napięcie zasilania (3.3V)
4. Sprawdź czy model wyświetlacza to ILI9341

### Sprawdzanie audio

Jeśli brak dźwięku:
1. Sprawdź połączenie I2S (DIN, BCK, LCK)
2. Sprawdź zasilanie DAC (3.3V lub 5V)
3. Zobacz logi: `task monitor`
4. Testuj inne URL stacji

---

## 7. Zaawansowane opcje

### Dodanie własnego wyświetlacza

Jeśli używasz niestandardowego wyświetlacza:

1. Znajdź driver w bibliotece Adafruit
2. Dodaj `lib_deps` w `platformio.ini`
3. Ustaw `DSP_MODEL` w `myoptions.h`
4. Dostosuj piny SPI

### Touchscreen

Jeśli masz wyświetlacz dotykowy:

```cpp
#define TS_MODEL TS_XPT2046    // Model touchscreen
#define TS_CS 255              // CS pin dla touch
```

### Wewnętrzny DAC ESP32

```cpp
#define I2S_INTERNAL true      // Użyj wbudowanego DAC
// Piny: DAC1=GPIO25, DAC2=GPIO26 (tylko ESP32, nie S3!)
```

**UWAGA:** ESP32-S3 nie ma wewnętrznego DAC! Musisz użyć zewnętrznego (I2S).

### Sleep mode (oszczędzanie energii)

```cpp
#define WAKE_PIN 6             // Pin do wybudzania (ENC_BTNB)
```

---

## 8. Backup i restore konfiguracji

### Backup przed aktualizacją

```bash
# Zapisz aktualne pliki
cp yoRadio/myoptions.h myoptions.h.backup
cp yoRadio/data/data/wifi.csv wifi.csv.backup
cp yoRadio/data/data/playlist.csv playlist.csv.backup
```

### Restore po aktualizacji

```bash
# Przywróć pliki
cp myoptions.h.backup yoRadio/myoptions.h
cp wifi.csv.backup yoRadio/data/data/wifi.csv
cp playlist.csv.backup yoRadio/data/data/playlist.csv

# Rebuild i upload
task full-flash
```

---

## 9. Troubleshooting

### Problem: Wyświetlacz biały ekran

**Rozwiązanie:**
1. Sprawdź czy `DSP_MODEL` jest poprawny
2. Sprawdź piny SPI (szczególnie CS, DC, RST)
3. Sprawdź zasilanie 3.3V
4. Spróbuj ustawić `TFT_RST` na konkretny pin zamiast -1

### Problem: Brak dźwięku

**Rozwiązanie:**
1. Sprawdź piny I2S (DOUT, BCLK, LRC)
2. Sprawdź czy DAC jest zasilany
3. Sprawdź URL stacji w przeglądarce
4. Zobacz logi: `task monitor`

### Problem: ESP32 się restartuje

**Rozwiązanie:**
1. Sprawdź zasilanie (stabilne 5V, min 1A)
2. Obniż `CORE_DEBUG_LEVEL` do 2
3. Sprawdź czy nie ma konfliktu pinów
4. Zobacz logi przed restartem

### Problem: Serial Monitor nie działa

**Rozwiązanie:**
1. Sprawdź czy `ARDUINO_USB_CDC_ON_BOOT=1` w `platformio.ini`
2. Sprawdź port: `task list-ports`
3. Spróbuj innego kabla USB
4. Restart ESP32

### Problem: Nie łączy się z WiFi

**Rozwiązanie:**
1. Sprawdź format `wifi.csv` (TAB separator!)
2. Sprawdź hasło WiFi
3. Zobacz logi: `task monitor`
4. Połącz się z AP: `yoRadioAP` / `12345987`

---

## 10. Linki i dokumentacja

- **GitHub projektu:** https://github.com/e2002/yoradio
- **Wiki:** https://github.com/e2002/yoradio/wiki
- **Dostępne wyświetlacze:** https://github.com/e2002/yoradio/wiki/Available-display-models
- **Schemat pinów:** https://github.com/e2002/yoradio#connection-tables
- **ESP32-S3 pinout:** http://wiki.fluidnc.com/en/hardware/ESP32-S3_Pin_Reference
- **Forum:** https://github.com/e2002/yoradio/discussions

---

## Autor konfiguracji

Konfiguracja stworzona dla ESP32-S3 DevKitC-1 z wyświetlaczem ILI9341 i DAC PCM5102.

Data: 2026-02-22