Support & Configuration
The watchdog functionality is provided by a low level peripheral within the chip. As a result, different ports within CircuitPython support different configurations and behaviors. This support matrix documents the differences between them.
Watchdog Support Matrix
- port - CircuitPython port or chipset.
- RAISE - watchdog support for RAISE mode.
- RESET - watchdog support for RESET mode.
- deactivate - whether the watchdog can be deactivated in RESET mode.
- max s - the largest allowed value for the timeout interval, in seconds.
| port | RAISE | RESET | deactivate | max s |
|---|---|---|---|---|
| Raspberry Pi | no | yes | yes | 8 |
| Espressif | yes | yes | yes | 512 |
| Nordic | yes | yes | no | 512 |
| SAMD51 | no | yes | yes | 16 |
| SAMD21 (no support) | - | - | - | - |
Configuration
Timeout
The watchdog.timeout property controls the timeout interval for required feeding. The table above notes the maximum supported value for each of the different ports. Attempting to set it above the maximum will raise an exception.
Exception vs. Reset
The watchdog.mode property controls the bite behavior and activates the watchdog. The Espressif and Nordic ports allow WatchDogMode.RAISE, Raspberry Pi and SAMD ports do not. All ports can use WatchDogMode.RESET.
The mode property also activates the watchdog. Once you set mode to RAISE or RESET the watchdog activates.
-
RAISEmode - The watchdog raises an exception that can be caught and reacted to from Python code. -
RESETmode - The watchdog resets the device.
Deactivating
Setting watchdog.mode to None will deactivate the watchdog on all ports except for Nordic. The Nordic watchdog can only be deactivated if it is in RAISE mode. Once it has been activated in RESET mode, it cannot be deactivated from software.
Reset Reason
When you set watchdog.mode to WatchDogMode.RESET, it is possible to determine on the next boot up whether a watchdog bite was responsible for the reset or not. To do so, check microcontroller.cpu.reset_reason. It will have the value microcontroller.ResetReason.WATCHDOG if the watchdog biting is what caused the most recent reset.
Nordic
The Nordic port differs from the rest in some important ways. As noted above, when the watchdog is activated in RESET mode, it cannot be deactivated. When the dog bites and the reset happens, the device boots back up into safe mode by default. So a RESET dog bite on Nordic will look like this on the serial console:
You are in safe mode because: Internal watchdog timer expired. Press reset to exit safe mode.
If you want to recover from safe mode and get back to the code.py file, as would be a typical use-case for a watchdog, then you can make a safemode.py file with code to reset back into normal mode. See the code examples on next page.
Page last edited September 04, 2026
Text editor powered by tinymce.
