63 lines
4.4 KiB
Markdown
63 lines
4.4 KiB
Markdown
---
|
|
name: cubemx-min-prj
|
|
description: Create a minimal STM32CubeMX reproduction project from scratch, regenerate code, and verify the local build/debug setup. Use when Codex needs to reproduce an STM32 issue in a clean workspace, derive a smallest CubeMX+CMake project from an existing board/project, rebuild `.vscode` STM32 debug files, or document the exact CubeMX CLI and `.ioc` patching steps required to recreate the project.
|
|
---
|
|
|
|
# CubeMX Minimal Project
|
|
|
|
Create a fresh STM32CubeMX project that reproduces only the hardware and firmware behavior the user needs to debug. Prefer a clean, scriptable reproduction over copying a large existing workspace.
|
|
|
|
## Workflow
|
|
|
|
1. Inspect the source context.
|
|
- Read the target `.ioc`, build presets, and any `.vscode` files before creating the reproduction.
|
|
- Identify the minimum MCU, clock tree, peripherals, DMA/NVIC settings, and user-code hooks required to reproduce the issue.
|
|
- Keep explicit dates and tool versions. For this workspace, the known-good CubeMX version is `6.11.1`.
|
|
|
|
2. Verify local tools.
|
|
- Detect the installed STM32CubeMX path and version before touching `.ioc` metadata.
|
|
- Run the local version check command from [REPRODUCTION_GUIDE.md](./REPRODUCTION_GUIDE.md) first.
|
|
- Stop immediately unless the detected version is exactly `6.11.1` or starts with `6.11.1-`.
|
|
- Confirm CMake, the selected toolchain, and any STM32CubeCLT paths needed for build/debug are present.
|
|
- If the installed CubeMX is older than the source `.ioc` format, stop and report the version mismatch.
|
|
|
|
3. Create the reproduction workspace.
|
|
- Default to a new subdirectory such as `reproduction/` under the current workspace.
|
|
- Generate the base project from CubeMX CLI/script mode instead of copying generated sources.
|
|
- Keep the project minimal: only add the peripherals, pins, and middleware needed to reproduce the issue.
|
|
|
|
4. Configure CubeMX deterministically.
|
|
- Use CubeMX script commands for project creation, pin assignment, peripheral mode selection, and code generation whenever the CLI supports it.
|
|
- If CubeMX CLI cannot express required metadata, patch the `.ioc` directly with exact keys and then regenerate code.
|
|
- Treat the `.ioc` as the source of truth. Do not hand-edit generated C files first and backfill the `.ioc` later.
|
|
|
|
5. Patch only the user-owned parts of generated code.
|
|
- Restrict manual source changes to `/* USER CODE BEGIN */` regions or isolated helper functions added specifically for the reproduction.
|
|
- Use this for items like `printf` retargeting, DMA idle receive callbacks, or small harness logic that CubeMX cannot generate.
|
|
|
|
6. Rebuild the developer workflow when requested.
|
|
- Mirror `.vscode/settings.json`, `tasks.json`, `launch.json`, `c_cpp_properties.json`, and `extensions.json` only if the user wants a debug-ready workspace.
|
|
- Reuse the existing project's naming and only swap the target ELF/project name where needed.
|
|
- Read [DEBUG_SETUP.md](./DEBUG_SETUP.md) for the BMSv31-style VS Code template expected in this workspace.
|
|
|
|
7. Validate before finishing.
|
|
- Re-open the `.ioc` in CubeMX after any direct file patching and confirm the GUI reflects the intended configuration.
|
|
- Run `cmake --preset Debug` and `cmake --build --preset Debug` unless the user explicitly asks only for scaffolding.
|
|
- Confirm the expected ELF exists under `build/Debug/`.
|
|
- Treat the task as incomplete if CubeMX generation or local build verification was skipped without user approval.
|
|
|
|
## Guardrails
|
|
|
|
- Prefer the smallest reproducible project, not a feature-complete clone.
|
|
- Do not proceed with project creation, `.ioc` edits, or code generation when CubeMX is not `6.11.1` or `6.11.1-*`.
|
|
- Preserve exact issue-critical details such as clock values, DMA streams, NVIC enables, and peripheral modes.
|
|
- Use absolute paths inside one-off local commands only when required by CubeMX or local tooling.
|
|
- Keep generated project names, MCU names, and toolchain selections explicit in the final notes.
|
|
- If reproducing from a larger project, document what was intentionally omitted.
|
|
- If CubeMX silently rewrites required metadata, capture the exact `.ioc` keys that must be re-applied.
|
|
|
|
## References
|
|
|
|
- Read [REPRODUCTION_GUIDE.md](./REPRODUCTION_GUIDE.md) when the task is specifically to recreate the known STM32F407ZGTx/BMSv4 minimal project with CubeMX CLI, `.ioc` patching, user-code updates, and local build verification.
|
|
- Read [DEBUG_SETUP.md](./DEBUG_SETUP.md) when the task includes restoring VS Code Cortex-Debug, flash tasks, STM32CubeCLT paths, or extension recommendations.
|