Files

T

Mateusz Gruszczyński e6c6855922 GREE Controller 0.13.9

2026-09-10 07:27:33 +02:00

5.8 KiB

Raw Blame History

GREE Controller — Home Assistant add-on

Repozytorium: https://git.linuxiarz.pl/gru/gree-controller-ha-addon/
Obraz OCI: zot.linuxiarz.pl/gree-controller:<version>

PL

Instalacja

W Home Assistant dodaj jako własne repozytorium:

https://git.linuxiarz.pl/gru/gree-controller-ha-addon/

Odśwież sklep dodatków/aplikacji i zainstaluj GREE Controller. config.yaml wskazuje gotowy wieloarchitekturowy obraz OCI; jego tag musi być równy polu version.

Sieć, VLAN i discovery

Dodatek celowo używa host_network: true, więc korzysta bezpośrednio z interfejsów hosta Home Assistant OS. Nie twórz dla niego Docker macvlan.

Interfejsy hosta:

ha network info

Przykład VLAN 50 na eth0, bez dodatkowej bramy domyślnej:

ha network vlan eth0 50 \
  --ipv4-method static \
  --ipv4-address 192.168.50.2/24 \
  --ipv6-method disabled

Dla jednej sieci GREE ustaw gree_interface na nazwę interfejsu (np. eth0.50) albo jego lokalny IPv4 (np. 192.168.50.2) oraz discovery_broadcast na broadcast tej podsieci, np. 192.168.50.255:7000.

Dla wielu bezpośrednio podłączonych podsieci pozostaw gree_interface puste. Kontroler dobiera lokalny interfejs najlepiej pasujący do IP znanego urządzenia. Discovery nadal wysyła jeden broadcast na skan, więc każdą podsieć/VLAN skanuj osobno, zmieniając discovery_broadcast, albo dodaj znane urządzenia ręcznie.

Broadcast zwykle nie przechodzi przez router. Sterowanie unicast może działać przez routing/firewall, jeżeli UDP jest dozwolone. Gdy urządzenia są w routowanym VLAN-ie, zapewnij hostowi HA interfejs w tej sieci, relay broadcast UDP albo wykonuj discovery lokalnie dla każdej podsieci.

Opcje

Opcja	Znaczenie
`gree_interface`	interfejs lub lokalny IPv4; puste = automatyczny dobór trasy
`discovery_broadcast`	cel discovery UDP, np. `192.168.50.255:7000`
`simulate`	praca bez fizycznych urządzeń
`auto_seed`	przykładowe urządzenie w pustej bazie symulatora
`poll_interval_seconds`	interwał odpytywania urządzeń
`zone_interval_seconds`	interwał sterowania strefami/termostatem
`discovery_timeout_ms`	timeout discovery UDP
`app_token`	opcjonalna ochrona bezpośredniego Web UI/API
`log_level`	`error`, `warn`, `info`, `debug`, `trace`

Dostęp, dane i bezpieczeństwo

Usługa słucha na TCP 8787; ingress Home Assistant przekazuje Web UI na ten port. Jeżeli 8787 jest osiągalny z niezaufanej sieci, ustaw app_token albo zablokuj port firewallem. Baza jest zapisywana w /data/gree-controller.db; konfiguracja używa backup: cold, więc dane są objęte backupem dodatku.

Watchdog sprawdza /api/health. Do diagnostyki sieci najpierw sprawdź ha network info, poprawność gree_interface, broadcast konkretnej podsieci i reguły UDP/firewalla.

EN

Installation

Add this custom repository in Home Assistant:

https://git.linuxiarz.pl/gru/gree-controller-ha-addon/

Refresh the app/add-on store and install GREE Controller. config.yaml points to a pre-built multi-architecture OCI image; its tag must match version.

Networking, VLANs and discovery

The add-on intentionally uses host_network: true, so it uses the Home Assistant OS host interfaces directly. Do not attach a Docker macvlan network to the add-on.

Inspect host interfaces with:

ha network info

Example VLAN 50 on eth0, without adding another default gateway:

ha network vlan eth0 50 \
  --ipv4-method static \
  --ipv4-address 192.168.50.2/24 \
  --ipv6-method disabled

For one GREE subnet, set gree_interface to the host interface name (for example eth0.50) or its local IPv4 address (for example 192.168.50.2), and set discovery_broadcast to that subnet broadcast, e.g. 192.168.50.255:7000.

For multiple directly attached subnets, leave gree_interface empty. The controller selects the local interface that best matches a known device IP. Discovery still sends one broadcast per scan, so scan each VLAN/subnet separately by changing discovery_broadcast, or add known devices manually.

Broadcast normally does not cross routers. Unicast control may work through routing/firewall rules when UDP is allowed. For routed GREE VLANs, give the HA host an interface in the VLAN, use a suitable UDP broadcast relay, or perform discovery locally per subnet.

Options

Option	Meaning
`gree_interface`	interface or local IPv4; empty = automatic route selection
`discovery_broadcast`	UDP discovery target, e.g. `192.168.50.255:7000`
`simulate`	run without physical devices
`auto_seed`	create a sample device in an empty simulator database
`poll_interval_seconds`	device polling interval
`zone_interval_seconds`	thermostat/zone control interval
`discovery_timeout_ms`	UDP discovery timeout
`app_token`	optional protection for direct Web UI/API access
`log_level`	`error`, `warn`, `info`, `debug`, `trace`

Access, data and security

The service listens on TCP 8787; Home Assistant ingress proxies the Web UI to that port. If 8787 is reachable from an untrusted network, configure app_token or block the port at the firewall. The database is stored in /data/gree-controller.db; backup: cold keeps it in the add-on backup.

The watchdog checks /api/health. For network troubleshooting, verify ha network info, gree_interface, the selected subnet broadcast, and UDP/firewall rules first.

5.8 KiB Raw Blame History