GREE Controller 0.13.9
This commit is contained in:
Mateusz Gruszczyński
@@ -1,12 +1,8 @@
|
|||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
Release version is maintained only in the project root `Cargo.toml`. Home Assistant metadata is generated by `ha-addon/build.sh` / `ha-addon/render-repository.sh`.
|
## 0.13.9
|
||||||
|
|
||||||
## Current
|
- Home Assistant add-on with `amd64` + `aarch64` multi-arch OCI image.
|
||||||
|
- Host networking for GREE UDP discovery and multi-interface/VLAN hosts.
|
||||||
- Home Assistant add-on packaging.
|
- Home Assistant ingress, watchdog and cold backup support.
|
||||||
- amd64 and aarch64 in one OCI multi-arch manifest.
|
- Polish and English documentation consolidated into one `DOCS.md`.
|
||||||
- Host-network operation for GREE UDP discovery and multi-interface hosts.
|
|
||||||
- Home Assistant ingress support.
|
|
||||||
- Polish and English topology diagrams and networking documentation.
|
|
||||||
- Debian Trixie or latest Alpine build/runtime target.
|
|
||||||
|
|||||||
+94
-32
@@ -1,26 +1,90 @@
|
|||||||
# GREE Controller - Home Assistant add-on
|
# GREE Controller — Home Assistant add-on
|
||||||
|
|
||||||
## Installation
|
Repozytorium: `https://git.linuxiarz.pl/gru/gree-controller-ha-addon/`
|
||||||
|
Obraz OCI: `zot.linuxiarz.pl/gree-controller:<version>`
|
||||||
|
|
||||||
Publish the `ha-addon/repository` directory as a Git repository. In Home Assistant open the app/add-on store, add that Git repository URL as a custom repository, refresh the store and install **GREE Controller**.
|
---
|
||||||
|
|
||||||
The repository metadata points to a pre-built multi-architecture OCI image. The image tag must be identical to `version` in `config.yaml`.
|
## PL
|
||||||
|
|
||||||
## Topology diagrams
|
### Instalacja
|
||||||
|
|
||||||
### English
|
W Home Assistant dodaj jako własne repozytorium:
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://git.linuxiarz.pl/gru/gree-controller-ha-addon/
|
||||||
|
```
|
||||||
|
|
||||||
### Polish
|
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
|
||||||
|
|
||||||
## Network model
|
|
||||||
|
|
||||||
The add-on deliberately uses `host_network: true`. Do not attach Docker `macvlan` networks to the add-on. With host networking, the controller shares the Home Assistant host network namespace and sees host ethernet/VLAN interfaces directly.
|
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`.
|
||||||
|
|
||||||
Configure physical NICs and VLANs on Home Assistant OS first. Check the current host interfaces with:
|
Interfejsy hosta:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ha network info
|
||||||
|
```
|
||||||
|
|
||||||
|
Przykład VLAN 50 na `eth0`, bez dodatkowej bramy domyślnej:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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:
|
||||||
|
|
||||||
|
```text
|
||||||
|
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:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ha network info
|
ha network info
|
||||||
@@ -35,30 +99,28 @@ ha network vlan eth0 50 \
|
|||||||
--ipv6-method disabled
|
--ipv6-method disabled
|
||||||
```
|
```
|
||||||
|
|
||||||
Then use one of these add-on configurations:
|
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`.
|
||||||
|
|
||||||
### One dedicated GREE interface
|
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.
|
||||||
|
|
||||||
Set `gree_interface` to the host interface name, for example `eth0.50`, or to its local IPv4 address, for example `192.168.50.2`. Set `discovery_broadcast` to the subnet broadcast, for example `192.168.50.255:7000`.
|
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.
|
||||||
|
|
||||||
### Several host interfaces / several directly attached subnets
|
### Options
|
||||||
|
|
||||||
Leave `gree_interface` empty. For already known devices the controller chooses the local IPv4 interface whose subnet best matches the device IP. This allows normal polling and commands to devices on different directly attached networks.
|
| 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` |
|
||||||
|
|
||||||
Discovery itself sends one broadcast target per scan. To discover devices on several VLANs, scan each subnet separately by supplying its broadcast address (for example `192.168.50.255:7000`, then `192.168.60.255:7000`) or add known devices manually. After discovery, normal traffic can use automatic per-target interface selection.
|
### Access, data and security
|
||||||
|
|
||||||
Do not use `discovery_broadcast=auto` when `gree_interface` is empty; automatic broadcast calculation needs an explicitly selected interface.
|
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.
|
||||||
|
|
||||||
## Routed VLANs
|
The watchdog checks `/api/health`. For network troubleshooting, verify `ha network info`, `gree_interface`, the selected subnet broadcast, and UDP/firewall rules first.
|
||||||
|
|
||||||
Unicast UDP commands can traverse routing/firewall rules if permitted. Discovery is broadcast-based and normally does not cross a router. Either give the Home Assistant host an interface in the GREE VLAN, use a suitable UDP broadcast relay, or discover/add devices from each local subnet explicitly.
|
|
||||||
|
|
||||||
## Docker limitations
|
|
||||||
|
|
||||||
Home Assistant add-on configuration supports host networking, but not arbitrary user-defined Docker networks/macvlan attachments. Giving an add-on Docker API/full host access just to create extra container interfaces is unnecessary here and would substantially weaken isolation. Configure the VLANs/NICs on the HA OS host and let this add-on share them through host networking.
|
|
||||||
|
|
||||||
## Direct access and ingress
|
|
||||||
|
|
||||||
The service listens on TCP 8787 because the same host network is needed for GREE UDP. Home Assistant ingress proxies the Web UI to that port. If TCP 8787 is reachable from untrusted networks, configure `app_token` or block that port at the network/firewall boundary.
|
|
||||||
|
|
||||||
The standalone Home Assistant custom integration can still use the controller API exactly as before; point it at an address that Home Assistant Core can reach and use an integration token generated by GREE Controller.
|
|
||||||
|
|||||||
@@ -1,64 +0,0 @@
|
|||||||
# GREE Controller - dodatek Home Assistant
|
|
||||||
|
|
||||||
## Instalacja
|
|
||||||
|
|
||||||
Opublikuj katalog `ha-addon/repository` jako repozytorium Git. W Home Assistant otwórz sklep dodatków/aplikacji, dodaj URL tego repozytorium jako repozytorium niestandardowe, odśwież listę i zainstaluj **GREE Controller**.
|
|
||||||
|
|
||||||
Metadane repozytorium wskazują na gotowy wieloarchitekturny obraz OCI. Tag obrazu musi być taki sam jak `version` w `config.yaml`.
|
|
||||||
|
|
||||||
## Diagramy topologii
|
|
||||||
|
|
||||||
### Polski
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### English
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Model sieciowy
|
|
||||||
|
|
||||||
Dodatek celowo używa `host_network: true`. Nie podpinaj do dodatku sieci Docker `macvlan`. Przy host networking kontroler współdzieli przestrzeń sieciową hosta Home Assistanta i widzi bezpośrednio interfejsy ethernet/VLAN hosta.
|
|
||||||
|
|
||||||
Najpierw skonfiguruj fizyczne NIC-i i VLAN-y w Home Assistant OS. Aktualne interfejsy hosta sprawdzisz poleceniem:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ha network info
|
|
||||||
```
|
|
||||||
|
|
||||||
Przykład VLAN 50 na `eth0`, bez dodawania kolejnej domyślnej bramy:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ha network vlan eth0 50 \
|
|
||||||
--ipv4-method static \
|
|
||||||
--ipv4-address 192.168.50.2/24 \
|
|
||||||
--ipv6-method disabled
|
|
||||||
```
|
|
||||||
|
|
||||||
Następnie użyj jednej z tych konfiguracji dodatku:
|
|
||||||
|
|
||||||
### Jeden dedykowany interfejs GREE
|
|
||||||
|
|
||||||
Ustaw `gree_interface` na nazwę interfejsu hosta, np. `eth0.50`, albo na jego lokalny adres IPv4, np. `192.168.50.2`. Ustaw `discovery_broadcast` na broadcast tej podsieci, np. `192.168.50.255:7000`.
|
|
||||||
|
|
||||||
### Kilka interfejsów hosta / kilka bezpośrednio podłączonych podsieci
|
|
||||||
|
|
||||||
Pozostaw `gree_interface` puste. Dla znanych urządzeń kontroler wybiera lokalny interfejs IPv4, którego podsieć najlepiej pasuje do adresu IP urządzenia. Dzięki temu normalne odpytywanie i sterowanie działa dla urządzeń w różnych bezpośrednio podłączonych sieciach.
|
|
||||||
|
|
||||||
Samo discovery wysyła jeden broadcast na skan. Aby wykrywać urządzenia w kilku VLAN-ach, skanuj każdą podsieć osobno, podając jej adres broadcast (np. `192.168.50.255:7000`, potem `192.168.60.255:7000`) albo dodaj znane urządzenia ręcznie. Po discovery zwykły ruch może działać z automatycznym doborem interfejsu dla celu.
|
|
||||||
|
|
||||||
Nie używaj `discovery_broadcast=auto`, gdy `gree_interface` jest puste; automatyczne wyliczenie broadcastu wymaga jawnie wybranego interfejsu.
|
|
||||||
|
|
||||||
## VLAN-y routowane
|
|
||||||
|
|
||||||
Polecenia unicast UDP mogą przechodzić przez routing/reguły firewalla, jeśli jest to dozwolone. Discovery jest oparte na broadcast i zwykle nie przechodzi przez router. Albo daj hostowi Home Assistant interfejs w VLAN-ie GREE, albo użyj odpowiedniego relaya UDP broadcast, albo wykrywaj/dodawaj urządzenia osobno z każdej lokalnej podsieci.
|
|
||||||
|
|
||||||
## Ograniczenia Dockera
|
|
||||||
|
|
||||||
Konfiguracja dodatków Home Assistant wspiera host networking, ale nie dowolne, własne sieci Docker/macvlan przypinane do dodatku. Nadawanie dodatkowi pełnego dostępu do hosta lub API Dockera tylko po to, aby tworzyć dodatkowe interfejsy kontenera, nie jest tu potrzebne i znacząco osłabia izolację. Skonfiguruj VLAN-y/NIC-e na hoście HA OS i pozwól temu dodatkowi współdzielić je przez host networking.
|
|
||||||
|
|
||||||
## Bezpośredni dostęp i ingress
|
|
||||||
|
|
||||||
Usługa nasłuchuje na TCP 8787, ponieważ ten sam host network jest potrzebny dla GREE UDP. Home Assistant ingress proxy przekazuje Web UI na ten port. Jeżeli TCP 8787 jest osiągalny z niezaufanych sieci, skonfiguruj `app_token` albo zablokuj ten port na granicy sieci/firewalla.
|
|
||||||
|
|
||||||
Samodzielna integracja Home Assistant może nadal używać API kontrolera jak wcześniej; wskaż adres osiągalny z Home Assistant Core i użyj tokenu integracji wygenerowanego przez GREE Controller.
|
|
||||||
@@ -1,35 +1,11 @@
|
|||||||
# GREE Controller
|
# GREE Controller
|
||||||
|
|
||||||
Local GREE HVAC controller packaged as a Home Assistant add-on. It uses `host_network: true` so UDP discovery and the host VLAN/ethernet interfaces are directly available to the controller. Persistent data is stored in `/data/gree-controller.db` and is included in Home Assistant backups.
|
Local GREE HVAC controller packaged as a Home Assistant add-on, with Web UI, local API, UDP discovery/control, `amd64` and `aarch64` support, ingress, and database backup from `/data/gree-controller.db`.
|
||||||
|
|
||||||
## PL - topologia HA / VLAN / GREE
|
|
||||||
|
|
||||||
|
For VLAN deployments, configure VLAN interfaces on the Home Assistant OS host. The add-on uses `host_network: true`; with multiple directly attached subnets, `gree_interface` may remain empty. Run broadcast discovery separately for each VLAN/subnet.
|
||||||
|
|
||||||
Najważniejsze:
|
|
||||||
|
|
||||||
- VLAN-y konfigurujesz na hoście Home Assistant OS,
|
|
||||||
- dodatek współdzieli interfejsy hosta przez `host_network`,
|
|
||||||
- nie trzeba tworzyć Docker `macvlan`,
|
|
||||||
- przy wielu bezpośrednio podłączonych podsieciach `gree_interface` może pozostać puste,
|
|
||||||
- discovery UDP broadcast wykonuj osobno dla każdego VLAN-u/podsieci.
|
|
||||||
|
|
||||||
Pełna dokumentacja: [DOCS.pl.md](./DOCS.pl.md).
|
|
||||||
|
|
||||||
## EN - HA / VLAN / GREE topology
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Key points:
|
|
||||||
|
|
||||||
- configure VLANs on the Home Assistant OS host,
|
|
||||||
- the add-on shares host interfaces via `host_network`,
|
|
||||||
- Docker `macvlan` is not required,
|
|
||||||
- with multiple directly attached subnets `gree_interface` may be left empty,
|
|
||||||
- run UDP broadcast discovery separately for each VLAN/subnet.
|
|
||||||
|
|
||||||
Full documentation: [DOCS.md](./DOCS.md).
|
Full documentation: [DOCS.md](./DOCS.md).
|
||||||
|
|
||||||
## Versioning
|
Repository: https://git.linuxiarz.pl/gru/gree-controller-ha-addon/
|
||||||
|
|
||||||
The project version is maintained only in the root `Cargo.toml`. The build script copies it into the Home Assistant `config.yaml` and publishes one `amd64 + aarch64` OCI manifest under that version. No separate architecture release tags are used.
|
|
||||||
|
|||||||
@@ -2,6 +2,7 @@ name: "GREE Controller"
|
|||||||
version: "0.13.9"
|
version: "0.13.9"
|
||||||
slug: "gree_controller"
|
slug: "gree_controller"
|
||||||
description: "Local GREE HVAC controller with Web UI and Home Assistant integration"
|
description: "Local GREE HVAC controller with Web UI and Home Assistant integration"
|
||||||
|
url: "https://git.linuxiarz.pl/gru/gree-controller-ha-addon/"
|
||||||
arch:
|
arch:
|
||||||
- amd64
|
- amd64
|
||||||
- aarch64
|
- aarch64
|
||||||
|
|||||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 MiB After Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 MiB After Width: | Height: | Size: 1.4 MiB |
@@ -1,2 +1,3 @@
|
|||||||
name: GREE Controller
|
name: GREE Controller
|
||||||
|
url: https://git.linuxiarz.pl/gru/gree-controller-ha-addon/
|
||||||
maintainer: linuxiarz.pl
|
maintainer: linuxiarz.pl
|
||||||
|
|||||||
Reference in New Issue
Block a user