diff --git a/Kuba/dokumentacja.md b/Kuba/dokumentacja.md
new file mode 100644
index 0000000..08def53
--- /dev/null
+++ b/Kuba/dokumentacja.md
@@ -0,0 +1,402 @@
+# Main Hub — Dokumentacja
+
+**Wersja firmware:** 1.1  
+**Platforma:** ESPHome (esp-idf)  
+**Autor:** Jan Kocoń / Peak Control
+
+---
+
+## Sprzęt
+
+| Komponent | Opis |
+|---|---|
+| MCU | ESP32-PoE (board: esp32dev, rev 3+) |
+| Łączność | Ethernet LAN8720 (MDC: GPIO23, MDIO: GPIO18, CLK_OUT: GPIO17, Power: GPIO12) |
+| Ekspandery wejść | 3× MCP23017 (hub1_IN, hub2_IN, hub3_IN) — łącznie 48 wejść |
+| Ekspandery wyjść | 3× MCP23017 (hub1_OUT, hub2_OUT, hub3_OUT) — łącznie 48 wyjść |
+| Sterowniki PWM | 2× PCA9685 @ 1500 Hz (pca9685_hub1, pca9685_hub2) |
+| Status LED | RGB — GPIO5 (niebieski), GPIO14 (zielony), GPIO15 (czerwony) |
+
+---
+
+## Sieć
+
+| Parametr | Wartość |
+|---|---|
+| Statyczne IP | `10.10.0.5` |
+| Gateway | `10.10.0.1` |
+| Subnet | `255.255.255.0` |
+| Port API (HA) | `6053` |
+| Web UI | `http://10.10.0.5` (login: admin) |
+
+---
+
+## Mapa I2C (SDA: GPIO13, SCL: GPIO16, 200 kHz)
+
+| Adres | ID | Rola |
+|---|---|---|
+| 0x20 | mcp23xxx_hub1_IN | 16 wejść (hub1_in0..15) |
+| 0x21 | mcp23xxx_hub1_OUT | 16 wyjść (hub1_out0..15) |
+| 0x22 | mcp23xxx_hub2_IN | 16 wejść (hub2_in0..15) |
+| 0x23 | mcp23xxx_hub2_OUT | 16 wyjść (hub2_out0..15) |
+| 0x24 | mcp23xxx_hub3_IN | 16 wejść (hub3_in0..15) |
+| 0x25 | mcp23xxx_hub3_OUT | 16 wyjść (hub3_out0..15) |
+| 0x40 | pca9685_hub1 | 16-kanałowy PWM |
+| 0x41 | pca9685_hub2 | 16-kanałowy PWM |
+
+---
+
+## Status LED
+
+| Stan | Kolor / Efekt |
+|---|---|
+| Boot | Niebieski — Slow Pulse |
+| Połączono z HA | Zielony — stały (50% brightness) |
+| Rozłączono z HA | Czerwony — Slow Pulse (100% brightness) |
+
+Dostępne efekty: `Fast Pulse`, `Slow Pulse`, `Random Effect`
+
+---
+
+## Wejścia — Binary Sensors
+
+### hub1_IN (mcp23xxx_hub1_IN)
+
+| ID | Opis | Debounce |
+|---|---|---|
+| hub1_in0 | Wejście 1 | 50ms |
+| hub1_in1 | Wejście 3 | 50ms |
+| hub1_in2 | Wejście 2 | 50ms |
+| hub1_in3 | Sypialnia 3 | 50ms |
+| hub1_in4 | Sypialnia 1 | 50ms |
+| hub1_in5 | Sypialnia 2 | 100ms |
+| hub1_in6 | Sypialnia Łóżko Prawa Strona | 50ms |
+| hub1_in7 | Sypialnia Łóżko Lewa Strona | 50ms |
+| hub1_in8 | Pokój dla Gości Lewy | 50ms |
+| hub1_in9 | Pokój dla Gości Prawy | 50ms |
+| hub1_in10..15 | (niepodpięte) | — |
+
+### hub2_IN (mcp23xxx_hub2_IN)
+
+| ID | Opis | Debounce |
+|---|---|---|
+| hub2_in0 | Korytarz 2 | 50ms |
+| hub2_in1 | Korytarz 3 | 50ms |
+| hub2_in2 | Korytarz 1 | 50ms |
+| hub2_in3 | Mały Korytarz | 50ms |
+| hub2_in4 | Garderoba Mała | 50ms |
+| hub2_in5 | Kuchnia 3_1 | 50ms |
+| hub2_in6 | Kuchnia 3_2 | 50ms |
+| hub2_in7 | Kuchnia 2_1 | 50ms |
+| hub2_in8 | Kuchnia 2_2 | 50ms |
+| hub2_in9 | Kuchnia 1_1 | 50ms |
+| hub2_in10 | Kuchnia 1_2 | 50ms |
+| hub2_in11 | Schody 3 | 50ms |
+| hub2_in12 | Schody 1 | 50ms |
+| hub2_in13 | Schody 2 | 50ms |
+| hub2_in14..15 | (niepodpięte) | — |
+
+### hub3_IN (mcp23xxx_hub3_IN)
+
+| ID | Opis | Debounce |
+|---|---|---|
+| hub3_in0 | Garderoba Duża Lewy | 50ms |
+| hub3_in1 | Garderoba Duża Prawy | 50ms |
+| hub3_in2 | SPA Lewy | 50ms |
+| hub3_in3 | SPA Prawy | 50ms |
+| hub3_in4 | Biała Łazienka Ściana | 50ms |
+| hub3_in5 | Małe WC Lustro Prawy | 50ms |
+| hub3_in6 | Małe WC Lustro Lewy | 50ms |
+| hub3_in7 | Biała Łazienka Skos | 50ms |
+| hub3_in8 | SPA Lustro Lewy | 50ms |
+| hub3_in9 | SPA Lustro Prawy | 50ms |
+| hub3_in10 | Biuro Skos | 50ms |
+| hub3_in11 | Serwer Prawy | 50ms |
+| hub3_in12 | Serwer Lewy | 50ms |
+| hub3_in13..15 | (niepodpięte) | — |
+
+---
+
+## Wyjścia — Switches
+
+### hub1_OUT (mcp23xxx_hub1_OUT)
+
+| ID | Opis |
+|---|---|
+| hub1_out0 | (wolne) |
+| hub1_out1 | SPA Kinkiet Lustro |
+| hub1_out2 | Biuro |
+| hub1_out3 | Kuchnia Halogen |
+| hub1_out4 | SPA Wentylator |
+| hub1_out5 | Kanciapa pod schodami |
+| hub1_out6 | (wolne) |
+| hub1_out7 | Garderoba Duża |
+| hub1_out8 | Jadalnia |
+| hub1_out9 | WC Lustro |
+| hub1_out10 | SPA Halogeny |
+| hub1_out11 | (wolne) |
+| hub1_out12 | (wolne) |
+| hub1_out13 | Mały Korytarz Kinkiet |
+| hub1_out14 | Korytarz Halogeny |
+| hub1_out15 | Wejście Halogeny |
+
+### hub2_OUT (mcp23xxx_hub2_OUT)
+
+| ID | Opis |
+|---|---|
+| hub2_out0 | Łazienka Sufit |
+| hub2_out1 | Sypialnia Łóżko Prawa strona |
+| hub2_out2 | WC Sufit |
+| hub2_out3 | Mały Korytarz Sufit |
+| hub2_out4 | Łazienka Skos |
+| hub2_out5 | WC Wentylator |
+| hub2_out6 | (wolne) |
+| hub2_out7 | Sypialnia Halogen |
+| hub2_out8 | Biała Łazienka Wentylator |
+| hub2_out9 | (wolne) |
+| hub2_out10 | Pokój Gościnny Sufit |
+| hub2_out11 | Salon Plafon |
+| hub2_out12 | Sypialnia Łóżko Lewa strona |
+| hub2_out13 | SPA Zwisy |
+| hub2_out14 | Mała Garderoba |
+| hub2_out15 | (wolne) |
+
+### hub3_OUT (mcp23xxx_hub3_OUT)
+
+| ID | Opis |
+|---|---|
+| hub3_out0 | (wolne) |
+| hub3_out1 | (wolne) |
+| hub3_out2 | Wentylator Główny Obieg |
+| hub3_out3 | Ogrzewanie Kuchnia |
+| hub3_out4 | Ogrzewanie Jadalnia/Salon |
+| hub3_out5 | Ogrzewanie Salon kanapa |
+| hub3_out6 | Ogrzewanie SPA |
+| hub3_out7 | Ogrzewanie Korytarz |
+| hub3_out8 | Ogrzewanie Pokój Dziecka 2 |
+| hub3_out9 | Ogrzewanie Biuro/Serwer |
+| hub3_out10 | Ogrzewanie Biuro |
+| hub3_out11 | Ogrzewanie Pokój Dziecka 1 |
+| hub3_out12 | Ogrzewanie Garderoba |
+| hub3_out13 | Ogrzewanie Sypialnia 2 |
+| hub3_out14 | Ogrzewanie Biała Łazienka/WC |
+| hub3_out15 | Ogrzewanie Sypialnia 1 |
+
+Wszystkie wyjścia: `restore_mode: ALWAYS_OFF`
+
+---
+
+## Światła PWM (PCA9685)
+
+| ID | Nazwa | Typ | Kanały PCA9685 |
+|---|---|---|---|
+| status_led | Status LED | rgb | GPIO5/14/15 (LEDC) |
+| sypialnia_led | Sypialnia LED | rgbww | PWM1_1_Hub1, PWM1_2_Hub1, PWM3_1_Hub1, PWM3_2_Hub1, PWM1_1_Hub2 |
+| serwer_led | Serwer LED | cwww | PWM2_1_Hub1, PWM2_2_Hub1 |
+| jadalnia_led | Jadalnia LED | cwww | PWM4_2_Hub1, PWM4_1_Hub1 |
+| biala_lazienka_wanna_led | Biała Łazienka wanna LED | cwww | PWM5_2_Hub1, PWM5_1_Hub1 |
+| kuchnia_lezka_led | Kuchnia Łezka LED | monochromatic | PWM2_1_Hub2 |
+| SPA_Ledy | SPA Ledy | cwww | PWM5_2_Hub2, PWM5_1_Hub2 |
+| pokoj_dla_gosci_led | Pokój dla gości LED | cwww | PWM3_2_Hub2, PWM4_1_Hub2 |
+| *(brak id)* | TEST LED 1 | monochromatic | PWM1_2_Hub2 |
+| test_led_2 | TEST LED 2 | monochromatic | PWM3_1_Hub2 |
+
+Wszystkie LED: `default_transition_length: 2.0s`  
+PWM3_2_Hub2 (ch5): `max_power: 95%` — pozostałe: `100%`
+
+---
+
+## Logika przycisków
+
+Granica single/multi-click: **350ms**
+
+| Gest | Timing |
+|---|---|
+| 1× | ON ≤350ms, OFF ≥350ms |
+| 2× | dwa krótkie impulsy |
+| 3× | trzy krótkie impulsy |
+| Długi | ON ≥350ms |
+
+### Legenda
+- **[HA]** — akcja przez `homeassistant.service` (WLED, wentylator salon)
+- **off_all** — skrypt wyłączający wszystkie switche i LED-y
+
+### hub1_IN
+
+| ID / Opis | 1× | 2× | 3× | Długi |
+|---|---|---|---|---|
+| hub1_in0 / Wejście 1 | hub1_out15 (Wejście Halogeny) | — | — | off_all |
+| hub1_in1 / Wejście 3 | — | — | — | — |
+| hub1_in2 / Wejście 2 | [HA] light.korytarz_kinkiety | — | — | off_all |
+| hub1_in3 / Sypialnia 3 | hub2_out12 + hub2_out1 (smart toggle¹) | hub2_out12 + hub2_out1 off | — | — |
+| hub1_in4 / Sypialnia 1 | sypialnia_led | — | — | — |
+| hub1_in5 / Sypialnia 2 | hub2_out7 (Sypialnia Halogen) | — | — | — |
+| hub1_in6 / Sypialnia Łóżko Prawo | hub2_out1 | hub2_out12 + hub2_out1 | — | off_all |
+| hub1_in7 / Sypialnia Łóżko Lewo | hub2_out12 | hub2_out12 + hub2_out1 | — | off_all |
+| hub1_in8 / Pokój Gości Lewy | hub2_out10 (Pokój Gościnny Sufit) | hub1_out7 (Garderoba Duża) | — | — |
+| hub1_in9 / Pokój Gości Prawy | pokoj_dla_gosci_led | — | — | — |
+
+¹ Smart toggle hub1_in3 1×: jeśli oba (hub2_out12 i hub2_out1) są ON → oba OFF; w przeciwnym razie → oba ON.
+
+### hub2_IN
+
+| ID / Opis | 1× | 2× | 3× | Długi |
+|---|---|---|---|---|
+| hub2_in0 / Korytarz 2 | hub1_out15 (Wejście Halogeny) | — | — | — |
+| hub2_in1 / Korytarz 3 | [HA] light.korytarz_kinkiety | — | — | off_all |
+| hub2_in2 / Korytarz 1 | hub1_out14 (Korytarz Halogeny) | — | — | off_all |
+| hub2_in3 / Mały Korytarz | hub1_out13 + hub2_out3 | — | — | — |
+| hub2_in4 / Garderoba Mała | hub2_out14 (Mała Garderoba) | hub3_out2 (Wentylator Główny Obieg) | — | — |
+| hub2_in5 / Kuchnia 3_1 | hub1_out8 (Jadalnia) | — | — | — |
+| hub2_in6 / Kuchnia 3_2 | jadalnia_led | — | — | — |
+| hub2_in7 / Kuchnia 2_1 | hub1_out3 (Kuchnia Halogen) | — | — | off_all |
+| hub2_in8 / Kuchnia 2_2 | kuchnia_lezka_led | — | — | — |
+| hub2_in9 / Kuchnia 1_1 | hub2_out11 (Salon Plafon) | [HA] switch.salon_wentylator | — | — |
+| hub2_in10 / Kuchnia 1_2 | [HA] light.komin_led + light.salon_kinkiety_led | [HA] light.komin_led | — | [HA] light.komin_led |
+| hub2_in11 / Schody 3 | [HA] light.oczka_taras_2 + light.skrzynia_2 + light.tunel_2 + light.zwis_schody_2 | — | — | — |
+| hub2_in12 / Schody 1 | hub2_out11 (Salon Plafon) | — | — | — |
+| hub2_in13 / Schody 2 | [HA] light.salon_kinkiet_1_led + light.salon_kinkiet_2_led + light.salon_kinkiet_3_led | [HA] light.salon_kinkiety_led + 1/2/3 | — | [HA] light.komin_led |
+
+### hub3_IN
+
+| ID / Opis | 1× | 2× | 3× | Długi |
+|---|---|---|---|---|
+| hub3_in0 / Garderoba Duża Lewy | hub1_out7 (Garderoba Duża) | — | — | — |
+| hub3_in1 / Garderoba Duża Prawy | — | — | — | — |
+| hub3_in2 / SPA Lewy | hub2_out13 (SPA Zwisy) | — | — | hub1_out4 (SPA Wentylator) |
+| hub3_in3 / SPA Prawy | hub1_out4 + hub1_out10 (SPA Wentylator + Halogeny) | — | — | SPA_Ledy |
+| hub3_in4 / Biała Łazienka Ściana | hub2_out0 (Łazienka Sufit) | biala_lazienka_wanna_led | — | hub2_out8 (Łazienka Wentylator) |
+| hub3_in5 / Małe WC Lustro Prawy | hub2_out5 + hub2_out2 + [HA] light.wc_led | — | — | — |
+| hub3_in6 / Małe WC Lustro Lewy | hub1_out9 (WC Lustro) | — | — | — |
+| hub3_in7 / Biała Łazienka Skos | hub2_out4 (Łazienka Skos) | — | — | — |
+| hub3_in8 / SPA Lustro Lewy | hub1_out5 (Kanciapa pod schodami) | — | — | — |
+| hub3_in9 / SPA Lustro Prawy | hub1_out1 (SPA Kinkiet Lustro) | — | — | — |
+| hub3_in10 / Biuro Skos | hub1_out2 (Biuro) | serwer_led | — | — |
+| hub3_in11 / Serwer Prawy | serwer_led | test_led_2 | hub3_out2 (Wentylator Główny Obieg) | — |
+| hub3_in12 / Serwer Lewy | hub1_out14 (Korytarz Halogeny) | hub1_out14 + hub1_out2 (Korytarz + Biuro) | — | off_all |
+
+---
+
+## Czujniki BLE (ATC Mithermometer)
+
+| Nazwa | MAC |
+|---|---|
+| Biuro | A4:C1:38:C5:11:58 |
+| Serwer | A4:C1:38:5C:4F:38 |
+| Kuchnia | A4:C1:38:67:6B:94 |
+| WC | A4:C1:38:C9:FE:CA |
+| Łazienka | A4:C1:38:63:6D:DB |
+
+Każdy czujnik raportuje: temperatura, wilgotność, poziom baterii.
+
+---
+
+## Czujniki diagnostyczne
+
+| Encja | Opis | Interwał |
+|---|---|---|
+| sensor.main_hub_uptime | Czas pracy (sekundy) | 300s |
+| sensor.main_hub_esp32_temperatura | Temperatura chipu ESP32 | 60s |
+| text_sensor.main_hub_ip_address | Adres IP | przy zmianie |
+| text_sensor.main_hub_firmware_version | Wersja firmware | przy zmianie |
+| text_sensor.main_hub_esphome_version | Wersja ESPHome | przy zmianie |
+
+---
+
+## Skrypty
+
+| ID | Opis |
+|---|---|
+| off_all | Wyłącza wszystkie switche (hub1/2/3_out) oraz wszystkie LED (PCA9685 + status_led) |
+
+Skrypt `off_all` jest wywoływany przez długie naciśnięcie wybranych wejść (patrz tabela logiki przycisków).
+
+---
+
+## Logi
+
+**Poziom globalny:** `INFO` — widoczne są tylko `[I]`, `[W]`, `[E]`
+
+Filtry per-komponent (wyciszenie INFO z BLE):
+```yaml
+logs:
+  atc_mithermometer: WARN
+  esp32_ble_tracker: WARN
+  ble_advertise: WARN
+```
+
+Format komunikatu przy naciśnięciu przycisku:
+```
+[I][main:XXXX]: Nazwa Przycisku [gest] → Co zostało włączone
+```
+
+Przykład:
+```
+[I][main:1775]: Schody 3 [1×] → Oczka Taras, Skrzynia, Tunel, Zwis Schody
+[I][main:1643]: Kuchnia Filar 1_1 [1×] → Salon Plafon
+[I][main:1138]: Sypialnia Łóżko Prawo [długi] → off_all
+```
+
+Zdarzenia połączenia z HA:
+```
+[I]: HA client connected
+[W]: HA client disconnected
+```
+
+---
+
+## Konfiguracja API
+
+| Parametr | Wartość |
+|---|---|
+| Szyfrowanie | Noise (klucz w secrets.yaml) |
+| reboot_timeout | 0s (nie restartuje się przy braku HA) |
+
+---
+
+## OTA / Flashowanie
+
+```bash
+# Tylko kompilacja
+esphome compile main-hub_do\ zrobienia.yaml
+
+# Wgranie OTA
+esphome upload main-hub_do\ zrobienia.yaml
+
+# Kompilacja + wgranie + logi
+esphome run main-hub_do\ zrobienia.yaml
+
+# Podgląd logów
+esphome logs main-hub_do\ zrobienia.yaml
+
+# Walidacja configu
+esphome config main-hub_do\ zrobienia.yaml
+```
+
+Wymagany plik `secrets.yaml` w tym samym katalogu:
+```yaml
+api_key: "<32-byte-base64>"
+ota_key: "<hasło>"
+web_password: "<hasło>"
+```
+
+---
+
+## Encje sterowane przez Home Assistant
+
+Poniższe encje są sterowane przez `homeassistant.service` (wymagają działającego HA):
+
+| Encja HA | Opis |
+|---|---|
+| light.korytarz_kinkiety | WLED — Korytarz kinkiety |
+| light.komin_led | WLED — Komin LED |
+| light.salon_kinkiety_led | WLED — Salon kinkiety (grupa) |
+| light.salon_kinkiet_1_led | WLED — Salon kinkiet 1 |
+| light.salon_kinkiet_2_led | WLED — Salon kinkiet 2 |
+| light.salon_kinkiet_3_led | WLED — Salon kinkiet 3 |
+| light.wc_led | WLED — WC LED |
+| light.oczka_taras_2 | WLED — Oczka taras |
+| light.skrzynia_2 | WLED — Skrzynia |
+| light.tunel_2 | WLED — Tunel |
+| light.zwis_schody_2 | WLED — Zwis schody |
+| switch.salon_wentylator | Wentylator salon |