From 848a433a608b97afb570e537a5c111987487e7ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Koco=C5=84?= Date: Sat, 18 Apr 2026 01:57:52 +0200 Subject: [PATCH] update doumentacji --- Kuba/dokumentacja.md | 185 +++++++++++++++++++++++++++++++++---------- 1 file changed, 141 insertions(+), 44 deletions(-) diff --git a/Kuba/dokumentacja.md b/Kuba/dokumentacja.md index 08def53..86a476f 100644 --- a/Kuba/dokumentacja.md +++ b/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: "" @@ -384,7 +471,9 @@ web_password: "" ## 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. \ No newline at end of file