added troubleshooting

Readme.md

@@ -203,3 +203,81 @@ In Arduino IDE → Tools, set:
 - Optimize → Debug (-Og)
 
 Then click the 🐞 Debug icon and press Start Debugging.
+
+## Troubleshooting
+
+### 1. Cannot Re-program Blue Pill After First Flash
+
+This guide addresses an issue where a Blue Pill (STM32F103) board can be programmed successfully once with Embeetle, but all subsequent attempts fail with an error similar to `Error: Error connecting DP: cannot read IDR`.
+
+**Symptom:** The OpenOCD output shows the following error on the second flash attempt:
+```
+Error: Error connecting DP: cannot read IDR
+in procedure 'program'
+** OpenOCD init failed **
+```
+
+### The Cause
+
+The root cause is that the application code reconfigures the debug pins (`PA13` for SWDIO and `PA14` for SWCLK) for other purposes. This effectively disables the Serial Wire Debug (SWD) interface, preventing the DAPLink programmer from establishing a connection.
+
+The SWD interface can be activated manually by switching the `BOOT0` jumper to `1` and the pressing reset button. However, this is inconvenient for normal development workflows.
+
+### The Solution
+
+Change the configuration to keep the SWD interface enabled.
+
+1.  Open the file `stm32f1xx_hal_msp.c` in your project. It is usually located in the `Src` or `Core/Src` directory.
+2.  Locate the `HAL_MspInit()` function.
+3.  Inside this function, find the line that disables the debug interface. It typically looks like this:
+    ```c
+    /**DISABLE: JTAG-DP Disabled and SW-DP Disabled
+    */
+    __HAL_AFIO_REMAP_SWJ_DISABLE();
+    ```
+4.  Replace it with the following line to keep SWD enabled while disabling the less-common JTAG interface:
+    ```c
+    /** DISABLE: JTAG-DP Disabled but keep SW-DP Enabled
+    */
+    __HAL_AFIO_REMAP_SWJ_NOJTAG();
+    ```
+
+### 2. Error: `Unable to reset target`
+
+If you encounter the following error message in Embeetle's output console during a flashing attempt:
+
+```
+Error: timed out while waiting for target halted
+embedded:startup.tcl:1813: Error: ** Unable to reset target **
+in procedure 'program'
+```
+
+This typically means there is a mismatch between the reset strategy configured in OpenOCD and your physical wiring. By default, the project is configured to use a **hardware reset**, which requires the `nRST` pin to be connected.
+
+### Solution 1 (Recommended): Connect the Hardware Reset Pin
+
+The most reliable solution is to ensure your wiring matches the default configuration.
+
+**Make sure the `nRST` pin of your DAPLink programmer is connected to the `R` (Reset) pin on the Blue Pill's board.**
+
+Your connections should be:
+*   `VCC` -> `3.3V`
+*   `SWDIO` -> `DIO`
+*   `SWCLK` -> `CLK`
+*   `GND` -> `G`
+*   `nRST` -> `R`
+
+### Solution 2 (Alternative): Use a Software Reset
+
+If you prefer to use a 3-wire setup (SWDIO, SWCLK, GND) and not connect the reset pin, you must change the configuration to instruct OpenOCD to use software-based reset commands instead of toggling a physical pin.
+
+1.  Open the project file `../config/openocd_chip.cfg`.
+2.  Find the following line:
+    ```tcl
+    reset_config srst_only
+    ```
+3.  Change it to `none`:
+    ```tcl
+    reset_config none
+    ```
+4.  Save the file and try programming again.