gree-controller/ha_addon.md

# GREE Controller - Home Assistant Add-on

This file contains the installation and release procedure in **Polish** and **English**.

---

# PL - Instalacja dodatku Home Assistant

## 1. Wymagania

Na maszynie, na której budujesz obrazy, potrzebujesz:

- Docker
- Docker Buildx
- dostępu do registry OCI, np. `zot.example.com` albo `oci.example.com`
- repozytorium Git dostępnego z Home Assistanta

Sprawdź:

```bash
docker --version
docker buildx version
```

## 2. Wejdź do katalogu dodatku

Z katalogu głównego projektu:

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

Edytuj `.env`:

```bash
nano .env
```

Przykład dla Zot:

```dotenv
REGISTRY=zot.example.com
IMAGE_NAME=gree-controller
DISTRO=trixie
BUILDER=gree-controller-multiarch
BUILDER_CONFIG=
```

Obsługiwane systemy bazowe:

- `DISTRO=trixie` - zalecany wariant Debian Trixie
- `DISTRO=alpine` - wariant Alpine

Na początek zalecany jest `trixie`.

## 3. Logowanie do registry

Jeżeli registry wymaga autoryzacji:

```bash
docker login zot.example.com
```

Po poprawnym logowaniu powinno pojawić się:

```text
Login Succeeded
```

## 4. Wersjonowanie

Wersję zmieniasz tylko w jednym miejscu:

```text
Cargo.toml
```

Przykład:

```toml
[package]
version = "0.13.9"
```

Przy kolejnym wydaniu zmień tylko:

```toml
version = "0.13.10"
```

Nie zmieniaj ręcznie wersji w:

- `Cargo.lock`
- `ha-addon/repository/gree-controller/config.yaml`

Skrypt `build.sh` synchronizuje te pliki automatycznie.

## 5. Włącz build ARM64 przez QEMU

Jeżeli host budujący jest `amd64`, zainstaluj emulację binfmt/QEMU:

```bash
docker run --privileged --rm tonistiigi/binfmt --install all
```

Sprawdź dostępne platformy:

```bash
docker buildx inspect --bootstrap
```

Jeżeli domyślny builder pokazuje tylko `amd64`, nie jest to problem. `build.sh` tworzy własny builder:

```text
gree-controller-multiarch
```

Po jego utworzeniu możesz sprawdzić go poleceniem:

```bash
docker buildx inspect gree-controller-multiarch --bootstrap
```

Powinny być dostępne co najmniej:

```text
linux/amd64
linux/arm64
```

Home Assistant używa nazwy architektury `aarch64`, natomiast Docker używa `linux/arm64`.

## 6. Build i push obrazu multi-arch

Będąc w katalogu:

```text
ha-addon/
```

uruchom:

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

Skrypt:

1. czyta wersję z `Cargo.toml`,
2. synchronizuje `Cargo.lock`,
3. aktualizuje `ha-addon/repository/gree-controller/config.yaml`,
4. buduje `linux/amd64`,
5. buduje `linux/arm64`,
6. publikuje jeden manifest multi-arch do registry.

Przykładowy wynik:

```text
zot.example.com/gree-controller:0.13.9
```

Nie musisz ręcznie utrzymywać osobnych wersji dla `amd64` i `arm64`.

## 7. Sprawdź obraz w registry

Po poprawnym buildzie:

```bash
docker buildx imagetools inspect \
  zot.example.com/gree-controller:0.13.9
```

Powinieneś zobaczyć:

```text
linux/amd64
linux/arm64
```

Możesz też sprawdzić pull dla bieżącej architektury:

```bash
docker pull zot.example.com/gree-controller:0.13.9
```

## 8. Jeżeli build kończy się błędem `docs/openapi.json`

Projekt korzysta podczas kompilacji z:

```text
src/api/openapi.rs -> ../../docs/openapi.json
```

Dockerfile musi więc kopiować katalog `docs` do etapu buildera:

```dockerfile
COPY docs ./docs
```

W tej wersji projektu jest to już poprawione dla `trixie` i `alpine`.

## 9. Przygotowanie repozytorium Home Assistant

Do Git publikujesz zawartość katalogu:

```text
ha-addon/repository/
```

Root repozytorium Git powinien wyglądać tak:

```text
repository.yaml
gree-controller/
├── config.yaml
├── README.md
├── DOCS.md
├── DOCS.pl.md
├── CHANGELOG.md
├── translations/
├── topology-ha-vlan-gree-en.png
└── topologia-ha-vlan-gree-pl.png
```

Przykład:

```bash
cd ha-addon/repository

git init -b main
git add .
git commit -m "Initial GREE Controller Home Assistant add-on"
```

Dodaj swoje repo Git:

```bash
git remote add origin \
  https://git.example.pl/mateusz/gree-controller-ha-addon.git

git push -u origin main
```

Home Assistant musi mieć dostęp do tego repozytorium Git.

## 10. Prywatne registry

Jeżeli obraz OCI nie jest publiczny, Home Assistant musi mieć możliwość zalogowania się do registry.

Jeżeli używasz prywatnego registry, dodaj dane dostępowe do registry w Home Assistant/Supervisor zgodnie z konfiguracją swojej instalacji.

Najprostszy wariant do pierwszego uruchomienia:

- Git repo może być publiczne lub dostępne dla HA,
- obraz może mieć anonymous pull,
- registry powinno działać po HTTPS z poprawnym certyfikatem.

## 11. Dodanie custom repository w Home Assistant

W Home Assistant otwórz sklep Apps/Add-ons i dodaj URL repozytorium Git jako custom repository.

Podajesz URL Git, np.:

```text
https://git.example.pl/mateusz/gree-controller-ha-addon.git
```

Nie podajesz:

- ZIP-a projektu,
- adresu obrazu OCI,
- adresu `zot.example.com/gree-controller`.

Podział jest następujący:

```text
Git repository
  -> opis dodatku i config.yaml

OCI/Zot registry
  -> gotowy obraz kontenera
```

## 12. Instalacja dodatku

Po dodaniu custom repository odśwież sklep dodatków.

Powinien pojawić się:

```text
GREE Controller
```

Kliknij:

```text
Install
```

Home Assistant odczyta np.:

```yaml
version: "0.13.9"
image: "zot.example.com/gree-controller"
```

i pobierze:

```text
zot.example.com/gree-controller:0.13.9
```

Manifest OCI automatycznie wybierze odpowiednią architekturę.

## 13. Konfiguracja jednej sieci/VLAN GREE

Przykład:

```text
eth0.50
192.168.50.2/24

GREE devices:
192.168.50.x
```

Konfiguracja dodatku:

```yaml
gree_interface: "eth0.50"
discovery_broadcast: "192.168.50.255:7000"
simulate: false
auto_seed: false
poll_interval_seconds: 15
zone_interval_seconds: 5
discovery_timeout_ms: 3000
app_token: ""
log_level: info
```

Zamiast nazwy interfejsu można podać lokalny IPv4:

```yaml
gree_interface: "192.168.50.2"
```

## 14. Kilka VLAN-ów / kilka interfejsów

Przykład:

```text
eth0
├── eth0.50 -> 192.168.50.2/24
└── eth0.60 -> 192.168.60.2/24
```

Dla automatycznego wyboru interfejsu pozostaw:

```yaml
gree_interface: ""
```

Dla znanych urządzeń kontroler dobiera interfejs do adresu docelowego.

Discovery UDP broadcast wykonuj osobno dla każdej podsieci.

VLAN 50:

```yaml
discovery_broadcast: "192.168.50.255:7000"
```

VLAN 60:

```yaml
discovery_broadcast: "192.168.60.255:7000"
```

Broadcast zwykle nie przechodzi przez router, dlatego discovery należy wykonywać per VLAN.

## 15. VLAN-y na Home Assistant OS

Sprawdź sieć:

```bash
ha network info
```

Przykład VLAN 50:

```bash
ha network vlan eth0 50 \
  --ipv4-method static \
  --ipv4-address 192.168.50.2/24 \
  --ipv6-method disabled
```

Przykład VLAN 60:

```bash
ha network vlan eth0 60 \
  --ipv4-method static \
  --ipv4-address 192.168.60.2/24 \
  --ipv6-method disabled
```

Następnie:

```bash
ha network info
```

Powinny być widoczne interfejsy podobne do:

```text
eth0
eth0.50
eth0.60
```

Jeżeli główny interfejs HA ma już default gateway, nie dodawaj bez potrzeby kolejnych bram domyślnych na VLAN-ach GREE.

## 16. Dlaczego `host_network`

Dodatek ma ustawione:

```yaml
host_network: true
```

Dzięki temu kontener korzysta z przestrzeni sieciowej hosta Home Assistant OS i widzi jego interfejsy/VLAN-y.

Nie trzeba tworzyć `macvlan` wewnątrz dodatku.

Schemat:

```text
Home Assistant OS
├── eth0
├── eth0.50
├── eth0.60
└── GREE Controller add-on
      └── host_network: true
           ├── VLAN 50 -> GREE A/B
           └── VLAN 60 -> GREE C/D
```

Diagramy znajdują się w:

```text
ha-addon/docs/topologia-ha-vlan-gree-pl.png
ha-addon/docs/topology-ha-vlan-gree-en.png
```

## 17. Uruchomienie i Web UI

Po instalacji uruchom dodatek i sprawdź logi.

Przykład:

```text
GREE Controller: interface=auto discovery=192.168.50.255:7000 database=/data/gree-controller.db
```

Web UI jest dostępne przez Home Assistant Ingress.

## 18. Aktualizacja dodatku

Przy nowym wydaniu:

### Krok 1 - zmień wersję tylko w `Cargo.toml`

```toml
version = "0.13.10"
```

### Krok 2 - build i push

```bash
cd ha-addon
./build.sh push
```

### Krok 3 - sprawdź manifest

```bash
docker buildx imagetools inspect \
  zot.example.com/gree-controller:0.13.10
```

### Krok 4 - wypchnij metadata repozytorium HA

```bash
cd repository
git add .
git commit -m "Release 0.13.10"
git push
```

### Krok 5 - aktualizacja w Home Assistant

Odśwież informacje o dodatkach i zainstaluj dostępną aktualizację.

Zalecana kolejność publikacji:

```text
1. zmiana Cargo.toml
2. ./build.sh push
3. sprawdzenie obrazu OCI
4. git commit/push ha-addon/repository
5. update w Home Assistant
```

Dzięki temu Home Assistant nie zobaczy nowej wersji zanim obraz będzie dostępny w registry.

---

# EN - Home Assistant Add-on installation

## 1. Requirements

The build machine needs:

- Docker
- Docker Buildx
- access to an OCI registry such as `zot.example.com` or `oci.example.com`
- a Git repository reachable by Home Assistant

Check:

```bash
docker --version
docker buildx version
```

## 2. Enter the add-on directory

From the project root:

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

Edit `.env`:

```bash
nano .env
```

Example for Zot:

```dotenv
REGISTRY=zot.example.com
IMAGE_NAME=gree-controller
DISTRO=trixie
BUILDER=gree-controller-multiarch
BUILDER_CONFIG=
```

Supported base distributions:

- `DISTRO=trixie` - recommended Debian Trixie variant
- `DISTRO=alpine` - Alpine variant

Start with `trixie` unless you specifically need Alpine.

## 3. Log in to the registry

If authentication is required:

```bash
docker login zot.example.com
```

Expected result:

```text
Login Succeeded
```

## 4. Versioning

Change the application version in one place only:

```text
Cargo.toml
```

Example:

```toml
[package]
version = "0.13.9"
```

For the next release change only:

```toml
version = "0.13.10"
```

Do not manually maintain the version in:

- `Cargo.lock`
- `ha-addon/repository/gree-controller/config.yaml`

`build.sh` synchronizes these files automatically.

## 5. Enable ARM64 builds with QEMU

When building on an `amd64` host, install binfmt/QEMU support:

```bash
docker run --privileged --rm tonistiigi/binfmt --install all
```

Check platforms:

```bash
docker buildx inspect --bootstrap
```

If the default builder still lists only `amd64`, that is not a problem. `build.sh` creates its own builder named:

```text
gree-controller-multiarch
```

After it has been created, inspect it with:

```bash
docker buildx inspect gree-controller-multiarch --bootstrap
```

You should have at least:

```text
linux/amd64
linux/arm64
```

Home Assistant calls the ARM architecture `aarch64`, while Docker uses `linux/arm64`.

## 6. Build and push the multi-arch image

From:

```text
ha-addon/
```

run:

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

The script:

1. reads the version from `Cargo.toml`,
2. synchronizes `Cargo.lock`,
3. updates `ha-addon/repository/gree-controller/config.yaml`,
4. builds `linux/amd64`,
5. builds `linux/arm64`,
6. pushes one multi-architecture OCI manifest.

Example result:

```text
zot.example.com/gree-controller:0.13.9
```

There is no manual per-architecture version maintenance.

## 7. Verify the published image

After a successful build:

```bash
docker buildx imagetools inspect \
  zot.example.com/gree-controller:0.13.9
```

Expected platforms:

```text
linux/amd64
linux/arm64
```

You can also test a pull for the current machine architecture:

```bash
docker pull zot.example.com/gree-controller:0.13.9
```

## 8. If the build fails on `docs/openapi.json`

The application embeds this file during compilation:

```text
src/api/openapi.rs -> ../../docs/openapi.json
```

Therefore each Docker builder stage must include:

```dockerfile
COPY docs ./docs
```

This project version already contains that fix for both `trixie` and `alpine`.

## 9. Prepare the Home Assistant repository

Publish the contents of:

```text
ha-addon/repository/
```

The Git repository root should contain:

```text
repository.yaml
gree-controller/
├── config.yaml
├── README.md
├── DOCS.md
├── DOCS.pl.md
├── CHANGELOG.md
├── translations/
├── topology-ha-vlan-gree-en.png
└── topologia-ha-vlan-gree-pl.png
```

Example:

```bash
cd ha-addon/repository

git init -b main
git add .
git commit -m "Initial GREE Controller Home Assistant add-on"
```

Add your Git remote:

```bash
git remote add origin \
  https://git.example.pl/mateusz/gree-controller-ha-addon.git

git push -u origin main
```

Home Assistant must be able to reach this Git repository.

## 10. Private registry

If the OCI image is private, Home Assistant/Supervisor must have valid credentials for the registry.

For the simplest first installation use:

- a Git repository reachable by Home Assistant,
- anonymous pull for the OCI image if possible,
- HTTPS with a trusted certificate on the registry.

## 11. Add the custom repository to Home Assistant

Open the Apps/Add-ons store in Home Assistant and add the Git repository URL as a custom repository.

Example:

```text
https://git.example.pl/mateusz/gree-controller-ha-addon.git
```

Do not use:

- the project ZIP,
- the OCI image URL,
- `zot.example.com/gree-controller` as the repository URL.

The roles are:

```text
Git repository
  -> add-on metadata and config.yaml

OCI/Zot registry
  -> pre-built container image
```

## 12. Install the add-on

Refresh the Apps/Add-ons store after adding the repository.

You should see:

```text
GREE Controller
```

Select it and click:

```text
Install
```

Home Assistant reads values such as:

```yaml
version: "0.13.9"
image: "zot.example.com/gree-controller"
```

and pulls:

```text
zot.example.com/gree-controller:0.13.9
```

The OCI manifest automatically selects the correct architecture.

## 13. Single GREE network/VLAN

Example:

```text
eth0.50
192.168.50.2/24

GREE devices:
192.168.50.x
```

Add-on configuration:

```yaml
gree_interface: "eth0.50"
discovery_broadcast: "192.168.50.255:7000"
simulate: false
auto_seed: false
poll_interval_seconds: 15
zone_interval_seconds: 5
discovery_timeout_ms: 3000
app_token: ""
log_level: info
```

A local IPv4 address can be used instead of the interface name:

```yaml
gree_interface: "192.168.50.2"
```

## 14. Multiple VLANs / multiple interfaces

Example:

```text
eth0
├── eth0.50 -> 192.168.50.2/24
└── eth0.60 -> 192.168.60.2/24
```

For automatic interface selection leave:

```yaml
gree_interface: ""
```

For known devices the controller selects an interface according to the destination address.

Run UDP broadcast discovery separately for each subnet.

VLAN 50:

```yaml
discovery_broadcast: "192.168.50.255:7000"
```

VLAN 60:

```yaml
discovery_broadcast: "192.168.60.255:7000"
```

Broadcast normally does not cross routers, therefore discovery should be performed per VLAN.

## 15. VLANs on Home Assistant OS

Check the current network configuration:

```bash
ha network info
```

Example VLAN 50:

```bash
ha network vlan eth0 50 \
  --ipv4-method static \
  --ipv4-address 192.168.50.2/24 \
  --ipv6-method disabled
```

Example VLAN 60:

```bash
ha network vlan eth0 60 \
  --ipv4-method static \
  --ipv4-address 192.168.60.2/24 \
  --ipv6-method disabled
```

Verify again:

```bash
ha network info
```

Expected interfaces are similar to:

```text
eth0
eth0.50
eth0.60
```

If the main Home Assistant interface already has the default gateway, normally do not add additional default gateways to GREE VLAN interfaces.

## 16. Why `host_network`

The add-on uses:

```yaml
host_network: true
```

This makes the container use the Home Assistant OS host network namespace and allows it to see the host interfaces and VLANs.

There is no need to create Docker `macvlan` networks inside the add-on.

Topology:

```text
Home Assistant OS
├── eth0
├── eth0.50
├── eth0.60
└── GREE Controller add-on
      └── host_network: true
           ├── VLAN 50 -> GREE A/B
           └── VLAN 60 -> GREE C/D
```

Diagrams are stored in:

```text
ha-addon/docs/topologia-ha-vlan-gree-pl.png
ha-addon/docs/topology-ha-vlan-gree-en.png
```

## 17. Start the add-on and open the Web UI

After installation start the add-on and check its logs.

Example:

```text
GREE Controller: interface=auto discovery=192.168.50.255:7000 database=/data/gree-controller.db
```

The Web UI is available through Home Assistant Ingress.

## 18. Updating the add-on

For a new release:

### Step 1 - change only `Cargo.toml`

```toml
version = "0.13.10"
```

### Step 2 - build and push

```bash
cd ha-addon
./build.sh push
```

### Step 3 - verify the OCI manifest

```bash
docker buildx imagetools inspect \
  zot.example.com/gree-controller:0.13.10
```

### Step 4 - publish updated Home Assistant metadata

```bash
cd repository
git add .
git commit -m "Release 0.13.10"
git push
```

### Step 5 - update in Home Assistant

Refresh the add-on information and install the available update.

Recommended release order:

```text
1. change Cargo.toml
2. ./build.sh push
3. verify the OCI image
4. git commit/push ha-addon/repository
5. update in Home Assistant
```

This prevents Home Assistant from seeing a new version before its image is available in the registry.

---

# References

- Home Assistant app repositories: https://developers.home-assistant.io/docs/apps/repository/
- Home Assistant app publishing: https://developers.home-assistant.io/docs/apps/publishing/
- Home Assistant app configuration: https://developers.home-assistant.io/docs/apps/configuration/
- Docker multi-platform builds: https://docs.docker.com/build/building/multi-platform/