HA-Blueprints/README.md

HA-Blueprints

Rozbudowane repozytorium blueprintow Home Assistant dla automatyzacji oswietlenia i ogrzewania.

Spis tresci

• Cel repozytorium
• Szybki start
• Import przez My Home Assistant
• Katalog blueprintow
• Struktura i organizacja plikow
• Wymagania techniczne
• Jak rozwijac i testowac
• Standard tworzenia blueprintow
• Troubleshooting
• Contributing
• Roadmap
• Licencja

Cel repozytorium

Repozytorium sluzy jako centralne miejsce dla blueprintow Home Assistant:

• gotowe automatyzacje do importu 1-kliknieciem,
• wersje robocze i testowe,
• kopie blueprintow zrodlowych, uzywanych jako referencja funkcjonalna.

Glowny remote:

• https://gitea.domowyasystent.com/PeakControl/HA-Blueprints.git

Domyslna galaz:

• main

Szybki start

1. Otworz wybrany link importu z sekcji Import przez My Home Assistant.
2. W Home Assistant kliknij Import Blueprint.
3. Utworz automatyzacje na podstawie blueprintu i wypelnij wymagane encje.
4. Zapisz i uruchom automatyzacje testowo.

Jesli import z URL nie dziala, skorzystaj z importu manualnego:

1. Skopiuj plik .yaml do:
   • config/blueprints/automation/<twoj_namespace>/<nazwa_pliku>.yaml
2. W Home Assistant przejdz do:
   • Ustawienia -> Automatyzacje i sceny -> Blueprints
3. Odswiez liste blueprintow i utworz automatyzacje.

Import przez My Home Assistant

Ponizsze linki wykorzystuja raw URL z Gitea.

Dynamic Radiator Valve

Sonoff TRVZB + External Temp AUTO

Sonoff TRVZB and External Sensor

Motion-activated Light

Smart Light

Dynamic Radiator Valve - Pro Configurator (test)

Advanced Heating Control V5 (reference)

Katalog blueprintow

Statusy (robocza klasyfikacja porzadkujaca):

• stable - plik traktowany jako docelowy do uzycia.
• experimental - wersja testowa lub robocza.
• reference - blueprint zewnetrzny trzymany jako punkt odniesienia.
• utility - plik pomocniczy/placeholder.

Plik	Nazwa blueprintu	Rozmiar	Status	Opis
dynamic_valve.yaml	Dynamic Radiator Valve	~3 KB	stable	Dynamiczne sterowanie zaworem grzejnika na podstawie roznicy temperatur i stanu okna.
test.yaml	Sonoff TRVZB + External Temp AUTO	~1.6 KB	stable	Synchronizacja temperatury z zewnetrznego sensora do glowicy Sonoff TRVZB.
TRVZB and External sensor.yaml	Sonoff TRVZB & Zewnetrzny czujnik temperatury	~2.1 KB	stable	Wersja z parametrami wejscia dla pojedynczego sensora/number/select.
motion_light.yaml	Motion-activated Light	~1.5 KB	reference	Klasyczny blueprint Home Assistant: swiatlo wlaczane ruchem.
smart-light.yaml	Smart Light	~499 KB	reference	Bardzo rozbudowany blueprint oswietleniowy (wiele trybow i warunkow).
dynamic_valve_test.yaml	Dynamic Radiator Valve - Pro Configurator	~5.2 KB	experimental	Rozszerzona wersja dynamic_valve.yaml, traktowana jako eksperymentalna.
dynamic_valve_test_na_kurwie.yaml	Advanced Heating Control V5	~139 KB	reference	Zaawansowany blueprint ogrzewania (kopia referencyjna).
helloworld.yaml	-	~0.03 KB	utility	Placeholder, nie jest poprawnym blueprintem HA.

Struktura i organizacja plikow

Aktualnie repozytorium ma plaski uklad (wszystkie pliki w katalogu glownym). Zalecany kierunek:

.
|- README.md
|- stable/
|  |- dynamic_valve.yaml
|  |- test.yaml
|  `- TRVZB and External sensor.yaml
|- experimental/
|  `- dynamic_valve_test.yaml
|- reference/
|  |- motion_light.yaml
|  |- smart-light.yaml
|  `- advanced_heating_control.yaml
`- misc/
   `- helloworld.yaml

Taki podzial ulatwia:

• szybkie znalezienie wersji produkcyjnej,
• oddzielenie plikow roboczych od referencyjnych,
• mniejsze ryzyko importu niechcianego testowego blueprintu.

Wymagania techniczne

• Home Assistant z obsluga blueprintow automatyzacji.
• Publiczny dostep do raw URL (jesli importujesz przez URL).
• Poprawnie skonfigurowane encje, na ktorych opiera sie dany blueprint:
  • climate, sensor, number, select, binary_sensor, input_boolean, input_text (zalezne od pliku).

Dla wybranych blueprintow:

• dynamic_valve.yaml:
  • wymagany termostat (climate) i sensor temperatury (sensor),
  • opcjonalnie input_text do zapisu roznicy/stopnia.
• test.yaml i TRVZB and External sensor.yaml:
  • wymagane encje number i select wspierajace aktualizacje temperatury z sensora.
• smart-light.yaml:
  • bardzo duza liczba opcji, zalecany import i konfiguracja etapami.

Jak rozwijac i testowac

1. Klonowanie

git clone https://gitea.domowyasystent.com/PeakControl/HA-Blueprints.git
cd HA-Blueprints

2. Walidacja skladni YAML (lokalnie)

Przyklad z yamllint:

yamllint .

Weryfikacja pojedynczego pliku:

yamllint dynamic_valve.yaml

3. Test w Home Assistant

1. Zaimportuj blueprint.
2. Utworz automatyzacje testowa na dedykowanych encjach.
3. Sprawdz logbook i trace automatyzacji.
4. Zweryfikuj skrajne przypadki:
   • encja unknown/unavailable,
   • restart HA,
   • szybkie zmiany stanu triggera.

4. Kontrola zmian

git status
git diff

Standard tworzenia blueprintow

Aby repo bylo spojne, trzymaj sie zasad:

1. Nazewnictwo plikow:
   • snake_case.yaml dla nowych plikow.
2. Metadane blueprintu:
   • zawsze podawaj name, description, domain,
   • dodawaj source_url jesli plik jest forkiem/kopia.
3. Opis wejsc:
   • kazdy input powinien miec czytelna nazwe i opis.
4. Bezpieczenstwo:
   • obsluguj unknown i unavailable w warunkach.
5. Czytelnosc:
   • dziel logike na sekcje variables, condition, action,
   • unikaj "magic numbers" bez opisu.
6. Wersjonowanie:
   • przy wiekszej zmianie zachowania aktualizuj opis i changelog w opisie blueprintu.

Troubleshooting

Import nie dziala

• Upewnij sie, ze URL wskazuje na raw/branch/main/<plik>.yaml.
• Sprawdz, czy repo i plik sa publicznie dostepne bez logowania.
• Zweryfikuj, czy link nie ma literowek w nazwie pliku.

Blueprint nie pojawia sie na liscie

• Sprawdz, czy plik zaczyna sie od sekcji blueprint:.
• Zweryfikuj wciecia YAML (spacje, nie taby).
• Sprawdz logi Home Assistant po restarcie.

Automatyzacja dziala niestabilnie

• Zweryfikuj encje w input blueprintu.
• Sprawdz, czy encje nie przechodza w unknown/unavailable.
• Uzyj trace automatyzacji, aby zobaczyc ktory warunek blokuje wykonanie.

Problem z kodowaniem znakow

Niektore pliki moga zawierac artefakty kodowania. Zalecenia:

• zapisuj pliki jako UTF-8,
• unikaj mieszania edytorow i kodowan ANSI/UTF-8,
• po zmianach zawsze testuj import do HA.

Contributing

1. Utworz branch:

git checkout -b feat/nazwa-zmiany

2. Wprowadz zmiany i wykonaj testy lokalne.
3. Opisz zmiane w PR/MR:
   • co zmieniono,
   • dlaczego,
   • jak przetestowano.
4. Dolacz przyklad konfiguracji inputow (jesli dodajesz nowy blueprint).

Roadmap

• uporzadkowanie struktury katalogow (stable/, experimental/, reference/),
• standaryzacja nazw plikow i metadanych,
• dodanie CI do walidacji YAML i podstawowych testow statycznych,
• wydzielenie CHANGELOG dla najwazniejszych blueprintow,
• dodanie sekcji kompatybilnosci (minimalna wersja HA na blueprint).

Licencja

Brak jawnie zdefiniowanej licencji w repozytorium.

Zalecane:

1. dodac plik LICENSE,
2. okreslic zasady dla blueprintow autorskich oraz kopii/forkow blueprintow zewnetrznych.

---

Jesli chcesz, moge w kolejnym kroku od razu:

1. uporzadkowac pliki do katalogow stable/experimental/reference,
2. przygotowac gotowy LICENSE (np. MIT),
3. dodac prosty workflow CI do walidacji YAML.