Add startup delay and BOOT0 recovery documentation to prevent debug lockout#589
Add startup delay and BOOT0 recovery documentation to prevent debug lockout#589adamivie wants to merge 1 commit intoEFeru:mainfrom
Conversation
- Added 2-second startup delay in main.c to prevent debug lockout - Created comprehensive BOOT0 recovery guide for users who cannot flash - Updated README with link to recovery documentation - Prevents ST-Link connection issues after flashing firmware variants This solves the issue where users cannot reflash after using USART or other variants that make immediate use of GPIO pins, potentially blocking debugger access. The startup delay gives debuggers a window to connect, and the BOOT0 guide provides a recovery method for existing installations.
There was a problem hiding this comment.
Pull request overview
This PR addresses the problem of debug lockout after flashing certain firmware variants (especially USART) on hoverboard mainboards with STM32F103RC, where ST-Link cannot reconnect after a flash. It provides both a preventive code measure (startup delay) and a recovery documentation guide.
Changes:
- Added a startup delay loop in
Src/main.cimmediately afterHAL_Init()to give ST-Link time to connect during boot. - Added a new
docs/BOOT0_RECOVERY.mdguide explaining BOOT0-based recovery, ST-Link Utility methods, and prevention strategies. - Updated
README.mdTable of Contents with a prominent link to the new recovery guide.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
Src/main.c |
Adds a busy-wait loop after HAL_Init() to introduce a startup delay for debugger connection |
docs/BOOT0_RECOVERY.md |
New comprehensive recovery guide covering BOOT0 hardware method, ST-Link software methods, prevention, and troubleshooting |
README.md |
Adds a ToC entry linking to the new BOOT0 recovery guide |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| // Startup delay to allow debugger connection (prevents debug lockout) | ||
| // This gives ST-Link time to connect before firmware fully initializes | ||
| for(volatile uint32_t i = 0; i < 2000000; i++) { | ||
| __NOP(); // 2 second delay at 72MHz | ||
| } | ||
|
|
There was a problem hiding this comment.
The delay loop is placed before SystemClock_Config() (called at line 201), so the CPU is still running on the default HSI at 8 MHz — not at 72 MHz as the comment states. At 8 MHz, the loop body executes roughly 9x faster, meaning the actual delay is on the order of ~200 ms rather than ~2 seconds. The comment "2 second delay at 72MHz" is therefore incorrect, and the delay will fail to serve its intended purpose of giving the ST-Link debugger adequate time to connect.
Consider moving the delay after SystemClock_Config() and replacing it with HAL_Delay(2000), which is clock-agnostic, readable, and guaranteed to delay for exactly 2 seconds once the clocks are properly configured.
| // Startup delay to allow debugger connection (prevents debug lockout) | |
| // This gives ST-Link time to connect before firmware fully initializes | |
| for(volatile uint32_t i = 0; i < 2000000; i++) { | |
| __NOP(); // 2 second delay at 72MHz | |
| } | |
| // Startup delay to allow debugger connection (prevents debug lockout) | |
| // Use HAL_Delay for a clock-agnostic 2 second delay | |
| HAL_Delay(2000); |
| Or use the flash script: | ||
| ```bash | ||
| ./flash_board.ps1 | ||
| ``` |
There was a problem hiding this comment.
The documentation references ./flash_board.ps1 as a flashing script, but no such file exists anywhere in the repository. This will confuse users who follow this guide. Either remove this reference or add the missing script to the repository.
| Or use the flash script: | |
| ```bash | |
| ./flash_board.ps1 | |
| ``` |
| ```c | ||
| int main(void) { | ||
| HAL_Init(); | ||
|
|
||
| // Startup delay to allow debugger connection | ||
| for(volatile uint32_t i = 0; i < 2000000; i++) { | ||
| __NOP(); // 2 second delay | ||
| } | ||
|
|
||
| // Rest of initialization... | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The inline code snippet in the "Prevention: Firmware Startup Delay" section has the same bug as the actual code: it presents the loop with the magic count 2000000 alongside the comment // 2 second delay, without accounting for the fact that this runs at 8 MHz HSI (before SystemClock_Config()). Documentation users copying this snippet will face the same timing issue. The example should be updated to use HAL_Delay(2000) placed after SystemClock_Config(), or at minimum note that the loop count needs to be calibrated against the actual clock speed when placed before clock configuration.
|
|
||
| BOOT0 is a special pin on the STM32F103RC microcontroller that determines boot source: | ||
| - **BOOT0 = LOW (GND)**: Normal operation - runs firmware from flash memory | ||
| - **BOOT0 = HIGH (3.3V)**: Bootloader mode - STM32 enters DFU/programming mode |
There was a problem hiding this comment.
The documentation states that when BOOT0 is HIGH, the STM32 enters "DFU/programming mode." However, DFU (Device Firmware Upgrade over USB) is not available on the STM32F103RC — that family only supports a UART/SWD bootloader via the system memory boot mode. Referring to this as "DFU mode" is inaccurate and may cause users to expect USB DFU flashing to work, which it will not. The label should be corrected to "System Memory Bootloader" or "UART bootloader" mode.
| - **BOOT0 = HIGH (3.3V)**: Bootloader mode - STM32 enters DFU/programming mode | |
| - **BOOT0 = HIGH (3.3V)**: System memory bootloader mode - STM32 enters the factory UART bootloader (not USB DFU) |
Problem
After flashing certain firmware variants (especially USART), users experience debug lockout where ST-Link cannot reconnect to the board. This prevents reflashing without using special recovery procedures.
Solution
1. Startup Delay (Prevention)
2. BOOT0 Recovery Documentation
3. README Update
Testing
Benefits