v0.13.9-ha_addon

2026-09-09 15:19:10 +02:00
parent 4196fbe0ef
commit fa0d4d0754
32 changed files with 1941 additions and 30 deletions
@@ -0,0 +1,116 @@
+# 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`.