# 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

![Topologia Home Assistant OS + GREE Controller + VLAN](./docs/topologia-ha-vlan-gree-pl.png)

### EN

![Home Assistant OS + GREE Controller + VLAN topology](./docs/topology-ha-vlan-gree-en.png)

## Minimal versioning

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

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

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

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

So a release version is changed in one place only.

## Configure build

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

Example:

```dotenv
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:

```bash
docker login zot.linuxiarz.pl
```

## Build and publish

Publish one multi-arch image for Home Assistant:

```bash
./build.sh push
```

Result:

```text
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:

```bash
./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:

```bash
./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`.