gru/gree-controller

Fork 0

Files

T

Mateusz Gruszczyński fa0d4d0754 v0.13.9-ha_addon

2026-09-09 15:19:10 +02:00

17 KiB

Raw Blame History

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ź:

docker --version
docker buildx version

2. Wejdź do katalogu dodatku

Z katalogu głównego projektu:

cd ha-addon
cp .env.example .env

Edytuj .env:

nano .env

Przykład dla Zot:

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:

docker login zot.example.com

Po poprawnym logowaniu powinno pojawić się:

Login Succeeded

4. Wersjonowanie

Wersję zmieniasz tylko w jednym miejscu:

Cargo.toml

Przykład:

[package]
version = "0.13.9"

Przy kolejnym wydaniu zmień tylko:

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:

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

Sprawdź dostępne platformy:

docker buildx inspect --bootstrap

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

gree-controller-multiarch

Po jego utworzeniu możesz sprawdzić go poleceniem:

docker buildx inspect gree-controller-multiarch --bootstrap

Powinny być dostępne co najmniej:

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:

ha-addon/

uruchom:

./build.sh push

Skrypt:

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

Przykładowy wynik:

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:

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

Powinieneś zobaczyć:

linux/amd64
linux/arm64

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

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:

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

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

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:

ha-addon/repository/

Root repozytorium Git powinien wyglądać tak:

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:

cd ha-addon/repository

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

Dodaj swoje repo Git:

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.:

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:

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ę:

GREE Controller

Kliknij:

Install

Home Assistant odczyta np.:

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

i pobierze:

zot.example.com/gree-controller:0.13.9

Manifest OCI automatycznie wybierze odpowiednią architekturę.

13. Konfiguracja jednej sieci/VLAN GREE

Przykład:

eth0.50
192.168.50.2/24

GREE devices:
192.168.50.x

Konfiguracja dodatku:

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:

gree_interface: "192.168.50.2"

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

Przykład:

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

Dla automatycznego wyboru interfejsu pozostaw:

gree_interface: ""

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

Discovery UDP broadcast wykonuj osobno dla każdej podsieci.

VLAN 50:

discovery_broadcast: "192.168.50.255:7000"

VLAN 60:

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ć:

ha network info

Przykład VLAN 50:

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

Przykład VLAN 60:

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

Następnie:

ha network info

Powinny być widoczne interfejsy podobne do:

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:

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:

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:

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:

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`

version = "0.13.10"

Krok 2 - build i push

cd ha-addon
./build.sh push

Krok 3 - sprawdź manifest

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

Krok 4 - wypchnij metadata repozytorium HA

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:

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:

docker --version
docker buildx version

2. Enter the add-on directory

From the project root:

cd ha-addon
cp .env.example .env

Edit .env:

nano .env

Example for Zot:

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:

docker login zot.example.com

Expected result:

Login Succeeded

4. Versioning

Change the application version in one place only:

Cargo.toml

Example:

[package]
version = "0.13.9"

For the next release change only:

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:

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

Check platforms:

docker buildx inspect --bootstrap

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

gree-controller-multiarch

After it has been created, inspect it with:

docker buildx inspect gree-controller-multiarch --bootstrap

You should have at least:

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:

ha-addon/

run:

./build.sh push

The script:

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

Example result:

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:

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

Expected platforms:

linux/amd64
linux/arm64

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

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:

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

Therefore each Docker builder stage must include:

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:

ha-addon/repository/

The Git repository root should contain:

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:

cd ha-addon/repository

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

Add your Git remote:

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:

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:

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:

GREE Controller

Select it and click:

Install

Home Assistant reads values such as:

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

and pulls:

zot.example.com/gree-controller:0.13.9

The OCI manifest automatically selects the correct architecture.

13. Single GREE network/VLAN

Example:

eth0.50
192.168.50.2/24

GREE devices:
192.168.50.x

Add-on configuration:

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:

gree_interface: "192.168.50.2"

14. Multiple VLANs / multiple interfaces

Example:

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

For automatic interface selection leave:

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:

discovery_broadcast: "192.168.50.255:7000"

VLAN 60:

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:

ha network info

Example VLAN 50:

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

Example VLAN 60:

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

Verify again:

ha network info

Expected interfaces are similar to:

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:

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:

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:

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:

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`

version = "0.13.10"

Step 2 - build and push

cd ha-addon
./build.sh push

Step 3 - verify the OCI manifest

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

Step 4 - publish updated Home Assistant metadata

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:

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/

17 KiB Raw Blame History

GREE Controller - Home Assistant Add-on

PL - Instalacja dodatku Home Assistant

1. Wymagania

2. Wejdź do katalogu dodatku

3. Logowanie do registry

4. Wersjonowanie

5. Włącz build ARM64 przez QEMU

6. Build i push obrazu multi-arch

7. Sprawdź obraz w registry

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

9. Przygotowanie repozytorium Home Assistant

10. Prywatne registry

11. Dodanie custom repository w Home Assistant

12. Instalacja dodatku

13. Konfiguracja jednej sieci/VLAN GREE

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

15. VLAN-y na Home Assistant OS

16. Dlaczego host_network

17. Uruchomienie i Web UI

18. Aktualizacja dodatku

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

Krok 2 - build i push

Krok 3 - sprawdź manifest

Krok 4 - wypchnij metadata repozytorium HA

Krok 5 - aktualizacja w Home Assistant

EN - Home Assistant Add-on installation

1. Requirements

2. Enter the add-on directory

3. Log in to the registry

4. Versioning

5. Enable ARM64 builds with QEMU

6. Build and push the multi-arch image

7. Verify the published image

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

9. Prepare the Home Assistant repository

10. Private registry

11. Add the custom repository to Home Assistant

12. Install the add-on

13. Single GREE network/VLAN

14. Multiple VLANs / multiple interfaces

15. VLANs on Home Assistant OS

16. Why host_network

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

18. Updating the add-on

Step 1 - change only Cargo.toml

Step 2 - build and push

Step 3 - verify the OCI manifest

Step 4 - publish updated Home Assistant metadata

Step 5 - update in Home Assistant

References

17 KiB

Raw Blame History

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

16. Dlaczego `host_network`

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

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

16. Why `host_network`

Step 1 - change only `Cargo.toml`