Librerías compatibles con ESP32 y Arduino

Un sketch puede compilar en un Arduino Uno y fallar al cambiar a un ESP32 aunque el sensor, la pantalla y las conexiones sean correctos. Por eso, al buscar librerías compatibles ESP32 Arduino, no basta con ver que el nombre del módulo coincide: hay que comprobar la placa objetivo, el bus usado, los pines disponibles y la versión del core instalada.

El ESP32 se programa desde el entorno Arduino, pero no es un Arduino clásico. Tiene otro procesador, una arquitectura diferente, más memoria, Wi-Fi, Bluetooth, periféricos propios y restricciones que aparecen justo cuando se usa una librería antigua o poco mantenida. La buena noticia es que gran parte del ecosistema Arduino funciona en ESP32. La mala es que no todas las librerías que instalan sin error están realmente preparadas para él.

Qué significa que una librería sea compatible

Una librería compatible no es solo una que aparece en el gestor de librerías o que permite incluir un archivo con `#include`. Debe compilar para la familia ESP32, reconocer su arquitectura y usar funciones disponibles en su core de Arduino.

Una librería puede fallar por varios motivos. Algunas contienen código específico para AVR, el microcontrolador de placas como Arduino Uno o Nano clásico. Otras dependen de temporizadores, interrupciones o registros internos que cambian completamente en ESP32. También están las que asumen una tensión de 5 V, cuando los GPIO del ESP32 trabajan a 3,3 V y no son tolerantes a 5 V.

La compatibilidad real se valida en tres niveles: que compile, que el cableado sea eléctricamente correcto y que el módulo responda de forma estable. Si falta uno, el proyecto no está terminado.

Librerías compatibles con ESP32 y Arduino más habituales

Para proyectos básicos, el soporte suele ser muy bueno. El core de Arduino para ESP32 incluye funciones conocidas como `digitalWrite`, `analogRead`, `PWM`, `Serial`, `Wire` y `SPI`, aunque algunas se comportan de forma distinta a una placa Arduino AVR.

Sensores por I2C

Los sensores de temperatura, humedad, presión, movimiento, luz y distancia que usan I2C suelen ser los más sencillos de trasladar. Librerías para BME280, BMP280, MPU6050, AHT20, SHT31, BH1750 o ADS1115 cuentan normalmente con versiones compatibles con ESP32.

Antes de cargar el ejemplo, revisa dos cosas. La primera es la dirección I2C del módulo: no todos arrancan en la misma. La segunda es el pinout. En muchas placas ESP32 se usa GPIO 21 como SDA y GPIO 22 como SCL, pero no es una regla fija. Puedes inicializar el bus indicando otros pines con una instrucción como `Wire.begin(SDA, SCL)`.

No copies una conexión de Arduino Uno sin pensar. En el Uno, SDA y SCL están ligados a pines concretos; en ESP32 el bus puede asignarse a varios GPIO válidos. Eso da flexibilidad, pero obliga a documentar la conexión elegida.

Pantallas OLED y LCD

Las pantallas OLED SSD1306 y SH1106 por I2C son una opción habitual para mostrar lecturas, estados de red o menús. Las familias de librerías más usadas suelen funcionar con ESP32, pero hay diferencias importantes entre controladores y tamaños de pantalla.

Una OLED de 0,96 pulgadas con controlador SSD1306 no usa necesariamente la misma configuración que una OLED de 1,3 pulgadas con SH1106. Si se selecciona el controlador incorrecto, la pantalla puede quedar en negro, mostrar ruido o desplazar la imagen. El problema no es siempre el ESP32 ni el cableado.

Con pantallas LCD de caracteres mediante adaptador I2C ocurre algo parecido. Conviene ejecutar primero un escáner I2C para confirmar que el dispositivo responde y conocer su dirección. Si el escáner no detecta nada, no tiene sentido cambiar de librería todavía: hay que revisar alimentación, masa común, pines y nivel lógico.

Sensores DHT y dispositivos de un solo hilo

Los DHT11 y DHT22 son populares, económicos y también una fuente frecuente de lecturas erráticas. Sus librerías pueden ser compatibles con ESP32, pero el protocolo depende de tiempos precisos. Un cable demasiado largo, una alimentación ruidosa o una resistencia pull-up ausente pueden provocar valores `NaN` aunque el código sea correcto.

En sensores de un solo hilo, como DS18B20, la combinación de una librería para OneWire y otra para el sensor suele funcionar bien en ESP32. Aun así, hay que usar una resistencia pull-up, normalmente de 4,7 kΩ entre datos y 3,3 V, y elegir un GPIO adecuado. No todos los pines tienen las mismas capacidades.

Motores, relés y actuadores

Las librerías para servos, tiras LED direccionables, motores paso a paso y relés requieren más atención que un sensor I2C. El motivo es simple: dependen de PWM, temporización o señales rápidas.

Un ejemplo típico es el servo. La librería Servo clásica fue creada pensando en Arduino AVR y puede no funcionar en ESP32. Para esta placa hace falta una alternativa diseñada para su periférico PWM. Lo mismo ocurre con determinadas librerías para LEDs WS2812B: algunas funcionan, pero pueden competir por recursos internos con Wi-Fi, Bluetooth u otras tareas si se configuran mal.

En motores paso a paso, una librería de alto nivel puede compilar pero producir un movimiento irregular si el programa bloquea la ejecución con `delay()`. El ESP32 tiene potencia de sobra para muchos proyectos, pero eso no elimina una mala estructura de código ni una fuente de alimentación insuficiente.

Cómo comprobar una librería antes de montar el proyecto

La forma más rápida de evitar horas de prueba es no empezar por el proyecto completo. Instala la librería, selecciona la placa ESP32 concreta en el IDE y compila uno de sus ejemplos mínimos. Si el ejemplo falla antes de cargarlo, lee el primer error relevante, no la última línea roja de la consola.

Los mensajes que mencionan `avr`, registros de puertos o archivos que solo existen para Arduino Uno suelen indicar que la librería no soporta ESP32. Si el error aparece en una función de PWM, temporizadores o interrupciones, puede que necesites una variante específica para ESP32 o actualizar la librería y el core de la placa.

Después de compilar, carga un ejemplo de detección básico. Para I2C, empieza con un escáner. Para una pantalla, muestra un texto fijo. Para un sensor, imprime una sola lectura por el monitor serie. Para un motor, ejecuta un movimiento corto sin Wi-Fi, pantallas ni otros módulos conectados. Añade complejidad solo cuando la prueba anterior funciona.

Este método parece lento, pero es más rápido que depurar cinco variables a la vez. Código que compila no garantiza hardware funcionando, pero es el primer filtro necesario.

Errores frecuentes al reutilizar código de Arduino

El error más común es asumir que los números de pin son equivalentes. En un Arduino Uno, escribir `2` significa usar el pin digital 2. En ESP32, GPIO 2 puede estar conectado al LED integrado en algunas placas y afectar al arranque en otras. Además, ciertos GPIO son solo de entrada, otros participan en el proceso de boot y algunos no conviene usarlos con periféricos que cambian de estado al encender.

También conviene evitar alimentar módulos de 5 V directamente desde señales de 3,3 V sin comprobar su lógica. Algunos dispositivos funcionan sin problemas a 3,3 V. Otros necesitan alimentación a 5 V, pero aceptan I2C a 3,3 V. Y algunos incorporan conversores de nivel que alteran el comportamiento esperado. La serigrafía del módulo no siempre cuenta toda la historia.

Otro fallo habitual es instalar varias librerías para el mismo componente. El IDE puede elegir una versión distinta a la que esperabas, sobre todo si hay copias antiguas guardadas manualmente. Cuando un ejemplo da errores extraños, revisa qué biblioteca está usando realmente el compilador y elimina duplicados.

Wi-Fi, Bluetooth y librerías que bloquean

Una ventaja del ESP32 es integrar conectividad sin módulos externos. El coste es que Wi-Fi y Bluetooth consumen memoria, tiempo de CPU y, en determinados casos, recursos compartidos con otras funciones. Una librería que funciona en una lectura aislada puede volverse inestable al sumar una pantalla, un servidor web y una tira LED.

Evita los bucles largos con `delay()` cuando el proyecto tenga conectividad o varias tareas. Usa lecturas periódicas con `millis()`, separa las funciones por responsabilidad y reduce las actualizaciones innecesarias de pantalla. Si un sensor necesita una lectura cada dos segundos, no hace falta consultarlo cien veces por segundo.

También revisa la alimentación. Un ESP32 conectado por USB puede parecer estable hasta que activa Wi-Fi, mueve un servo o enciende LEDs. En ese momento aparecen reinicios, desconexiones o datos corruptos. La librería recibe la culpa, pero el origen puede ser una fuente que no entrega corriente suficiente o una masa mal distribuida.

Una selección práctica ahorra más que una instalación rápida

Al elegir módulos para ESP32, prioriza los que indiquen protocolo, voltaje de trabajo, dirección I2C si corresponde y una librería mantenida con ejemplos claros. Si necesitas reproducir el montaje en una clase, un taller o varias unidades, documenta la versión de la librería y del core ESP32 que has usado. Instalar “la última versión” meses después puede cambiar el resultado.

En Pinout, la referencia útil no es que un módulo tenga muchas especificaciones copiadas de fábrica. Es contar con pinout, tensión, conexión y un ejemplo probado para la combinación real de placa y periférico. Si una librería tiene límites, conviene decirlo antes de comprar y no después de que el montaje falle.

La regla final es sencilla: selecciona una librería pensada para ESP32, prueba el periférico de forma aislada y valida primero tensión y pines. Cuando ese mínimo funciona, el resto del proyecto deja de ser una apuesta y pasa a ser ingeniería reproducible.