ESP32-Hub/Kuba/dokumentacja.md

# Main Hub — Dokumentacja

**Wersja firmware:** 1.1  
**Platforma:** ESPHome (esp-idf)  
**Autor:** Jan Kocoń / Peak Control

---

## 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 |
|---|---|
| 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) |

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` |
| Gateway | `10.10.0.1` |
| Subnet | `255.255.255.0` |
| 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) |
| 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

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` (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 |
|---|---|---|
| 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

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 |
|---|---|
| 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 |

---

## Ś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) |
| 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 |

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

### 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, potem OFF ≥350ms |
| 2× | dwa krótkie impulsy, każdy ≤350ms |
| 3× | trzy krótkie impulsy |
| Długi | ON ≥350ms (akcja przy trzymaniu) |

### 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

| 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: 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)

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 |
| 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: 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 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`).

---

## 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 na wejściach: hub1_in0, hub1_in2, hub1_in6, hub1_in7, hub2_in1, hub2_in2, hub2_in7, hub3_in12.

---

## Logi

### 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.

```yaml
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 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ł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

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 — sprawdza błędy w YAML
esphome compile "main-hub_do zrobienia.yaml"

# Wgranie OTA (kompilacja + upload)
esphome upload "main-hub_do zrobienia.yaml"

# Kompilacja + wgranie + podgląd logów
esphome run "main-hub_do zrobienia.yaml"

# Podgląd logów z działającego urządzenia
esphome logs "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 co YAML:

```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` — 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 |
|---|---|
| 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 |

---

## 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.