GREE Controller — Home Assistant distribution

This directory contains the OCI build, Home Assistant add-on repository source, custom integration and repository synchronization tooling.

The packaged controller includes its HTTP/WebSocket API and built-in Swagger documentation at /api-docs (/api-docs/openapi.json for OpenAPI 3.1).

Configuration

Create the local build/repository configuration once:

cd ha-addon
cp .env.example .env
$EDITOR .env

build.sh and sync-repository.sh read all deployment-specific values from .env; .env is ignored by Git.

Important variables:

REGISTRY=repo.example.com
IMAGE_NAME=gree-controller
DISTRO=alpine
RUST_VERSION=1.98.1
BUILD_PLATFORMS=linux/amd64,linux/arm64
BUILDER=gree-controller-multiarch
BUILDER_CONFIG=
HA_REPO_URL=https://repo.example.com/gree-controller-ha-addon/
HA_REPO_BRANCH=master
HA_REPO_PATH=../gree-controller-ha-addon
ADDON_DIR=gree-controller
INTEGRATION_DOMAIN=gree_controller

OCI image

./build.sh render
./build.sh load amd64
./build.sh load aarch64
./build.sh push

The project version comes only from root Cargo.toml. render synchronizes it to add-on config.yaml and the custom integration manifest.json, and sets the OCI image from .env. The container build generates Cargo.lock from the exact direct dependency versions in Cargo.toml before fetching and compiling dependencies.

For the Home Assistant package, TCP 8787 is an intentional fixed host-network/ingress port contract. build.sh render verifies config.yaml, run.sh, the watchdog URL and Docker image metadata stay consistent. The runtime also compares the Supervisor-reported ingress port before starting. Standalone installations remain free to use any GREE_CONTROLLER_BIND port.

DISTRO still selects the target image system: alpine builds a musl binary for Alpine and trixie builds a GNU/glibc binary for Debian Trixie. Multi-architecture builds continue to run through build.sh; the Docker builder cross-compiles Rust on BUILDPLATFORM so ARM compilation does not run under QEMU, and BuildKit cache mounts preserve Cargo downloads and target artifacts between builds.

Home Assistant repository

./sync-repository.sh

The command updates/clones HA_REPO_URL, mirrors the repository and pushes only when content changed. The resulting repository contains:

repository.yaml
gree-controller/                    # Home Assistant add-on
custom_components/gree_controller/  # Home Assistant custom integration

The custom integration source is maintained only in:

ha-addon/home-assistant/custom_components/gree_controller/

It is added to the separate HA repository during synchronization, so it is not duplicated in this project.

Adding the repository to the Home Assistant add-on store installs the add-on only. The bundled custom integration can be copied from the same repository to /config/custom_components/gree_controller/ when required.

Layout

.env.example          local deployment configuration template
Dockerfile            multi-architecture image
build.sh              metadata + OCI build/push
run.sh                add-on entrypoint
sync-repository.sh    separate HA repository synchronization
repository/           add-on repository source
home-assistant/       custom integration source and migration output