WSL Embedded Debugging

Overview

Use Windows-side toolchains from WSL so code stays in the Linux workspace while USB-capable flashing and runtime logging happen through Windows executables.

Codex Sandbox and Setup Requirements

Require an execution mode that can launch Windows executables from WSL:

• Prefer full-access sandboxing (for example danger-full-access) when running flash/debug commands from this skill.
• If sandbox policy blocks *.exe or /mnt/c/... binaries, stop and switch to a less restricted mode before continuing.

Require Windows tools to be callable from the WSL shell:

• Invoke by name when PATH bridging is configured (cargo.exe, probe-rs.exe, openocd.exe).
• Invoke by explicit path when PATH bridging is not configured (for example /mnt/c/Users/<user>/.cargo/bin/cargo.exe).
• Verify setup quickly with cargo.exe --version and probe-rs.exe --version.
• Use wslpath -w <linux-path> when a Windows-native tool requires Windows-style paths.

Core Workflow

1. Confirm that the hardware step needs Windows USB access.
2. Run the command through scripts/run_windows_embedded.sh.
3. Use a bounded timeout to capture useful logs quickly.
4. Treat timeout exit 124 as expected log capture, not automatic failure.
5. Iterate with adjusted timeout, bin target, and command flags.

Run Commands

Use this wrapper as the default execution path:

./scripts/run_windows_embedded.sh --timeout 15 -- cargo.exe run --bin <firmware-bin> --release

Capture logs to a file for later inspection:

./scripts/run_windows_embedded.sh --timeout 20 --log /tmp/embedded-run.log -- cargo.exe run --bin <firmware-bin> --release

Use log-only mode when log frequency is high and terminal/context noise is expensive:

./scripts/run_windows_embedded.sh --timeout 20 --log /tmp/embedded-run.log --log-only -- cargo.exe run --bin <firmware-bin> --release

Use artifacts mode when you want reproducible run bundles (run.log + run.json):

./scripts/run_windows_embedded.sh --timeout 20 --artifacts-dir /tmp/embedded-run --log-only --tail 40 -- cargo.exe run --bin <firmware-bin> --release

Run environment checks before long debugging loops:

./scripts/run_windows_embedded.sh --check -- cargo.exe run --bin <firmware-bin> --release

Pass any Windows executable command after -- (for example probe-rs.exe run ..., openocd.exe ..., or vendor CLI tools).

Choose Output Mode

Agents should intentionally choose output mode based on expected verbosity and run duration:

• Use raw terminal output for short, low-frequency logs where live feedback is valuable.
• Use --log for balanced runs that need both live stream and saved artifacts.
• Use --log --log-only for noisy/long sessions to avoid blowing context while preserving complete logs for targeted inspection.
• Use --artifacts-dir when reproducibility matters; this saves both run.log and run.json metadata.
• Use --tail N with --log-only when you still need a compact end-of-run preview.

--log-only is an intended first-class option, not a workaround.

Interpret Exit Codes

• 0: Command completed before timeout.
• 124: Timeout reached; treat as successful bounded capture for long-running firmware sessions.
• Any other non-zero code: Treat as a real error and debug.

Debug Loop

1. Start with 10–20 second timeout.
2. Confirm flash + early boot logs appear.
3. Increase timeout only when deeper runtime phases are needed.
4. Keep command explicit (--bin, --release, feature flags).
5. Repeat with focused changes between runs.

Troubleshoot

• If cargo.exe is missing, verify Windows Rust toolchain installation and PATH exposure to WSL.
• If flashing fails with probe errors, verify the device is visible to Windows and no other process owns the probe.
• If no runtime logs appear, confirm logger transport settings and runtime command configuration.

Use references/wsl-windows-embedded-troubleshooting.md for detailed checks and alternatives.