What if I told you there was a pet inside your micro-controller? A watchdog (sometimes even two). Once you let it out of the kennel, you have to pet it regularly, or else it will bark. And you don’t want that.
In the world of electronics, a watchdog is a security device that checks the status of a system. On most STM32 devices, there are two watchdogs; the IWDG and the WWDG. The WWDG is the Window Watchdog, and this is a rather complex beast. The IWDG, called the Independent Watchdog, is a much simpler device, and this is the one we will be talking about.
As far as STM32 peripherals go, the IWDG is probably the simplest. Some have different functionality, including the possibility to function in low power, watch multiple clock sources, or even work in window mode, but that is out of the scope of this article.
The watchdog, puis simply, is a counter. It is generally hooked up to the internal low-speed clock (the LSI). Once initialized, it spends its time counting down to zero. If it reaches zero, then it initiates an electric reset to the micro-controller, and everything starts again. There are a two main use cases for a device like this; one where safety is absolutely critical, and the other where access is extremely limited. For example, the brake controller of your car probably has a watchdog; if something happens to the normal execution of your code, then you really want the system to start again. Likewise, if you place a tracer on a turtle and release it back to the wild to study migratory patterns, you can’t track down the turtle again to push a reset button. And no matter how robust the code is, it can never be 100% safe. The subject of cosmic rays is a delicate one, but is also one of the reasons why servers tend to have ECC memory that automatically correct for bit flips.
In this example, we will look at how the IWDG operates. I’m using an STM Nucleo board with the STM32H563. Totally overkill for my needs, but it has the advantage of having an external debugger connector, and three user LEDs, as well as a push button.
The strategy is simple. On boot, we will turn on the red LED for 200 milliseconds, and then blink the yellow LED.
Once the card is prepared using STM32CubeIDE, the code looks like this:
/* USER CODE BEGIN WHILE */
BSP_LED_On(LED_RED);
HAL_Delay(200);
BSP_LED_Off(LED_RED);
while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
BSP_LED_On(LED_YELLOW);
HAL_Delay(200);
BSP_LED_Off(LED_YELLOW);
HAL_Delay(200);
}
Once flashed to your board, the LED will blink to your heart’s content.
Let’s add in the watchdog. Using CubeMX or STM32CubeIDE makes this trivial. This is the formula to know the maximum time the watchdog has before resetting:
The STM32H563 has an LSI of 32kHz, or 32000. By default, STM32Cube proposes a prescaler of 4, and a down-counter of 4095. In essence:
The result is a fraction over 0.5 seconds. We’ll activate the watchdog but change one parameter: the prescaler to IWDG_PRESCALER_16, which allows us a little bit more time, just over 2 seconds.
This adds in the following code:
hiwdg.Instance = IWDG;
hiwdg.Init.Prescaler = IWDG_PRESCALER_16;
hiwdg.Init.Window = 4095;
hiwdg.Init.Reload = 4095;
hiwdg.Init.EWI = 0;
if (HAL_IWDG_Init(&hiwdg) != HAL_OK)
{
Error_Handler();
}
And then we call the watchdog on boot. As soon as we start it, it will begin counting down to zero, and when it reaches zero, the board will reset, shown by the red LED turning on briefly, before blinking the yellow LED. After a few seconds, this repeats itself, the watchdog continuously resetting the device and being enabled again.
Petting the dog
To keep our dog happy, we need to pet it periodically. This is done by writing a specific value into a specific register. For the STM32H563 that I’m using, the Reference Manual (RM0481) states in section 44.4.3:
Whenever the key value 0x0000 AAAA is written in the IWDG key register (IWDG_KR), the IWDG_RLR value is reloaded into the IWDCNT, and the watchdog reset is prevented.
You can perform this action or, for the sake of portability (or simplicity) use the HAL function provided: HAL_IWDG_Refresh(). Let’s change the loop code:
while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
BSP_LED_On(LED_YELLOW);
HAL_Delay(200);
BSP_LED_Off(LED_YELLOW);
HAL_Delay(200);
HAL_IWDG_Refresh(&hiwdg);
}
As soon as we finish one blink sequence (around 400 milliseconds), then we will update the register. We’ll flash this to the board, and the result is a happy blinking yellow LED. No more problems! But let’s simulate one. The Nucleo board has an onboard pushbutton, so let’s use that to simulate a process taking too long. Change the code to this:
while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
while(BSP_PB_GetState(BUTTON_USER) == 1)
{}
BSP_LED_On(LED_YELLOW);
HAL_Delay(200);
BSP_LED_Off(LED_YELLOW);
HAL_Delay(200);
HAL_IWDG_Refresh(&hiwdg);
}
During the loop, the application will become stuck in a while loop until we let go of the button. This also prevents us from refreshing the watchdog counter. If we press on the button for too long, the watchdog kicks in, seen by a flashing red LED. Now our application is complete.
Actually, not quite. During the debug phase of the project, a few things can happen. Remember when I told you the watchdog couldn’t be stopped? Well, that is only partially true. Advanced Cortex-M devices have a complete debug system, and this is certainly the case for the rather impressive STM32H563. Plug in an external debugger, run the program in debug mode, and then randomly pause the program. What happens? Well, this all depends. On STM32CubeIDE using my STLinkV3 PWR, the program pauses, but only because there is an option to allow the IWDG to be frozen. By default this is activated, but when I turn this off, the system resets when the debugger pauses for too long. With other debuggers using different IDEs, your mileage may vary. In any case, debugging with an active watchdog might not be feasible, especially for short watchdogs. We can add a function to the startup:
if (CoreDebug->DHCSR & CoreDebug_DHCSR_C_DEBUGEN_Msk)
{
BSP_LED_On(LED_GREEN);
__HAL_DBGMCU_FREEZE_IWDG();
}
This has the effect of detecting if a debug session is ongoing. On first boot after flashing, it is possible that the green LED is lit, because the debugger took control of the micro-controller in order to wipe the flash and to write the new program.