bakesheep/emberprobe-mcu-flash-debug/mcu-cubemx

CubeMX initialization code

MCP first: if this session provides EmberProbe MCP tools (such as cubemx_prepare), use them; the script here is the fallback. The authorization and hardware rules on this page apply to both.

Requires Windows or Linux, the EmberProbe Agent Bridge, an existing configured .ioc, and the matching standalone CubeMX installation with its bundled Java and installed firmware package. No hardware is required. On Linux, select the standalone STM32CubeMX launcher (no .exe suffix) with its bundled jre/bin/java; firmware package installation is interactive and requires a graphical desktop.

Use mcu-config to select iocPath. CubeMX executable paths are read-only through the Bridge. Firmware package status is derived by the sidebar from the MCU target and optional IOC; it is not a writable config.set field, and --inspect does not verify package installation. For missing packages, use the sidebar's native interactive firmware installer; the Bridge generation workflow does not install packages or change the IOC's package version.

Read ../_emberprobe/agent-workflow.md for failure handling and evidence boundaries.

Use node <skill-dir>/scripts/cubemx.js --workspace <workspace> <operation>:

1. --detect checks CubeMX. --inspect reads the selected project and its configuration (returns a compact summary by default; use --prefix <prefix> to filter properties, or --full for full raw properties). If no .ioc is selected, have the user select one or click Auto-detect Configuration under MCU configuration. The mcu-config skill can also select an existing workspace iocPath. The CubeMX executable is configured only through the extension UI or user settings.
2. Prepare the requested configuration in a separate candidate text file inside the selected project workspace. The Bridge reads this file by path, so large configurations do not exceed its request-body limit. Never edit the original .ioc directly. Preserve unrelated properties, chip, project name, toolchain, package and CubeMX versions. Resolve related pin, DMA, NVIC and clock settings from the existing project and appropriate device documentation; do not invent undocumented property values.
3. Run --prepare --candidate <candidate-file>. For regeneration without configuration changes, omit --candidate. --prepare returns a categorized summary of changes (at most 20 shown, full diff saved to disk) and verification status. Show the returned configuration changes, project path and generation scope to the user.
4. When confirmationRequired is true, ask whether to allow this operation once, allow this project for 24 hours, or deny. Only after the user's answer run --start --candidate <same-candidate-file> --confirm <confirmationId> (or --execute). Add --remember only for explicit 24-hour authorization. Never manufacture approval or reuse a consumed ID. If already trusted or explicitly authorized by the sidebar full-access grant (mode: "full"), run without a confirmation ID. A changed plan requires fresh preparation. Denial ends the operation without executing.
5. With --start, monitor progress using --status --operation-id <operationId>. If a network/bridge timeout occurs, query --status first. Re-running the exact same --start command is also safe: the CLI persists unresolved request IDs and binds candidates to their content hash. Once a recorded operation completes, a new invocation starts a new request. Do not manually change request IDs to recover an unknown result. Never re-execute with a new request ID while an operation may still be running. The extension generates a baseline and candidate in isolated project copies outside the workspace, checks for existing hand edits and concurrent changes, then writes back with a recovery backup. On baseline drift, show the affected files and stop; details.baselineOutput holds CubeMX's regenerated version of each drifted file for comparison. Inspect and migrate hand-written logic separately before retrying. Do not bypass the check, delete the diagnostics of an unresolved failure, or patch generated initialization code to suppress the error. CubeMX online updater and advertisement panel errors (for example [ERROR] WebUtils:658 - Updater is busy) are reported in warnings and do not fail generation; the result is decided by the project generate OK/KO status, the exit code and the regenerated output.
6. Report the actual changed files and generation result. If generation failed, leave the task as uncompleted; you may write independent application logic, but do not claim CubeMX succeeded. Run the project's existing documented build command when available. If no build entry exists, report “Generation completed; compilation not verified.” A failed build must be reported separately, without claiming generation proves compilation or hardware correctness.

Use --check for quick consistency checking against the last committed generation manifest (verifying IOC and source modifications without running CubeMX; it works even when CubeMX is not installed). Use --check --deep to run an explicit isolated regeneration check. The deep check runs in the background and reports staleCandidates: files inside generation-owned directories that a fresh regeneration no longer produces (for example leftovers after removing a peripheral); this list is informational and does not by itself make the project inconsistent. Both report clear evidence boundaries without mutating the source project: quick check proves changes relative to the recorded manifest only, deep check proves regenerability under the current tools, and neither proves build or hardware behavior.

Use --permission to inspect remembered authorization independently of generation validation. It returns the saved target and expiry; applicability: unknown and trusted: false mean the current target could not be verified, not that the saved record was deleted. Version mismatch alone does not block this query. Use --reset-permission to revoke authorization, and --cancel (optionally with --operation-id) to cancel active CubeMX jobs. A notification in VS Code also provides cancellation. Do not automatically retry a timed-out or failed mutation.

To derive a candidate without editing the source, use:

node <skill-dir>/scripts/cubemx.js --workspace <workspace> --generate-candidate --output candidate.ioc --changes '{"USART2.BaudRate":"115200"}'
# Or using a workspace changes file:
node <skill-dir>/scripts/cubemx.js --workspace <workspace> --generate-candidate --output candidate.ioc --changes-file changes.json

--changes is a JSON object of decoded property names and string values; --changes-file points to a workspace JSON file. They are mutually exclusive. Use --deletions '["Mcu.IP1", "Mcu.Pin2"]' to explicitly delete removed properties and prevent orphaned indices. The output must be a new file in the selected workspace with an existing parent directory. Existing output files are never overwritten. Unmodified text is preserved; changed properties are escaped and the command returns their differences. This checks Properties syntax and structural declarations (contiguous IP/Pin indices and unique members), not pin conflicts, clock validity or peripheral compatibility. Continue with --prepare --candidate <returned-candidatePath> and the normal authorization workflow. Creating a candidate does not authorize writing the source or generating code.

Files EmberProbe keeps, and when they can be deleted:

• Staged project copies live in the system temporary directory (emberprobe-cubemx-stage-*) only while an operation runs; they are removed on success, failure and cancellation, and leftovers older than 24 hours are swept automatically.
• Each operation's diagnostics directory (diagnosticsPath in the result, error details and --status) is in EmberProbe's extension storage, outside the workspace. It contains the CubeMX logs (baseline.log, generating.log or deepCheck.log), baseline-drift/ for drift failures, and backup/ with the original bytes of every file a writeback modified or deleted. The newest 20 are kept automatically. A directory may be deleted once its operation is no longer needed for diagnosis, except while sourceProjectStatus is recoveryRequired or unknown: then restore or verify the listed files from backup/ first.
• .emberprobe-cubemx-audit/ in the workspace holds the CLI's small request-ID records used for safe retries; delete it only when no --start request is unresolved. .emberprobe-cubemx-*/ directories in a project root were left by EmberProbe 0.8.6 and earlier; they are safe to delete unless an operation reported recoveryRequired with a backup inside one.

Links outside the generation scope, and tool directories such as .claude, .agents, .vscode and .git, are skipped. Links in CubeMX inputs or outputs (Core, Drivers, Middlewares, cmake, the .ioc, linker scripts and other generated root files), and any link that regenerated output would be written through, are rejected with CUBEMX_LAYOUT_UNSUPPORTED.

CubeMX2 (.ioc2) projects

When the selected project is a .ioc2, EmberProbe uses STM32CubeMX2 (emberprobe.cubemx2Path) automatically. Do not write candidate files and do not edit the .ioc2 (it is TOML with embedded JSON stores). Change it only through CubeMX2 operations, [{ "command": "peripherals enable", "args": { "peripheral": "USART1", "mode": "Async" } }], with options written without dashes and flags as true:

1. --inspect summarizes chip, peripherals and pins. --query --operations '<json>' (or --operations-file ops.json) runs read-only commands such as peripherals list, peripherals view, pinout pin, clock get-clock-status or ide-project build-target list on a staged copy; each result has ok and data or error. Look values up before changing them instead of guessing ids.
2. --prepare --operations-file ops.json applies configuration commands to a staged copy, saves it, and returns operationResults, clockStatus, candidateHash and changes by category. Check clockStatus and the changes before asking the user. The workspace is not modified.
3. When confirmationRequired is true, wait for the user's answer, then run --start --candidate-hash <candidateHash> --confirm <confirmationId>. If the Bridge reports confirmationRequired: false, keep the same candidate hash and start without an ID. Regeneration without configuration changes is --prepare without operations, then --start --confirm <id>.

Unsupported commands, generate, save, project creation, pack installation and options such as project-path or port are rejected with CUBEMX2_OPERATION_INVALID. CUBEMX2_PACK_MISSING means the user must install the pack in CubeMX2; EmberProbe never downloads packs. CUBEMX2_VERSION_MISMATCH means the project's CubeMX2 version is not installed; do not migrate the project. CubeMX2 has no USER CODE markers: main.c, main.h and user_modifiable/ files are user-owned and kept once they exist (edits are reported in warnings), while generated/ and project files are CubeMX2-owned and covered by the drift check. Put application logic in user-owned or separate files. See docs/design/cubemx-pipeline.md.

.ioc projects

Initialization configuration belongs in .ioc; application logic belongs in separate .c/.h files. Put necessary calls inside preserved USER CODE blocks. Do not hand-edit CubeMX-owned regions. The first version does not migrate CubeMX versions, install packages, change chips/toolchains, or support external generation paths, links inside the generation scope, hooks and custom templates.