Skip to content
 
 

Repository files navigation

GitHub release GitHub last commit Maintenance GitHub license GitHub issues Add-on Repository Security Scan Python Security Docker Linter Vulnerability Scan Secret Scan Bash Scan Lint & Semgrep Python Selenium SQLite Dependabot Open in VS Code Vultron Developerzy mile widziani

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

 

Wychodzi na to ze eduvulcan.pl serwuje dwie lub wiecej wersji zalezne od CDN.

⚠️ 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)

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.

Autor: AI i Tomasz H.
Wersja: 7.0.5.1
Nazwa Kodowa: Jungfru ♍

📖 Spis treści

🚨🚨🚨 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.
  • 📊 Monitoring: Monitoring 16KB.
  • 🛠️ 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
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ęć. 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.
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:

Dodaj repozytorium do Home Assistant

🚨 Coś popsuli w HA :D

Jezeli powyzszy link nie dziala to uzyj: 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ę:

  1. Zainstaluj dodatek SSH & Web Terminal.
  2. Po instalacji wyłącz Protection mode oraz włącz Show in sidebar.
  3. Wejdź w dodatek SSH i przejdź do folderu addons:
cd /addons
  1. Sklonuj repozytorium:
git clone https://github.com/htomasz/vultron.git
  1. 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.


⚙️ 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)
  1. Kliknij Zapisz.
  2. 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

🍀 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ć wartosci monitoringu uzyj 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 zwizualizowac alarm uzyj 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ć?

  1. Kliknij przycisk Importuj przy wybranym schemacie.
  2. Zatwierdź import w swojej instancji Home Assistant.
  3. Wybierz odpowiedni sensor Twojego dziecka (np. sensor.vultron_oceny_jan_kowalski).
  4. 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). Importuj Blueprint
Frekwencja Alert o nieobecnościach i spóźnieniach z nazwą przedmiotu z planu. Importuj Blueprint
Zmiana Planu Powiadomienia o zastępstwach, odwołanych lekcjach i przeniesieniach. Importuj Blueprint
Uwagi i Pochwały Informacja o zachowaniu dziecka z automatycznym doborem emoji (🌟/⚠️). Importuj Blueprint
Wiadomości Powiadomienie o nowej wiadomości od nauczyciela lub dyrekcji. Importuj Blueprint

💡 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 zainstalowac poprzez manage-palette)

Ponizsze automatyzacje instaluje się poprzez import i wklej :D

W plikach

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 zmien "entity"

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

Plan lekcji

📅 Terminarz

Terminarz

📊 Frekwencja

Frekwencja

📝 Oceny

Oceny1 Oceny3

💬 Wiadomości

Wiadomości

⚠️ Uwagi

Uwagi

📊 Monitoring

Monitoring

🍀 Szczęśliwy Numerek

Numerek

⚠️ Debugowanie

Jeśli napotkasz problemy z logowaniem:

  1. 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:

  1. 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.

  2. 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.
  3. 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:

  1. Odinstaluj Vultron w zakładce Dodatki.
  2. Ręcznie usuń folder /config/www/vultron.
  3. 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.

About

nieEduvulcan for HA

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages