2026-04-03 14:35:33 -07:00
|
|
|
|
# pio
|
|
|
|
|
|
pio stands for "PlatformIO".
|
|
|
|
|
|
|
|
|
|
|
|
In your context (ESP32 / T-Beam / PlatformIO workflows), **“pio” stands for:**
|
|
|
|
|
|
|
|
|
|
|
|
> **PlatformIO**
|
|
|
|
|
|
|
|
|
|
|
|
More precisely, `pio` is the **command-line interface (CLI)** for the PlatformIO environment.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## What PlatformIO is (practically speaking)
|
|
|
|
|
|
|
|
|
|
|
|
PlatformIO is an embedded development framework that wraps:
|
|
|
|
|
|
|
|
|
|
|
|
* toolchains (GCC for ESP32, ARM, etc.)
|
|
|
|
|
|
* build system
|
|
|
|
|
|
* library manager
|
|
|
|
|
|
* uploader (esptool, etc.)
|
|
|
|
|
|
* serial monitor
|
|
|
|
|
|
|
|
|
|
|
|
So instead of juggling:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
xtensa-esp32-elf-gcc
|
|
|
|
|
|
esptool.py
|
|
|
|
|
|
arduino-cli
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
…you use:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pio run
|
|
|
|
|
|
pio run -t upload
|
|
|
|
|
|
pio device monitor
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## What `pio` actually does in your workflow
|
|
|
|
|
|
|
|
|
|
|
|
Given your T-Beam usage (as shown in the LilyGO docs, which explicitly include PlatformIO as a supported environment ), `pio` is orchestrating:
|
|
|
|
|
|
|
|
|
|
|
|
### Build
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pio run
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
* compiles your firmware using the environment in `platformio.ini`
|
|
|
|
|
|
|
|
|
|
|
|
### Upload
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pio run -t upload
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
* invokes the correct uploader (ESP32 → `esptool`)
|
|
|
|
|
|
* uses the selected `/dev/tty*` device
|
|
|
|
|
|
|
|
|
|
|
|
### Monitor
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pio device monitor
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
* serial console at configured baud
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## Why it exists (the “systems view”)
|
|
|
|
|
|
|
|
|
|
|
|
PlatformIO abstracts away:
|
|
|
|
|
|
|
|
|
|
|
|
* board definitions
|
|
|
|
|
|
* pin mappings
|
|
|
|
|
|
* compiler flags
|
|
|
|
|
|
* library dependencies
|
|
|
|
|
|
|
|
|
|
|
|
In your `platformio.ini`, for example:
|
|
|
|
|
|
|
|
|
|
|
|
```ini
|
|
|
|
|
|
[env:node_a]
|
|
|
|
|
|
platform = espressif32
|
|
|
|
|
|
board = esp32-s3-devkitc-1
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
That single block drives:
|
|
|
|
|
|
|
|
|
|
|
|
* toolchain selection
|
|
|
|
|
|
* linker scripts
|
|
|
|
|
|
* upload protocol
|
|
|
|
|
|
* memory layout
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## Important nuance (since you’re working low-level)
|
|
|
|
|
|
|
|
|
|
|
|
`pio` is **not**:
|
|
|
|
|
|
|
|
|
|
|
|
* a compiler
|
|
|
|
|
|
* a flasher
|
|
|
|
|
|
* an IDE
|
|
|
|
|
|
|
|
|
|
|
|
It is a **build orchestration layer** (think “make + package manager + uploader + board database”).
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## Quick mental model
|
|
|
|
|
|
|
|
|
|
|
|
If we translate to Unix analogies:
|
|
|
|
|
|
|
|
|
|
|
|
| Concept | Analogy |
|
|
|
|
|
|
| ------------------- | -------------------------------------------- |
|
|
|
|
|
|
| PlatformIO | `portage + make + gcc + flash tool` combined |
|
|
|
|
|
|
| `pio run` | `make` |
|
|
|
|
|
|
| `pio run -t upload` | `make install` (but to hardware) |
|
|
|
|
|
|
| `platformio.ini` | hybrid of `Makefile` + config |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## Bottom line
|
|
|
|
|
|
|
|
|
|
|
|
When you type:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pio run -t upload
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
You are saying:
|
|
|
|
|
|
|
|
|
|
|
|
> “Use PlatformIO to build this firmware for the specified environment and flash it to the target device.”
|
|
|
|
|
|
|
|
|
|
|
|
|
2026-04-06 11:38:06 -07:00
|
|
|
|
## PlatformIO configuration file
|
|
|
|
|
|
platformio.ini is the configuration file. Each unit should have it's own entry so that the code can automaticaly be modified.
|
|
|
|
|
|
|
|
|
|
|
|
INSERT IMAGE
|
|
|
|
|
|
|
|
|
|
|
|
## Uploading Image
|
|
|
|
|
|
pio run -e flo -t upload --upload-port /dev/ttytFLO
|
