3.4 KiB
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:
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
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.