ESP32 desde cero

Electricidad en 5 minutos

La electricidad es un flujo de cargas que necesita un empujón y un camino de ida y vuelta.

Pensalo como agua en una cañería. Hay tres palabras que vas a ver todo el tiempo:

• Voltaje (V, voltios): la presión, cuánto empuja la electricidad. La ESP32 trabaja con 3,3 V.
• Corriente (A, amperes; mA, miliamperes): el caudal, cuánta electricidad pasa por segundo.
• GND (tierra): el punto de referencia, que vale 0 V. Es el desagüe por donde vuelve la electricidad.

Por qué importa GND

Un voltaje siempre se mide entre dos puntos. Decir "este cable tiene 2 V" significa "2 V más que GND". Por eso la placa y el sensor tienen que compartir el mismo GND: si no, cada uno mide contra un cero distinto y los números no significan nada.

Dos reglas para no romper nada

• Nunca unas 3V3 (o 5V) directamente con GND. Eso es un cortocircuito: la corriente pasa sin freno, calienta y puede quemar la placa.
• Los pines de la ESP32 aguantan hasta 3,3 V. Si les llega 5 V se pueden dañar. Si un sensor funciona con 5 V, primero revisá cuánto voltaje entrega en su salida.

Digital y analógico

Algunas cosas son sí o no. Otras son "cuánto". La humedad es "cuánto".

Un botón está apretado o no lo está. Eso es digital: dos estados. Para la ESP32:

• HIGH (1) = cerca de 3,3 V
• LOW (0) = cerca de 0 V

La tierra no está "húmeda" o "seca" sin más. Está un poco húmeda, bastante, muy mojada. Eso es analógico: cualquier voltaje entre 0 y 3,3 V.

Para que tu código pueda usar un voltaje analógico, la placa tiene un ADC (conversor analógico-digital). Mide el voltaje y lo convierte en un número entero: con 12 bits, de 0 a 4095.

¿Qué es la ESP32?

La ESP32 es una computadora diminuta que hace una sola cosa: lo que vos le programes.

Tu Mac tiene sistema operativo, ventanas y mil programas abiertos. La ESP32 no tiene nada de eso. Es un microcontrolador: un procesador, un poco de memoria y Wi-Fi/Bluetooth en un solo chip. Corre un único programa: el tuyo.

¿Para qué sirve algo tan limitado? Justamente para eso. Es barata, consume poco y puede quedarse prendida meses haciendo una tarea simple, como mirar la tierra de una maceta.

"ESP32", "chip", "módulo", "placa": cuál es cuál

• El chip ESP32: el cerebro. El tuyo es un ESP32-D0WD-V3 con 2 núcleos a 240 MHz.
• El módulo: la cajita metálica plateada. Adentro tiene el chip, la memoria flash y el cristal que marca el ritmo. La parte con zigzag que asoma es la antena de Wi-Fi.
• La placa de desarrollo (NodeMCU): todo lo demás. Pone el módulo sobre una placa con USB, botones y pines para que lo puedas usar sin soldar.

Las partes de tu placa

Cómo arranca la placa

Al prenderse, el chip lee tu programa desde la flash. Si no puede leerla, no arranca nada.

Dentro del chip hay un programa minúsculo grabado de fábrica que nunca se borra: la ROM. Es lo primero que corre cada vez que la placa recibe energía o se reinicia.

La flash está conectada al chip por seis pines: GPIO 6 a 11 (en tu placa dicen CLK, SD0, SD1, SD2, SD3, CMD). Si algo externo toca esos pines, la ROM no puede leer la flash y la placa no arranca.

Del código a la placa

Escribís en tu Mac, lo traducís y lo mandás por el cable. Ese es el ciclo.

El chip no entiende el código que escribís, solo instrucciones de máquina. Hay que traducirlo.

1. Escribir: un archivo .ino. Es C++, simplificado.
2. Compilar: se traduce a un archivo binario que el chip entiende.
3. Cargar (o "flashear"): el binario viaja por el USB y se guarda en la flash.
4. Mirar logs: la placa te escribe mensajes por el mismo cable. Eso es el monitor serie.

Una vez cargado, el programa queda guardado. Podés desenchufar la placa de la Mac, conectarla a un cargador de celular y arranca sola.

El puerto serie y los baudios

El puerto serie es un canal de texto que manda un bit atrás de otro. Los dos lados tienen que acordar la velocidad: los baudios. Si tu programa dice Serial.begin(115200), el monitor también tiene que estar en 115200. Si no coinciden, vas a ver caracteres basura.

# compilar
arduino-cli compile --fqbn esp32:esp32:esp32 ~/Documents/Arduino/humedad_suelo_prueba
# cargar
arduino-cli upload -p /dev/cu.usbserial-0001 --fqbn esp32:esp32:esp32 ~/Documents/Arduino/humedad_suelo_prueba
# mirar logs (salís con Ctrl+C)
arduino-cli monitor -p /dev/cu.usbserial-0001 -c baudrate=115200

Un programa que nunca termina

Todo programa de ESP32 tiene dos partes: lo que pasa una vez, y lo que se repite para siempre.

Un script común arranca, hace su trabajo y termina. Algo que vigila una planta día y noche no puede terminar nunca. Por eso los programas se dividen así:

• setup(): se ejecuta una sola vez, al prender la placa. Ahí preparás todo.
• loop(): se ejecuta una y otra vez, hasta que le cortes la energía.

void setup() {
  pinMode(2, OUTPUT);        // el pin 2 (el LED) va a ser una salida
}

void loop() {
  digitalWrite(2, HIGH);     // prender: 3,3 V en el pin
  delay(500);                // esperar medio segundo
  digitalWrite(2, LOW);      // apagar: 0 V
  delay(500);
}                            // ...y vuelve a empezar

Qué puede hacer un pin

Tu código no ve la tierra ni toca un LED. Lo que hace es poner o medir voltaje en una patita.

A los pines que tu código controla se los llama GPIO ("entrada/salida de uso general"). Cada uno tiene un número: GPIO 2, GPIO 34, etc. En la placa a veces figura solo el número.

1. Salida digital: la placa actúa

El pin pone 3,3 V (HIGH) o 0 V (LOW). Así se prende un LED o se activa un relé.

• Cada pin entrega poca corriente: lo seguro es hasta ~12 mA. Alcanza para un LED con su resistencia, no para un motor.

2. Entrada digital: la placa mira

El pin dice si recibe algo cercano a 3,3 V o a 0 V. Así se lee un botón.

• Pin flotante: si no hay nada conectado, el pin capta ruido y da valores al azar. Por eso existen las resistencias pull-up / pull-down, que lo "tironean" a un valor fijo cuando nadie le habla. La ESP32 las tiene adentro: pinMode(4, INPUT_PULLUP).

3. Entrada analógica (ADC): la placa mide cuánto

El pin convierte un voltaje en un número de 0 a 4095 (lección 2). La ESP32 tiene dos ADC:

• ADC1 (GPIO 32–39): funciona siempre. Es el que usás para sensores.
• ADC2 (GPIO 0, 2, 4, 12–15, 25–27): deja de funcionar cuando el Wi-Fi está prendido, porque el Wi-Fi lo usa.

4. Otras habilidades que vas a cruzarte

5. Pines con condiciones

• Solo entrada (GPIO 34, 35, 36, 39): no pueden sacar voltaje ni tienen pull-ups internos. Son ideales para sensores analógicos.
• Strapping (GPIO 0, 2, 5, 12, 15): la ROM los mira en el instante del arranque para decidir cómo arrancar. Si algo externo los fuerza a un valor raro, la placa puede no arrancar.
• Flash (GPIO 6–11): ocupados por la memoria. No se usan nunca.
• Serie USB (GPIO 1 TX, 3 RX): los usa el CP2102 para hablar con la Mac. Si conectás algo ahí, cargar o leer logs puede fallar.

Mapa de los 38 pines

Un semáforo: verde se usa tranquilo, amarillo con cuidado y rojo nunca.

Así se ve tu NodeMCU desde arriba, con la antena arriba y el USB abajo. Tocá cualquier pin para ver qué hace, o filtrá por color.

Cómo mide la humedad

El sensor no toca el agua: siente cuánta agua tiene cerca.

Desde cero: el capacitor

Un capacitor son dos superficies de metal que no se tocan. Si le aplicás voltaje, guarda un poquito de carga, como un tanque chico que se llena y se vacía.

Cuánta carga guarda depende de qué hay alrededor de esas superficies. El agua hace que guarde muchísimo más que el aire:

Tu sensor V1.2 tiene dos pistas de cobre adentro de la varilla negra, cubiertas por barniz. Esas pistas son el capacitor. Al clavarlo, la tierra y el agua que contiene quedan alrededor.

De capacitor a voltaje

Es un sensor "capacitivo" porque mide cambios de capacitancia. Como el cobre no queda expuesto, no se oxida: por eso es mejor que el sensor de dos patitas de metal con forma de horquilla.

Conectarlo y leerlo

Tres cables: energía, retorno y señal. Y un programa de diez líneas.

Por qué estos pines

• 3V3 y no 5V: así la señal del sensor nunca supera lo que aguanta el pin.
• GPIO 34: es de ADC1 (sigue funcionando con Wi-Fi) y es solo entrada, justo lo que hace falta para leer.

El programa

Está en ~/Documents/Arduino/humedad_suelo_prueba/.

const int PIN_SENSOR = 34;

void setup() {
  Serial.begin(115200);                          // abrir los logs a 115200 baudios
  analogReadResolution(12);                      // valores de 0 a 4095
  analogSetPinAttenuation(PIN_SENSOR, ADC_11db); // rango de entrada ~0 a 3,1 V
}

void loop() {
  int crudo = analogRead(PIN_SENSOR);            // medir el voltaje
  Serial.println(crudo);                         // mandarlo a la Mac
  delay(1000);                                   // una vez por segundo
}

¿Qué es la atenuación?

El ADC, por sí solo, solo mide hasta ~1 V. La atenuación achica la señal antes de medirla, para que entren voltajes más altos. Con ADC_11db el rango llega a ~3,1 V, suficiente para los ~1–2,5 V del sensor.

Tu primera prueba

Que llegue un número estable no prueba nada. Hay que ver que cambie cuando cambia la humedad.

Lo que pasó, paso a paso

1. Herramientas: Arduino CLI 1.5.1 y el soporte para ESP32 3.3.12 ya estaban instalados. Placa: esp32:esp32:esp32, puerto /dev/cu.usbserial-0001.
2. La flash no respondía (ff ffff, flash read err). Se descartaron la velocidad del puerto y el modo de carga. No se reinstaló nada.
3. Se arregló en lo físico. La flash respondió bien: 4 MB.
4. Copia de seguridad del firmware de fábrica en ~/Documents/Arduino/backups/firmware_original_04b24753e728.bin.
5. Programa cargado y verificado: llega una lectura por segundo.
6. Prueba de la mano: el valor bajó casi 1000 unidades. El sensor responde.
7. En la tierra no cambió: probablemente estaba muy seca. Falta la prueba con agua.

Las lecturas

Calibrar

"2142" no dice nada solo. Necesita dos puntos de referencia: seco y mojado.

Con dos extremos, cualquier lectura se convierte en un porcentaje con una regla de tres. La pregunta es qué extremos usar.

Por qué no alcanza con "aire" y "vaso de agua"

Una tierra para macetas recién regada tiene entre 60 y 80 % de agua en volumen: nunca llega a lo que mide el sensor en un vaso. Calibrando con el vaso, tu planta recién regada marcaría algo como 70 %, nunca 100 %.

Mejor: calibrar en la maceta real

1. "Regada": regá la difenbaquia, esperá unos 30 minutos a que escurra y mirá el valor en el gráfico.
2. "Hay que regar": cuando al meter el dedo los primeros 2–3 cm estén secos, mirá el valor. Ese es el umbral para el aviso.

No hace falta anotar nada a mano: el historial ya guarda todo. Mientras tanto, el panel usa una calibración provisoria (2557 al aire, 1500 con la mano) en lib/humedad.ts.

const int SECO   = 2557;   // "hay que regar" (provisorio: al aire)
const int MOJADO = 1500;   // "regada" (provisorio: con la mano)

int humedad() {
  int valor = analogRead(34);
  int pct = map(valor, SECO, MOJADO, 0, 100);  // regla de tres
  return constrain(pct, 0, 100);               // que no se pase de 0–100
}

De la placa a internet

La placa hace lo mismo que un fetch: un POST con JSON a una URL.

Hasta acá la placa le hablaba solo a tu Mac, por el cable. Para mandar datos a internet necesita dos cosas:

1. Wi-Fi: se conecta a tu router como un celular y recibe una dirección en tu red (algo como 192.168.1.74).
2. HTTP: el mismo idioma que usa el navegador. La placa arma un pedido y el servidor contesta.

Cómo es el pedido

POST /api/lecturas                         ← método y ruta
Content-Type: application/json             ← "te mando JSON"
Authorization: Bearer <token>              ← el token: "soy la placa"

{"dispositivo":"planta-1","lecturas":[{"crudo":2142,"medido_en":1792881667}]}

El token es una contraseña compartida entre la placa y el servidor. Sin él, cualquiera que conozca la URL podría mandar lecturas falsas. Vive en dos lugares: secrets.h en la placa y una variable secreta en Vercel. Nunca en git.

Cómo es la respuesta

Todo pedido vuelve con un código de estado. La placa decide qué hacer según ese número:

El backend: recibir, validar, guardar

El backend es el programa que atiende a la placa: revisa lo que llega y lo guarda en una base de datos.

Está hecho con Next.js, en app/api/lecturas/route.ts. Ese archivo tiene dos funciones: POST (la placa manda lecturas) y GET (la página pide el historial).

1. Validar: nunca confiar en lo que llega

Antes de guardar, el backend comprueba que el token coincida, que crudo sea un entero entre 0 y 4095, y que la hora no esté en el futuro ni tenga más de 7 días. Si algo no cierra, contesta 400 y no guarda nada.

2. Guardar: una base de datos es una planilla con reglas

La base es Postgres. Una tabla es como una planilla donde cada columna tiene un tipo fijo:

create table lecturas (
  id          bigint generated always as identity primary key,  -- número automático
  dispositivo text        not null,                              -- "planta-1"
  crudo       integer     not null check (crudo between 0 and 4095),
  creado_en   timestamptz not null default now()                 -- fecha y hora
);

Se le habla en SQL: insert agrega filas y select las lee.

insert into lecturas (dispositivo, crudo) values ('planta-1', 2142);
select crudo, creado_en from lecturas where dispositivo = 'planta-1' order by creado_en;

3. Guardar el número crudo, no el porcentaje

La base guarda 2142, no "39 %". El porcentaje se calcula al mostrar. Así, cuando calibres de nuevo, todo el historial se recalcula solo y no se pierde nada.

Local y nube, mismo código

En tu Mac la base es PGlite, un Postgres que corre dentro de Node y guarda los datos en una carpeta. En la nube es Supabase. El SQL es el mismo. Lo que decide cuál se usa es una sola variable: si existe DATABASE_URL, va a Supabase.

La nube: Supabase y Vercel

Vercel corre tu código; Supabase guarda tus datos. Los dos están en São Paulo, cerca entre sí.

Supabase: Postgres administrado

• Es un Postgres que corre en un servidor que no tenés que mantener.
• Pooler: en Vercel cada pedido abre una conexión corta. Postgres no aguanta miles de conexiones; el pooler las agrupa en unas pocas. Por eso la dirección usa el puerto 6543.

Seguridad en capas

1. RLS (seguridad por fila): Supabase expone las tablas por una API pública. Con RLS activado y sin permisos para esa API, nadie puede leer ni escribir por ahí.
2. Usuario con permisos mínimos: el backend no usa el administrador postgres sino un usuario propio que solo puede insertar y leer en lecturas. Se probó: no puede borrar ni crear tablas. Si algún día roban esa contraseña, el daño es mínimo.
3. La contraseña no salió de tu Mac: a Supabase se le mandó solo su hash (SCRAM-SHA-256). Sirve para verificar la contraseña, no para recuperarla.

Vercel: el código en la nube

• Funciones: tu backend no está prendido todo el tiempo; se ejecuta cuando llega un pedido.
• Región gru1: si las funciones corrieran en Estados Unidos, cada lectura viajaría a Estados Unidos y volvería a São Paulo para guardarse. Ahora tarda unos 0,3 s.
• Variables de entorno: DATABASE_URL y DEVICE_TOKEN están guardadas como secretas en Vercel. El código las lee con process.env.
• Deploy automático: cada git push al repo despliega una versión nueva en unos 20 segundos.

HTTPS desde cero

HTTPS hace dos cosas: cifra lo que viaja y prueba que del otro lado está quien dice ser.

Sin HTTPS, cualquiera en el camino (el Wi-Fi de un vecino, un router intermedio) podría leer el token y usarlo para mandar datos falsos. Con HTTPS ve solo bytes sin sentido.

¿Cómo sabe la placa que habla con Vercel?

Con un certificado: el DNI del sitio, firmado por una autoridad. Esa autoridad a su vez está firmada por otra, y así hasta llegar a un certificado raíz, en el que se confía de antemano.

Tu navegador trae cientos de certificados raíz. La placa solo los que le cargamos en certificados.h: GTS Root R1 (de Google, el que usa Vercel hoy) e ISRG Root X1 (Let's Encrypt, de respaldo). Vencen en 2036 y 2035.

¿Por qué la placa necesita saber la hora?

Los certificados tienen fecha de vencimiento. La placa arranca creyendo que es 1970, así que todos le parecerían inválidos. Por eso, antes del primer envío, le pregunta la hora a un servidor de tiempo (NTP).

echo | openssl s_client -connect planta-monitor-pearl.vercel.app:443 2>/dev/null | grep -E "s:|i:"

Que no se pierda nada: robustez

Un dispositivo que funciona solo tiene que suponer que todo va a fallar alguna vez: el Wi-Fi, el servidor y él mismo.

Tres memorias, tres duraciones

1. Buffer circular: guardar lo que no se pudo mandar

Cada lectura entra primero a un buffer. Solo sale cuando el servidor confirma con 201. Es circular: tiene 480 lugares (8 horas) y, si se llena, la lectura nueva pisa a la más vieja. Vive en la memoria RTC (RTC_NOINIT_ATTR), así que sobrevive a cuelgues y reinicios.

2. Lotes con la hora real de medición

Si el Wi-Fi vuelve después de una hora, la placa manda las 60 lecturas juntas y cada una con medido_en, la hora en que se midió. En el gráfico aparecen en su lugar, no amontonadas en el momento de reconexión.

3. Reenviar sin duplicar (idempotencia)

¿Qué pasa si el servidor guardó, pero la respuesta se perdió? La placa no sabe y reenvía. Para que eso no duplique datos, la base tiene una regla: no puede haber dos lecturas del mismo dispositivo con la misma hora (índice único). El insert usa on conflict do nothing: lo repetido se ignora en silencio.

4. Watchdog: el perro guardián

Es un temporizador de hardware. El programa le dice "sigo vivo" (esp_task_wdt_reset()) en cada vuelta del loop(). Si pasan 2 minutos sin noticias, porque algo se trabó, el watchdog reinicia la placa. Gracias al buffer en RTC, lo pendiente no se pierde.

5. Último recurso y filtro de ruido

• Si pasa 1 hora sin poder enviar nada, la placa se reinicia completa: a veces el Wi-Fi o la red quedan trabados de formas que solo un reinicio arregla.
• Cada lectura es la mediana de 9 mediciones: se ordenan y se toma la del medio. Un pico de ruido aislado queda en un extremo y no afecta.

El panel y la planta 3D

La página pide el historial cada 10 segundos y lo dibuja de dos formas: un gráfico y una planta que reacciona.

Del número crudo al porcentaje

La página usa lib/humedad.ts, que hace la regla de tres de la lección 12: 0 % es el momento de regar y 100 %, recién regada. Con el porcentaje elige el estado: hasta 10 % "Le toca agua", hasta 35 % "Se está secando", hasta 85 % "Bien de agua" y, arriba de eso, "Húmeda" (o "Recién regada" si el riego fue en las últimas 24 h).

three.js desde cero

Una escena 3D tiene siempre las mismas piezas:

• Escena: el mundo donde se ponen las cosas.
• Cámara: desde dónde se mira. Acá gira sola despacio y la podés arrastrar.
• Luces: sin luz, todo se ve negro. Hay una luz general, una principal desde arriba y un relleno desde la cámara.
• Mallas (meshes): cada objeto es una geometría (la forma) más un material (color, textura, brillo). La maceta es una silueta que gira 360° con 9 caras. Cada hoja es un contorno dibujado con curvas, con las manchas crema generadas por código.
• Bucle de animación: unas 60 veces por segundo (useFrame), el código acerca de a poco la planta a la humedad actual. Si falta agua, las hojas se inclinan y amarillean, y la tierra se aclara.

Cuándo avisar (sin volverte loco)

"Avisame si baja de 30 %" suena perfecto. Hasta que te llegan 40 notificaciones.

Las lecturas tiemblan un poco (ya lo viste: 2555, 2557, 2559). La humedad puede quedar oscilando entre 29 % y 31 % durante una hora. Cada vez que baja de 30, te avisaría.

La solución es usar dos límites en vez de uno (se llama histéresis):

• Avisás cuando baja de 30 %.
• No volvés a avisar hasta que suba de 45 %, o sea, hasta que la riegues.

bool yaAvise = false;

void revisar(int pct) {
  if (!yaAvise && pct < 30) {
    avisar("🌱 Tengo sed");
    yaAvise = true;
  }
  if (yaAvise && pct > 45) {
    yaAvise = false;     // me regaron: listo para el próximo aviso
  }
}

El aviso al celular

La placa se conecta al Wi-Fi y hace un POST. Igual que un fetch.

Acá vuelve terreno conocido. El servicio más simple para notificaciones es ntfy:

1. Instalás la app ntfy en el celular.
2. Te suscribís a un "tema" con un nombre difícil de adivinar, por ejemplo planta-santi-x7k2.
3. Cada vez que la placa hace un POST a ntfy.sh/planta-santi-x7k2, te llega una notificación.

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <HTTPClient.h>

void setup() {
  WiFi.begin("TU_RED", "TU_CLAVE");
  while (WiFi.status() != WL_CONNECTED) delay(300);   // esperar conexión
}

void avisar(String mensaje) {
  WiFiClientSecure cliente;
  cliente.setInsecure();          // simplifica HTTPS, está bien para aprender
  HTTPClient http;
  http.begin(cliente, "https://ntfy.sh/planta-santi-x7k2");
  http.POST(mensaje);
  http.end();
}

Si algo falla

Regla general: primero entendé el error, después cambiá cosas. Reinstalar herramientas casi nunca es la respuesta.

Comandos y archivos

# ver qué está conectado
arduino-cli board list

# compilar y cargar el programa del sensor
arduino-cli compile --fqbn esp32:esp32:esp32 ~/Documents/Arduino/humedad_suelo_prueba
arduino-cli upload  -p /dev/cu.usbserial-0001 --fqbn esp32:esp32:esp32 ~/Documents/Arduino/humedad_suelo_prueba

# mirar las lecturas (Ctrl+C para salir)
arduino-cli monitor -p /dev/cu.usbserial-0001 -c baudrate=115200

# ¿quién está usando el puerto?
lsof /dev/cu.usbserial-0001

# cargar el firmware con Wi-Fi (el que va en la planta)
cd ~/projects/planta-monitor
arduino-cli upload -p /dev/cu.usbserial-0001 --fqbn esp32:esp32:esp32 firmware/humedad_wifi

# backend: desplegar = commitear y pushear
git add -A && git commit -m "mensaje" && git push

# ver errores del backend en producción
npx vercel logs --since 30m

# correr la app en tu Mac con la base local (no la de Supabase)
DATABASE_URL= npm run dev:lan

Archivos

• Programa del sensor: ~/Documents/Arduino/humedad_suelo_prueba/
• Copia del firmware original: ~/Documents/Arduino/backups/firmware_original_04b24753e728.bin
• Proyecto completo (backend, panel, firmware): ~/projects/planta-monitor/, en un repo privado de GitHub
• Firmware con Wi-Fi: ~/projects/planta-monitor/firmware/humedad_wifi/ (secrets.h no se sube a git)
• Panel público: planta-monitor-pearl.vercel.app
• Esta guía: ~/study-notes/esp32-desde-cero/index.html

Palabras que vas a cruzarte