# HA-Blueprints

Rozbudowane repozytorium blueprintow Home Assistant dla automatyzacji oswietlenia i ogrzewania.

## Spis tresci

- [Cel repozytorium](#cel-repozytorium)
- [Szybki start](#szybki-start)
- [Import przez My Home Assistant](#import-przez-my-home-assistant)
- [Katalog blueprintow](#katalog-blueprintow)
- [Struktura i organizacja plikow](#struktura-i-organizacja-plikow)
- [Wymagania techniczne](#wymagania-techniczne)
- [Jak rozwijac i testowac](#jak-rozwijac-i-testowac)
- [Standard tworzenia blueprintow](#standard-tworzenia-blueprintow)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Roadmap](#roadmap)
- [Licencja](#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](#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

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2Fdynamic_valve.yaml)

### Sonoff TRVZB + External Temp AUTO

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2Ftest.yaml)

### Sonoff TRVZB and External Sensor

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2FTRVZB%20and%20External%20sensor.yaml)

### Motion-activated Light

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2Fmotion_light.yaml)

### Smart Light

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2Fsmart-light.yaml)

### Dynamic Radiator Valve - Pro Configurator (test)

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2Fdynamic_valve_test.yaml)

### Advanced Heating Control V5 (reference)

[![Import blueprint](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitea.domowyasystent.com%2FPeakControl%2FHA-Blueprints%2Fraw%2Fbranch%2Fmain%2Fdynamic_valve_test_na_kurwie.yaml)

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

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

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

### 2. Walidacja skladni YAML (lokalnie)

Przyklad z `yamllint`:

```bash
yamllint .
```

Weryfikacja pojedynczego pliku:

```bash
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

```bash
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:

```bash
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.