From 6a37b79d33f2c36b69a01ab3da4ad990a760f5af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Koco=C5=84?= Date: Tue, 24 Feb 2026 01:51:05 +0100 Subject: [PATCH] codex README --- README.md | 279 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 264 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index c66a90e..8b1620e 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,272 @@ -# HA - Bluerpints +# HA-Blueprints -Home Assistant Blueprints repository for automating smart home tasks. +Rozbudowane repozytorium blueprintow Home Assistant dla automatyzacji oswietlenia i ogrzewania. -## Project Info -- **Repo:** https://gitea.domowyasystent.com/PeakControl/HA-Blueprints -- **Created:** January 3, 2026 -- **Auto DevOps:** Enabled +## Spis tresci -## Usage -1. Browse the available blueprints in this repository. -2. Import the desired blueprint into your Home Assistant instance. -3. Customize triggers and actions as needed for your devices. +- [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) -[![Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgitlab.domowyasystent.com%2Fpeakcontroll%2Fha-bluerpints%2F-%2Fraw%2Fmain%2FTRVZB+and+External+sensor.yaml?) +## 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//.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/.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 -- Fork the repo and create a branch for your changes. -- Submit a merge request with clear description of the new blueprint or improvement. -## License -Specify your license here (e.g., MIT, Apache 2.0). +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.