Zařízení¶

Zařízení jsou fyzické prvky (zámky, světla, zásuvky) připojené k systému Dveřník.

Typy zařízení¶

Role zařízení v zóně¶

Každé zařízení je přiřazeno k zóně přes kolekci zone_devices s jednou ze dvou rolí:

Primární zařízení (primary)¶

• Řídí přístup do zóny (typicky zámek)
• Každá zóna musí mít alespoň jedno primární zařízení
• Při zahájení relace se odemkne
• Při odchodu posledního uživatele se zavře
• Určuje, zda je zóna "obsazena"

Sekundární zařízení (secondary)¶

• Doplňková zařízení (světla, zásuvky)
• Zapínají se při zahájení relace
• Vypínají se při ukončení relace
• Uživatelé je mohou během relace ovládat manuálně

Režimy zámku (lock_mode)¶

Primární zařízení typu lock mají nastavení režimu:

Režim zámku se uplatňuje vždy — jak při zahájení relace, tak při manuálním ovládání během relace.

Komunikační adaptéry¶

Každé zařízení má nastavený komunikační adaptér, který určuje jak systém komunikuje s fyzickým hardwarem.

Demo adaptér (demo)¶

Simuluje zařízení pro vývoj a testování. Stav se ukládá do kolekce app_config.

Konfigurace: adapter_config = null nebo libovolný JSON objekt (např. {}) — obsah se ignoruje.

Stav zařízení v app_config:

• demo_lock_state_{device_id} — hodnoty: "open", "close"
• demo_light_state_{device_id} — hodnoty: "on", "off"
• demo_outlet_state_{device_id} — hodnoty: "on", "off"

REST API adaptér (rest_api)¶

Komunikuje s hardwarem přes HTTP. Koncové zařízení (Raspberry Pi, ESP, …) je „hloupý“ GPIO řadič — nic neví o zámcích ani světlech. Veškerý význam akcí je v adapter_config, kde pin_mapping říká, které piny se mají při které akci nastavit.

Adaptér mluví s řadičem dvěma endpointy:

HTTP klient má timeout 15 sekund.

Příklad — zámek:

{
  "base_url": "http://192.168.1.50:9999",
  "auth_header": "Bearer váš-token",
  "pin_mapping": {
    "open":       {"pins": [{"pin": 4, "state": "on"}]},
    "close":      {"pins": [{"pin": 4, "state": "off"}]},
    "short_open": {"pins": [{"pin": 4, "state": "on", "duration_ms": 5000}]}
  },
  "status_pin": 4
}

Jiné klíče na nejvyšší úrovni nejsou povoleny.

Pin v pins (pole s alespoň jedním prvkem):

Klíče pin_mapping mohou být pouze open, close, short_open, on, off, blink. Které jsou povinné a které povolené, závisí na typu zařízení:

Stav zařízení se odvozuje z status_pin a mapování: pokud pin 4 je u open ve stavu on, znamená on na pinu 4 „otevřeno“. Podporuje tak jakoukoli konvenci zapojení — viz invertovaný zámek v předvolbách (on = zavřeno).

Kontrola konfigurace při uložení¶

Při vytvoření zařízení a při změně adapter_config, communication_adapter nebo device_type systém konfiguraci zkontroluje a při chybě zařízení neuloží; chyba obsahuje cestu k problému, např. pin_mapping.open.pins[0].state. Kontrola je pouze strukturální — nezjišťuje, zda je zařízení dostupné ani zda je aktivní. Neaktivní (ještě nezapojené) zařízení tak lze předem nakonfigurovat, ale musí mít stejně platnou konfiguraci.

Stávající zařízení se tím nerozbijí. Běh systému (sestavení adaptéru, ovládání, heartbeat) se nezměnil. U zařízení, jehož uložená konfigurace dnešním pravidlům neodpovídá, funguje dál přejmenování, aktivace/deaktivace i změna jiných polí — kontrola se spustí, až když změníte některé z výše uvedených tří polí. Přehled takových zařízení ukazuje kontrola stavu konfigurace.

Znak CHANGE_ME v hodnotě (např. Bearer CHANGE_ME z předvolby) vyvolá jen upozornění — uložit lze, ale zařízení s placeholderem nebude komunikovat, dokud hodnotu nenahradíte.

MQTT adaptér (mqtt)¶

Není implementován. Volba zůstává v databázi kvůli zpětné kompatibilitě, ale ve formuláři se nenabízí (zobrazí se jen u zařízení, které ji již má) a nové zařízení ani změnu konfigurace s ním systém neuloží.

Akce zařízení¶

Všechny příkazy jsou explicitní — systém nikdy nepoužívá "toggle". Vždy se posílá konkrétní příkaz (OPEN/CLOSE, ON/OFF).

Stav zařízení v panelu relace¶

Panel aktivní relace ukazuje u zařízení stav (Svítí / Zhasnuto / Otevřeno / Zamčeno) jen tehdy, když ho adaptér skutečně potvrdil — to znamená, že dotaz na stav zařízení proběhl bez chyby a vrátil jiný stav než unknown. Jinak panel žádný stav nezobrazí a místo toho napíše poslední známý příkaz („Naposledy: zapnuto 18:02“).

Poslední příkaz se bere z action_logs napříč všemi relacemi (zařízení mohl mezitím přepnout jiný uživatel, cron nebo ukončení relace). Příkaz blink se nepočítá — stav zapnuto/vypnuto nepřepisuje. Chcete-li, aby panel ukazoval skutečný stav i u REST zařízení, nastavte status_pin.

Dotazy na stav se krátce (3 s) cachují, aby časté obnovování dashboardu nezatěžovalo řadič. Po úspěšném příkazu se cache daného zařízení hned zahodí.

Online / offline zařízení (heartbeat)¶

Cron úloha (výchozí interval DEVICE_HEARTBEAT_INTERVAL_MINUTES = 5 min) ověřuje dostupnost každého aktivního zařízení a ukládá čas posledního úspěšného ověření. Zařízení je online, jen pokud má platný heartbeat (ne starší než DEVICE_HEARTBEAT_TIMEOUT_MINUTES, výchozí 15 min); bez důkazu se nikdy neoznačí jako online.

• REST API adaptér: heartbeat je autorizovaný dotaz GET /gpio/status na řadič. Provádí se vždy, i když zařízení nemá status_pin — status_pin ovlivňuje jen to, zda lze z odpovědi zjistit stav (zapnuto/vypnuto), nikoli zda je zařízení dostupné. Úspěchem je odpověď HTTP 200; chyba spojení, timeout (5 s na zařízení) nebo jiný HTTP kód heartbeat neobnoví, takže zařízení po vypršení timeoutu přejde na offline.
• Demo adaptér: je vždy dostupný (simuluje se v databázi).

Zařízení se kontrolují postupně, každé nejvýše 5 s, takže nedostupné zařízení zdržuje běh jen o tento limit.

Auditní log¶

Každá akce zařízení se zaznamenává do action_logs s:

• ID relace
• ID zařízení
• Typ akce
• Kdo akci vyvolal (uživatel / systém)
• Časová značka
• Metadata (jméno uživatele, doba trvání)
• Výsledek příkazu (status, failure_reason, error_detail)

Výsledek příkazu¶

Do action_logs se zapisuje každý pokus o příkaz zařízení, i ten nepovedený. Sloupec status má hodnoty:

U failed je v failure_reason důvod: timeout (zařízení neodpovědělo včas), unreachable (spojení se nepodařilo navázat), device_rejected (zařízení vrátilo chybu), config_error (chybí pin_mapping pro danou akci nebo je neplatný) a unknown. Pole error_detail (max. 1024 znaků, bez přihlašovacích údajů v URL a tokenů) obsahuje technický detail — HTTP status a tělo odpovědi zařízení — a vidí ho jen administrátor (admin tabulka akcí a časová osa relace); uživatel vidí jen přeložený důvod.

Neúspěšné pokusy nemění cenu relace: cena se počítá jen ze záznamů, které nejsou failed, takže výsledná cena je stejná, jako kdyby se pokus nikdy nestal. Stejně tak neúspěšný příkaz nepřepíše „poslední příkaz“ zařízení na dashboardu. Zapisují se tyto pokusy: otevření primárních zařízení při vstupu (včetně zavíracích pokusů při vrácení vstupu zpět), tlačítka v běžící relaci, vypnutí světel a zavření zámků při ukončení relace, vypnutí světel po zavření provozu (cron) a blikání před zavřením. Záznamy mají stejnou retenci jako ostatní action_logs (90 dní); relace zrušená kvůli nepovedenému vstupu se i s těmito záznamy smaže běžným úklidem prázdných relací.