⚠️ BARDZO WAŻNE: KROKI PRZED INSTALACJĄ

Używanie projektu jest jawnym łamaniem regulaminu EduVulcan.pl.
Nie rób tego.

⚠️ BARDZO WAŻNE: KROKI PRZED INSTALACJĄ

Aby aplikacja zadziałała prawidłowo, musisz najpierw wykonać te 3 kroki:

1. Zaloguj się na swoje konto przez stronę WWW.

2. Zaakceptuj nowe regulaminy i zgody (cookies).

3. Przełącz się na profil KAŻDEGO ze swoich dzieci i kliknij w dowolną zakładkę (cokolwiek!).

🛑 DOPIERO WTEDY MOŻESZ ZAINSTALOWAĆ APLIKACJĘ! 🛑

⛔ UWAGA: Problemy wynikające z pominięcia tych kroków nie są błędami aplikacji. Prosimy nie zakładać zgłoszeń (Bug / Issue), jeśli nie wykonałeś powyższej instrukcji. Szanujmy swój czas i Wasz!

Vultron (Jungfru)

GPE Gdansk accounts can use the optional gdansk provider. See the GPE setup, supported data and limitations. The default remains eduVULCAN.

Vultron to totalnieNIEzaawansowana integracja Home Assistant z systemem dziennika elektronicznego EduVulcan.pl. Dodatek został zaprojektowany, aby dostarczać rodzicom i uczniom kluczowe informacje o edukacji w sposób przejrzysty, zautomatyzowany i bezpieczny.

🙏 Co-authored-by:

AI i Tomasz H.
@KamillJot — wsparcie dla GPE Gdańsk

Wersja: 7.1.1
Nazwa Kodowa: Jungfru ♍

📖 Spis treści

🚨 Achtung
🧩 Changelog
✨ Główne Funkcje
🏗️ Architektura Systemu
🚀 Instalacja
🐳 Samodzielny kontener Docker
⚙️ Konfiguracja
📊 Konfiguracja Kart Dashboardu
🔄 Automatyzacja
🔍 Monitoring
📸 Próbki/screenshoty
🪲 Zgłaszanie błędów
🗑️ Odinstalowanie
⚖️ Nota prawna

🚨🚨🚨 Achtung Achtung 🚨🚨🚨

Przy pierwszym uruchomieniu ZALECANE śledzenie zakładki LOGI czy proces logowania przechodzi poprawnie.

W razie błędów skrypt SAMOCZYNNIE zabije kontener.

Przed ponownym startem: Sprawdź ręcznie logowanie w oryginalnym dzienniku przez W W W.

🧩 Changelog

📝 Changelog

✨ Główne Funkcje

👨‍👩‍👧‍👦 Multi-Student Support: Automatyczne wykrywanie wszystkich(wszystkie dzieci nasze są) dzieci przypisanych do konta rodzica. Każde dziecko otrzymuje własny zestaw sensorów (np. adam_nowak, jan_kowalski).
📅 Profesjonalny Plan Lekcji: Klasyczny układ tabelaryczny z nawigacją tygodniową (poprzedni / obecny / następny — łącznie 3 tygodnie). Możliwość dodawania własnych zajęć. Opisane w Changelog 6.4.0
📈 Monitoring Ocen: Śledzenie ocen cząstkowych z systemem powiadomień o nowych wpisach i zmianach. Zakładka KOŃCOWE pokazuje oceny proponowane i końcowe z automatycznie wyliczonymi średnimi (bez Zachowania).
💬 Uwagi i Pochwały: Pełny wgląd w zachowanie ucznia z podziałem na wpisy pozytywne, negatywne oraz informacyjne.
✉️ Centrum Wiadomości: Licznik wiadomości nieprzeczytanych oraz odczytanych wraz z listą ostatnich nadawców i tematów.
🎒 Terminarz Wydarzeń: Podgląd sprawdzianów, kartkówek i zadań domowych z kolorystycznym rozróżnieniem priorytetów.
✔️ Frekwencja: Szczegółowe informacje o frekwencji na zajęciach.
🏆 Osiągnięcia: Szczegółowe informacje o osiągnięciach.
👩‍🏫 Zebrania: Szczegółowe informacje o zebraniach.
🧸 Przedszkole: Osobny zestaw sensorów dla kont przedszkolnych (wykrywane automatycznie, całkowicie niezależnie od uczniów szkół) — plan zajęć, ewidencja obecności (kalendarz miesięczny + godziny wejścia/wyjścia), jadłospis (skład i alergeny), zebrania, opłaty, informacje o placówce, nauczyciele, wiadomości.
📊 Monitoring: Dedykowana encja binary_sensor.vultron_rozmiar_alert ostrzega, gdy atrybuty którejkolwiek encji zbliżają się do twardego limitu Home Assistant (16 384 B) — pozwala wykryć problem, zanim HA zacznie po cichu odrzucać dane.
🛠️ Zero-Click UI: Dodatek automatycznie rejestruje wymagane karty JavaScript w zasobach Lovelace (Resources) przy każdym starcie.
🕵️ System Anty-Detekcyjny:
- Zapytania do serwerów Vulcan wysyłane są w losowych odstępach (40-60 min).
- Tryb Nocny: Całkowite wstrzymanie aktywności między 01:00 a 05:59.
📝 Precyzyjne Logowanie: Wszystkie zdarzenia logowane są z timestampem w formacie [YYYY-MM-DD HH:MM:SS].

🏗️ Architektura Systemu

System opiera się na modularnej strukturze współpracujących funkcji:

Moduł	Role	Opis techniczny
`vultron.py`	🔑 Logowanie 📝 Oceny 💬 Uwagi ✉️ Wiadomości 📅 Plan lekcji 🎒 Zadania ✔️ Frekwencja 🏆 Osiągnięcia 📊 Monitoring 🎨 UI Setup ⚙️ Orkiestrator 👩‍🏫 Zebrania 🧸 Przedszkole	Główny silnik aplikacji. Obsługuje logowanie Selenium Headless (Panel Rodzica + Panel Wiadomości), ekstrakcję kluczy sesji (`key`), pobieranie ocen, uwag, wiadomości, planu lekcji, zadań, frekwencji i osiągnięć. Automatycznie rozpoznaje konta przedszkolne i przetwarza je osobną ścieżką (plan zajęć, ewidencja obecności, jadłospis, zebrania, opłaty, informacje o placówce, nauczyciele). Zarządza bazą SQLite (`vultron.db`), monitoringiem zasobów, automatyczną rejestracją kart w Home Assistant oraz pętlą czasową z mechanizmem anty-detekcji.
`vultron-card.js`	🎨 Stylizacja	Karta Lovelace — plan lekcji.
`vultron-grades-card.js`	🎨 Stylizacja	Karta Lovelace — oceny (widoki: PRZEDMIOTY, NAJNOWSZE, KOŃCOWE).
`vultron-messages-card.js`	🎨 Stylizacja	Karta Lovelace — wiadomości.
`vultron-stats-card.js`	🎨 Stylizacja	Karta Lovelace — frekwencja.
`vultron-osiagniecia-card.js`	🎨 Stylizacja	Karta Lovelace — osiągnięcia.
`vultron-uwagi-card.js`	🎨 Stylizacja	Karta Lovelace — uwagi i pochwały.
`vultron-work-card.js`	🎨 Stylizacja	Karta Lovelace — zadania domowe i sprawdziany.
`vultron-zebrania-card.js`	🎨 Stylizacja	Karta Lovelace — zebrania.
`vultron-przedszkole-plan-card.js`	🎨 Stylizacja	Karta Lovelace — plan zajęć przedszkola.
`vultron-przedszkole-obecnosc-card.js`	🎨 Stylizacja	Karta Lovelace — obecność przedszkola (kalendarz miesięczny + godziny).
`vultron-przedszkole-jadlospis-card.js`	🎨 Stylizacja	Karta Lovelace — jadłospis przedszkola (skład, alergeny).
`vultron-przedszkole-zebrania-card.js`	🎨 Stylizacja	Karta Lovelace — zebrania przedszkola.
`vultron-przedszkole-oplaty-card.js`	🎨 Stylizacja	Karta Lovelace — opłaty przedszkola.
`vultron-przedszkole-informacje-card.js`	🎨 Stylizacja	Karta Lovelace — informacje o placówce przedszkolnej.
`vultron-przedszkole-nauczyciele-card.js`	🎨 Stylizacja	Karta Lovelace — nauczyciele przedszkola.
`vultron-przedszkole-wiadomosci-card.js`	🎨 Stylizacja	Karta Lovelace — wiadomości przedszkola.
`automation/node-red`	🔄 Automatyzacje	Przykładowe przepływy Node-RED.
`automation/ha`	🔄 Automatyzacje	Przykładowe natywne automatyzacje Home Assistant.
`automation/blueprints`	🔄 Automatyzacje	Przykładowe blueprinty automatyzacji.
`lovelace/`	🎨 Stylizacja	Przykładowe konfiguracje kart Lovelace. Zamiast *** wstaw osobe imie_nazwisko
`vultron-szczesliwy-numerek-card.js`	🎨 Stylizacja	Karta Lovelace — szczęśliwy numerek.

🚀 Instalacja

Vultron jest dostępny jako standardowe repozytorium Home Assistant.

🚨 Metoda 1: Automatyczna (Zalecana)

Kliknij poniższy przycisk, aby dodać repozytorium do swojego Home Assistanta jednym kliknięciem:

🚨 Coś popsuli w HA :D

Jeżeli powyższy link nie działa, użyj: Ustawienia → Aplikacje → Sklep z aplikacjami → ⋮ → Repozytoria → wpisz URL https://github.com/htomasz/vultron → Dodaj

Po dodaniu repozytorium, wejdź w Ustawienia → Dodatki → Sklep z dodatkami, wyszukaj Vultron i kliknij Zainstaluj.

Metoda 2: Ręczna / Deweloperska (SSH)

Jeśli wolisz zainstalować dodatek ręcznie przez konsolę:

Zainstaluj dodatek SSH & Web Terminal.
Po instalacji wyłącz Protection mode oraz włącz Show in sidebar.
Wejdź w dodatek SSH i przejdź do folderu addons:

cd /addons

Sklonuj repozytorium:

git clone https://github.com/htomasz/vultron.git

W interfejsie HA przejdź do Ustawienia → Dodatki → Sklep z dodatkami, kliknij trzy kropki (prawy górny róg) i wybierz Odśwież.

💾 Wymagania sprzętowe (ważne dla Raspberry Pi)

Vultron w tle uruchamia headless Chromium (Selenium) do logowania w dzienniku - to najbardziej wymagający pamięciowo fragment całego dodatku. Na Raspberry Pi 4 z 2GB RAM bez skonfigurowanego swapu/zram obserwowaliśmy sporadyczne zawieszenia logowania pod większym obciążeniem pamięci (inne dodatki, integracje HA działające równolegle).

Zalecenie: jeśli Twoje urządzenie ma 2GB RAM, włącz zram (kompresowany swap w pamięci RAM - szybszy i nie zużywa karty SD, w przeciwieństwie do tradycyjnego swapu na pliku). To ustawienie na poziomie systemu Home Assistant OS, nie samego dodatku - najprościej przez dodatek zram / swap ze społecznościowego repozytorium, ewentualnie ręcznie z poziomu SSH. Vultron sam w sobie nie potrafi tego skonfigurować z poziomu kontenera.

Dodatek od wersji 7.0.1 sam potrafi wykryć i posprzątać po zawieszonej przeglądarce (żeby jedna awaria nie eskalowała do wyczerpania pamięci na całym urządzeniu), ale przy bardzo ciasnym budżecie RAM-u pojedyncze, odosobnione timeouty logowania wciąż mogą się zdarzać - to fizyczne ograniczenie sprzętu, nie błąd dodatku.

🐳 Samodzielny kontener Docker

Vultron w Dockerze — przewodnik "krok po kroku dla każdego"

Ten przewodnik zakłada, że nic nie wiesz o Dockerze tak jak JA. Każdy krok jest opisany osobno. Nie przechodź do kolejnego kroku, dopóki poprzedni nie zadziała.

Dla kogo jest ten przewodnik? Dla osób, które mają Home Assistant uruchomiony jako zwykły kontener Docker (bez tzw. "Supervisora" — jeśli nie wiesz co to jest, prawdopodobnie ten przewodnik jest dla Ciebie).

Zanim zaczniesz — co będzie Ci potrzebne

Komputer/serwer z zainstalowanym Dockerem, na którym już działa Twój Home Assistant.
Login i hasło do dziennika eduVULCAN.
Konto w Home Assistant, do którego możesz się zalogować przez przeglądarkę.
15-20 minut czasu.

Krok 1: Zdobądź "przepustkę" dla Vultrona do Home Assistant

Vultron musi umieć "rozmawiać" z Twoim Home Assistant. Żeby to zrobić bezpiecznie, potrzebuje specjalnego kodu — nazywa się token. To jak klucz do drzwi, tylko cyfrowy.

Otwórz Home Assistant w przeglądarce.
Kliknij swoje imię/nazwę użytkownika w lewym dolnym rogu ekranu.
Zobaczysz stronę "Profil". Przewiń ją w dół, aż zobaczysz napis "Bezpieczeństwo".
Znajdź tam "Długoterminowe tokeny dostępu".
Kliknij przycisk "Utwórz token".
Pojawi się długi ciąg liter i cyfr. To jest Twój token.
Kliknij, żeby go skopiować.
Bardzo ważne: ten token pokazuje się tylko RAZ. Jeśli go zamkniesz bez skopiowania, będziesz musiał zrobić nowy. Wklej go od razu w jakimś bezpiecznym miejscu (np. notatnik na komputerze) — będzie potrzebny za chwilę.

Krok 2: Otwórz terminal (czarne okienko z tekstem)

Wszystkie kolejne kroki wykonujesz w terminalu na komputerze/serwerze, na którym działa Twój Home Assistant. Jeśli już wiesz jak to otworzyć — otwórz. Jeśli nie — poszukaj w systemie aplikacji o nazwie "Terminal" albo połącz się przez SSH, jeśli Twój serwer jest zdalny.

Krok 3: Ściągnij pliki Vultrona na dysk

Wpisz w terminalu (i wciśnij Enter):

git clone https://github.com/htomasz/vultron.git

To pobierze wszystkie potrzebne pliki do nowego folderu o nazwie vultron.

Teraz wejdź do tego folderu:

cd vultron

Krok 4: Przygotuj dwa foldery na Twoje dane

Wpisz:

mkdir -p secrets data

To tworzy dwa puste foldery: secrets (na Twój token) i data (na dane logowania do eduVULCAN).

Krok 5: Zapisz token w pliku

Wpisz:

nano secrets/ha_token.txt

Otworzy się prosty edytor tekstu. Wklej tam token, który skopiowałeś w Kroku 1 (samo kliknięcie prawym przyciskiem myszy → "Wklej", albo Ctrl+Shift+V w większości terminali).

Nie wpisuj nic więcej — sam token, nic ponad to.

Zapisz plik: wciśnij Ctrl+O, potem Enter, potem Ctrl+X żeby wyjść z edytora.

Krok 6: Zapisz dane do logowania do eduVULCAN

Wpisz:

nano data/options.json

Wklej dokładnie to (i podmień dwa miejsca — swój login i swoje hasło):

{"username": "TUTAJ_TWOJ_LOGIN", "password": "TUTAJ_TWOJE_HASLO", "log_level": "info", "test_mode": false}

Przykład jak to powinno wyglądać po wypełnieniu:

{"username": "jan.kowalski", "password": "MojeHaslo123", "log_level": "info", "test_mode": false}

Zapisz: Ctrl+O, Enter, Ctrl+X.

Krok 7: Przygotuj miejsce na "karty" (ładny wygląd danych w Home Assistant)

Vultron pokazuje dane (oceny, plan lekcji itd.) w ładnej formie na dashboardzie Home Assistant. Żeby to zadziałało, potrzebny jest jeden dodatkowy folder — wewnątrz miejsca, gdzie Home Assistant trzyma swoje pliki.

7a. Znajdź, gdzie na dysku są pliki Twojego Home Assistant:

docker inspect homeassistant --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'

Zobaczysz linijkę podobną do tej:

/home/user/ha-config -> /config

Zapisz sobie tę część przed strzałką (u Ciebie może być inna niż w tym przykładzie) — będzie potrzebna za chwilę.

7b. Stwórz w tym miejscu folder www:

mkdir -p /home/user/ha-config/www

(Podmień /home/user/ha-config na to, co zobaczyłeś w kroku 7a).

Nic więcej nie musisz robić z Home Assistantem — sam zacznie widzieć ten folder.

Krok 8: Sprawdź jedną rzecz w ustawieniach Home Assistant

Wejdź w Home Assistant do Ustawienia → Panel sterowania.
Sprawdź, czy widzisz opcję edycji przez przyciski/myszkę (nie same pliki tekstowe). Jeśli tak — wszystko gra, idź dalej.
Jeśli nie masz pewności — po prostu przejdź dalej, sprawdzimy to na końcu.

Krok 9: Stwórz plik z instrukcjami dla Dockera

Wpisz:

nano compose.yaml

Wklej całą tę treść (jeszcze nic nie uruchamiamy, tylko zapisujemy instrukcje):

services:
  vultron:
    build:
      context: ./vultron
    container_name: vultron
    restart: unless-stopped
    mem_limit: 2g

    networks:
      - ha-net

    environment:
      TZ: Europe/Warsaw
      HA_URL: http://homeassistant:8123/api
      HA_WS_URL: ws://homeassistant:8123/api/websocket

    volumes:
      - ./data:/data:z
      - /home/user/ha-config/www:/config/www:z
      - ./secrets/ha_token.txt:/run/secrets/ha_token:ro,z

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

networks:
  ha-net:
    external: true

Ważne podmiany, których musisz dokonać w tym tekście, zanim zapiszesz:

/home/user/ha-config/www → wstaw swoją prawdziwą ścieżkę z Kroku 7a (z dopisanym /www na końcu).
Europe/Warsaw → jeśli mieszkasz w Polsce, zostaw jak jest. Jeśli w innym kraju, zamień na swoją strefę czasową.

Zapisz: Ctrl+O, Enter, Ctrl+X.

Krok 10: Podłącz Home Assistant do specjalnej "sieci" dla Vultrona

Żeby Vultron i Home Assistant mogły się ze sobą "widzieć", muszą być w tej samej wirtualnej sieci. Wpisz po kolei:

docker network create ha-net
docker network connect ha-net homeassistant

(Jeśli druga komenda pokaże błąd, że sieć już istnieje/jest podłączona — to znaczy że ktoś to już zrobił wcześniej, w porządku, idź dalej).

Krok 11: Uruchom Vultrona

To jest ten moment. Wpisz:

docker compose up --build -d

To zajmie kilka minut za pierwszym razem — Docker musi pobrać i przygotować wszystko od zera. Nie przerywaj, poczekaj aż komenda się zakończy i wróci do zwykłego wiersza poleceń.

Krok 12: Sprawdź, czy działa

Wpisz:

docker compose logs -f

Zobaczysz strumień tekstu — to jest "dziennik" tego, co Vultron robi na żywo. Poczekaj chwilę i patrz, czy nie pojawia się czerwony napis CRITICAL (to oznaczałoby błąd). Jeśli widzisz, że próbuje się logować do eduVULCAN i nie ma błędów — świetnie, działa!

Żeby przestać patrzeć na ten strumień (nie wyłącza to Vultrona, tylko podgląd): wciśnij Ctrl+C.

Krok 13: Zobacz swoje dane w Home Assistant

W Home Assistant wejdź do Narzędzia deweloperskie → Stany.
W polu wyszukiwania wpisz vultron.
Jeśli po kilku minutach zobaczysz tam pozycje takie jak sensor.vultron_plan_... czy sensor.vultron_oceny_... — to znaczy, że dane faktycznie przyszły z eduVULCAN do Home Assistant. Gratulacje, udało się!

Coś nie działa? Sprawdź to

Widzę czerwony napis "Permission denied" (odmowa dostępu)

To zdarza się na niektórych systemach (Fedora, CentOS, RHEL, Rocky, AlmaLinux). Sprawdź:

getenforce

Jeśli pokaże Enforcing — to jest przyczyna. Upewnij się, że każda linijka w volumes: w pliku compose.yaml (Krok 9) kończy się literką :z na samym końcu — dokładnie tak, jak w przykładzie wyżej.

Karty w Home Assistant są puste albo nic się nie pokazuje

Wciśnij Ctrl+Shift+R w przeglądarce (to "twarde" odświeżenie strony).
W Home Assistant wejdź do Ustawienia → Panel sterowania, kliknij trzy kropki w prawym górnym rogu, wybierz Zasoby. Jeśli lista jest pusta — dodaj tam ręcznie wpisy, po jednym dla każdej karty Vultrona, którą chcesz widzieć (typ: JavaScript Module, adres: /local/vultron/nazwa-karty.js).

Vultron ciągle się restartuje / wyłącza

Wpisz:

docker compose logs vultron --tail 50

Poszukaj pierwszej czerwonej linijki (CRITICAL) na samej górze wyniku — ona zwykle mówi wprost, czego brakuje (np. że plik z tokenem jest pusty, albo że coś jest źle wpisane w data/options.json).

Nie wiem, jaki adres wpisać przy `HA_URL`

Sprawdź, jak jest ustawiony Twój Home Assistant:

docker inspect homeassistant --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}'

Jeśli wynikiem jest słowo host — napisz o tym, to wymaga innej wersji pliku compose.yaml niż ta z Kroku 9.

To wszystko!

Jeśli dotarłeś do końca i widzisz swoje dane w Home Assistant — Vultron działa poprawnie. Możesz teraz dodać ładne "karty" na swój dashboard, żeby widzieć te dane w wygodnej formie (to już osobny, dodatkowy krok — zapytaj, jeśli chcesz instrukcję).

⚙️ Konfiguracja

W zakładce Konfiguracja zainstalowanego dodatku wypełnij dane dostępowe:

Parametr	Opis	Przykład
`username`	Adres e-mail do EduVulcan	`rodzic@email.pl`
`password`	Hasło do portalu	`TwojeTajneHasło`
`Poziom logowania`	Określa szczegółowość logów w zakładce Logi. Domyślnie: info.	`info`,`debug`,`trace` (nie rozumiesz, nie zmieniaj)
`Tryb testowy`	Włączenie tej opcji sprawia, że skrypt całkowicie ignoruje nocne oraz weekendowe przerwy i pobiera dane w trybie ciągłym. Używaj tylko do testowania modyfikacji!	`true`,`false` (nie rozumiesz, nie zmieniaj)

Kliknij Zapisz.
Kliknij Uruchom.

Ważne: Przy pierwszym uruchomieniu zalecane jest śledzenie zakładki Logi, aby upewnić się, że proces logowania przebiega pomyślnie. Skrypt posiada zabezpieczenie, które w razie błędnego hasła automatycznie zatrzyma kontener, chroniąc Twoje konto przed blokadą.

💡 Ważna uwaga dotycząca kart UI i odświeżania

Z powodu sposobu, w jaki Home Assistant oraz przeglądarki internetowe zarządzają plikami interfejsu (Lovelace), po instalacji dodatku lub jego aktualizacji możesz napotkać problemy z wyświetlaniem kart (np. błąd Custom element doesn't exist lub brak nowych funkcji).

Oto jak sobie z tym poradzić:

1. "Zwykłe" Odświeżanie vs "Twarde" Odświeżanie

Przeglądarki często przechowują starą wersję plików .js, aby przyspieszyć ładowanie strony. Jeśli karta nie wygląda tak, jak powinna:

Na komputerze: Użyj kombinacji Ctrl + F5 (Windows/Linux) lub Cmd + Shift + R (Mac). Wymusza to na przeglądarce ponowne pobranie plików z serwera Home Assistant zamiast czytania ich z dysku.
W aplikacji mobilnej: Zamknij całkowicie aplikację Home Assistant i uruchom ją ponownie. Możesz również wejść w Ustawienia → Aplikacja towarzysząca → Debugowanie → Wyczyść pamięć podręczną.

2. Kiedy wyczyścić ciasteczka i dane strony?

Jeśli "Twarde odświeżanie" nie pomaga, może to oznaczać, że w pamięci podręcznej przeglądarki utknął błędny stan zasobów.

W takim przypadku zalecane jest wyczyszczenie danych podręcznych dla adresu IP/domeny Twojego Home Assistanta.
Wskazówka: Często najszybszym testem jest otwarcie panelu w trybie Inkognito. Jeśli tam karty działają poprawnie, oznacza to, że Twoja główna sesja przeglądarki wymaga czyszczenia cache.

3. Rejestracja Zasobów

Dodatek posiada wbudowaną funkcję run_setup_ui() (część vultron.py), która automatycznie dodaje karty do zasobów Lovelace przy każdym starcie. Home Assistant czasami potrzebuje chwili (lub restartu interfejsu), aby "zauważyć" nową ścieżkę /local/vultron/vultron-*.js. Jeśli po instalacji nie widzisz kart, przejdź do: Ustawienia → Pulpity sterujące → Trzy kropki → Zasoby i upewnij się, że wpisy dla Vultrona są obecne na liście.

📊 Konfiguracja Kart Dashboardu

Po uruchomieniu dodatku sensory zostaną utworzone automatycznie (np. sensor.vultron_oceny_jan_kowalski). Dodaj nową kartę (Manual Card) na swoim Dashboardzie, korzystając z poniższych wzorów:

📅 Plan Lekcji (Tabelaryczny z nawigacją)

type: custom:vultron-card
entity: sensor.vultron_plan_jan_kowalski_curr
freq_entity: sensor.vultron_freq_jan_kowalski

📈 Oceny Cząstkowe

type: custom:vultron-grades-card
entity: sensor.vultron_oceny_jan_kowalski_p2 # tu sensor ma p1 okres 1 i p2 okres 2
default_sort: date or subject
limit: 10   #0 - pokazuje wszystkie

Karta posiada trzy widoki:

PRZEDMIOTY — oceny pogrupowane według przedmiotu ze średnią oraz ocenami proponowaną i końcową
NAJNOWSZE — wszystkie oceny posortowane chronologicznie
KOŃCOWE — oceny proponowane i końcowe w postaci cyfr (1–6) dla wszystkich przedmiotów wraz ze średnimi (bez Zachowania)

✉️ Wiadomości (Licznik i Lista)

type: custom:vultron-messages-card
entity: sensor.vultron_wiadomosci_jan_kowalski
limit: 10   #0 - pokazuje wszystkie

💬 Uwagi i Pochwały

type: custom:vultron-uwagi-card
entity: sensor.vultron_uwagi_jan_kowalski
default_sort: desc or asc
limit: 10   #0 - pokazuje wszystkie

🎒 Terminarz (Sprawdziany i Zadania)

type: custom:vultron-work-card
entity: sensor.vultron_terminarz_jan_kowalski
default_sort: desc or asc
limit: 10   #0 - pokazuje wszystkie

✔️ Frekwencja

type: custom:vultron-stats-card
entity: sensor.vultron_stats_jan_kowalski

👩‍🏫 Zebrania

type: custom:vultron-zebrania-card
entity: sensor.vultron_zebrania_jan_kowalski

🧸 Przedszkole — Plan Zajęć (Tabelaryczny z nawigacją)

type: custom:vultron-przedszkole-plan-card
entity: sensor.vultron_przedszkole_plan_jan_kowalski_curr

Karta sama dogrywa _prev/_next przy przełączaniu strzałkami - w konfiguracji podajesz tylko encję z sufiksem _curr, ale wszystkie trzy encje (_prev, _curr, _next) muszą istnieć dla danego dziecka.

🧸 Przedszkole — Obecność (Kalendarz miesięczny + godziny)

type: custom:vultron-przedszkole-obecnosc-card
entity: sensor.vultron_przedszkole_obecnosc_jan_kowalski

Zakładka "Kalendarz" pokazuje historię 31 dni (tylko dni robocze Pon-Pt, weekendy pominięte) z możliwością przeglądania miesięcy. Zakładka "Godziny" pokazuje zawsze bieżący miesiąc z dokładną godziną wejścia/wyjścia i wyliczonym czasem pobytu.

🧸 Przedszkole — Jadłospis

type: custom:vultron-przedszkole-jadlospis-card
entity: sensor.vultron_przedszkole_jadlospis_jan_kowalski

Zakładki Dziś/Jutro, posiłki rozwijane po kliknięciu (skład i alergeny). Wartości odżywcze celowo nieuwzględnione — przekraczały limit rozmiaru encji Home Assistant.

🧸 Przedszkole — Zebrania

type: custom:vultron-przedszkole-zebrania-card
entity: sensor.vultron_przedszkole_zebrania_jan_kowalski

🧸 Przedszkole — Opłaty

type: custom:vultron-przedszkole-oplaty-card
entity: sensor.vultron_przedszkole_oplaty_jan_kowalski

Ze względów bezpieczeństwa numer konta bankowego i tytuł przelewu NIE są publikowane jako atrybuty encji (trafiają wyłącznie do lokalnej bazy vultron.db) — karta pokazuje tylko kwoty i status.

🧸 Przedszkole — Informacje o placówce

type: custom:vultron-przedszkole-informacje-card
entity: sensor.vultron_przedszkole_informacje_jan_kowalski

🧸 Przedszkole — Nauczyciele

type: custom:vultron-przedszkole-nauczyciele-card
entity: sensor.vultron_przedszkole_nauczyciele_jan_kowalski

🧸 Przedszkole — Wiadomości

type: custom:vultron-przedszkole-wiadomosci-card
entity: sensor.vultron_przedszkole_wiadomosci_jan_kowalski

🍀 Szczęśliwy Numerek

type: custom:vultron-szczesliwy-numerek-card
entity: sensor.vultron_szczesliwy_numerek_jan_kowalski

🏆 Osiągnięcia

type: custom:vultron-osiagniecia-card
entity: sensor.vultron_osiagniecia_jan_kowalski

mozna też użyć

- type: gauge
  entity: sensor.vultron_stats_jan_kowalski
  min: 0
  max: 100
  name: Frekwencja Jan Kowalski
  needle: true
  severity:
    green: 80
    yellow: 50
    red: 0

🔍 Monitoring

Oblicza sumaryczny rozmiar atrybutów wszystkich encji sensor.vultron_* w Home Assistant (w bajtach). Tworzy szczegółowy raport z rozmiarem każdej encji. Generuje listę ostrzeżeń dla encji przekraczających próg ostrzegawczy (14 000 B). Cel: wczesne wykrycie dużych encji, które mogą spowolnić HA lub przekroczyć limity ~16 kB. Sensory tworzone automatycznie i automatycznie aktualizowane.

sensor.vultron_system_monitor
binary_sensor.vultron_rozmiar_alert

Aby zwizualizować wartości monitoringu, użyj karty markdown dla sensor.vultron_system_monitor

type: markdown
content: >
  <table> {%- set szczegoly = state_attr('sensor.vultron_system_monitor',
  'szczegoly') -%} {%- set last_update =
  state_attr('sensor.vultron_system_monitor', 'last_update') -%} {%- if
  szczegoly -%}
    {%- for item in szczegoly.split(' | ') -%}
      {%- set dane = item.split(': ') -%}
      <tr>
        <td style="padding: 0px 15px 0px 0px; border: none;">{{ dane[0].replace('sensor.vultron_', '') }}</td>
        <td style="padding: 0px; border: none; text-align: right;"><b>{{ dane[1].replace('B', ' B') }}</b></td>
      </tr>
    {%- endfor -%}
    <tr>
      <td colspan="2" style="padding: 4px 0px 0px 0px; border: none; font-size: 0.8em; color: gray;">
        🕐 {{ last_update }}
      </td>
    </tr>
  {%- endif -%} </table>

  {% if is_state('binary_sensor.vultron_rozmiar_alert', 'on') -%} ### ⚠️
  OSTRZEŻENIE! Przekroczono próg 15 500 B dla co najmniej jednej encji. Sprawdź listę powyżej. {%- endif %}

aby zwizualizować alarm, użyj karty encji dla binary_sensor.vultron_rozmiar_alert

type: tile
entity: binary_sensor.vultron_rozmiar_alert
vertical: false
features_position: bottom

🔄 Automatyzacja

IMPLEMENTUJ PO TYM JAK DODATEK WYKONA CAŁY JEDEN CYKL bo inaczej wszystko bedzie powiadomieniem.

🔄 Automatyzacje (Blueprints)

Zapomnij o ręcznym kopiowaniu kodu YAML. Dzięki Blueprints (Schematom) możesz skonfigurować powiadomienia o ocenach, nieobecnościach czy wiadomościach w kilka sekund za pomocą prostego interfejsu graficznego.

🎓 Jak używać?

Kliknij przycisk Importuj przy wybranym schemacie.
Zatwierdź import w swojej instancji Home Assistant.
Wybierz odpowiedni sensor Twojego dziecka (np. sensor.vultron_oceny_jan_kowalski).
Wybierz telefon, na który mają przychodzić powiadomienia, i kliknij Zapisz.

📦 Vultron Alert Pack

Funkcja	Opis	Import
Nowe Oceny	Zaawansowane powiadomienia o ocenach (obsługuje wiele ocen naraz).
Frekwencja	Alert o nieobecnościach i spóźnieniach z nazwą przedmiotu z planu.
Zmiana Planu	Powiadomienia o zastępstwach, odwołanych lekcjach i przeniesieniach.
Uwagi i Pochwały	Informacja o zachowaniu dziecka z automatycznym doborem emoji (`🌟`/`⚠️`).
Wiadomości	Powiadomienie o nowej wiadomości od nauczyciela lub dyrekcji.

💡 Personalizacja powiadomień

W sekcji Akcje każdego Blueprintf-a możesz używać dynamicznych zmiennych, aby dostosować treść powiadomienia:

Oceny: {{ uczen }}, {{ przedmiot }}, {{ ocena }}, {{ opis }}, {{ data }}
Frekwencja: {{ uczen }}, {{ wiadomosc }}
Zmiana Planu: {{ uczen }}, {{ wiadomosc }}
Uwagi: {{ uczen }}, {{ kategoria }}, {{ tresc }}, {{ autor }}, {{ wiadomosc }}
Wiadomości: {{ uczen }}, {{ nadawca }}, {{ temat }}, {{ wiadomosc }}

Przykład wiadomości: {{ uczen }} otrzymał ocenę {{ ocena }} z przedmiotu {{ przedmiot }}!

🛑 Node-RED

Do działania wymagany jest node-red-contrib-home-assistant-websocket dla Node-RED. (najprościej zainstalować poprzez manage-palette)

Poniższe automatyzacje instaluje się poprzez import i wklej :D

W plikach

plan.json - powiadomienia o zmianach w planie
frekwencja.json - powiadomienia o zmianach we frekwencji
oceny.json - powiadomienia o zmianach w ocenach
terminarz.json - powiadomienia o zmianach w zadaniach domowych/sprawdzianach
uwagi.json - powiadomienia o zmianach w uwagach
wiadomosci.json - powiadomienia o nowych wiadomościach
patusek.json - wyjście do "odłącz prąd i zablokuj MAC" :D

odszukaj sekcję entities i zmień nazwę sensora.

...
[
    {
        "id": "vultron_plan_trigger",
        "type": "server-state-changed",
        "z": "vultron_grades_flow",
        "name": "Zmiana w Planie",
        "server": "a8398b8a.edbcf8",
        "version": 6,
        "outputs": 1,
        "exposeAsEntityConfig": "",
        "entities": {
            "entity": [
                "sensor.vultron_plan_jan_kowalski" <-- TU WPISZ SWOJĄ ENCJE
                moze byc tu druga encja w przypadku planu _curr,_next oraz ocen p1,p2
            ],
            "substring": [],
            "regex": []
        },
...

🏠 HA Automations

Najprosciej dodać:

Ustawienia → Automatyzacje oraz sceny → Utwórz automatyzację → Utwórz nową automatyzację → ⋮ → Edycja w YAML → Wklej i zmień "entity"

plan.yaml - powiadomienia o zmianach w planie
frekwencja.yaml - powiadomienia o zmianach we frekwencji
oceny.yaml - powiadomienia o zmianach w ocenach
uwagi.yaml - powiadomienia o zmianach w uwagach
wiadomosci.yaml - powiadomienia o nowych wiadomościach

...
alias: "Vultron: Alert Frekwencji"
description: ""
triggers:
  - entity_id:
      - sensor.vultron_freq_jan_kowalski <-- TU WPISZ SWOJĄ ENCJE
    attribute: wpisy
    trigger: state
actions:
...

📸 Próbki/screenshoty

📚 Plan lekcji

📅 Terminarz

📊 Frekwencja

📝 Oceny

💬 Wiadomości

⚠️ Uwagi

📊 Monitoring

🍀 Szczęśliwy Numerek (podgląd)

⚠️ Debugowanie

Jeśli napotkasz problemy z logowaniem:

Sprawdź zakładkę Logi dodatku. Wszystkie błędy są tam opisywane w czasie rzeczywistym.

🪲 Zgłaszanie błędów i Bezpieczeństwo

Znalazłeś błąd lub masz pomysł na nową funkcję? Postępuj zgodnie z poniższymi krokami:

Błędy bezpieczeństwa (Security): Jeśli znalazłeś lukę dotyczącą haseł, sesji, wycieku danych lub prywatności, NIE OTWIERAJ publicznego zgłoszenia w Issues. Przeczytaj naszą politykę 🛡️ SECURITY.md i postępuj zgodnie z zawartą tam instrukcją prywatnego zgłoszenia.
Błędy techniczne (Bugs): Jeśli błąd nie dotyczy bezpieczeństwa (np. błąd w planie lekcji, błąd w karcie UI):
- Sprawdź, czy problem nie został już zgłoszony w GitHub Issues.
- Jeśli nie, otwórz nowe zgłoszenie tutaj.
Sugestie (Features): Masz pomysł na nową funkcję? Otwórz zgłoszenie typu "Feature Request" w zakładce Issues.

🗑️ Odinstalowanie

Jeśli zdecydujesz się usunąć dodatek:

Odinstaluj Vultron w zakładce Dodatki.
Ręcznie usuń folder /config/www/vultron.
Usuń wpisy kart (filtr po vultron_) w Ustawienia → Pulpity sterujące → Zasoby

⚖️ Nota prawna

Important

Projekt Vultron jest narzędziem edukacyjnym i służy TYLKO wyłącznie do użytku prywatnego. Autor nie bierze odpowiedzialności za ewentualne blokady kont, błędy w synchronizacji danych czy inne konsekwencje wynikające z automatyzacji dostępu do portalu EduVulcan.pl. Korzystasz z dodatku na własną odpowiedzialność.

🏚️️ Łamanie prawa

Important

Używanie projektu jest jawnym łamaniem regulaminu EduVulcan.pl. Nie rób tego.

Name		Name	Last commit message	Last commit date
.github		.github
automation		automation
lovelace		lovelace
samples		samples
tests		tests
vultron		vultron
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
GDANSK.md		GDANSK.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
compose.yaml		compose.yaml
icon.png		icon.png
logo.png		logo.png
package-lock.json		package-lock.json
package.json		package.json
repository.yaml		repository.yaml
ruff.toml		ruff.toml

Latest commit

History

Folders and files

Repository files navigation

⚠️ BARDZO WAŻNE: KROKI PRZED INSTALACJĄ

Aby aplikacja zadziałała prawidłowo, musisz najpierw wykonać te 3 kroki:

1. Zaloguj się na swoje konto przez stronę WWW.

2. Zaakceptuj nowe regulaminy i zgody (cookies).

3. Przełącz się na profil KAŻDEGO ze swoich dzieci i kliknij w dowolną zakładkę (cokolwiek!).

🛑 DOPIERO WTEDY MOŻESZ ZAINSTALOWAĆ APLIKACJĘ! 🛑

⛔ UWAGA: Problemy wynikające z pominięcia tych kroków nie są błędami aplikacji. Prosimy nie zakładać zgłoszeń (Bug / Issue), jeśli nie wykonałeś powyższej instrukcji. Szanujmy swój czas i Wasz!

Vultron (Jungfru)

🙏 Co-authored-by:

📖 Spis treści

🚨🚨🚨 Achtung Achtung 🚨🚨🚨

🧩 Changelog

✨ Główne Funkcje

🏗️ Architektura Systemu

🚀 Instalacja

🚨 Metoda 1: Automatyczna (Zalecana)

🚨 Coś popsuli w HA :D

💾 Wymagania sprzętowe (ważne dla Raspberry Pi)

🐳 Samodzielny kontener Docker

Vultron w Dockerze — przewodnik "krok po kroku dla każdego"

Zanim zaczniesz — co będzie Ci potrzebne

Krok 1: Zdobądź "przepustkę" dla Vultrona do Home Assistant

Krok 2: Otwórz terminal (czarne okienko z tekstem)

Krok 3: Ściągnij pliki Vultrona na dysk

Krok 4: Przygotuj dwa foldery na Twoje dane

Krok 5: Zapisz token w pliku

Krok 6: Zapisz dane do logowania do eduVULCAN

Krok 7: Przygotuj miejsce na "karty" (ładny wygląd danych w Home Assistant)

Krok 8: Sprawdź jedną rzecz w ustawieniach Home Assistant

Krok 9: Stwórz plik z instrukcjami dla Dockera

Krok 10: Podłącz Home Assistant do specjalnej "sieci" dla Vultrona

Krok 11: Uruchom Vultrona

Krok 12: Sprawdź, czy działa

Krok 13: Zobacz swoje dane w Home Assistant

Coś nie działa? Sprawdź to

Widzę czerwony napis "Permission denied" (odmowa dostępu)

Karty w Home Assistant są puste albo nic się nie pokazuje

Vultron ciągle się restartuje / wyłącza

Nie wiem, jaki adres wpisać przy HA_URL

To wszystko!

⚙️ Konfiguracja

💡 Ważna uwaga dotycząca kart UI i odświeżania

1. "Zwykłe" Odświeżanie vs "Twarde" Odświeżanie

2. Kiedy wyczyścić ciasteczka i dane strony?

3. Rejestracja Zasobów

📊 Konfiguracja Kart Dashboardu

📅 Plan Lekcji (Tabelaryczny z nawigacją)

📈 Oceny Cząstkowe

✉️ Wiadomości (Licznik i Lista)

💬 Uwagi i Pochwały

🎒 Terminarz (Sprawdziany i Zadania)

✔️ Frekwencja

👩‍🏫 Zebrania

🧸 Przedszkole — Plan Zajęć (Tabelaryczny z nawigacją)

🧸 Przedszkole — Obecność (Kalendarz miesięczny + godziny)

🧸 Przedszkole — Jadłospis

🧸 Przedszkole — Zebrania

🧸 Przedszkole — Opłaty

🧸 Przedszkole — Informacje o placówce

🧸 Przedszkole — Nauczyciele

🧸 Przedszkole — Wiadomości

🍀 Szczęśliwy Numerek

🏆 Osiągnięcia

🔍 Monitoring

🔄 Automatyzacja

🔄 Automatyzacje (Blueprints)

🎓 Jak używać?

📦 Vultron Alert Pack

💡 Personalizacja powiadomień

🛑 Node-RED

🏠 HA Automations

📸 Próbki/screenshoty

📚 Plan lekcji

📅 Terminarz

📊 Frekwencja

📝 Oceny

1. Zaloguj się na swoje konto przez stronę `WWW`.

Nie wiem, jaki adres wpisać przy `HA_URL`