Modul MCAL IWDG

Podporované rodiny STM32: H5
Nepodporované: G4, H7, L4, U5

Tento repozitář poskytuje ovladač MCAL (Microcontroller Abstraction Layer) pro nezávislý watchdog (IWDG) používaný v mikrokontrolérech STM32.
Nabízí jednoduché a bezpečné rozhraní pro spuštění, konfiguraci a obnovování watchdogu, aniž byste se museli zabývat předděličkami, reload hodnotami či příznaky aktualizace registrů.

Každá rodina STM32 je podporována ve vyhrazené větvi tohoto repozitáře:

• STM32G4
• STM32U5
• STM32L4
• STM32H5
• a další podle potřeby.

---

📘 Přehled

Ovladač IWDG MCAL abstrahuje nezávislý watchdog STM32 do rozhraní založeného na čase.
Uživatel nakonfiguruje watchdog v milisekundách, o zbytek se postará modul:

• Výpočet předděličky (4 - 1024) a reload hodnoty z požadovaného timeoutu a frekvence LSI
• Volitelné okno - obnovení je povoleno pouze v poslední části timeoutu
• Volitelné přerušení včasného upozornění (early wakeup) - uživatelský callback zavolaný dříve, než watchdog resetuje MCU
• Automatické obnovování z Iwdg_Task() nebo ruční obnovení pomocí Iwdg_Set_Refresh()
• Načtení stavu watchdogu a dosaženého timeoutu

Zápis do registrů (klíčový registr), příznaky aktualizace registrů a zpětné ověření každého konfiguračního zápisu zajišťuje modul interně.

✅ Uživatel nemusí zahrnovat ani používat žádné další moduly, například ovladače RCC nebo NVIC.
Frekvence LSI se čte z modulu RCC a přerušení early wakeup se konfiguruje interně prostřednictvím modulu NVIC.

⚠️ Po spuštění nelze watchdog zastavit (hardwarové omezení). Zastaví ho pouze reset systému, pokud není v option bytes zvolen režim hardwarového watchdogu. Iwdg_Deinit() pouze zakáže přerušení a automatické obnovování - aplikace musí watchdog obnovovat dál.

---

🧩 Architektura

Architektura odpovídá standardnímu vrstvení MCAL používanému ve všech repozitářích MCAL pro STM32:

┌────────────────────────────┐
│        Application         │
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│           HAL              │
│(Hardware Abstraction Layer)│
└────────────┬───────────────┘
┌────────────▼───────────────┐
│       MCAL - Iwdg          │
│       ├── Iwdg_Port.h      │  
│       ├── Iwdg_Types.h     │  
│       └── Iwdg.c/.h        │  
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│           RAL              │
│(Register Abstraction Layer)│
└────────────────────────────┘

---

🧠 Pokyny k použití

Uživatel smí pracovat pouze s následujícími dvěma veřejnými hlavičkovými soubory:

Soubor	Účel
Iwdg_Port.h	Obsahuje všechny funkce veřejného API (inicializace, obnovení, načtení stavu a timeoutu, výchozí konfigurace)
Iwdg_Types.h	Obsahuje definice typů používaných v API (konfigurační struktura, typ času, typ callbacku, stavy požadavků)

Vše ostatní — tabulky předděliček, pomocné funkce, obsluha přerušení — je interní a nesmí se k tomu přistupovat přímo.

Veřejné API

Funkce	Popis
Iwdg_Get_ModuleVersion()	Vrací verzi SW modulu
Iwdg_Init( config )	Vypočítá konfiguraci, spustí a nakonfiguruje watchdog
Iwdg_Deinit()	Zakáže přerušení early wakeup a automatické obnovování (watchdog dál běží)
Iwdg_Task()	Automaticky obnovuje watchdog (pouze pokud se nepoužívá okno)
Iwdg_Get_DefaultConfig( config )	Naplní výchozí konfiguraci: timeout 1 s, bez okna, bez přerušení early wakeup
Iwdg_Get_State( state )	Vrací IWDG_FUNCTION_ACTIVE, pokud watchdog běží
Iwdg_Get_Timeout( timeout )	Vrací dosažený timeout v ms vypočtený z registrů
Iwdg_Set_Refresh()	Obnoví (znovu načte) čítač watchdogu

Konfigurace

Položka	Popis
Timeout	Požadovaný timeout v ms. S LSI 32 kHz je rozsah přibližně 1 ms - 131 s.
Window	Délka okna před timeoutem v ms, ve kterém je obnovení povoleno. IWDG_TIME_UNUSED okno zakáže. Musí být kratší než Timeout.
EarlyWakeup	Čas před timeoutem v ms, kdy se spustí přerušení early wakeup. IWDG_TIME_UNUSED přerušení zakáže. Musí být kratší než Timeout.
EarlyWakeupIsr	Uživatelský callback přerušení early wakeup, může být NULL
IrqPriority	Priorita přerušení early wakeup (0 - nejvyšší)

Neplatná konfigurace (timeout mimo rozsah, okno nebo early wakeup není kratší než timeout) je funkcí Iwdg_Init() odmítnuta dříve, než se zapíše jakýkoli registr.

Poznámky

• Režim okna - obnovení před oknem okamžitě resetuje MCU (chování hardwaru), software to nemůže nahlásit. Iwdg_Task() v režimu okna neobnovuje, aplikace musí volat Iwdg_Set_Refresh() uvnitř okna.
• Režim hardwarového watchdogu - pokud Iwdg_Get_State() vrátí po resetu před Iwdg_Init() hodnotu IWDG_FUNCTION_ACTIVE, watchdog byl spuštěn pomocí option bytes.
• Příčina resetu - reset od IWDG lze po startu zjistit pomocí Rcc_Get_ResetSource( RCC_RESET_SRC_IWDG, &flag ) a vymazat pomocí Rcc_Set_ResetSourceClear() v modulu RCC.
• Přesnost timeoutu - frekvence LSI se mění s teplotou a napětím (viz datasheet), skutečný timeout se tomu odpovídajícím způsobem liší od vypočteného.

---

⚙️ Typický příklad použití

#include "Iwdg_Port.h"

static void App_WatchdogWarning( void )
{
    // Last chance to store diagnostic data before the watchdog reset
}

int main(void)
{
    iwdg_Config_t       iwdgConfig;
    iwdg_Time_ms_t      achievedTimeout = 0u;
    iwdg_RequestState_t iwdgState       = IWDG_REQUEST_ERROR;

    iwdgState = Iwdg_Get_DefaultConfig( &iwdgConfig );

    iwdgConfig.Timeout        = 500u;   // Reset after 500 ms without refresh
    iwdgConfig.EarlyWakeup    = 50u;    // Callback 50 ms before reset
    iwdgConfig.EarlyWakeupIsr = App_WatchdogWarning;
    iwdgConfig.IrqPriority    = 0u;

    if( IWDG_REQUEST_OK == iwdgState )
    {
        iwdgState = Iwdg_Init( &iwdgConfig );
    }

    if( IWDG_REQUEST_OK == iwdgState )
    {
        iwdgState = Iwdg_Get_Timeout( &achievedTimeout );
    }

    while (1)
    {
        // Refreshes the watchdog automatically (no window configured)
        Iwdg_Task();
    }
}

---

🧾 Strategie větvení

Každá rodina STM32 má vlastní větev:

Větev	Popis
STM32G4	Ovladač MCAL pro rodinu STM32G4
STM32U5	Ovladač MCAL pro rodinu STM32U5
STM32L4	Ovladač MCAL pro rodinu STM32L4
STM32H5	Ovladač MCAL pro rodinu STM32H5

Tyto větve obsahují definice registrů, rozsahy předděliček a vazby na RCC/NVIC specifické pro danou rodinu, a přitom zachovávají společné rozhraní.

---

🧩 Závislosti

• Rcc_Lib – frekvence hodin LSI (RCC_PERIPH_IWDG)
• Nvic_Lib – obsluha přerušení early wakeup
• RAL (Register Abstraction Layer) – používá se interně pro přístup k nízkoúrovňovým registrům

Veškerá povinná konfigurace RCC a NVIC se provádí interně.

---

🧱 Příklad adresářové struktury

Iwdg/
├── Iwdg_Port.h
├── Iwdg_Types.h
├── Iwdg.c
├── Iwdg.h
├── CMakeLists.txt
├── LICENSE.md
└── README.md

---

🛠 Integrace s CMake

1. Zahrňte Iwdg_Lib do své knihovny CMake.
2. Zahrňte Iwdg_Port.h do svého projektu.
3. Prolinkujte implementační soubory modulu Iwdg.
4. Nakonfigurujte modul podle potřeb vašeho hardwaru.

---

Licence

Tento projekt je licencován pod licencí Creative Commons Uveďte původ–Neužívejte komerčně 4.0 Mezinárodní (CC BY-NC 4.0).

Toto dílo můžete volně používat, upravovat a sdílet pro nekomerční účely za předpokladu, že uvedete odpovídající autorství.

Úplné podmínky najdete v LICENSE.md nebo navštivte creativecommons.org/licenses/by-nc/4.0.

---

Autoři

• Mr.Nobody — embedbits.com

Příspěvky jsou vítány! Otevřete prosím pull request.

---