====== Lokal watchdog och fallback vid överstyrning via Miner ======

När Miner används för kontinuerlig överstyrning av ett värmesystem rekommenderas att det lokala styrsystemet kompletteras med en lokal watchdog- och fallbackfunktion. Funktionen kan implementeras i styrprogramvaran i DUC/PLC eller i det lokala överordnade systemet.

Miner har en inbyggd funktion för [[projektering:larmhantering|fallbackhantering]]. Den lokala funktionen är ett komplement till denna och är särskilt viktig när Miner inte körs i samma nätverk som det lokala styrsystemet. Vid exempelvis kommunikationsavbrott, nätverksfel eller stoppad Miner-tjänst ska det lokala systemet självständigt kunna avbryta överstyrningen och återgå till normal lokal reglering.

Grundprincipen är att den senast mottagna externa överstyrningen endast får vara aktiv så länge kommunikationen med Miner kan verifieras. Ett senast mottaget börvärde får därför inte ligga kvar obegränsat vid kommunikationsbortfall.

===== Rekommenderad funktionsprincip =====

  - Miner skriver önskad börvärdesförskjutning till ''OFFSET''.
  - Miner sätter ''WATCHDOG_VALUE'' till ''1'' minst en gång under varje watchdogcykel.
  - När tiden i ''WATCHDOG_TIMER'' har löpt ut kontrollerar det lokala styrsystemet att ''WATCHDOG_VALUE'' har värdet ''1''.
  - Om watchdog-signalen har rätt värde och ''OFFSET'' ligger inom ''OFFSET_MIN'' och ''OFFSET_MAX'' får den externa börvärdesförskjutningen användas.
  - Det lokala styrsystemet sätter därefter ''WATCHDOG_VALUE'' till ''0'', verifierar nollställningen och startar en ny watchdogcykel.
  - Om ''WATCHDOG_VALUE'' inte är ''1'' vid kontrollen, eller inte kan nollställas, ska den externa överstyrningen avaktiveras. Systemet ska då återgå till ordinarie lokal reglering och en definierad lokal fallback, normalt utan extern börvärdesförskjutning.
  - Lokala skydds-, begränsnings- och säkerhetsfunktioner ska alltid ha högre prioritet än den externa överstyrningen.

Det är viktigt att det lokala styrsystemet verifierar att ''WATCHDOG_VALUE'' verkligen har återgått till ''0''. Annars kan en signal som har fastnat i läge ''1'' felaktigt tolkas som fungerande kommunikation. Skrivintervallen ska dessutom samordnas så att det lokala systemet hinner nollställa och verifiera signalen innan Miner sätter den till ''1'' på nytt.

<mermaid>
  flowchart TD
    A["Lokalt system sätter WATCHDOG_VALUE = 0"] --> B{"Nollställningen verifierad?"}
    B -- Nej --> H["Avaktivera extern överstyrning"]
    B -- Ja --> C["Starta ny watchdogcykel"]
    C --> D["Miner skriver OFFSET och sätter WATCHDOG_VALUE = 1"]
    D --> E{"WATCHDOG_VALUE = 1 när WATCHDOG_TIMER löper ut?"}
    E -- Nej --> H
    E -- Ja --> F{"OFFSET inom tillåtna gränser?"}
    F -- Nej --> H
    F -- Ja --> G["Använd extern börvärdesförskjutning"]
    G --> A
    H --> I["Ordinarie lokal reglering tar över"]
    I --> A
</mermaid>

===== Datapunkter =====

Följande datapunkter rekommenderas för funktionen. Punktbeteckningarna är exempel och ska anpassas till projektets beteckningssystem.

^ Datapunkt/funktion ^ Beskrivning ^ Datatyp ^ Enhet/skalning ^ Exempel på punktbeteckning ^
| ''WATCHDOG_VALUE'' | Watchdog-signal som Miner sätter till ''1'' och det lokala styrsystemet återställer till ''0'' inför nästa cykel. | Digital (Bool) | 0/1 | ''BY01_VS1_GT11_WD'' |
| ''WATCHDOG_TIMER'' | Tidsintervall mellan det lokala styrsystemets kontroller av watchdog-signalen. | Integer | Sekunder, 1–900 | ''BY01_VS1_GT11_WD_FL'' |
| ''OFFSET'' | Begärd börvärdesförskjutning från Miner. | Real (Float) | °C | ''BY01_VS1_GT11_BVF'' |
| ''OFFSET_MAX'' | Högsta tillåtna börvärdesförskjutning. | Real (Float) | °C | ''BY01_VS1_GT11_BVFMAX'' |
| ''OFFSET_MIN'' | Lägsta tillåtna börvärdesförskjutning. | Real (Float) | °C | ''BY01_VS1_GT11_BVFMIN'' |

==== Krav på konfigurering ====

  * **Negativa värden:** ''OFFSET'' och ''OFFSET_MIN'' ska konfigureras så att negativa värden kan hanteras. Detta krävs för att Miner ska kunna sänka det ordinarie börvärdet.
  * **Watchdog-timer:** ''WATCHDOG_TIMER'' ska kunna konfigureras inom intervallet 1–900 sekunder. Miner ska hinna sätta ''WATCHDOG_VALUE'' till ''1'' med god marginal innan varje cykel löper ut, så att enstaka fördröjda meddelanden inte orsakar onödig fallback.
  * **Nollställning av watchdog:** Det lokala styrsystemet ska efter varje kontroll sätta ''WATCHDOG_VALUE'' till ''0'' och verifiera att nollställningen har genomförts. Om nollställningen misslyckas ska watchdog-funktionen betraktas som felaktig och lokal fallback aktiveras.
  * **Samordning av skrivintervall:** Miner får inte skriva ''1'' så tätt att det lokala styrsystemets nollställning och verifiering riskerar att skrivas över. Intervallen ska fastställas och dokumenteras för varje projekt.
  * **Datatyper och skalning:** Samtliga datapunkter ska ha rätt datatyp, teckenhantering och skalning från start. Samma definitioner ska användas i Miner, kommunikationsgränssnittet och det lokala styrsystemet.
  * **Gränskontroll:** ''OFFSET'' ska valideras mot ''OFFSET_MIN'' och ''OFFSET_MAX'' innan värdet används. Ett ogiltigt värde får inte kringgå lokala begränsningar.
  * **Fallbackvärde:** Det ska vara tydligt definierat vad systemet återgår till vid utebliven eller felaktig watchdog-signal. Rekommenderat normalfall är att den externa förskjutningen tas bort och att den ordinarie lokala regleringen återtar kontrollen. Om förskjutningen är stor rekommenderas att återgången till det lokalt beräknade börvärdet sker mjukt genom så kallad ''rampning'', för att minska risken för effekttoppar.

===== Exempel på styrlogik =====

Nedanstående pseudokod visar principen. Den exakta implementationen anpassas till aktuell DUC, PLC eller överordnat system.

<code>
Vid initiering:
    sätt WATCHDOG_VALUE = 0
    verifiera att WATCHDOG_VALUE = 0
    starta WATCHDOG_TIMER

När WATCHDOG_TIMER har löpt ut:
    watchdog_ok = WATCHDOG_VALUE = 1
    offset_ok   = OFFSET >= OFFSET_MIN och OFFSET <= OFFSET_MAX

    sätt WATCHDOG_VALUE = 0
    reset_ok = verifiera att WATCHDOG_VALUE = 0

    om watchdog_ok och offset_ok och reset_ok:
        använd OFFSET som extern börvärdesförskjutning
    annars:
        avaktivera den externa överstyrningen
        använd lokal fallback och ordinarie lokal reglering

    starta nästa watchdogcykel
</code>

När kommunikationen återkommer bör den externa överstyrningen inte återaktiveras förrän en fullständig watchdogcykel har genomförts med korrekt värde på ''WATCHDOG_VALUE'', lyckad nollställning och ett giltigt ''OFFSET''. Återstartssekvensen ska vara definierad och avprovad för både Miner och det lokala styrsystemet.

===== Avprovning =====

Funktionen bör minst provas för följande händelser:

  * normal watchdogcykel där Miner sätter ''WATCHDOG_VALUE'' till ''1'' och det lokala styrsystemet återställer signalen till ''0'';
  * normal överstyrning med både positivt och negativt ''OFFSET'';
  * ''OFFSET'' under ''OFFSET_MIN'' respektive över ''OFFSET_MAX'';
  * avbruten nätverkskommunikation;
  * stoppad Miner-tjänst;
  * omstart av Miner och omstart av det lokala styrsystemet;
  * återgång, inklusive eventuell rampning, till ordinarie lokal reglering efter felaktig watchdog-signal; samt
  * kontrollerad återaktivering när kommunikationen har återställts.

Resultatet av avprovningen, valt watchdogintervall och definierat fallbackbeteende bör dokumenteras i projektets relationshandlingar.