platformio (PlatformIO Core)

What it is

PlatformIO Core (pio) — cross-platform embedded build system: one platformio.ini pins the platform, board, framework (Arduino/ESP-IDF/Zephyr), and library deps. The default for multi-board firmware projects.

Install

Via pipx (isolated, current stable):

sudo apt install pipx python3-venv
pipx install platformio
pipx ensurepath          # re-login so ~/.local/bin is on PATH

Serial access + udev rules for common boards:

sudo usermod -aG dialout $USER
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules \
  | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

Authenticate

Core features need no login. pio account (registry publishing, remote builds) is optional — skip it; if ever used, token goes in Vaultwarden.

Configure for this environment

Example platformio.ini for an ESP32 lab node:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_port = /dev/ttyUSB0
lib_deps =
    knolleary/PubSubClient @ ^2.8

pio run                  # build all envs
pio run -t upload        # flash
pio device monitor       # serial
pio run -t clean

Self-hosted equivalent

Builds are fully local. The PlatformIO Registry is a cloud service, but deps are cached in ~/.platformio/ and can be vendored into the repo (lib_deps = symlink://lib/... or committed libraries) for offline reproducibility; firmware artifacts archive to MinIO (http://192.168.0.40:9000).

Aurélio integration

The embedded-linux skill drives pio for firmware build/upload/monitor cycles. Devices built here typically target the mqtt-local broker or aws-iot connectors.

Verify

pio --version
# PlatformIO Core, version 6.x.y
pio device list
# /dev/ttyUSB0  ...  USB Serial
pio run
# ... SUCCESS ... RAM: [...] Flash: [...]

Troubleshooting

First build downloads a lot — platforms/toolchains install into ~/.platformio/ on demand; keep that dir cached between CI runs.
Upload fails, port busy — close pio device monitor (or the IDE serial monitor) before flashing.
Board not auto-detected — set upload_port explicitly in platformio.ini (as above) after checking pio device list.
dialout permission errors — group membership needs a re-login; udev rules above fix most FTDI/CP210x/CH340 cases.

2.5 KiB Raw Blame History