Tutorial 6: vCLU jako CLU w instalacji Grenton#

Hook: vCLU to wirtualny kontroler Grenton, który działa na zwykłym Raspberry Pi (albo dowolnym Linuksie). Pojawia się w Object Managerze jak prawdziwy CLU, rozumie ten sam protokół i obiekty, a przy okazji dokłada rzeczy, których fizyczny CLU nie ma: lokalny MQTT, integrację z Home Assistant i HomeKit, dashboardy oraz agenta AI. W tym tutorialu podłączymy vCLU do gotowego domu na Grentonie i spinamy całość lokalnie z Home Assistant oraz HomeKit.

Co zbudujemy#

Bierzemy istniejący dom postawiony na Grentonie i dokładamy do niego vCLU. Na koniec tego tutoriala:

• vCLU podłączone do działającej instalacji Grenton i widoczne w Object Managerze
• obiekty z prawdziwych CLU dostępne w vCLU
• całość wystawiona lokalnie do Home Assistant
• te same urządzenia widoczne w HomeKit (Apple Home)

Wszystko działa w lokalnej sieci, bez chmury.

Czas: ~?? minut. Wymaga: Grenton Object Manager, działająca instalacja Grenton, Raspberry Pi (lub inny Linux) z vCLU.

1. Instalacja#

Potrzebujesz komputera z Linuksem (np. Raspberry Pi) w tej samej sieci co Grenton: ta sama podsieć, ta sama maska. Grenton gada przez broadcasty UDP, a te nie przechodzą między podsieciami, więc jeśli vCLU i CLU wylądują w różnych segmentach (osobny VLAN, ruch przez router), discovery ich po prostu nie znajdzie.

Instalujesz jednym poleceniem:

curl -sSL https://vclu.pl/install.sh | bash

Szczegóły, wymagania i inne metody instalacji znajdziesz na stronie Instalacja.

2. Konfiguracja instancji (wizard)#

Po instalacji wejdź w panel vCLU w przeglądarce. Przy pierwszym uruchomieniu wita Cię kreator konfiguracji, który prowadzi przez pięć kroków: typ urządzenia, moduły, Grenton, zabezpieczenia i zakończenie.

Pierwszy krok jest najważniejszy: wybierasz typ urządzenia, a tego wyboru nie da się później zmienić. Masz trzy karty:

• CLU without I/O - vCLU jest wykrywane przez Object Managera jako kolejne urządzenie w sieci. Najprostsza konfiguracja z poziomu OM.
• CLU with I/O - vCLU jest wykrywane przez Object Managera jako kolejne urządzenie w sieci, wraz z dodatkowymi, wirtualnymi obiektami I/O. Definiujesz wirtualne obiekty, które w systemie widoczne są jako moduły I/O: przekaźniki, wejścia, ściemniacze. Pod każdy taki obiekt podpinasz to, co chcesz - HTTP, MQTT albo realne piny GPIO. W tym trybie vCLU jest pełnoprawnym kontrolerem.
• Standalone - bez żadnej zewnętrznej centrali. Samodzielny kontroler na MQTT, HomeKit i resztę integracji.

Niezależnie od wybranego trybu masz do dyspozycji MQTT, Home Assistant, HomeKit i pozostałe integracje vCLU.

W tym tutorialu wybieramy CLU with I/O - chcemy mieć w instalacji pełnoprawny kontroler z własnymi wirtualnymi obiektami.

Uwaga: tego wyboru nie zmienisz po zakończeniu kreatora. Przemyśl go dokładnie, zanim klikniesz dalej.

W kolejnych krokach skonfigurujesz PIN urządzenia (krok Grenton) oraz hasło do panelu (krok Zabezpieczenia). To samo hasło logowania do całej instancji, więc zapamiętaj je. PIN zostaw domyślny - osiem zer (00000000).

Dla zaawansowanych: wszystko, co ustawiasz w kreatorze, zapisuje się do pliku konfiguracyjnego .vclu.json na serwerze. Możesz go podejrzeć i edytować ręcznie albo wersjonować w gicie - panel i kreator to tylko nakładka na ten plik.

3. Dashboard i projekt w Object Managerze#

Po zakończeniu kreatora vCLU jest skonfigurowane. Wita Cię dashboard ze statystykami: czas pracy, zużycie pamięci, liczba przetworzonych komend, stan integracji i pluginów. Stąd masz podgląd na to, co dzieje się pod spodem.

Na stronie Stats znajdziesz kilka sekcji:

• System Overview - kondycja całej instancji: czas pracy (uptime), zużycie pamięci, liczba goroutines i przebiegów garbage collectora. Pierwsze miejsce, w które zaglądasz, gdy coś działa nie tak.
• Lua Runtime - silnik skryptów Lua, na którym stoi cała logika: liczba wykonań, błędy, aktywne i wyzwolone timery, obciążenie pętli (Busy %) oraz jej opóźnienie (Loop Lag). Wysoki Busy % albo rosnący Loop Lag to sygnał, że coś przeciąża instancję.
• CLU Protocol - komunikacja z systemem automatyki: czy nasłuch jest aktywny, ile komend odebrano, ile wykonano i ile było błędów.
• HTTP Server - wbudowany serwer: łączna liczba żądań z podziałem na API, panel webowy i błędy.
• Plugins - pluginy rozszerzające vCLU: ile jest aktywnych, ich timery, żądania HTTP i zużycie pamięci Lua.
• MQTT - osobno wbudowany broker (status, podłączeni klienci, wiadomości, retained) i klient MQTT (status, opublikowane, odebrane, subskrypcje).
• HomeKit - mostek do Apple Home: status, liczba udostępnionych akcesoriów, żądania i zdarzenia.

Niżej są jeszcze szczegóły pluginów oraz wykresy z ostatnich 24 godzin (pamięć, tempo komend, ruch HTTP, obciążenie Lua, opóźnienie pętli) - przydatne, gdy chcesz zobaczyć trend, a nie tylko bieżącą wartość.

Dla zaawansowanych: najważniejsze do obserwacji są statystyki Lua Runtime - to na tym silniku stoi cała Twoja logika, więc rosnący Busy %, Loop Lag czy liczba błędów od razu mówią, że coś przeciąża instancję. Jeśli chcesz wejść głębiej, vCLU wystawia endpointy do profilowania całego procesu (pprof: heap, goroutines, alokacje, CPU) oraz metryki w formacie Prometheus na /metrics.

W menu po lewej, w sekcji Integracje, masz osobne strony konfiguracji dla każdego kierunku:

• Grenton - integracja z systemem automatyki: parowanie, obiekty, synchronizacja.
• MQTT - broker i klient: adresy, dane logowania, tematy.
• HomeKit - mostek do Apple Home: kod parowania i udostępniane akcesoria.
• MCP - dostęp dla agenta AI.

Teraz przechodzisz do Object Managera. Otwórz istniejący projekt swojego domu albo załóż nowy.

4. Discovery - wykrycie vCLU w sieci#

Mając otwarty projekt, w Object Managerze uruchom CLU Discovery. To procedura, która przeszukuje sieć i wykrywa kontrolery, w tym nasze vCLU.

Otworzy się okno z parametrami wyszukiwania:

• Interfejs sieciowy - karta, przez którą leci wyszukiwanie. Upewnij się, że to ta podłączona do sieci z vCLU (na zrzucie en0 z adresem 192.168.0.90).
• Maska sieciowa, Brama, Początek i koniec zakresu IP - określają, jaki fragment sieci zostanie przeszukany. Zakres musi obejmować adres, pod którym działa vCLU.

Tu wraca to, o czym była mowa przy instalacji: vCLU i kontrolery muszą być w tej samej podsieci. Jeśli vCLU dostało adres spoza zakresu wpisanego w tym oknie, discovery go nie znajdzie.

Jeśli adresy w Twojej sieci przydziela serwer DHCP, sprawdź pod jakim IP faktycznie działa vCLU i upewnij się, że mieści się w podanym zakresie.

Zatwierdź przyciskiem OK. Object Manager przeszuka sieć i pokaże znalezione kontrolery.

5. Parowanie i dodanie vCLU do projektu#

Object Manager skanuje sieć i sprawdza konfigurację znalezionych urządzeń. U dołu okna na bieżąco rośnie licznik wykrytych kontrolerów.

Po drodze zostaniesz poproszony o PIN urządzenia. Wpisz osiem zer:

00000000

Object Manager łączy się z vCLU i zapisuje na nim klucz projektu oraz adres IP.

Następnie dostajesz listę znalezionych kontrolerów. Zaznacz te, które chcesz dodać lub zaktualizować - na liście jest też nasze vCLU (rozpoznasz je po numerze seryjnym i adresie IP).

Na koniec Object Manager weryfikuje status urządzeń. Przy naszym vCLU w kolumnie operacji zobaczysz Dodanie, a status powinien świecić na zielono (OK). Kliknij Zakończ.

Od tego momentu vCLU jest w drzewie projektu jak każdy inny kontroler - możesz wysyłać na nie skrypty dokładnie tak samo jak na fizyczne urządzenie.

6. Zmiana nazwy#

Świeżo dodane vCLU ma nazwę z numerem seryjnym (np. CLU221064687). Dla porządku warto je przemianować. Kliknij prawym przyciskiem na kontrolerze i wybierz Zmień nazwę.

Nadaj czytelną nazwę, np. Vclu.

7. Pierwszy skrypt - HelloWorld#

Czas sprawdzić, że wszystko działa. Na vCLU dodaj nowy skrypt (gałąź Skrypty → Dodaj skrypt), nazwij go HelloWorld i wpisz prostą linijkę:

print("test")

Wyślij skrypt na vCLU i uruchom go (Uruchom Skrypt). Efekt podejrzysz w panelu vCLU - w narzędziu Console albo w sekcji Debug.

Od tej pory vCLU zachowuje się w Object Managerze jak zwykły kontroler: piszesz i wysyłasz skrypty tak samo jak na fizyczny sprzęt.

Dla zaawansowanych: kod wysłany z Object Managera możesz podejrzeć w panelu vCLU, w narzędziu Editor - skrypty z OM lądują w pliku user.lua. Cały katalog skryptów możesz trzymać w gicie, żeby mieć kontrolę wersji, historię zmian i łatwy powrót do poprzedniej wersji.

8. Podłączenie pod MQTT#

MQTT to szyna, po której vCLU wymienia stany z Home Assistant i innymi systemami. W naszym scenariuszu broker jest już zainstalowany na serwerze - to Mosquitto. Instalacją brokera nie zajmujemy się w tym tutorialu.

vCLU może działać w MQTT na dwa sposoby: jako klient (podłącza się do zewnętrznego brokera) i jako broker (uruchamia własny, wbudowany).

Dobra praktyka: broker lepiej trzymać na zewnątrz - osobny Mosquitto jest stabilny, wydajny i sprawdzony. Wbudowany broker vCLU to opcja awaryjna: jeśli nie chcesz nic instalować, włączysz go jednym kliknięciem, ale nie nadaje się do dużych integracji. Traktuj go raczej jako ciekawostkę niż produkcyjne rozwiązanie.

W tym tutorialu vCLU łączy się jako klient z istniejącym Mosquitto. Wejdź w Integracje → MQTT, włącz Enable MQTT Client i podaj dane brokera: host, port (domyślnie 1883), Client ID oraz - jeśli broker tego wymaga - login i hasło. Włącz też Enable Home Assistant Integration, żeby vCLU samo zgłaszało urządzenia do HA (tym zajmiemy się w następnym kroku).

Kliknij Test Connection, a po sukcesie Save. U góry zobaczysz status połączenia (np. Connected to 192.168.0.50:1883).

Niżej, w sekcji MQTT Clients (Lua), widać wszystkie aktywne połączenia wraz ze statusem, liczbą wiadomości i subskrypcji. Klient z panelu to ten główny.

Dla zaawansowanych: z poziomu kodu Lua możesz utworzyć dodatkowych klientów MQTT. Przydaje się, gdy musisz spiąć się z drugim, niezależnym brokerem - np. urządzeniem albo usługą, która gada wyłącznie z własnym brokerem (falownik, Zigbee2MQTT na innym hoście, broker w chmurze producenta), podczas gdy Home Assistant siedzi na Twoim głównym Mosquitto. Każdy klient ma własne poświadczenia, TLS i subskrypcje. Szczegóły i API: Integracja MQTT.

9. Import obiektów z paczki diagnostycznej#

Mamy już vCLU w sieci i podpięte MQTT, ale vCLU nie zna jeszcze urządzeń z Twojego domu. Najszybszy sposób, żeby je poznało, to paczka diagnostyczna z Object Managera. Zawiera ona definicje wszystkich kontrolerów w projekcie i ich obiektów.

W Object Managerze wybierz Zapisz paczkę diagnostyczną. Powstanie plik .zip (np. 17052026_diagnosticPack.zip).

Teraz wgraj go do vCLU. Wejdź w Integracje → Grenton → OM Files, w sekcji Upload plików OM wskaż paczkę i kliknij Upload i waliduj.

Co się dzieje po wgraniu pliku:

• vCLU rozpakowuje paczkę i wyciąga z niej definicje wszystkich kontrolerów z Twojego projektu.
• Dla każdego kontrolera odczytuje jego obiekty (przekaźniki, ściemniacze, rolety, wejścia, czujniki) i dodaje je do swojego rejestru.
• Od tej chwili urządzenia z całego domu są widoczne w vCLU i gotowe, żeby je wystawić do MQTT, Home Assistant czy HomeKit.

Wgrane paczki zobaczysz niżej, na Liście plików OM.

Dla zaawansowanych: vCLU nie kopiuje tych urządzeń, tylko tworzy do nich obiekty proxy. Dla każdego kontrolera z paczki generowany jest plik proxy_<serial>.lua w katalogu imports/ (obok zapisanego om_<serial>.lua), a następnie od razu wykonywany w runtime Lua, żeby zarejestrować obiekty. Proxy nie trzyma stanu lokalnie - komendy i odczyty przekazuje do prawdziwego kontrolera, a stan aktualizuje przez subskrypcje. Dzięki temu sterowanie z vCLU i z fizycznego CLU pozostaje spójne.

10. Synchronizacja stanu#

Mamy już obiekty z całego domu, ale vCLU musi jeszcze wiedzieć, kiedy zmienia się ich stan na prawdziwych kontrolerach - bez tego światło zapalone fizycznym włącznikiem nie zaktualizuje się w Home Assistant. Od tego jest zakładka Sync w Integracje → Grenton.

Pod spodem ta synchronizacja korzysta z tego samego mechanizmu, co aplikacja mobilna Grenton - kontrolery cyklicznie raportują stany subskrybowanych obiektów. To wygodne i działa od ręki, ale ma swoją cenę: nie zawsze jest niezawodne. Przy większej liczbie obiektów albo słabszej sieci raporty potrafią się spóźniać lub gubić, a vCLU ma wtedy stan trochę nieaktualny.

Konfiguracja:

• Enable sync - włącza synchronizację.
• TTL (seconds) - jak długo żyje subskrypcja, zanim zostanie odnowiona.
• Batch size i Batch delay - na ile obiektów dzielić rejestrację subskrypcji i z jaką przerwą, żeby nie zalać kontrolera na raz.
• Objects to sync - lista wszystkich obiektów z możliwością zaznaczenia, które mają być synchronizowane. Filtry (DOUT, DIN, DIMM, AnalogIN) i wyszukiwarka pomagają wybrać tylko to, co Cię interesuje.

Zaznacz obiekty, które chcesz widzieć na bieżąco, i zapisz. W praktyce najsensowniej synchronizować:

• przekaźniki (DOUT) - oświetlenie, gniazdka, ogrzewanie - chcesz wiedzieć, czy są włączone,
• termometry i czujniki analogowe - temperatura, wilgotność, pomiary.

Synchronizacja wejść (DIN) zwykle nie ma większego sensu - to najczęściej chwilowe naciśnięcia przycisków, których stan i tak Cię nie interesuje na bieżąco. Co więcej, ta synchronizacja raportuje stan okresowo, więc krótki impuls (naciśnięcie i puszczenie przycisku) może po prostu wypaść między raportami i zostać pominięty - nie traktuj jej jako pewnego źródła zdarzeń.

Jeśli naprawdę zależy Ci na stanie konkretnego wejścia czy wyjścia (np. czujnik otwarcia bramy), pewniejszym rozwiązaniem jest twarda synchronizacja _:sync() opisana niżej - leci dokładnie w momencie zmiany i nic nie gubi.

Dla zaawansowanych: jeśli zależy Ci na twardej, pewnej synchronizacji, nie polegaj na raportach z aplikacji mobilnej. Zamiast tego wykorzystaj funkcję _:sync(): na prawdziwym kontrolerze w Object Managerze dopisujesz do zdarzeń obiektów (np. OnSwitchOn/OnSwitchOff) wywołanie, które przepycha stan do vCLU - VCLU:execute(0, "_:sync('CLU123.DOUT1', 1)"). Stan jest wtedy aktualizowany dokładnie w momencie zmiany, prosto ze zdarzenia, a nie przez okresowy raport. Pełny opis: API rejestru - _:sync().

11. Wystawienie obiektów (expose)#

Import paczki diagnostycznej dodał urządzenia do rejestru vCLU, ale to jeszcze nie znaczy, że widać je w Home Assistant czy HomeKit. Rejestr to wewnętrzna lista obiektów - żeby urządzenie pojawiło się na zewnątrz, trzeba je wystawić (expose).

expose() to most między rejestrem a integracjami. Mówisz nim: „ten obiekt ma się pojawić w HA/HomeKit, jako taki typ, pod taką nazwą, w takim pomieszczeniu". Bez tego obiekt istnieje, ale jest niewidoczny dla świata zewnętrznego.

Kod piszesz w plikach w katalogu modules/ (te, w przeciwieństwie do om.lua/user.lua, nie są nadpisywane przy synchronizacji z OM):

-- modules/dom.lua

-- Pobierz obiekt z rejestru i wystaw go
local lampa = _:get("CLU111000111.DOU5048")
expose(lampa, "switch", { name = "Lampa salon", area = "Salon" })

-- Ściemniacz jako światło z regulacją
local led = _:get("CLU111000111.DIM3021")
expose(led, "dimmer", { name = "LED kuchnia", area = "Kuchnia" })

-- Roleta
local roleta = _:get("CLU111000111.ROL1102")
expose(roleta, "cover", { name = "Roleta sypialnia", area = "Sypialnia" })

Drugi argument to typ ekspozycji - mówi integracjom, czym obiekt jest i jak go pokazać. Najczęstsze: switch, light, dimmer, cover, sensor, binary_sensor, temperature, humidity, number. W options ustawiasz m.in. name, area, group, readonly, hidden, a także zawęzisz ekspozycję do jednej integracji (mqttOnly/homekitOnly).

Jeśli nie chcesz wystawiać obiektów po jednym, możesz wystawić cały rejestr na raz:

exposeRegistry()

vCLU sam dobierze wtedy typ ekspozycji na podstawie typu obiektu (przekaźnik → switch, ściemniacz → dimmer, roleta → cover itd.).

Pełny opis API, wszystkie typy i opcje: expose() API.

Dla leniwych: niech LLM nazwie wszystko za Ciebie#

Pisanie expose() dla każdego obiektu z osobna - z ładną nazwą i pomieszczeniem - to przy większym domu godzina nudnej roboty. Da się to zrzucić na dowolny model językowy (ChatGPT, Claude, Gemini - obojętne). Plan jest prosty: dajesz LLM-owi listę swoich obiektów, a on oddaje gotowy plik modules/dom.lua.

Krok 1. W panelu vCLU otwórz Console i zrzuć cały rejestr do JSON-a:

print(_:toJSON())

Dostaniesz tablicę wszystkich obiektów wraz z ich ścieżkami, typami i nazwami nadanymi w Object Managerze - dokładnie to, czego LLM potrzebuje, żeby się domyślić, co jest czym i gdzie. Skopiuj cały wynik.

Krok 2. Wklej do LLM-a poniższy prompt, a pod nim - skopiowany JSON:

Jesteś generatorem konfiguracji dla vCLU (wirtualny kontroler Grenton).
Na podstawie listy obiektów w JSON-ie wygeneruj zawartość pliku modules/dom.lua,
który wystawia (expose) te obiekty do Home Assistant i HomeKit.

Dla każdego obiektu wygeneruj jedną linię w formacie:
expose(_:get("<path>"), "<typ>", { name = "<nazwa>", area = "<pomieszczenie>" })

Zasady doboru typu ekspozycji na podstawie pola "type":
- DOUT  -> "switch", ale "light" jeśli nazwa sugeruje oświetlenie
          (lampa, światło, oświetlenie, LED, kinkiet, żyrandol, plafon, podświetlenie)
- DIMMER (DIM) -> "dimmer"
- ROLLER (ROL) -> "cover"
- ONE_WIRE / czujnik temperatury -> "temperature"
- analogowe wejście / pomiar -> "sensor"
- DIN -> pomiń (zakomentuj linią z -- ), bo to chwilowe naciśnięcia przycisków

Zasady nazewnictwa:
- Z pola "name" wyciągnij czytelną nazwę urządzenia ORAZ pomieszczenie (area).
  Przykład: "Salon_Lampa_Sufitowa" -> name = "Lampa sufitowa", area = "Salon".
- Jeśli nazwa nie zdradza pomieszczenia, zostaw area = "" i dopisz na końcu linii
  komentarz -- TODO: uzupełnij pomieszczenie
- Nazwy po polsku, z dużej litery, bez podkreśleń i numerów seryjnych.

Zwróć WYŁĄCZNIE kod Lua w jednym bloku, pogrupowany komentarzami po pomieszczeniach,
bez żadnego dodatkowego opisu. Pierwsza linia pliku: -- modules/dom.lua

JSON z obiektami:

LLM odda Ci gotowy plik - coś takiego:

-- modules/dom.lua

-- Salon
expose(_:get("CLU111000111.DOU5048"), "light",  { name = "Lampa sufitowa", area = "Salon" })
expose(_:get("CLU111000111.DIM3021"), "dimmer", { name = "LED podsufitka", area = "Salon" })

-- Sypialnia
expose(_:get("CLU111000111.ROL1102"), "cover",  { name = "Roleta",         area = "Sypialnia" })

Krok 3. Wklej wynik do pliku modules/dom.lua w Editorze vCLU, przejrzyj go (LLM bywa kreatywny przy nazwach i pomieszczeniach - poprawisz w minutę zamiast pisać wszystko od zera) i zapisz. Po przeładowaniu obiekty pojawią się w Home Assistant i HomeKit z ładnymi nazwami.

Uwaga: to wciąż Twoja konfiguracja - przejrzyj, co LLM wygenerował, zanim zostawisz to na produkcji. Zwłaszcza podział switch vs light i przypisanie pomieszczeń warto sprawdzić okiem.

Uwaga - czujniki temperatury: czujniki 1-Wire (ONE_WIRE) są obsługiwane - po imporcie paczki trafiają do rejestru i wystawisz je jako temperature (świetne na dashboardy). Natomiast termostaty to osobne, bardziej złożone urządzenie (climate: temperatura bieżąca, zadana, stan grzania) i nie są jeszcze wystawiane przez import - to pozycja na roadmapie. Podobnie czujniki paneli Smart Panel (temp/wilgotność/lux) czekają na pełne wsparcie.

12. Kontrola dostępu (Access)#

Wystawiliśmy obiekty, ale to jeszcze nie znaczy, że każda integracja ma widzieć i móc sterować wszystkim. Co innego chcesz pokazać Home Assistant (pełne sterowanie domem), co innego HomeKit (może tylko podgląd), a co innego agentowi AI, którego dopuszczasz wyłącznie do kilku obiektów. Od tego jest strona Access w menu po lewej.

Dla każdego obiektu ustawiasz poziom dostępu osobno dla każdego kierunku. Poziomy są trzy:

• Full - obiekt jest widoczny i można nim sterować.
• Readonly - stan obiektu jest widoczny, ale nie można nim sterować (np. czujnik, albo światło, które ma być tylko podglądane, a nie przełączane z aplikacji).
• Hidden - obiekt w ogóle nie jest udostępniony danej integracji ani botowi.

W tabeli Dostęp do obiektów każdy wiersz to jeden obiekt, a poziom ustawiasz niezależnie w dwóch kolumnach: MQTT/HA (Home Assistant) i HomeKit. Boty MCP (agenci AI) mają własny zestaw uprawnień - konfigurujesz je przez profile (link Profile w prawym górnym rogu).

Przy 150+ obiektach klikanie każdego z osobna to mordęga, więc masz narzędzia do masowej konfiguracji:

• Wyszukiwarka - filtruj po nazwie lub ścieżce.
• Filtr po typie - zawęź listę do jednego typu (np. DOUT (68)), żeby zająć się np. wszystkimi przekaźnikami na raz.
• Zaznaczanie i „Ustaw wszystko" - zaznacz wiele wierszy (licznik 22 sel.) i ustaw im poziom jednym ruchem.
• Licznik 68 / 158 objects u góry pokazuje, ile obiektów jest aktualnie udostępnionych (nie-Hidden).

W naszym scenariuszu typowo ustawiasz MQTT/HA na Full dla wszystkiego, czym chcesz sterować z Home Assistant, czujniki i termometry zostawiasz na Readonly, a obiekty czysto wewnętrzne (pomocnicze przekaźniki, logika) chowasz na Hidden. HomeKit możesz potraktować węziej - np. tylko oświetlenie i rolety w salonie.

HomeKit: zmiany dostępu dla HomeKit wymagają restartu mostu HomeKit, żeby Apple Home zobaczyło nowy zestaw akcesoriów. Panel przypomina o tym osobnym komunikatem.

Dla zaawansowanych: zamiast klikać każdy obiekt, możesz pracować na profilach - nazwanych zestawach reguł z poziomem domyślnym i nadpisaniami per-obiekt (np. profil tylko-czujniki: default: hidden, a wybrane czujniki readonly). Profile przypisujesz do integracji i do botów MCP, a gdy klient ma ich kilka, obowiązuje zasada most permissive wins (full > readonly > hidden). To samo, co ustawiasz tu klikaniem, zapisuje się do konfiguracji - możesz to też wersjonować w gicie. Pełny opis: AccessControl & Expose, a dostęp dla agentów AI: MCP - kontrola dostępu.

13. Home Assistant#

Mamy obiekty wystawione (expose) i ustawiony dostęp (MQTT/HA na Full). Teraz spinamy to z Home Assistant. Cały trik polega na tym, że vCLU i Home Assistant gadają przez ten sam broker MQTT - to samo Mosquitto, do którego vCLU podłączyło się w kroku 8 (u nas na Mac mini, 192.168.0.50). vCLU publikuje opisy swoich urządzeń w formacie Home Assistant MQTT Discovery, a HA samo tworzy z nich encje. Nic nie klikasz ręcznie po stronie urządzeń.

Krok 1 - podłącz Home Assistant do brokera. W Home Assistant wejdź w Ustawienia → Urządzenia i usługi → Dodaj integrację i wybierz MQTT (jeśli HA samo wykryło broker w sieci, po prostu potwierdź). Wpisz dane tego samego Mosquitto, którego używa vCLU:

• Pośrednik (broker) - adres Mosquitto, u nas 192.168.0.50 (Mac mini).
• Port - 1883.
• Nazwa użytkownika i Hasło - te same, którymi loguje się vCLU (u nas użytkownik vclu).

Zatwierdź. Od tej chwili HA jest podłączone do tej samej szyny co vCLU.

Krok 2 - zrestartuj vCLU. Przy starcie vCLU rozsyła na MQTT komplet komunikatów discovery - opis każdego wystawionego urządzenia (typ, nazwa, tematy stanu i komend). To właśnie te wiadomości mówią Home Assistant „mam taką lampę, taki czujnik, taką roletę". Restart gwarantuje, że HA - świeżo podłączone do brokera - dostanie pełen, aktualny zestaw.

Restart zrobisz z poziomu systemu (sudo systemctl restart vclu) albo przyciskiem restartu w panelu vCLU.

Efekt. Po chwili w Home Assistant, w Ustawienia → Urządzenia i usługi → Wpisy → Rejestr encji, pojawiają się wszystkie wystawione obiekty. Rozpoznasz je po nazwie vCLU <Pomieszczenie> <Nazwa> (np. vCLU Biuro LED) i identyfikatorze encji w stylu light.vclu_clu111000111_dou3328 - typ encji (light, switch, sensor), nazwa i Obszar biorą się dokładnie z tego, jak wystawiłeś obiekt przez expose() (pole area trafia prosto do pomieszczenia w HA, dlatego encje od razu są pogrupowane po pokojach).

Od teraz lampy, rolety i czujniki z Twojego Grentona są pełnoprawnymi encjami Home Assistant - wrzucisz je na dashboard, przypiszesz do pomieszczeń i użyjesz w automatyzacjach. Sterowanie działa w obie strony: zmiana w HA leci przez MQTT do vCLU i dalej do prawdziwego CLU, a stan przełączony fizycznym włącznikiem wraca do HA (o ile obiekt synchronizujesz - patrz krok 10).

Dla zaawansowanych: komunikaty discovery są publikowane jako retained, więc HA odtworzy encje także po swoim restarcie, bez ponownego restartu vCLU. Jeśli encja nie znika po usunięciu expose(), wyczyść retained config na temacie homeassistant/.../config. Szczegóły mapowania typów i tematów: Integracja MQTT oraz Home Assistant.

I to wszystko - Grenton spięty z Home Assistant przez vCLU. Na pulpicie HA masz teraz cały dom: światła, przełączniki i czujniki pogrupowane po pokojach (każdy obiekt z area trafia do swojego pomieszczenia), gotowe do dashboardów i automatyzacji. Nie trzeba się w to bardziej zagłębiać - dalej działasz już czystym Home Assistant.

14. HomeKit (dla ludzi z Apple)#

Jeśli w domu rządzi Apple, vCLU wpina Twojego Grentona prosto do aplikacji Dom (Apple Home) - bez Home Assistant, bez chmury, bez dodatkowego sprzętu. vCLU działa jako mostek HomeKit (HAP): pojawia się w aplikacji Dom jako jedno urządzenie-mostek, a pod nim te same obiekty, które wystawiłeś przez expose() - lampy, przełączniki, rolety, czujniki. Komunikacja jest lokalna i szyfrowana, a sterujesz głosem przez Siri, scenami i automatyzacjami Apple.

To samodzielna alternatywa dla HA - możesz mieć oba na raz (ten sam obiekt naraz w HA i w HomeKit) albo tylko HomeKit.

Krok 1 - włącz mostek w panelu vCLU. Wejdź w Integracje → HomeKit i włącz mostek. Ustawisz tu:

• PIN parowania - 8-cyfrowy kod, który podasz w aplikacji Dom. Panel pokazuje go bez kresek (domyślnie 00102003), a Apple Home sam sformatuje go jako 001-02-003. Zapamiętaj go.
• Nazwę mostu - jak ma się nazywać w aplikacji Dom (np. vCLU Bridge).
• Port - HAP, domyślnie 5123.

Po zmianach kliknij Restart Bridge, żeby most wstał ze świeżą konfiguracją.

Krok 2 - sparuj w aplikacji Dom. Na iPhonie/iPadzie otwórz Dom, stuknij + w prawym górnym rogu i wybierz Dodaj akcesorium. Zeskanuj kod QR albo wybierz „Nie mam kodu lub nie mogę zeskanować" i wpisz PIN z panelu (domyślnie 001-02-003). Apple Home znajdzie vCLU Bridge i poprosi o potwierdzenie - dodaj go.

Krok 3 - efekt. Po sparowaniu wszystkie wystawione obiekty pojawiają się jako akcesoria HomeKit. Dorzucisz je do scen („Dobranoc" gasi światła) i automatyzacji, i powiesz „Hej Siri, zgaś światło w salonie".

Przypisywanie do pomieszczeń - to robisz ręcznie. W odróżnieniu od Home Assistant, HomeKit nie przyjmuje pokoju z mostka - aplikacja Dom zawsze każe Ci samodzielnie przypisać każde akcesorium do pomieszczenia (to ograniczenie Apple, nie vCLU). Żeby to nie była zgadywanka „dziesięć razy Światło", vCLU dokleja pokój do nazwy akcesorium - zobaczysz Salon Lampa sufitowa, Kuchnia Temperatura, Łazienka góra Lustro. Dzięki temu od razu wiesz, gdzie co wrzucić, a po przypisaniu możesz w aplikacji Dom skrócić nazwę do samego Lampa sufitowa.

Tym, co pojawia się w HomeKit, rządzi dokładnie to samo, co w HA - expose i kontrola dostępu (krok 11 i 12), tylko w kolumnie HomeKit:

• obiekt ukryty (Hidden) dla HomeKit nie pojawia się jako akcesorium,
• obiekt tylko do odczytu (Readonly) widać jako kafelek statusu (np. stan czujnika), bez możliwości przełączania,
• reszta jest w pełni sterowalna.

Ważne - restart mostu po zmianach. W odróżnieniu od MQTT/HA, HomeKit nie podchwytuje zmian na żywo. Po każdej zmianie dostępu (Access) albo zestawu wystawionych obiektów kliknij Restart Bridge w panelu HomeKit - dopiero wtedy aplikacja Dom zobaczy nowy układ akcesoriów.

Dla zaawansowanych: wszystko skonfigurujesz też w .vclu.json (sekcja homeKit: pin, port, bridgeName, refreshInterval). Baza parowania siedzi w katalogu homekit-db/ - nie usuwaj go, bo stracisz parowanie i trzeba będzie usunąć mostek z aplikacji Dom i sparować od nowa. Pełny opis typów akcesoriów i API: Integracja HomeKit.

Co dalej?#

• Tutorial 2: Grenton (Gate HTTP) — najprostszy tryb integracji
• Tutorial 3: MQTT + HomeKit + Home Assistant
• Tutorial 5: Agent AI

vCLU to niezależny, nieoficjalny projekt społecznościowy. Nie jest powiązany z Grenton Sp. z o.o., nie jest przez tę firmę wspierany, zatwierdzony ani firmowany. Odwołania do Grenton, CLU i Object Manager służą wyłącznie opisaniu kompatybilności oraz kontekstu technicznego. Wszystkie nazwy własne i ewentualne znaki towarowe pozostają własnością ich właścicieli.