Sieć#

vCLU nasłuchuje na kilku portach i protokołach. Konfiguracja sieci odbywa się przez flagi startowe i ustawienia w .vclu.json.

Porty i protokoły#

Usługa	Port	Protokół	Uwierzytelnianie
Panel webowy / REST API	8080 (konfigurowalne `--web-port`)	HTTP	Sesja cookie
Grenton CLU	1234	UDP	AES-128-CBC
TFTP	69	UDP/TFTP	Brak
Broker MQTT (wbudowany)	1883 (konfigurowalne)	TCP	Opcjonalnie user/pass
MQTT WebSocket	konfigurowalne	WS	Opcjonalnie user/pass
HomeKit Bridge	5123 (domyślnie)	TCP	Protokół HomeKit
Prometheus `/metrics`	8080	HTTP	Przez middleware auth

Port panelu webowego zmienia się flagą --web-port. Porty MQTT i HomeKit konfiguruje się w .vclu.json (przez panel webowy w zakładce Ustawienia).

Wybór interfejsu sieciowego#

vCLU musi znać swój adres IP — używa go do komunikacji UDP z urządzeniami Grenton, rozgłaszania w sieci i mDNS (HomeKit). Interfejs wybierasz flagą startową:

Flaga	Opis	Przykład
`--auto`	Automatyczny wybór pierwszego interfejsu non-loopback z adresem IPv4	`./vclu --auto`
`--interface <nazwa>`	Wybór po nazwie interfejsu	`./vclu --interface eth0`
`--ip <adres>`	Wybór po adresie IP	`./vclu --ip 192.168.1.100`
`--list`	Wyświetl dostępne interfejsy i zakończ	`./vclu --list`

Tryb --auto jest domyślny i sprawdza się w większości przypadków. Użyj --interface lub --ip, gdy urządzenie ma wiele interfejsów sieciowych (np. Ethernet + Wi-Fi).

# Sprawdź dostępne interfejsy
./vclu --list

# Uruchom na konkretnym interfejsie
./vclu --interface eth0

# Uruchom na konkretnym IP
./vclu --ip 192.168.1.100

Wbudowany broker MQTT#

vCLU zawiera wbudowany broker MQTT (oparty na Mochi MQTT). Konfiguracja w .vclu.json, zarządzana przez panel webowy:

Parametr	Opis
Port TCP	Port nasłuchiwania brokera (domyślnie 1883)
Port WebSocket	Port WS dla klientów przeglądarkowych (opcjonalny)
Użytkownik / Hasło	Opcjonalne uwierzytelnianie klientów MQTT

Broker uruchamia się automatycznie. Możesz też użyć zewnętrznego brokera MQTT — w takim przypadku wyłącz wbudowany i skonfiguruj adres zewnętrznego.

Docker#

Uruchamianie vCLU w Dockerze wymaga trybu --network host:

docker run --network host vclu:latest

Powód: vCLU używa broadcast UDP do wykrywania urządzeń Grenton oraz mDNS do rozgłaszania HomeKit. Oba mechanizmy wymagają bezpośredniego dostępu do sieci hosta — mapowanie portów (-p) nie wystarczy.

Bez --network host urządzenia Grenton nie wykryją vCLU w sieci, a HomeKit nie będzie widoczny w aplikacji Dom.

Systemd#

Instalacja produkcyjna (przez install.sh) tworzy plik vclu.service z wymaganymi uprawnieniami:

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_BROADCAST

Capability	Powód
`CAP_NET_BIND_SERVICE`	Nasłuchiwanie na portach < 1024 (TFTP na porcie 69)
`CAP_NET_BROADCAST`	Wysyłanie pakietów broadcast UDP (discovery Grenton)

Dzięki temu vCLU działa jako zwykły użytkownik (nie root), zachowując dostęp do wymaganych portów.

Firewall#

Jeśli na urządzeniu działa firewall, upewnij się, że przepuszcza ruch na portach używanych przez vCLU. Minimalna konfiguracja dla ufw:

sudo ufw allow 8080/tcp   # Panel webowy
sudo ufw allow 1234/udp   # Grenton CLU
sudo ufw allow 69/udp     # TFTP
sudo ufw allow 1883/tcp   # MQTT

W typowej instalacji na Raspberry Pi w sieci domowej firewall nie jest konieczny. Konfiguruj go, jeśli vCLU działa w bardziej złożonym środowisku sieciowym.