# VS Code Debug Setup

Use this guide when the reproduction workspace must be flashable and debuggable in VS Code with ST-Link and Cortex-Debug.

## Expected local prerequisites

- `STM32CubeCLT` installed locally
- `marus25.cortex-debug` extension available in VS Code
- `STM32_Programmer_CLI` on `PATH` or otherwise discoverable by VS Code tasks

## 1. `.vscode/settings.json`

Keep the active CMake preset on `Debug` and point VS Code to the local CubeCLT root.

```json
{
  "files.associations": {
    "tcp_client.h": "c",
    "lwip.h": "c",
    "ethernetif.h": "c"
  },
  "cmake.configurePreset": "Debug",
  "cmake.buildPreset": "Debug",
  "STM32VSCodeExtension.cubeCLT.path": "C:/ST/STM32CubeCLT_1.19.0"
}
```

## 2. `.vscode/tasks.json`

Provide three tasks:

- `CMake: clean rebuild`
- `CubeProg: Flash project (SWD)`
- `Build + Flash`

Use `${command:cmake.launchTargetPath}` for the download path so the task follows the active target.

## 3. `.vscode/launch.json`

Create both launch and attach profiles with:

- `type: "cortex-debug"`
- `servertype: "stlink"`
- `device: "STM32F407ZGTx"`
- `interface: "swd"`
- `runToEntryPoint: "main"`
- `serverArgs: ["-m", "0"]`

Point `executable` at the reproduction ELF. For this skill's default example:

```json
"executable": "${workspaceFolder}/build/Debug/BMSv4.elf"
```

Keep all tool paths derived from `STM32VSCodeExtension.cubeCLT.path`:

- `serverpath`
- `stm32cubeprogrammer`
- `stlinkPath`
- `armToolchainPath`
- `gdbPath`
- `svdFile`

## 4. `.vscode/c_cpp_properties.json`

Use the CMake Tools provider instead of hardcoded include paths.

```json
{
  "version": 4,
  "configurations": [
    {
      "name": "STM32",
      "configurationProvider": "ms-vscode.cmake-tools",
      "intelliSenseMode": "${default}"
    }
  ]
}
```

## 5. `.vscode/extensions.json`

Recommend, at minimum:

- `ms-vscode.cpptools-extension-pack`
- `ms-vscode.cmake-tools`
- `marus25.cortex-debug`
- `mcu-debug.debug-tracker-vscode`
- `mcu-debug.memory-view`
- `mcu-debug.peripheral-viewer`
- `mcu-debug.rtos-views`

Add project-specific editor helpers only if they are already part of the source workflow.

## 6. Final checks

- `cmake --build --preset Debug` succeeds before debugging.
- VS Code resolves `${command:cmake.launchTargetPath}` to the expected ELF.
- ST-Link GDB server starts without path errors.
- Flash task uses the same ELF that the debug configuration launches.