PlatformIO

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<value>) 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…

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.

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

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.

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.

Close a serial monitor session and release the port.

Send text to the device over the open session's serial port (newline appended by default). 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…

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=.

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

Show which project dependencies have newer versions available.

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'.

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

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

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.

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<value>) and optional (?P<unit>)/(?P<voltage>) groups, default: first number with uA/mA/A). source='ppk2' drives a Nordic Power Profiler Kit II (needs the `power` extra).…

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.

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.

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.

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.

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.

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.

Run PlatformIO unit tests (`pio test`, Unity framework) and return per-case pass/fail with file, line, and message. Tests live in test/test_<name>/. 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*'.

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.

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/<env>/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…