Programar el ESP32 en VS Code con PlatformIO

Para quién es este tutorial

Este es el camino para quien prefiere trabajar con una interfaz gráfica. Todos los pasos ocurren dentro de VS Code haciendo clic en botones; no hace falta escribir ningún comando en la terminal.

La placa objetivo es el ESP32 clásico de dos núcleos, el que tiene el módulo plateado WROOM-32 y dos filas de pines. El ejemplo hace parpadear el LED azul soldado en la propia placa, conectado al GPIO 2.

Si prefieres la línea de comandos o tienes la placa con pantalla, consulta el tutorial hermano de primeros pasos con ESP32-C3 y LCD de 1,44 pulgadas. Elige uno de los dos: hacer ambos al mismo tiempo solo genera confusión.

Qué instalar

Hay dos instalaciones, en este orden. Primero instala Visual Studio Code desde el sitio oficial, acepta las opciones predeterminadas y deja activada la opción para añadirlo al PATH.

Después, dentro del propio VS Code, instala la extensión PlatformIO IDE: haz clic en el icono de Extensiones de la barra lateral izquierda, busca PlatformIO IDE e instala la extensión de PlatformIO Labs. La primera instalación descarga PlatformIO Core y tarda unos minutos.

La instalación funcionó cuando aparece un icono de hormiga en la barra lateral y una nueva barra de herramientas en la parte inferior de la ventana, con símbolos de casa, marca de verificación y flecha.

Abrir el proyecto correctamente

Extrae la carpeta del proyecto en un lugar fácil de encontrar, como Documentos, y nunca trabajes desde dentro del ZIP. En VS Code, elige Archivo y después Abrir carpeta.

Aquí ocurre el error más común de PlatformIO: abre la carpeta que contiene platformio.ini, no la carpeta superior. Si abres la carpeta equivocada, PlatformIO no reconoce el proyecto y su barra de herramientas simplemente no aparece; es fácil pensar que la instalación falló.

Elegir el entorno de la placa

El mismo proyecto admite tres placas diferentes: el ESP32 común, ESP32-S3 y el ESP32-C3 con pantalla. Para el ESP32 clásico, el entorno es esp32dev, que ya está incluido en el archivo de configuración.

En la parte inferior de VS Code, haz clic en el nombre del entorno y elige env:esp32dev en la lista que aparece en la parte superior de la ventana. Ese es el entorno que define el LED del GPIO 2.

Conectar la placa

Conecta el ESP32 con un cable USB de datos; un cable que solo sirve para cargar no transmite datos y es la causa más común de que la placa no aparezca. Después abre el icono de la hormiga, entra en Devices y haz clic en Device List.

Si solo aparece COM1, o no aparece ningún puerto, casi siempre se trata de un controlador: el convertidor USB-serie de tu placa es un CP2102 o un CH340 y Windows no siempre incluye el controlador listo. Comprueba qué chip está impreso cerca del conector USB e instala el controlador correspondiente.

Cómo descubrir el puerto COM de la placa

COM es el nombre que Windows asigna al puerto serie. Cada ordenador numera los puertos de una forma, así que el mismo ESP32 puede ser COM3 en una máquina y COM7 en otra.

La ruta más fiable es el Administrador de dispositivos: haz clic en el menú Inicio, escribe Administrador de dispositivos, abre el resultado, busca la sección Puertos (COM y LPT) y expándela. El número entre paréntesis es tu puerto.

La placa no aparece con el nombre ESP32; aparece con el nombre del convertidor USB-serie soldado en ella. Es normal ver algo como Silicon Labs CP210x USB to UART Bridge (COM5) o USB-SERIAL CH340 (COM3). Si aparece un triángulo amarillo en lugar del nombre, el controlador no está instalado.

Existe un método infalible cuando hay varios dispositivos serie conectados: abre el Administrador de dispositivos con la placa desconectada y observa la sección Puertos. Conecta el cable y vuelve a mirar. El puerto que apareció es el tuyo.

En la mayoría de los casos no necesitas esta información: PlatformIO detecta el puerto automáticamente al cargar. Solo hace falta encontrar el COM cuando hay más de un dispositivo serie conectado y se elige el incorrecto. En ese caso, fija el puerto añadiendo dos líneas al entorno de platformio.ini:

Un detalle confunde a mucha gente: COM1 casi nunca es tu placa. Suele ser un puerto serie de la propia placa base que existe aunque no haya nada conectado. Si solo aparece COM1, el ESP32 no fue reconocido.

Compilar y cargar con los botones

En la barra inferior, la marca de verificación compila y la flecha hacia la derecha carga el firmware. Haz clic primero en la marca: la primera compilación descarga el compilador y las bibliotecas, así que tarda unos minutos. El resultado esperado es SUCCESS en verde en la terminal.

Si aparece FAILED, desplázate por la terminal hasta la primera línea roja. Esa línea explica la causa; la última casi nunca lo hace.

Después haz clic en la flecha para cargar. No retires el cable durante la carga. Si se queda en Connecting, mantén pulsado el botón BOOT de la placa hasta que empiece la carga; en algunas placas hay que pulsar EN una vez mientras se mantiene BOOT y después soltar BOOT.

Lo que deberías ver

Después de cargar, la placa se reinicia sola y el LED azul empieza a parpadear: un segundo encendido y un segundo apagado. Si el LED parpadea, se validan a la vez tres elementos: el procesador, la memoria flash y la comunicación USB.

Para ver lo que informa el programa, haz clic en el icono de enchufe de la barra inferior. Abre el monitor serie a la velocidad correcta. La salida es:

Las dos últimas líneas se repiten cada segundo, al ritmo del parpadeo. Ese es el comportamiento esperado.

Antes de volver a cargar

Cierra el monitor serie con el icono de papelera de la terminal. Con el monitor abierto, el puerto está ocupado y la siguiente carga falla con un error de permisos. Es el segundo error más común al empezar.

Después de que funcione

Cambia una sola cosa cada vez y vuelve a cargar después de cada cambio. Empieza cambiando el intervalo del parpadeo de un segundo a 200 milisegundos, después escribe una frase propia en el monitor serie y luego conecta un LED externo con una resistencia a otro GPIO.

Guarda siempre una copia del último programa que funcionó. Cuando un experimento falle, podrás volver al punto anterior en segundos en vez de empezar de nuevo.