update doumentacji

Kuba/dokumentacja.md

@@ -6,6 +6,16 @@
 
 ---
 
+## Opis ogólny
+
+Main Hub to centralny kontroler oświetlenia dla całego domu, oparty na mikrokontrolerze ESP32. Urządzenie działa pod kontrolą firmware ESPHome skompilowanego z frameworkiem esp-idf i łączy się z siecią domową przez Ethernet (nie WiFi — co zapewnia stabilniejsze połączenie i niższe opóźnienia).
+
+Fizycznie hub obsługuje **48 wejść** (przyciski, przełączniki) i **48 wyjść** (przekaźniki, obwody oświetleniowe) poprzez sześć ekspanderów I2C MCP23017. Dodatkowo steruje **9 kanałami LED** (taśmy RGBWW, CWWW, monochromatic) przez dwa sterowniki PWM PCA9685. Integracja z Home Assistant odbywa się przez natywne szyfrowane API ESPHome.
+
+Urządzenie działa w pełni **lokalnie** — logika przycisków jest wykonywana na ESP32, bez zależności od Home Assistant. HA jest potrzebne tylko do sterowania zewnętrznymi encjami (paski WLED, wentylator salon).
+
+---
+
 ## Sprzęt
 
 | Komponent | Opis |
@@ -17,10 +27,14 @@
 | Sterowniki PWM | 2× PCA9685 @ 1500 Hz (pca9685_hub1, pca9685_hub2) |
 | Status LED | RGB — GPIO5 (niebieski), GPIO14 (zielony), GPIO15 (czerwony) |
 
+Wszystkie ekspandery i sterowniki PWM komunikują się przez jeden magistrali I2C (SDA: GPIO13, SCL: GPIO16, 200 kHz). Scan I2C jest wyłączony (`scan: False`) aby nie spowalniać startu.
+
 ---
 
 ## Sieć
 
+Hub używa statycznego adresu IP — brak DHCP eliminuje opóźnienia przy restarcie i zapewnia przewidywalny adres niezależnie od stanu routera.
+
 | Parametr | Wartość |
 |---|---|
 | Statyczne IP | `10.10.0.5` |
@@ -29,10 +43,14 @@
 | Port API (HA) | `6053` |
 | Web UI | `http://10.10.0.5` (login: admin) |
 
+Urządzenie **nie restartuje się automatycznie** przy braku połączenia z Home Assistant (`reboot_timeout: 0s`). Oznacza to że hub działa i obsługuje przyciski lokalnie nawet gdy HA jest niedostępny (restart, aktualizacja).
+
 ---
 
 ## Mapa I2C (SDA: GPIO13, SCL: GPIO16, 200 kHz)
 
+Adresy I2C są przydzielone kolejno — parzyste dla wejść (IN), nieparzyste dla wyjść (OUT). Ułatwia to diagnozowanie problemów na magistrali.
+
 | Adres | ID | Rola |
 |---|---|---|
 | 0x20 | mcp23xxx_hub1_IN | 16 wejść (hub1_in0..15) |
@@ -48,18 +66,24 @@
 
 ## Status LED
 
+Wbudowany RGB LED (trzy niezależne kanały LEDC) informuje wizualnie o stanie urządzenia. Jest widoczny z zewnątrz obudowy i pozwala ocenić stan połączenia bez dostępu do logów.
+
 | 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`
+Dostępne efekty: `Fast Pulse` (0.5s), `Slow Pulse` (1s), `Random Effect` (2s)
 
 ---
 
 ## Wejścia — Binary Sensors
 
+Wszystkie wejścia są skonfigurowane jako `INPUT` z inwersją (`inverted: True`) — przyciski zwierają do masy. Filtr `delayed_on_off` eliminuje drgania styków (debouncing). Hub1_in5 ma zwiększony debounce (100ms) ze względu na właściwości konkretnego przycisku w sypialni.
+
+Wejścia hub1_in10..15, hub2_in14..15 oraz hub3_in13..15 są niepodpięte — reserved na przyszłość.
+
 ### hub1_IN (mcp23xxx_hub1_IN)
 
 | ID | Opis | Debounce |
@@ -119,6 +143,12 @@ Dostępne efekty: `Fast Pulse`, `Slow Pulse`, `Random Effect`
 
 ## Wyjścia — Switches
 
+Wszystkie wyjścia MCP23017 są zdefiniowane jako `switch` (platforma gpio) z `restore_mode: ALWAYS_OFF` — po każdym restarcie urządzenia wszystkie wyjścia startują wyłączone, niezależnie od poprzedniego stanu. Zapobiega to przypadkowemu włączeniu oświetlenia przy restarcie huba.
+
+Wyjścia hub1_out4, hub2_out5, hub2_out8 i hub3_out2 sterują wentylatorami. Pozostałe wyjścia sterują obwodami oświetleniowymi (halogeny, sufity, kinkiety, lustra).
+
+Hub3_out3..out15 są przeznaczone wyłącznie do sterowania ogrzewaniem — są kontrolowane przez automacje Home Assistant (generic_thermostat), a nie przez logikę przycisków.
+
 ### hub1_OUT (mcp23xxx_hub1_OUT)
 
 | ID | Opis |
@@ -182,12 +212,17 @@ Dostępne efekty: `Fast Pulse`, `Slow Pulse`, `Random Effect`
 | hub3_out14 | Ogrzewanie Biała Łazienka/WC |
 | hub3_out15 | Ogrzewanie Sypialnia 1 |
 
-Wszystkie wyjścia: `restore_mode: ALWAYS_OFF`
-
 ---
 
 ## Światła PWM (PCA9685)
 
+Taśmy LED są podłączone do dwóch sterowników PCA9685 pracujących na częstotliwości 1500 Hz. Każde światło ma zdefiniowane `default_transition_length: 2.0s` — płynne przejście przy włączaniu i wyłączaniu.
+
+Typy świateł:
+- **cwww** — zimna + ciepła biel (regulacja temperatury barwowej)
+- **rgbww** — pełny kolor RGB + zimna/ciepła biel (sypialnia)
+- **monochromatic** — jeden kanał PWM (regulacja jasności)
+
 | ID | Nazwa | Typ | Kanały PCA9685 |
 |---|---|---|---|
 | status_led | Status LED | rgb | GPIO5/14/15 (LEDC) |
@@ -201,25 +236,40 @@ Wszystkie wyjścia: `restore_mode: ALWAYS_OFF`
 | *(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%`
+PWM3_2_Hub2 (ch5 na pca9685_hub2): `max_power: 95%` — ograniczenie ze względu na właściwości podłączonej taśmy. Pozostałe kanały: `max_power: 100%`.
 
 ---
 
 ## Logika przycisków
 
-Granica single/multi-click: **350ms**
+### Jak działa multi-click
+
+Każde wejście używa mechanizmu `on_multi_click` z granicą **350ms** między pojedynczym a wielokrotnym naciśnięciem. ESP32 samodzielnie mierzy czas i decyduje o wykonaniu akcji — bez udziału Home Assistant. Opóźnienie między naciśnięciem a reakcją wynosi od 350ms (po zwolnieniu przycisku ESPHome czeka czy nie nastąpi kolejne naciśnięcie) do kilku ms dla długiego naciśnięcia.
 
 | Gest | Timing |
 |---|---|
-| 1× | ON ≤350ms, OFF ≥350ms |
-| 2× | dwa krótkie impulsy |
+| 1× | ON ≤350ms, potem OFF ≥350ms |
+| 2× | dwa krótkie impulsy, każdy ≤350ms |
 | 3× | trzy krótkie impulsy |
-| Długi | ON ≥350ms |
+| Długi | ON ≥350ms (akcja przy trzymaniu) |
 
-### Legenda
-- **[HA]** — akcja przez `homeassistant.service` (WLED, wentylator salon)
-- **off_all** — skrypt wyłączający wszystkie switche i LED-y
+### Zasada działania toggle
+
+Większość akcji 1× wykonuje `switch.toggle` — jeśli światło jest OFF to je włącza, jeśli ON to wyłącza. Wyjątek stanowi **hub1_in3** (Sypialnia 3), który używa logiki warunkowej:
+
+- jeśli **oba** łóżka (hub2_out12 i hub2_out1) są włączone → wyłącz oba
+- w każdym innym przypadku → włącz oba
+
+Dzięki temu jeden przycisk przy drzwiach sypialni zawsze zachowuje się intuicyjnie — jedno naciśnięcie rozświetla lub gasi całą sypialnię.
+
+### Skrypt off_all
+
+Długie naciśnięcie na wybranych wejściach wywołuje skrypt `off_all`, który wyłącza wszystkie wyjścia MCP23017 (hub1/2/3_out) oraz wszystkie LED PCA9685. Przydatny jako "wychodzę z domu" — jedno przytrzymanie przy wyjściu i cały dom jest ciemny.
+
+### Legenda tabel
+
+- **[HA]** — akcja przez `homeassistant.service` (wymaga działającego HA; jeśli HA jest niedostępny, akcja jest pomijana)
+- **off_all** — lokalny skrypt ESPHome, działa bez HA
 
 ### hub1_IN
 
@@ -236,7 +286,7 @@ Granica single/multi-click: **350ms**
 | 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.
+¹ Smart toggle: jeśli oba (hub2_out12 i hub2_out1) są ON → oba OFF; w przeciwnym razie → oba ON.
 
 ### hub2_IN
 
@@ -279,6 +329,10 @@ Granica single/multi-click: **350ms**
 
 ## Czujniki BLE (ATC Mithermometer)
 
+Hub ma aktywny skaner BLE (`esp32_ble_tracker`) który odbiera dane z czujników temperatury/wilgotności Xiaomi ATC Mithermometer rozmieszczonych w kluczowych pomieszczeniach. Dane są raportowane do Home Assistant i wykorzystywane przez termostaty ogrzewania (`generic_thermostat`).
+
+Czujniki używają zmodyfikowanego firmware ATC (nie oryginalnego Xiaomi), który nadaje dane w formacie BLE advertisement — hub nie musi parować się z czujnikami, tylko nasłuchuje.
+
 | Nazwa | MAC |
 |---|---|
 | Biuro | A4:C1:38:C5:11:58 |
@@ -287,19 +341,23 @@ Granica single/multi-click: **350ms**
 | WC | A4:C1:38:C9:FE:CA |
 | Łazienka | A4:C1:38:63:6D:DB |
 
-Każdy czujnik raportuje: temperatura, wilgotność, poziom baterii.
+Każdy czujnik raportuje: temperaturę (°C), wilgotność względną (%), poziom baterii (%).
 
 ---
 
 ## Czujniki diagnostyczne
 
+Encje diagnostyczne są widoczne w Home Assistant w sekcji urządzenia i pomagają monitorować stan huba bez logowania się do Web UI.
+
 | 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 |
+| sensor.main_hub_uptime | Czas pracy w sekundach od ostatniego restartu | 300s |
+| sensor.main_hub_esp32_temperatura | Temperatura wewnętrzna chipu ESP32 | 60s |
+| text_sensor.main_hub_ip_address | Aktualny adres IP | przy zmianie |
+| text_sensor.main_hub_firmware_version | Wersja firmware (z substitutions) | przy zmianie |
+| text_sensor.main_hub_esphome_version | Wersja ESPHome użyta do kompilacji | przy zmianie |
+
+> **Uwaga:** Temperatura chipu ESP32 może zwracać błąd `Ignoring invalid temperature` na niektórych wersjach esp-idf. Jest to znany problem — encja jest wyciszona w logach (`internal_temperature: WARN`).
 
 ---
 
@@ -309,71 +367,100 @@ Każdy czujnik raportuje: temperatura, wilgotność, poziom baterii.
 |---|---|
 | 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).
+Skrypt `off_all` jest wywoływany przez długie naciśnięcie na wejściach: hub1_in0, hub1_in2, hub1_in6, hub1_in7, hub2_in1, hub2_in2, hub2_in7, hub3_in12.
 
 ---
 
 ## Logi
 
-**Poziom globalny:** `INFO` — widoczne są tylko `[I]`, `[W]`, `[E]`
+### Poziom i filtry
+
+Globalny poziom logów ustawiony na `INFO` — w konsoli pojawiają się tylko zdarzenia istotne operacyjnie. Poziomy `DEBUG` i `CONFIG` (różowy dump konfiguracji przy starcie) są wyciszone.
 
-Filtry per-komponent (wyciszenie INFO z BLE):
 ```yaml
-logs:
-  atc_mithermometer: WARN
-  esp32_ble_tracker: WARN
-  ble_advertise: WARN
+logger:
+  level: INFO
+  logs:
+    atc_mithermometer: WARN   # wycisza INFO z BLE czujników
+    esp32_ble_tracker: WARN   # wycisza INFO ze skanera BLE
+    ble_advertise: WARN       # wycisza INFO z BLE advertise
+    # Odkomentuj poniższe gdy log_level ustawiony na DEBUG:
+    #sensor: WARN
+    #text_sensor: WARN
+    #internal_temperature: WARN
+    #binary_sensor: WARN
+    #switch: WARN
+    #light: WARN
+    #component: WARN
 ```
 
-Format komunikatu przy naciśnięciu przycisku:
+### Format komunikatów
+
+Każde naciśnięcie przycisku loguje komunikat INFO z nazwą wejścia, gestem i listą urządzeń które zostały przełączone:
+
 ```
 [I][main:XXXX]: Nazwa Przycisku [gest] → Co zostało włączone
 ```
 
-Przykład:
+Przykłady:
+
 ```
 [I][main:1775]: Schody 3 [1×] → Oczka Taras, Skrzynia, Tunel, Zwis Schody
 [I][main:1643]: Kuchnia Filar 1_1 [1×] → Salon Plafon
+[I][main:1694]: Kuchnia Filar 1_2 [1×] → Komin LED, Salon Kinkiety LED
+[I][main:998]:  Sypialnia 3 [1×] → Sypialnia Łóżko Lewa strona, Sypialnia Łóżko Prawa strona
 [I][main:1138]: Sypialnia Łóżko Prawo [długi] → off_all
 ```
 
 Zdarzenia połączenia z HA:
+
 ```
 [I]: HA client connected
 [W]: HA client disconnected
 ```
 
+### Historia w Home Assistant
+
+Każde naciśnięcie przycisku zapisuje wpis w logbooku HA (`logbook.log`) przypisany do konkretnej encji (switcha lub światła które zostało przełączone). Dzięki temu w historii danej encji widać który przycisk ją ostatnio przełączył.
+
 ---
 
 ## Konfiguracja API
 
-| Parametr | Wartość |
-|---|---|
-| Szyfrowanie | Noise (klucz w secrets.yaml) |
-| reboot_timeout | 0s (nie restartuje się przy braku HA) |
+Komunikacja z Home Assistant używa natywnego protokołu ESPHome z szyfrowaniem Noise (klucz zapisany w `secrets.yaml`). Protokół jest binarny i bardziej efektywny niż MQTT.
+
+| Parametr | Wartość | Opis |
+|---|---|---|
+| Port | 6053 | Standardowy port ESPHome API |
+| Szyfrowanie | Noise Protocol | Klucz w secrets.yaml (`api_key`) |
+| reboot_timeout | 0s | Brak automatycznego restartu przy braku HA |
+| Max połączeń | 8 | Maksymalna liczba klientów jednocześnie |
 
 ---
 
 ## OTA / Flashowanie
 
+Urządzenie wspiera OTA (Over-The-Air) przez dwa mechanizmy: natywne ESPHome OTA oraz przez web server. Pierwsze wgranie firmware wymaga połączenia USB (jeśli urządzenie nie ma jeszcze ESPHome), kolejne można robić zdalnie.
+
 ```bash
-# Tylko kompilacja
-esphome compile main-hub_do\ zrobienia.yaml
+# Tylko kompilacja — sprawdza błędy w YAML
+esphome compile "main-hub_do zrobienia.yaml"
 
-# Wgranie OTA
-esphome upload main-hub_do\ zrobienia.yaml
+# Wgranie OTA (kompilacja + upload)
+esphome upload "main-hub_do zrobienia.yaml"
 
-# Kompilacja + wgranie + logi
-esphome run main-hub_do\ zrobienia.yaml
+# Kompilacja + wgranie + podgląd logów
+esphome run "main-hub_do zrobienia.yaml"
 
-# Podgląd logów
-esphome logs main-hub_do\ zrobienia.yaml
+# Podgląd logów z działającego urządzenia
+esphome logs "main-hub_do zrobienia.yaml"
 
-# Walidacja configu
-esphome config main-hub_do\ zrobienia.yaml
+# Walidacja i dump połączonego configu (z pakietami)
+esphome config "main-hub_do zrobienia.yaml"
 ```
 
-Wymagany plik `secrets.yaml` w tym samym katalogu:
+Wymagany plik `secrets.yaml` w tym samym katalogu co YAML:
+
 ```yaml
 api_key: "<32-byte-base64>"
 ota_key: "<hasło>"
@@ -384,7 +471,9 @@ web_password: "<hasło>"
 
 ## Encje sterowane przez Home Assistant
 
-Poniższe encje są sterowane przez `homeassistant.service` (wymagają działającego HA):
+Poniższe encje są sterowane przez `homeassistant.service` — wywołanie wysyłane jest do HA przez API i HA wykonuje akcję lokalnie. Oznacza to że jeśli HA jest niedostępny, te konkretne akcje nie zadziałają (hub nadal działa lokalnie dla pozostałych świateł).
+
+Wszystkie poniższe encje to paski WLED lub wentylator zarządzany przez HA.
 
 | Encja HA | Opis |
 |---|---|
@@ -400,3 +489,11 @@ Poniższe encje są sterowane przez `homeassistant.service` (wymagają działaj
 | light.tunel_2 | WLED — Tunel |
 | light.zwis_schody_2 | WLED — Zwis schody |
 | switch.salon_wentylator | Wentylator salon |
+
+---
+
+## Ogrzewanie
+
+Strefy ogrzewania (hub3_out3..out15) są sterowane wyłącznie przez Home Assistant — nie mają przypisanej logiki przycisków w ESPHome. Każda strefa to osobny przekaźnik włączający/wyłączający siłownik zaworu.
+
+Kontrola odbywa się przez encje `climate` (generic_thermostat) w HA, które jako czujniki temperatury używają kombinacji czujników BLE z main-huba oraz dodatkowych czujników Zigbee (z2m). Harmonogramy i logika termostatów są w całości po stronie HA.