Tema 0 · Entorno ESP32-C3 con VS Code y PlatformIO

En esta asignatura vas a perseguir eventos a dos alturas muy distintas. En Android el sistema te entrega un onClick ya masticado; en un sistema empotrado puedes seguir el evento desde el cambio eléctrico en un pin hasta la interrupción, la rutina que la atiende y el código que acaba usando ese dato. Esta unidad deja listo el entorno para la parte empotrada.

La placa de referencia es la ESP32-C3-DevKitM-1, que PlatformIO identifica como esp32-c3-devkitm-1. Su microcontrolador tiene un núcleo RISC-V de 32 bits, Wi-Fi y Bluetooth Low Energy.

Anfitrión frente a objetivo

La idea clave del día es separar dos máquinas:

• Anfitrión (host): tu Windows o tu Mac, donde escribes y compilas.
• Objetivo (target): el núcleo RISC-V de la ESP32-C3, donde se ejecutará el firmware.

Compilas en un sitio para ejecutar en otro. Por eso hace falta una toolchain específica (compilador, ensamblador, enlazador y utilidades para RISC-V), y por eso compilar sin placa es una prueba real: valida el código, el framework, el compilador y el enlazado. Lo único que queda pendiente es la interacción con el hardware.

Compilar para una ESP32-C3 pide pocos recursos. Lo esencial: que VS Code sea compatible con tu sistema, espacio para los paquetes de PlatformIO e Internet durante la primera instalación.

Autodiagnóstico en dos minutos. En Windows: Win + R → msinfo32 → «Tipo de sistema», y el espacio libre en Este equipo. En macOS: menú Apple → «Acerca de este Mac» y Ajustes del Sistema → General → Almacenamiento. No necesitas virtualización para compilar.

Reglas que evitan casi todos los problemas

1. Misma plantilla y mismo platformio.ini que el resto de la clase: no cambies platform, board ni framework.
2. En Windows, usa Git Bash para los comandos: así la sintaxis es casi la de macOS.
3. Rutas simples, sin tildes: C:\dev\pde en Windows, ~/dev/pde en macOS.
4. No instales a mano GCC para RISC-V, esptool ni Arduino-ESP32: PlatformIO gestiona versiones compatibles en ~/.platformio.
5. No borres ~/.platformio para «arreglar» algo sin saber la causa: tendrías que volver a descargarlo todo.
6. Hoy no lances pio run -t upload ni pio device monitor: sin placa no se pueden verificar.
7. Distingue compilación de ejecución.

En Windows usamos Git for Windows porque, además de Git, trae Git Bash, una terminal con sintaxis tipo Unix. Luego instalamos VS Code y, desde el propio editor, la extensión PlatformIO IDE.

1. Git. Descarga el instalador para tu arquitectura desde https://git-scm.com/download/win y deja las opciones por defecto (el editor predeterminado da igual).
2. Abre Inicio → Git Bash y comprueba:

git --version

3. VS Code desde https://code.visualstudio.com («User Installer» basta). Marca Add to PATH si aparece. Cierra y vuelve a abrir Git Bash.
4. Comprueba:

code --version

5. PlatformIO IDE. En VS Code, Ctrl + Shift + X, busca «PlatformIO IDE», verifica que el publicador es PlatformIO y pulsa Install. Espera a que se pueda abrir PIO Home.
6. La extensión instala su Core en ~/.platformio. Para usar pio fuera de VS Code, añade su carpeta Scripts al PATH de Bash:

echo 'export PATH="$HOME/.platformio/penv/Scripts:$PATH"' >> ~/.bashrc
source ~/.bashrc
pio --version

7. Si pio sigue sin existir, abre una vez PIO Home, espera a que termine y abre una Git Bash nueva.

La instalación está lista cuando git --version, code --version y pio --version responden. En Windows ARM64 usa instaladores ARM64; no hace falta activar Hyper-V, WHPX ni virtualización.

En macOS Git llega con las Command Line Tools de Apple y la terminal por defecto es zsh.

1. Git. En Terminal:

xcode-select --install

Pulsa «Instalar», acepta la licencia y espera. Si dice que ya están instaladas, sigue. Después: git --version.

2. VS Code desde https://code.visualstudio.com, versión Apple Silicon o Intel según tu equipo. Arrástralo a Aplicaciones.
3. Para tener el comando code: en VS Code, Cmd + Shift + P → escribe «shell command» → Shell Command: Install 'code' command in PATH. Cierra y abre Terminal y prueba code --version.
4. PlatformIO IDE. Cmd + Shift + X, busca «PlatformIO IDE» del publicador PlatformIO, Install, y espera a que termine PlatformIO Core.
5. Añade PlatformIO al PATH de zsh:

echo 'export PATH="$HOME/.platformio/penv/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
pio --version

6. Si pio no aparece, abre PIO Home, espera a que se inicialice, abre una Terminal nueva y repite.

Windows frente a macOS, de un vistazo

PlatformIO separa tres conceptos que conviene no mezclar:

La plantilla de la asignatura trae exactamente esto:

[env:esp32-c3-devkitm-1]
platform = espressif32@7.0.1
board = esp32-c3-devkitm-1
framework = arduino
monitor_speed = 115200

Léelo línea a línea como decisiones reproducibles:

• [env:...] da nombre al entorno. Ese nombre aparece luego en la salida de pio run y en la carpeta .pio/build/esp32-c3-devkitm-1/.
• platform = espressif32@7.0.1 fija la versión de la plataforma, para que toda la clase resuelva el mismo conjunto de paquetes.
• board selecciona la ESP32-C3-DevKitM-1.
• framework = arduino activa la API Arduino-ESP32. No significa que uses el IDE de Arduino.
• monitor_speed = 115200 deja preparado el monitor serie para cuando haya placa.

Cómo llega la toolchain

No descargas ningún compilador RISC-V. Al procesar el proyecto, el gestor de paquetes de PlatformIO resuelve plataforma, toolchain, framework y utilidades, y lo guarda en ~/.platformio:

pio pkg install   # instala o completa los paquetes del proyecto
pio pkg list      # muestra lo que ha quedado resuelto
pio project config  # cómo interpreta PlatformIO tu platformio.ini
pio boards esp32-c3 # placas cuyo identificador contiene esp32-c3

La primera vez tarda varios minutos y descarga cientos de megabytes; después se reutiliza la caché.

Partimos de una plantilla común en lugar de crear el proyecto desde cero: así todos compilamos para la misma placa, plataforma y framework, y nadie obtiene resultados distintos por haber creado el proyecto otro día.

La plantilla es pde-esp32c3-eventos.zip y contiene platformio.ini, src/main.cpp y un README.md. No trae la toolchain ni binarios: eso lo resuelve PlatformIO en tu equipo.

1. Crea la carpeta

# Windows · Git Bash
mkdir -p /c/dev/pde
cd /c/dev/pde
pwd

# macOS · Terminal
mkdir -p ~/dev/pde
cd ~/dev/pde
pwd

2. Descomprime y abre

Copia el ZIP a esa carpeta y extráelo (Windows: clic derecho → «Extraer todo…»; macOS: doble clic). Luego:

cd /c/dev/pde/pde-esp32c3-eventos   # en macOS: cd ~/dev/pde/pde-esp32c3-eventos
code .

Si PlatformIO reconoce platformio.ini, la barra inferior muestra Build, Upload y Serial Monitor. Hoy solo usas Build.

3. Reconoce la estructura

pde-esp32c3-eventos/
├── platformio.ini
├── README.md
└── src/
    └── main.cpp

Al compilar aparecerá además .pio: paquetes y resultados generados. No la edites ni la entregues. Antes de compilar, confirma que estás en la raíz:

pwd
ls      # debe aparecer platformio.ini

Si ls no muestra platformio.ini, estás un nivel por encima o por debajo y pio run no sabrá qué proyecto construir.

La compilación no necesita dispositivo: el objetivo ya está descrito en platformio.ini. Desde la raíz del proyecto:

pio pkg install
pio run

La primera vez descargará paquetes y luego compilará y enlazará. Al final debe aparecer SUCCESS para el entorno esp32-c3-devkitm-1.

Los artefactos

ls -lh .pio/build/esp32-c3-devkitm-1/

De forma simplificada, pio run coordina: fuente C/C++ → preprocesado → compilación → objetos → enlazado → firmware. Tú no invocas gcc, el enlazador ni esptool a mano.

Comandos útiles

pio run -t clean   # limpia la compilación sin borrar las dependencias descargadas
pio run            # vuelve a compilar desde cero
pio run -v         # verbose: compilador, flags, cabeceras y paquetes reales

La salida -v es enorme: úsala solo cuando necesites saber qué está usando PlatformIO de verdad. Desde la interfaz, lo mismo es PlatformIO (barra lateral) → Project Tasks → esp32-c3-devkitm-1 → General → Build.

Verificación completa

git --version && code --version && pio --version && pio system info
pio project config
pio pkg install
pio pkg list
pio run
ls -lh .pio/build/esp32-c3-devkitm-1/

Cuando algo falla, busca el primer error significativo: los mensajes posteriores suelen ser consecuencia de él. Esta es la parte de la tabla de problemas que tiene que ver con la terminal, el PATH y la carpeta en la que estás.

Ahora tú. Lee cada caso, decide la causa y la primera acción.

La segunda mitad de la tabla trata de lo que pasa dentro del proyecto: paquetes, red, disco y hardware.

Red del campus y proxy

Si la descarga va en casa pero falla en el campus, no toques platformio.ini: el problema es de conectividad, no de la placa. Si el centro usa un proxy, se configura de forma temporal en la terminal con los datos reales que te den:

export HTTP_PROXY=http://proxy.ejemplo:8080
export HTTPS_PROXY=http://proxy.ejemplo:8080
pio pkg install

No dejes contraseñas en documentos compartidos ni en el historial. Si una descarga queda a medias, vuelve a lanzar pio pkg install: PlatformIO detecta lo que falta y continúa.

Si tu equipo no puede

PlatformIO Core desde Python (avanzado, no recomendado para la clase), Wokwi (simulador web con ESP32, GPIO, botones e interrupciones), un equipo del aula, o hacer la primera descarga en otra red y conservar el perfil de usuario.

Lista final: git, code y pio responden · ruta simple (C:\dev\pde o ~/dev/pde) · VS Code reconoce platformio.ini · pio project config muestra el entorno · pio pkg install y pio pkg list correctos · pio run en SUCCESS · existen los dos artefactos.