This module enables access to secure firmware functionalities specific to the target microcontroller. It can be safely imported in every program, however its functions will raise UnsupportedError if the target VM is not enabled for secure firmware features (available for Pro users only).
There are many ways of securing the firmware running on a microcontroller:
- disable access to the flash memory wher the firmware resides with external means (e.g. JTAG probes)
- reserve some memory areas to critical parts of the system (e.g. VM running in mcu Trust Zones)
- detect device tampering and take action accordingly (e.g. erase firmware)
- detect and recover from firmware malfunctions (e.g. watchdogs)
Of the above features, only watchdogs are implemented in all architectures; the rest of features are strongly platform dependent. This module allow access to the microcontroller watchdogs and will enable access to anti-tampering features soon.
A Watchdog is usually implemented as a countdown timer that resets the microcontroller if it is not refreshed by firmware in a specified timeout period. The action of refreshing the watchdog timer is often called “kicking” or “feeding” the watchdog. A windowed watchdog is a specially configured watchdog that resets the microcontroller both on a normal timeout or on a kick that happens before a specified time from last refresh.
Normal Watchdog time window |----------------------------------------------| --> a reset happens! 0 timeout A kick here restarts the watchdog Windowed Watchodog |............|---------------------------------| --> a reset happens! 0 t1 timeout A kick here A kick here reset the mcu! restarts the watchdog
Each microcontroller family has its own watchdog peculiarities, described in the following sections:
This module provides the following functions for watchdog usage:
Enable the watchdog. If
time0is zero, the watchdog is configured in normal mode; if it is greater than zero, the watchdog is configured in windowed mode (if supported) in such a way that a kick in the first
time0milliseconds resets the device.
timeoutconfigures the number of milliseconds the whole watchdog window lasts. Once started, the watchdog CAN’T be stopped!
Refresh the watchdog, resetting its time window.
Trueif the microcontroller has been reset by the watchdog,
Watchdogs for STM32Fxx families¶
For STM32 microcontrollers the watchdog is implemented using the IWDG. The maximum timeout is 32768 milliseconds and there is no support for windowed mode (an exception is raised if
time0 is greater than zero in
The watchdog is disabled in low power modes.
Watchdogs for NXP K64 families¶
For K64 microcontrollers the watchdog is implemented using WDOG. The WDOG is clocked by the low power oscillator with a frequency of 1kHz.T The maximum timeout is around 74 hours and windowed mode is supported. The watchdog is disabled in low power modes.
Watchdogs for Microchip SAMD21¶
For SAMD21 microcontrollers the watchdog is implemented using WDT. The WDT is clocked by the ultra low power oscillator with a frequency of 1kHz. In normal mode the maximum timeout is 16 seconds. In windowed mode
timeout can reach 32 seconds and
time0 16 seconds; this is because windowed mode works with two timers, the first for
time0 and the second for
The timeout granularity of WDT is quite coarse, allowing only 12 different timeout values, expressed in WDT clock cycles:
- 8 cycles, 8 milliseconds
- 16 cycles, 16 milliseconds
- 16384 cycles, 16384 milliseconds
watchdog() function will select the nearest allowed time rounding up with respect to the specified time.
Watchdogs for ESP32 devices¶
For ESP32 devices the watchdog is implemented using a hardware timer. The maximum timeout is 2^31 milliseconds and there is no support for windowed mode (an exception is raised if time0 is greater than zero in watchdog()). There are also two additional watchdogs configured by default: the task watchdog and the exception watchdog.
The task watchdog is enabled on both cores and prints out a warning when a thread is using a core for too much time. The exception watchdog resets the microcontroller in case a hard fault exception is raised; before resetting, a dump of both cores is printed on the serial console.