Qué es PlatformIO (PIO) y por qué se convirtió en estándar para ESP32

La pregunta que todo el mundo hace mal

La duda suele formularse así: "¿PlatformIO es un editor mejor que Arduino IDE?". No lo es, y esa comparación dificulta entenderlo.

PlatformIO no es un editor, un compilador ni un grabador. Es un gestor: el programa que descubre lo que necesita tu proyecto, descarga cada pieza en la versión correcta, llama al compilador adecuado con los parámetros adecuados y después graba el firmware en la placa. Tú eliges el editor; PlatformIO instala el compilador.

Una comparación útil es pensar en un director de orquesta. No toca ningún instrumento, pero sin él los instrumentos no tocan juntos.

Por qué el comando se llama "pio" y no "platformio"

PIO es el propio comando. Después de instalarlo, el programa se llama pio en la terminal; platformio también funciona, porque es el mismo ejecutable con dos nombres.

Por eso aparecen las dos formas en Internet. Cuando un tutorial escribe pio run, es exactamente lo mismo que platformio run. Y cuando el comando no está en el PATH del sistema, todavía puedes llamarlo desde Python:

Las tres líneas hacen lo mismo.

Dos piezas con el mismo nombre

Aquí nace buena parte de la confusión. "PlatformIO" se refiere a dos productos diferentes:

PlatformIO Core es el programa de línea de comandos, pio. Es el que realiza todo el trabajo de verdad y funciona sin ningún editor.

PlatformIO IDE es una extensión de VS Code. No sustituye a Core: lo instala por debajo y coloca botones en pantalla para llamar a los mismos comandos. Cuando haces clic en el botón de compilar, por detrás se ejecuta pio run.

Por eso son válidos tanto los tutoriales de línea de comandos como los de interfaz gráfica: ambos conducen el mismo motor.

El problema que resuelve

Imagina que montas un proyecto en Arduino IDE. Para que funcione tuviste que añadir la URL del gestor de placas, instalar el core de ESP32, instalar tres bibliotecas mediante el gestor y ajustar dos opciones del menú Herramientas.

Ahora envías el proyecto a otra persona. Esa persona recibe solo el código; las decisiones se quedaron en tu máquina, dentro de menús. Tiene que repetirlo todo a mano, adivinando qué bibliotecas y qué versiones usaste. Si instala una versión diferente de una biblioteca, el programa puede compilar y comportarse de otra manera.

PlatformIO lo resuelve trasladando todas esas decisiones a un archivo de texto dentro del proyecto: platformio.ini. Quien reciba la carpeta ejecuta un comando y PlatformIO descarga lo que falte, usando las versiones que fijaste.

Es la diferencia entre "funciona en mi máquina" y "funciona en cualquier máquina".

Las cuatro capas que gestiona

Cuando compilas por primera vez, PlatformIO descarga cuatro tipos de componentes. Conviene conocer sus nombres porque los mensajes de error usan este vocabulario.

1. Plataforma

Es el paquete que enseña a PlatformIO a trabajar con una familia de chips. Para ESP32, la plataforma se llama espressif32. Sabe cuánta memoria tiene cada modelo, cómo poner el chip en modo de grabación y qué herramienta de carga utilizar.

2. Framework

Es la API con la que escribes el programa. En ESP32 hay dos opciones principales: arduino, con setup() y loop(), y espidf, el framework oficial de Espressif, más detallado y con mayor control. El mismo chip, dos formas de programarlo.

3. Herramientas

Compilador, ensamblador, grabador y utilidades. En ESP32 entran paquetes como tool-esptoolpy, el grabador oficial de Espressif, y tool-cmake. No instalas nada de esto manualmente; por eso la primera compilación tarda unos minutos.

4. Bibliotecas

Se declaran en lib_deps y se descargan del registro de PlatformIO o directamente de un repositorio Git.

Dónde se guarda todo

Las cuatro capas no están dentro del proyecto. Viven en una única carpeta del usuario, .platformio, con las subcarpetas platforms, packages y su propio Python.

Esto tiene dos ventajas prácticas. La primera es que diez proyectos que usan ESP32 comparten el mismo compilador, descargado una sola vez. La segunda es que la carpeta del proyecto sigue siendo pequeña y fácil de enviar.

Dentro del proyecto, PlatformIO crea la carpeta .pio, con los archivos temporales de compilación y el binario generado. Esta carpeta es desechable: puedes borrarla sin miedo y se volverá a crear en la siguiente compilación. Por eso nunca entra en el ZIP ni en Git.

Leer platformio.ini

Este es el archivo que describe todo el proyecto. Un ejemplo mínimo para ESP32:

Línea por línea: [env:esp32dev] abre un entorno llamado esp32dev; platform indica la familia de chips; framework indica la API; board indica el modelo exacto de placa; monitor_speed fija la velocidad del monitor serie para no tener que escribirla cada vez.

El campo board es el que más trabajo ahorra. Al escribir board = esp32dev, PlatformIO ya sabe que ese modelo es un ESP32 de 240 MHz, con 4 MB de flash y 320 KB de RAM, y prepara el mapa de memoria correspondiente. Actualmente reconoce más de 1.100 modelos de placa; puedes listarlos con pio boards.

Varios entornos en el mismo proyecto

Un proyecto puede declarar tantos entornos como necesite, y así el mismo código sirve para placas diferentes:

build_flags pasa definiciones al compilador antes de compilar. En el ejemplo, el mismo main.cpp activa la parte de pantalla solo en el entorno de la placa que tiene pantalla, sin duplicar archivos ni comentar líneas a mano.

Fijar versiones de bibliotecas

^1.11.11 significa "esta versión o una revisión compatible posterior, pero ningún cambio que rompa el proyecto". Así el proyecto compilado hoy seguirá compilando dentro de seis meses.

Los comandos que resuelven el 90 % del uso

El primero compila. El segundo compila y graba. El tercero lista los puertos serie. El cuarto abre el monitor. El quinto limpia la carpeta .pio cuando algo se queda extraño: el famoso "borrar y compilar otra vez", con su propio comando.

En VS Code, esos mismos comandos aparecen en los iconos de la barra inferior: marca para compilar, flecha para grabar y enchufe para el monitor.

¿PlatformIO o Arduino IDE?

Ninguno es mejor para todo. La elección depende de lo que estés construyendo.

Arduino IDE gana durante la primera hora: se instala rápido, tiene menos conceptos y permite compilar sin entender la estructura del proyecto. Para encender un LED y aprender la lógica, es suficiente.

PlatformIO gana cuando el proyecto crece o sale de tu máquina: configuración versionada junto con el código, varias placas en el mismo proyecto, versiones de bibliotecas fijadas, pruebas automatizadas e integración con sistemas de compilación. Por eso domina en proyectos profesionales y firmware industrial.

Algo suele sorprender: no compiten. PlatformIO usa el mismo Arduino Core por debajo cuando eliges framework = arduino. El código que escribiste en Arduino IDE compila igual; solo cambia quién organiza la construcción.

Tres malentendidos comunes

"Tengo que instalar el compilador antes." No. PlatformIO descarga el compilador en la primera compilación. Instalar la toolchain a mano suele crear conflictos en vez de resolverlos.

"Borré .pio y perdí el proyecto." No lo perdiste. Tu código está en src y .pio solo contiene el resultado de la compilación.

"PlatformIO es de pago." Core y la extensión de VS Code son gratuitos y de código abierto. Hay servicios de pago opcionales para equipos y desarrollo remoto, pero no necesitas ninguno para compilar y grabar.

Por dónde empezar

Si llegaste aquí para entender qué es PIO antes de instalarlo, el siguiente paso es elegir uno de dos caminos prácticos: el tutorial de primeros pasos mediante VS Code, completamente basado en botones, o el tutorial de línea de comandos con la placa que tiene pantalla. Los dos usan el mismo proyecto y el mismo platformio.ini descrito aquí; ahora el vocabulario tiene sentido.