PlatformIO — Signal Toolkit

What It Does

PlatformIO is an embedded development platform that runs as a VS Code extension. It replaces the Arduino IDE's board manager, library manager, and build system with a unified toolchain that supports over 1,500 boards across 50+ frameworks. It handles dependency resolution, cross-platform compilation, and serial debugging from within the VS Code editor.

Why You Need It

When projects grow beyond a single sketch file — multiple source files, custom libraries, build configurations per board — PlatformIO manages the complexity that Arduino IDE was not designed for. It also provides proper IntelliSense, linting, and debugging that professional embedded workflows require.

Used in: SG-21 SG-22

How to Install It

Download VS Code first if you do not have it: https://code.visualstudio.com

VS Code Extension (all platforms)

Open VS Code.
Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).
Search for PlatformIO IDE and click Install.
Wait for the initial setup to complete. PlatformIO will download its core CLI and base toolchains automatically. This takes several minutes on the first install.
Restart VS Code when prompted. The PlatformIO alien-head icon should appear in the sidebar.

CLI Only (advanced)

If you prefer the CLI without VS Code:

pip install platformio

Verify the install:

pio --version

Linux USB Permissions

Same as Arduino IDE — add yourself to dialout:

sudo usermod -aG dialout $USER

Log out and back in for this to take effect.

How to Use It

Create a project. Click the PlatformIO icon in the VS Code sidebar, then New Project. Choose your board (e.g., "Espressif ESP32 Dev Module") and framework (usually "Arduino"). PlatformIO generates a platformio.ini config file and a src/ folder for your code.
Write code. Put your main sketch in src/main.cpp. PlatformIO uses .cpp files, not .ino. Add #include <Arduino.h> at the top — the Arduino IDE adds this implicitly, PlatformIO does not.

Add libraries. Edit platformio.ini and add a lib_deps line:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
    adafruit/Adafruit NeoPixel@^1.12.0

PlatformIO downloads the library automatically on next build.

Build and upload. Click the checkmark icon (Build) or the right-arrow icon (Upload) in the PlatformIO toolbar at the bottom of VS Code. Or use the CLI:
```
pio run --target upload
```
Monitor serial output. Click the plug icon in the toolbar, or:
```
pio device monitor --baud 115200
```

Common Gotchas

PlatformIO takes several minutes on first install to download toolchains. The extension installs Python, the PIO Core, and platform packages. Do not close VS Code or assume it is frozen — watch the progress bar in the VS Code status bar. On slow connections this can take 10+ minutes.

Arduino .ino files do not work directly. Rename them to .cpp, add #include <Arduino.h> at the top, and ensure all function prototypes are declared before use. The Arduino IDE auto-generates prototypes; PlatformIO follows standard C++ rules.

"No such board" errors after selecting a board. The platform package for that board family may not be installed yet. PlatformIO downloads platform packages on demand. Check platformio.ini — the platform line must match your board (e.g., espressif32 for ESP32 boards, atmelavr for Arduino Uno/Nano).

VS Code IntelliSense shows red squiggles on valid Arduino code. Run PlatformIO: Rebuild IntelliSense Index from the Command Palette (Ctrl+Shift+P). PlatformIO generates a .vscode/c_cpp_properties.json that the C/C++ extension reads — it sometimes falls out of sync after adding libraries.

PlatformIO and Arduino IDE conflict on serial ports. Only one program can hold a serial port at a time. Close the Arduino IDE Serial Monitor before uploading from PlatformIO, and vice versa.