PlatformIO

Warnings

• breaking PlatformIO Core 6.0 introduced a unified Package Management CLI (`pio pkg`), deprecating older commands like `pio lib`, `pio platform`, and `pio update`. Scripts or configurations relying on these older commands will break.
  Fix: Migrate to the new `pio pkg` commands. For example, use `pio pkg install` instead of `pio lib install` or `pio platform install`. Review the PlatformIO 6.0 Migration Guide.
• gotcha Having multiple PlatformIO Core installations or conflicting Python interpreters (especially on Windows) can lead to various issues, including `ImportError` or `pio` command not being recognized.
  Fix: For VSCode IDE users, enable 'Use built-in PlatformIO Core' in settings. For standalone users, ensure only one instance of PlatformIO Core is installed, preferably using the recommended installer script which uses an isolated virtual environment. Uninstall obsolete Python interpreters and PlatformIO cores if necessary.
• gotcha PlatformIO Core (CLI) does not support projects with non-ASCII characters in their full path or in library names, leading to `UnicodeDecodeError` during compilation or `UnicodeWarning`.
  Fix: Ensure all project folders and source files are located in paths that contain only ASCII characters. Avoid using non-ASCII characters in project names or directory structures.
• gotcha Antivirus software can interfere with PlatformIO's background operations (e.g., downloading and unpacking packages), resulting in 'Access is denied' errors.
  Fix: Temporarily disable your antivirus, or add the PlatformIO Core directory (`~/.platformio` on Unix, `C:\Users\YourUserName\.platformio` on Windows) to your antivirus's exclusion/whitelist. Running `pio` commands from a system terminal might also bypass some antivirus blocks.
• gotcha Not explicitly defining platform and library versions in `platformio.ini` (e.g., `platform = espressif32` instead of `platform = espressif32@^6.10.0`) can lead to projects breaking with future updates of platforms or libraries.
  Fix: Always use Semantic Versioning Requirements (`@^x.y.z`, `@~x.y.z`, etc.) for `platform` and `lib_deps` in your `platformio.ini` to ensure project reproducibility and stability over time.

Install

• pip install platformio Via Python Package Manager (recommended for CI/containers)
• python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py)" Via Installer Script (recommended for personal use)

Quickstart

This quickstart demonstrates how to programmatically interact with PlatformIO Core CLI from Python. It initializes a new PlatformIO project for an `esp32dev` board and then lists the packages installed for that project. This interaction pattern is common for integrating PlatformIO into automation scripts or custom applications, as PlatformIO's primary interface is its command-line tool (`pio`). Ensure 'pio' is in your system's PATH.

import subprocess
import os

# Create a dummy project directory
project_dir = "my_pio_project"
os.makedirs(project_dir, exist_ok=True)
os.chdir(project_dir)

try:
    # Initialize a PlatformIO project for a common board (e.g., esp32dev)
    # This will download necessary frameworks and tools into the project's .pio folder
    print(f"Initializing PlatformIO project in {os.getcwd()}...")
    result = subprocess.run(
        ["pio", "project", "init", "--board", "esp32dev"],
        capture_output=True, text=True, check=True
    )
    print("\n--- pio project init Output ---")
    print(result.stdout)
    if result.stderr:
        print("\n--- pio project init Errors ---")
        print(result.stderr)

    # List installed packages within the project
    print("\nListing installed packages...")
    result = subprocess.run(
        ["pio", "pkg", "list"],
        capture_output=True, text=True, check=True
    )
    print("\n--- pio pkg list Output ---")
    print(result.stdout)

except subprocess.CalledProcessError as e:
    print(f"Error executing PlatformIO command: {e}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
except FileNotFoundError:
    print("Error: 'pio' command not found. Ensure PlatformIO Core CLI is installed and in your PATH.")
finally:
    # Clean up the created project directory
    os.chdir("..")
    # In a real scenario, you might want to remove the directory:
    # import shutil
    # shutil.rmtree(project_dir)
    print(f"\nQuickstart finished. Project directory: {project_dir}")