Přeskočit na hlavní obsah

Shelly Actions - Automatizace a správa zařízení

Tento repozitář obsahuje kompletní systém automatizace pro správu vašich Shelly zařízení:

  1. Export zařízení ze Shelly Cloud a audit IP konfigurace (s vyloučením TRV a H&T) do Actions/devices.json. Statická IP je vyžadována (provoz i při výpadku DHCP serveru); při nálezu zařízení na DHCP odešle e-mailové varování.
  2. Hromadná konfigurace Syslog serveru na runneru vmhome.
  3. Obousměrná správa a verzování skriptů (GitOps pro Shelly) – stažení (záloha) skriptů ze zařízení a nahrání změn zpět do Shelly při Git commitu.

📁 Struktura složek a souborů​

  • Actions/:
    • vl_logger.py: Pomocný klient pro odesílání strukturovaných logů do centrálního VictoriaLogs.
    • get_shelly_devices.py: Stáhne zařízení ze Shelly Cloudu, detekuje statické IP vs DHCP a odesílá e-mailové varování při detekci DHCP.
    • devices.json: Aktuální seznam nalezených zařízení, IP adres a příznaku static_ip.
    • dhcp_alert_report.json: Přehled zařízení s DHCP vyžadujících přepnutí na statickou IP.
    • set_shelly_syslog.py: Hromadně nastaví Syslog na zařízeních.
    • sync_scripts_from_devices.py: Stáhne všechny skripty ze zařízení do složky Devices/.
    • deploy_scripts_to_devices.py: Nahraje skripty ze složky Devices/ zpět do zařízení.
    • check_shelly_scripts.py: Zkontroluje běh skriptů s autostartem a odešle notifikaci / restartuje.
  • Devices/ (vytvoří se automaticky při prvním stažení):
    • Zařízení jsou organizována podle místností: Devices/<Místnost>/<Zařízení>/
    • Např. Devices/Loznice/Loznice_1p_display_192.168.100.66/ nebo Devices/Kotelna/Regulace-vetyl_192.168.100.31/
    • Uvnitř každého zařízení je device.json (mapování IP, ID slotů, jmen a static_ip) a samotné skripty 1_topeni.js, 2_el_dotapeni.js atd.
  • .github/workflows/:
    • shelly_fetch_devices.yml: Běží na GitHub Cloudu, stahuje devices.json, hlídá nežádoucí DHCP a odesílá e-mailové varování.
    • shelly_set_syslog.yml: Běží na vmhome, nastaví Syslog server.
    • shelly_pull_scripts.yml: Běží na vmhome, stáhne a roztřídí skripty do složek podle místností.
    • shelly_push_scripts.yml: Běží na vmhome, nasadí upravené skripty zpět do zařízení.
    • shelly_watchdog_scripts.yml: Běží na vmhome, hlídá stav skriptů a odesílá e-mailové notifikace.

🔄 Jak funguje obousměrná správa skriptů (GitOps)?​

1. Stažení skriptů ze zařízení do Gitu (Pull / Backup)​

  • Workflow: Pull Scripts from Shelly Devices (na runneru vmhome)
  • Postup:
    1. Skript projde každou IP adresu v Actions/devices.json.
    2. Zjistí místnost ze Shelly Cloud metadat nebo z názvu zařízení (Kotelna, Loznice, Kuchyne, Obyvak, Eliska, Sauna, Chodba, FVE_Solar, Venek...).
    3. Zjistí, zda zařízení podporuje Shelly Scripting (Script.List).
    4. Pokud zařízení obsahuje skripty, stáhne jejich kód po částech (Script.GetCode) a zjistí nastavení autostartu (enable).
    5. Vytvoří pro každé zařízení složku v příslušné místnosti, např: 
      Devices/
      ├── Kotelna/
      │   └── Regulace-vetyl_192.168.100.31/
      │       ├── device.json
      │       ├── 1_topeni.js
      │       └── 2_el_dotapeni.js
      └── Loznice/
          └── Loznice_1p_display_192.168.100.66/
              ├── device.json
              ├── 2_luminace.js
              ├── 3_TRV_sync_temp.js
              └── 4_TRV_sync.js
    6. Automaticky vytvoří Git commit a pushne skripty do repozitáře.

2. Nahrání upraveného skriptu zpět do Shelly (Push / Deploy)​

  • Workflow: Push Scripts to Shelly Devices (na runneru vmhome)
  • Kdy se spouští:
    • Automaticky: Když uděláte commit a push jakékoliv změny do souborů ve složce Devices/**.
    • Ručně: Přes záložku Actions na GitHubu (s volbou konkrétního zařízení nebo všech).
  • Jak skript bezpečně nahrává:
    1. Ze souboru device.json v dané složce zjistí cílovou IP adresu a ID slotu skriptu.
    2. Zastaví starý skript na zařízení (Script.Stop).
    3. Nahraje nový kód po 512B chuncích (Script.PutCode s append: true), takže bezpečně zvládne i velké 50kB+ skripty bez přetečení paměti Shelly.
    4. Zpětná kontrola integrity obsahu (Script.GetCode): Skript po nahrání načte celý obsah ze zařízení a znak po znaku porovná s lokálním souborem. Pokud by se nahrála jen část nebo došlo k chybě, nahrávání automaticky zopakuje (až 3 pokusy). Pokud kontrola neprojde, nahlásí chybu a neúplný kód nespustí!
    5. Nastaví název a autostart (Script.SetConfig).
    6. Pokud byl skript spuštěný, znovu ho nastartuje (Script.Start).

3. Automatický dohled nad skripty a e-mailové notifikace (Watchdog)​

  • Workflow: Shelly Script Watchdog & Notifications (na runneru vmhome)
  • Kdy se spouští:
    • Automaticky: Každých 30 minut přes GitHub Actions cron.
    • Ručně: Přes záložku Actions na GitHubu (s možností testovacího odeslání mailu či zapnutí auto-restartu).
  • Jak funguje:
    1. Projde IP adresy ze souboru Actions/devices.json.
    2. Zavolá Script.List a vyfiltruje skripty, které mají enable: true (autostart), ale running: false (zastaveno / pád).
    3. Pokud je zapnutý parametr auto-restartu (--restart), pokusí se skript ihned nahodit (Script.Start) a ověří stav.
    4. Při detekci problému vygeneruje přehlednou tabulku do GitHub Actions Step Summary a odešle HTML e-mail.

📧 Nastavení GitHub Secrets pro e-mailové notifikace:​

V nastavení GitHub repozitáře (Settings -> Secrets and variables -> Actions) přidejte:

  • SMTP_SERVER: Adresa SMTP serveru (např. smtp.gmail.com, smtp.seznam.cz, nebo IP lokální relay).
  • SMTP_PORT: Port (např. 587 pro STARTTLS nebo 465 pro SSL). Výchozí je 587.
  • SMTP_USERNAME: Přihlašovací jméno (váš e-mail).
  • SMTP_PASSWORD: Heslo (u Gmailu použijte Heslo aplikace / App Password).
  • NOTIFICATION_EMAIL: Cílová e-mailová adresa, kam mají chodit upozornění.
  • (Volitelné) SMTP_FROM: Odesílatel v hlavičce (výchozí je SMTP_USERNAME).

4. Centrální telemetrie a logování do VictoriaLogs​

Všechny automatizační skripty běžící na self-hosted runneru (vmhome) automaticky odesílají strukturované logy a události do centrálního systému VictoriaLogs (http://100.81.155.15:9428).

  • Knihovna: Actions/vl_logger.py (čistý Python standardní knihovny bez dalších závislostí, tichý fail-safe timeout).
  • Stream fields: app,env (např. app=action_watchdog, env=vmhome).
  • Přiřazení aplikací (app):
    • action_watchdog: Detekce zastavených autostart skriptů, výsledky automatických restartů a souhrny kontrol.
    • action_deploy: Hlášení o nasazení skriptů, selhání nahrávání a kontrola integrity.
    • action_sync: Záznamy o stažení (pull) skriptů ze zařízení do repozitáře.
    • action_syslog: Výsledky hromadné konfigurace Syslog serveru na Shelly zařízeních.
  • Konfigurační proměnné prostředí (volitelné):
    • VICTORIALOGS_URL: Vlastní URL endpointu (výchozí: http://100.81.155.15:9428/insert/jsonline?_stream_fields=app,env&_msg_field=_msg).
    • VICTORIALOGS_ENABLED: false pro dočasné vypnutí logování.