89 lines
2.5 KiB
Markdown
89 lines
2.5 KiB
Markdown
# 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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```ini
|
|
[env:esp32dev]
|
|
platform = espressif32
|
|
board = esp32dev
|
|
framework = arduino
|
|
monitor_speed = 115200
|
|
upload_port = /dev/ttyUSB0
|
|
lib_deps =
|
|
knolleary/PubSubClient @ ^2.8
|
|
```
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|