v0.13.9-rework_ha_addon

2026-09-10 08:24:53 +02:00
parent b905a6fcc4
commit 34e62da372
45 changed files with 405 additions and 1597 deletions
@@ -1,37 +1,10 @@
-# GREE Controller - Home Assistant add-on
+# GREE Controller — Home Assistant distribution

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

-## Topology / topologia
+## Configuration

-### 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
+Create the local build/repository configuration once:

 ```bash
 cd ha-addon
@@ -39,78 +12,68 @@ cp .env.example .env
 $EDITOR .env
 ```

-Example:
+`build.sh` and `sync-repository.sh` read all deployment-specific values from `.env`; `.env` is ignored by Git.
+
+Important variables:

 ```dotenv
-REGISTRY=zot.linuxiarz.pl
+REGISTRY=repo.example.com
 IMAGE_NAME=gree-controller
-DISTRO=trixie
+DISTRO=alpine
+RUST_VERSION=1.89
+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
 ```

-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:
+## OCI image

 ```bash
 ./build.sh render
+./build.sh load amd64
+./build.sh load aarch64
+./build.sh push
 ```

-## Home Assistant network model
+The project version comes only from root `Cargo.toml`. `render` synchronizes it to `Cargo.lock`, add-on `config.yaml` and the custom integration `manifest.json`, and sets the OCI image from `.env`.

-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.
+## Home Assistant repository

-Recommended model:
+```bash
+./sync-repository.sh
+```

- 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.
+The command updates/clones `HA_REPO_URL`, mirrors the repository and pushes only when content changed. The resulting repository contains:

-Detailed documentation:
+```text
+repository.yaml
+gree-controller/                    # Home Assistant add-on
+custom_components/gree_controller/  # Home Assistant custom integration
+```

- `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
+The custom integration source is maintained only in:

-## Publish the custom repository
+```text
+ha-addon/home-assistant/custom_components/gree_controller/
+```

-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`.
+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
+
+```text
+.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
+```