boot_guard.h File Reference

Detailed Description

Early-boot loop guard: escape to the bootloader when firmware keeps failing before it ever reaches a healthy state, even before USB is up.

The watchdog's crash-count escape (Watchdog::escapeToBootloaderIfLooping, #3713) runs from setup(). A firmware that hangs or faults before that point – during static construction, or before the USB stack enumerates – never gets there, and the host cannot reach the board. The boot guard runs in the platform's earliest startup hook instead:

1. every boot increments a counter kept in reset-persistent memory;
2. the hardware watchdog is armed with early_timeout_ms, so a hang becomes a reset instead of a permanent wedge;
3. once the counter reaches escape_boots, the hook zeroes it and reboots into the bootloader, where the host can flash the board;
4. the sketch calls FastLED.watchdog().markBootHealthy() once it is healthy (e.g. at the end of setup()), which zeroes the counter.

The counter is keyed to the firmware image, so a reflash (a warm reset) starts the new firmware from 0 instead of inheriting the old count.

The early watchdog stays armed until the sketch takes it over with FastLED.watchdog().begin()/feed() or calls disable(). If the sketch never called begin(), markBootHealthy() disables it.

Opt in by placing the macro once, at file scope, in a sketch .cpp file (not a .ino: Arduino prototype generation can give C-linkage startup hooks the wrong linkage):

#include "FastLED.h"
FL_WATCHDOG_BOOT_GUARD(3, 30000);

Platforms that support it define FL_WATCHDOG_HAS_BOOT_GUARD (Teensy 4.x today). Everywhere else the macro generates no code – it expands to a static assertion that only checks its arguments – bootGuardCount() returns 0 and markBootHealthy() does nothing.

Hardware test option: build with -DFL_WATCHDOG_DEBUG_EARLY_HANG to make the guard hang forever right after arming, every boot. A supported board must then come back in its bootloader by itself. Never ship it.

Definition in file boot_guard.h.

#include "fl/stl/static_assert.h"
#include "fl/wdt/boot_guard_record.h"
#include "platforms/watchdog_boot_guard.h"

Include dependency graph for boot_guard.h:

Go to the source code of this file.

Macros
#define	FL_WATCHDOG_BOOT_GUARD(escape_boots, early_timeout_ms)