codex README
This commit is contained in:
279
README.md
279
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)
|
||||
|
||||
[](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/<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
|
||||
|
||||
[](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
|
||||
|
||||
[](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
|
||||
|
||||
[](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
|
||||
|
||||
[](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
|
||||
|
||||
[](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)
|
||||
|
||||
[](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)
|
||||
|
||||
[](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
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user