65 lines
3.4 KiB
Markdown
65 lines
3.4 KiB
Markdown
# GREE Controller - Home Assistant add-on
|
|
|
|
## Installation
|
|
|
|
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`.
|
|
|
|
## Topology diagrams
|
|
|
|
### English
|
|
|
|
|
|
|
|
### Polish
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
Configure physical NICs and VLANs on Home Assistant OS first. Check the current host interfaces with:
|
|
|
|
```bash
|
|
ha network info
|
|
```
|
|
|
|
Example VLAN 50 on `eth0`, without adding another default gateway:
|
|
|
|
```bash
|
|
ha network vlan eth0 50 \
|
|
--ipv4-method static \
|
|
--ipv4-address 192.168.50.2/24 \
|
|
--ipv6-method disabled
|
|
```
|
|
|
|
Then use one of these add-on configurations:
|
|
|
|
### One dedicated GREE interface
|
|
|
|
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`.
|
|
|
|
### Several host interfaces / several directly attached subnets
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Do not use `discovery_broadcast=auto` when `gree_interface` is empty; automatic broadcast calculation needs an explicitly selected interface.
|
|
|
|
## Routed VLANs
|
|
|
|
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.
|