Check that PlatformIO is installed and report its version, core directory, the active safety policy (full | build_only | read_only), the log directory, and any open serial monitor sessions. Call this first in a session; if PlatformIO is missing the result tells you how to install it.

Search PlatformIO's board catalogue (~1,700 boards). Query matches board id, name, MCU, or vendor, e.g. 'esp32-s3', 'uno', 'STM32F4', 'DOIT'. Returns board ids plus MCU, clock, RAM, flash, and frameworks. Use the returned id in platformio.ini or pio_project_init.

Full details for one board id: MCU, clock, RAM and flash sizes in bytes, supported frameworks, connectivity, and debug probes. Use it to learn memory limits before writing code.

Create a new PlatformIO project (or add an environment to an existing one) with pio project init. Give an absolute project_dir, a board id from pio_list_boards, and optionally a framework (arduino, espidf, stm32cube, zephyr, ...). project_options are extra platformio.ini keys like 'monitor_speed=115200' or 'lib_deps=bblanchon/ArduinoJson'. Never hand-write platformio.ini for a new project; use this.

Read platformio.ini and list every environment with its board, platform, framework, monitor/upload settings, lib_deps, and build_flags, plus which envs are default. Cheap; call before building or flashing.

Computed build metadata per environment: defines, include paths, compiler paths and flags, library dirs. Useful for understanding what the compiler actually sees. Triggers platform/toolchain install on first use.

Compile the project (pio run). Returns a status, parsed compiler errors and warnings with file/line/column, RAM and Flash usage percentages, the last 40 lines of output, and a path to the full log. Fix the listed errors, then build again. First builds may take minutes while toolchains download.

Build and flash firmware to the connected board (pio run -t upload). Refuses while a serial monitor session holds the port unless stop_open_sessions=true, which closes our own session(s) first. Pass upload_port when several boards are attached. Port failures come back classified (port_busy, port_permission, port_missing, no_response) with a port_diagnosis naming the holder and the fix. Blocked when PLATFORMIO_MCP_POLICY is build_only or read_only.

Delete build artifacts for an env (pio run -t clean); full=true also removes downloaded dependencies (fullclean).

List extra build targets the platform offers for this project, such as buildfs, uploadfs, erase, size, or menuconfig.

Run one named target from pio_list_targets (e.g. 'buildfs', 'uploadfs', 'erase', 'size'). Flash-related targets follow the same policy, stop_open_sessions, and port-diagnosis rules as pio_upload.

List serial ports (pio device list) and flag which ones look like USB dev boards (CP210x, CH340, FTDI, ESP, Arduino, ST-Link...). Use the port with pio_upload, pio_monitor_start, or pio_monitor_capture.

Explain why a serial port is unusable before or after a failed upload: whether it exists, whether one of our monitor sessions holds it, which other process has it open (lsof/fuser on macOS and Linux), and read/write permission, plus the concrete fix. Port defaults from platformio.ini or the single detected board. Reports only; it never closes anything.

Open a background serial monitor session and return a session_id. Port and baud default from platformio.ini (monitor_port/monitor_speed) when project_dir is given, else the single detected dev board and 115200. Output is buffered (ring buffer, max_lines); read it with pio_monitor_read. The session holds the port, so stop it before pio_upload.

Read new serial lines from a session since cursor (start at 0) and get the next cursor back. Set wait_for to a regex to block up to timeout_s until a matching line arrives (e.g. wait_for='setup done|Guru Meditation'). Without wait_for and with timeout_s>0 it waits for at least one new line.

Send text to the device over the open session's serial port (newline appended by default). Blocked under build_only/read_only policy.

Close a serial monitor session and release the port.

List open serial monitor sessions with port, baud, buffered line count, and next cursor.

One-shot serial capture with no session to manage: open the port, collect output for up to seconds (or until regex until matches), close the port, and return the lines. Ideal right after pio_upload to grab the boot log.

Run PlatformIO unit tests (pio test, Unity framework) and return per-case pass/fail with file, line, and message. Tests live in test/test_/. Native envs run on the host; embedded envs build, flash, and read results over serial (set without_uploading=true to only build them). filter/ignore take glob patterns like 'test_math*'.

Static analysis (pio check, cppcheck by default; clangtidy/pvs-studio if configured). Returns defects grouped and sorted by severity with file, line, CWE, and message. severity is the minimum level to report (low|medium|high).

Search the PlatformIO registry for libraries (default), platforms, or tools. Returns owner/name specs with the latest version and description. Example query: 'ArduinoJson', 'ssd1306 display', 'mqtt'.

Install a library/platform/tool into the project and add it to platformio.ini (pio pkg install -l spec). spec examples: 'bblanchon/ArduinoJson@^7', 'adafruit/Adafruit NeoPixel', 'https://github.com/user/repo.git'. Restrict to one env with env=.

Remove a library/platform/tool from the project and platformio.ini.

List resolved platform, toolchain, and library packages for the project with versions.

Show which project dependencies have newer versions available.

Update dependencies within the version ranges declared in platformio.ini.

Turn a crash dump into source locations. Give text containing an ESP32/ESP-IDF 'Guru Meditation' register dump and 'Backtrace: 0x...:0x...' line, or a Cortex-M HardFault pc/lr dump, or give session_id of an open monitor session to scan its buffer. Resolves every program-counter address with the toolchain's addr2line against the env's firmware.elf and returns function, file, line (with inlined frames) per address, plus the crash cause and reset reason. The ELF must be from the same build that was flashed.

Explain where flash and RAM go in the built firmware.elf: text/data/bss totals with percent of the board's flash and RAM, loaded sections classified as flash/ram, the biggest symbols (demangled, with file:line), and per-source-file totals. Use it to shrink firmware on purpose: drop the largest fonts/tables, remove unused features, tune build flags. Run pio_build first; filter is a regex applied to symbol names and file paths.

Hardware-in-the-loop check with no human: build + flash (pio run -t upload), then open the serial port and watch the boot log until expect (regex) matches -> verdict pass, or fail_on matches -> verdict fail with the crash automatically decoded to file:line, or timeout_s elapses -> verdict timeout. Port and baud come from platformio.ini (monitor_port/monitor_speed) or the single detected board. Set expect to a line your firmware prints once it is healthy, e.g. 'WiFi connected'. Blocked under build_only/read_only policy.

Flash firmware over Wi-Fi to an ESP32/ESP8266 running ArduinoOTA (espota). Give host (IP or name.local); port defaults to 3232 (ESP32) / 8266 (ESP8266) and auth is the ArduinoOTA password. By default it resolves and pings the host first, then runs pio run -t upload --upload-port <host> so the image matches the current build; build=false sends the existing .pio/build//firmware.bin with espota.py directly. filesystem=true sends the SPIFFS/LittleFS image instead. Failures are mapped to what to fix: no_response (ArduinoOTA.handle not running), auth_failed, no_callback (firewall), device_rejected (partition table has no OTA slot). Blocked under build_only/read_only policy.

Validate the ESP32 flash layout before it bites. Reads the partition CSV the env uses (board_build.partitions, project partitions.csv, or the Arduino framework default), checks alignment, overlaps, fit against the chip's flash size, OTA slot/otadata consistency, nvs/coredump presence, whether the built firmware.bin fits the smallest app slot, and whether the build dir's partitions.bin is stale. With read_device=true it also reads the live table at 0x8000 over serial (esptool) and diffs it against the CSV, catching the silent-corruption case where an app-only flash left an old table on the chip. Returns partitions plus issues with fixes.

Pull the ESP32 core dump out of the coredump flash partition after a crash (esptool read_flash) and save it. When the optional esp-coredump analyzer is installed (platformio.mcp[coredump]), it runs esp-coredump info_corefile against the env's firmware.elf with the toolchain's gdb and returns the crashed task, reason, registers, and backtrace. Reports clearly when the partition is erased (no crash recorded) or the analyzer is missing. Stop monitor sessions on the port first.

Measure the device's current draw for seconds and report average/min/max/p95 mA, energy (mWh and µAh when voltage is known), a bucketed timeline, the share of time in sleep vs active (threshold auto-detected from the two dominant current levels, or sleep_threshold_ma), and a battery-life estimate. source='serial' reads a meter streaming readings on port (INA219/INA226 sketch, USB power meter log; pattern regex with (?P) and optional (?P)/(?P) groups, default: first number with uA/mA/A). source='ppk2' drives a Nordic Power Profiler Kit II (needs the power extra). Set trigger + trigger_session_id to start measuring when the firmware prints a line.

Audit the project's library dependencies before they bite: compares lib_deps against what is installed in .pio/libdeps/, lib/, and lib_extra_dirs, and reports name collisions (two libraries with the same name, where lib_deps order silently decides which one wins), unpinned specs, declared-but-missing and leftover libraries, and circular dependencies between manifests. build=true also runs pio run and returns the LDF dependency graph as a tree, flagging a RecursionError as a cycle. Each issue carries a severity, message, and a concrete fix.

Watch serial output for heap and stack telemetry and diagnose leaks, fragmentation, and stack headroom. Give session_id of an open monitor session (its buffer plus seconds more) or a port for a one-shot capture. Understands Arduino-ESP32 'Free heap: N min: N largest: N', ESP.getFreeHeap() prints, ESP-IDF heap_caps_print_heap_info blocks, FreeRTOS vTaskList tables, and uxTaskGetStackHighWaterMark lines; pattern (regex with a (?P) group) adds a custom metric. Returns per-metric min/max/trend with a stable/shrinking/growing verdict, a per-task stack table flagged below stack_warn_bytes, and a fragmentation hint. When the firmware prints nothing usable, instrumentation_hint has copy-paste snippets.

Open a live gdb session on the board through its debug probe (pio debug --interface=gdb, GDB/MI over pipes): starts the debug server (OpenOCD, J-Link, ST-Link, esp-prog, ...) from debug_tool in platformio.ini, builds a debug firmware, loads it (load=true) and halts at debug_init_break (default: main). Returns session_id, the .pioinit script PlatformIO generated, and the initial stop frame. The session holds the probe: stop it (pio_debug_stop) before pio_upload or pio_flash_and_verify. Blocked under build_only/read_only policy.

Send one gdb command to an open debug session and get its output back, parsed from GDB/MI: bt, p var, p/x reg, info locals, info registers, x/16xw addr, break src/main.cpp:42, watch counter, next, step, finish, continue, monitor reset halt, or raw MI such as -stack-list-frames. Execution commands (continue/next/step/finish) block until the target stops again or timeout_s passes; on timeout the target keeps running and interrupt halts it. Returns result_class, console lines, error, and stopped {reason, frame{function,file,line}}.

Quit gdb and the debug server, resume the target, and free the probe so pio_upload works again.

List open debug sessions with env, debug tool, running/halted state, and the last stop frame.