jl-codes/platformio-mcp/platformio-debug

PlatformIO Debug

Reading results: a non-zero exit means look at BOTH streams. An operation

that ran but failed (a build with errors) puts success: false on stdout;

one that could not run (bad arguments, policy, a busy port) puts errorType on

stderr with stdout empty. Capture both (--json 2>&1). See the

pio-manager skill for the full contract.

Purpose

Use this skill when a PlatformIO project fails to build, upload, or pass static checks.

Safety Rules

• Do not hide raw error logs. Summarize them and preserve the log path.
• Do not make broad dependency changes without explaining why.
• Do not flash firmware unless the user explicitly approves.

Workflow

1. Call pio-agent project context --project-dir <dir>, resolve one environment, and run pio-agent agent-build-diagnose --project-dir <dir> --environment <env>.
2. Use its structured diagnostics, nextSteps, task ID, and log paths before reading broad logs.
3. Extract the smallest redacted error snippet.
4. Identify the likely root cause.
5. Patch code, dependencies, or platformio.ini.
6. Rebuild with pio-agent build --project-dir <dir> --environment <env> --json. Retry automatically only when safeToAutoRetry is true and the retry remains bounded.
7. Repeat until build succeeds or a configuration, dependency, policy, approval, or hardware blocker is identified.
8. Summarize the exact fix.

Error Types

Classify failures as one of:

MissingHeader
MissingLibrary
WrongBoard
WrongFramework
SyntaxError
LinkerError
MemoryOverflow
DeviceBusy
PermissionDenied
UploadFailed
Unknown

For upload failures, resolve the target binding again before retrying. Treat port drift as safe only when the stable device fingerprint still matches; stop on substitution or ambiguity.

Dependency audit

Use deps_check with projectDir and an optional environment to inspect declarations and installed library manifests. build defaults to false. An explicit build: true requires separate build permission and returns LDF graph evidence. Inspect inventoryComplete, diagnostics, and graph status before claiming the audit is clean. Name collisions and leftover-library findings do not prove which library was linked. Scoped approvals are separate for the overall request, configuration, inventory and optional build stages.

Crash and size analysis

Use decode_backtrace with projectDir, environment, and the captured text. Keep includeAllHex false unless the trace format requires it; arbitrary hex values need not be code addresses. Supply expectedElfSha256 when the matching firmware identity is known, or archivedElfSha256 for an available retained ELF. Keep unresolved frames explicit. Decoding against an ELF does not prove that ELF matches the firmware currently running on the board.

Use size_report with projectDir, environment, and optionally top or filter to locate large symbols and sections. These operations may execute PlatformIO build metadata collection and require its permission even when no hardware is contacted. Static symbol sizes do not measure runtime heap/stack use; inspect accounting and partition evidence before diagnosing flash overflow. The dashboard command feed shows a bounded preview; use the tool result for the full returned analysis.

Permission failures

Call get_policy_status for the same projectDir. Inspect valid, source, sources, projectEnrollment, and the allowed/approval-required/denied lists. An invalid policy is a configuration error, not permission to fall back to a more permissive profile. Follow the reported source and error to correct it within the user's authorized scope, then read status again.

serverPolicy describes this server's gates. hostPolicy reports external host enforcement with unknown effective runtime permissions. Do not interpret a server allow as approval from Codex or another MCP host, or edit host config.toml to bypass a denial. Preserve customized host tool settings during installation.