117 lines
3.1 KiB
Markdown
117 lines
3.1 KiB
Markdown
# 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`.
|
|
|
|
```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`.
|