GREE Controller - Home Assistant add-on

Everything related to the Home Assistant add-on lives in this directory: build, OCI publishing, custom repository, VLAN/multi-interface docs and diagrams.

Topology / topologia

PL

EN

Minimal versioning

There is only one manually maintained version: package.version in the project root Cargo.toml.

[package]
version = "X.Y.Z"

Do not set a version in .env and do not create architecture-specific release tags. ./build.sh automatically:

reads the version from Cargo.toml,
synchronizes the root package entry in Cargo.lock,
writes the same version to https://git.linuxiarz.pl/gru/gree-controller-ha-addon/gree-controller/config.yaml,
builds linux/amd64 and linux/arm64,
publishes one multi-arch OCI manifest: REGISTRY/IMAGE_NAME:<version>.

So a release version is changed in one place only.

Configure build

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

Example:

REGISTRY=zot.linuxiarz.pl
IMAGE_NAME=gree-controller
DISTRO=trixie

Supported base images:

DISTRO=trixie - Debian Trixie builder + debian:trixie-slim runtime
DISTRO=alpine - latest Alpine builder + runtime

Registry authentication, when required:

docker login zot.linuxiarz.pl

Build and publish

Publish one multi-arch image for Home Assistant:

./build.sh push

Result:

zot.linuxiarz.pl/gree-controller:X.Y.Z
  ├─ linux/amd64
  └─ linux/arm64

No -amd64, -aarch64, -trixie, -alpine or latest release tags are required.

Local single-architecture test:

./build.sh load amd64
# or
./build.sh load aarch64

The local test image is always tagged REGISTRY/IMAGE_NAME:local.

Only refresh Home Assistant repository metadata:

./build.sh render

Home Assistant network model

The add-on uses host_network: true. VLANs and physical/logical interfaces are configured on Home Assistant OS, not created as Docker macvlan networks inside the add-on.

Recommended model:

configure NICs/VLANs on HA OS,
let the add-on share host networking,
set gree_interface to a specific host interface/IP for one GREE subnet,
leave gree_interface empty for automatic per-device routing across several directly attached subnets,
run UDP broadcast discovery separately for each VLAN/subnet.

Detailed documentation:

NETWORKING.md - PL
NETWORKING.en.md - EN
https://git.linuxiarz.pl/gru/gree-controller-ha-addon/gree-controller/DOCS.pl.md - PL add-on docs
https://git.linuxiarz.pl/gru/gree-controller-ha-addon/gree-controller/DOCS.md - EN add-on docs

Publish the custom repository

Publish ha-addon/repository/ as a Git repository and add its URL in the Home Assistant add-on/app store as a custom repository. The generated config.yaml points Home Assistant at the same OCI repository and version taken from Cargo.toml.

3.1 KiB Raw Blame History