Objetivo y caso de uso

Qué construirás: Un nodo sensor de bajo consumo para monitoreo ambiental utilizando TTGO LoRa32, BME280 y ADS1115.

Para qué sirve

• Monitoreo de temperatura y humedad en invernaderos usando BME280.
• Medición de niveles de agua en cultivos mediante ADS1115.
• Transmisión de datos de sensores a través de LoRa para largas distancias.
• Integración con sistemas de alerta temprana para condiciones ambientales adversas.

Resultado esperado

• Datos de temperatura y humedad reportados cada 10 minutos.
• Latencia de transmisión de datos inferior a 5 segundos.
• Consumo de energía del nodo menor a 50 mA en modo activo.
• Rango de transmisión efectivo de al menos 5 km en campo abierto.

Público objetivo: Ingenieros y desarrolladores en IoT; Nivel: Avanzado

Arquitectura/flujo: Nodo sensor LoRa -> Gateway LoRa -> Plataforma de monitoreo en la nube.

Nivel: Avanzado

Prerrequisitos

• Sistemas operativos verificados
• Windows 11 Pro 23H2 (con privilegios de administrador para instalar drivers)
• Ubuntu 22.04.4 LTS (usuario en grupo dialout)

• macOS 14 Sonoma

• Toolchain exacta (probada)

• PlatformIO Core 6.1.14 (CLI)
• Python 3.11.6
• Git 2.44.0
• PlatformIO platform espressif32@6.5.0
• Framework Arduino-ESP32 2.0.14 (resuelto por espressif32@6.5.0)
• toolchain-xtensa-esp32 gcc 8.4.0 (instalado por la plataforma anterior)
• esptool.py 4.6 (tool-esptoolpy suministrado por PlatformIO)

• Librerías Arduino (versiones fijas en este proyecto)

  • sandeepmistry/LoRa@0.8.0
  • adafruit/Adafruit BME280 Library@2.2.4
  • adafruit/Adafruit Unified Sensor@1.1.14
  • adafruit/Adafruit ADS1X15@2.4.0

• Drivers de USB–Serie

• La TTGO LoRa32 emplea normalmente CP2102/CP2104 (Silicon Labs). Instalar el driver:
  • Windows/macOS: descargar de Silicon Labs “CP210x Universal Windows/Mac Driver”.
  • Linux: el kernel ya incluye cp210x. Añade tu usuario a dialout: sudo usermod -aG dialout $USER y reinicia sesión.

• Si tu variante usase CH340/CH34x, instala el driver de WCH.

• Notas de conformidad LoRa

• Selecciona banda según tu región y normativa:
  • EU868: 868.1/868.3/868.5 MHz (duty-cycle 1% típico).
  • US915: 903.9–927.5 MHz (canales espaciados 0.2 MHz).
• En este caso práctico se configura por defecto EU868 (868.1 MHz); puedes cambiarlo en build_flags.

Materiales

• 1× TTGO LoRa32 (ESP32 + SX1276) con interfaz USB (modelo de LILYGO, también llamado “TTGO LoRa32 v1/v2”).
• 1× BME280 (módulo I2C, dirección por defecto 0x76/0x77).
• 1× ADS1115 (módulo I2C, dirección por defecto 0x48).
• 1× Sensor capacitivo de humedad de suelo 3.3 V (salida analógica, no el resistivo).
• 1× Batería LiPo 3.7 V (con conector JST-PH compatible con la TTGO LoRa32).
• Resistencias para divisor de tensión de batería hacia ADS1115 (ejemplo: 100 kΩ + 100 kΩ).
• Cables Dupont Macho–Hembra/Macho–Macho.
• Cable USB-C o Micro-USB según tu TTGO LoRa32.
• Opcional, para validación por radio:
• 1× segunda TTGO LoRa32 (ESP32 + SX1276) para actuar como receptor simple.

Notas:
– El objetivo “lora-agro-telemetry-lowpower” exige minimizar consumo: usaremos deep sleep del ESP32, el SX1276 en sleep entre tramas, BME280 en modo forced y lecturas single-shot del ADS1115.

Preparación y conexión

La TTGO LoRa32 integra el SX1276 y el bus SPI ya cableado en la propia placa. Los sensores BME280 y ADS1115 se conectan por I2C. Para sensar humedad de suelo usando un sensor capacitivo, su salida analógica se conectará a la entrada A0 del ADS1115. Si se desea telemetría de batería, llevaremos la tensión VBAT a A1 del ADS1115 a través de un divisor 1:2 (por ejemplo, 100 kΩ/100 kΩ), de modo que un máximo de 4.2 V quede por debajo del rango seguro del ADC externo.

Tabla de pines, buses y direcciones

Conexiones paso a paso:
1. Alimentación y bus I2C:
– TTGO 3V3 → 3V3 de BME280, 3V3 de ADS1115 y VCC del sensor de suelo.
– TTGO GND → GND de BME280, GND de ADS1115 y GND del sensor de suelo.
– TTGO GPIO21 (SDA) → SDA de BME280 y SDA de ADS1115.
– TTGO GPIO22 (SCL) → SCL de BME280 y SCL de ADS1115.
2. Entradas analógicas en ADS1115:
– Sensor suelo OUT → ADS1115 A0.
– Punto medio del divisor de VBAT (entre 100 kΩ y 100 kΩ) → ADS1115 A1.
– Extremos del divisor: superior a VBAT (línea de batería de la TTGO, no al 5 V), inferior a GND.
3. Batería:
– Conecta la LiPo al conector JST de la TTGO LoRa32. La placa integra carga/gestión básica.
4. Antena:
– Conecta una antena adecuada a la TTGO (imprescindible para no dañar el SX1276).

Verificación inicial (opcional pero recomendable):
– Con un escáner I2C se deben ver 0x48 (ADS1115) y 0x76/0x77 (BME280).

Código completo

A continuación se muestra un proyecto completo para PlatformIO (framework Arduino). Implementa:
– Lectura de BME280 en modo forced (reduce consumo).
– Lectura single-shot de ADS1115 en A0 (humedad de suelo) y A1 (VBAT/2).
– Trama binaria compacta con CRC16-IBM.
– SX1276 dormido entre tramas; ESP32 en deep sleep con temporizador.
– Frecuencia, SF y TX power configurables por build_flags.
– Desactivación de WiFi/BT.

platformio.ini

Crea el proyecto y pega este contenido en platformio.ini:

; Proyecto: lora-agro-telemetry-lowpower
; Dispositivo: TTGO LoRa32 (ESP32 + SX1276) + BME280 + ADS1115
; Toolchain exacta fijada vía platform y libs

[env:ttgo-lora32-v1]
platform = espressif32@6.5.0
board = ttgo-lora32-v1
framework = arduino

; Paquetes de plataforma (se instalan automáticamente con espressif32@6.5.0)
; - toolchain-xtensa-esp32 (gcc 8.4.0)
; - tool-esptoolpy (esptool.py 4.6)
; - framework-arduinoespressif32 (Arduino-ESP32 2.0.14)

monitor_speed = 115200
monitor_filters = time, esp32_exception_decoder

lib_deps =
  sandeepmistry/LoRa@0.8.0
  adafruit/Adafruit BME280 Library@2.2.4
  adafruit/Adafruit Unified Sensor@1.1.14
  adafruit/Adafruit ADS1X15@2.4.0

; Parámetros de radio y hardware (modificables)
build_flags =
  -D LORA_FREQ_MHZ=868.1
  -D LORA_SF=7
  -D LORA_TX_PWR_DBM=14
  -D I2C_SDA=21
  -D I2C_SCL=22
  -D SOIL_CH=0
  -D VBAT_CH=1
  -D WAKE_INTERVAL_S=900
  -D REGION_EU868

Notas:
– Para US915, cambia LORA_FREQ_MHZ=915.0 y retira REGION_EU868 o define REGION_US915.
– Puedes afinar la SF (7–12) y potencia (2–20 dBm) según normativa y enlace.

src/main.cpp

Crea src/main.cpp con el siguiente código. Está documentado por bloques clave.

#include <Arduino.h>
#include <Wire.h>
#include <SPI.h>
#include <LoRa.h>
#include <WiFi.h>
#include "esp_bt.h"
#include <Adafruit_BME280.h>
#include <Adafruit_ADS1X15.h>

#ifndef LORA_FREQ_MHZ
#define LORA_FREQ_MHZ 868.1
#endif
#ifndef LORA_SF
#define LORA_SF 7
#endif
#ifndef LORA_TX_PWR_DBM
#define LORA_TX_PWR_DBM 14
#endif
#ifndef I2C_SDA
#define I2C_SDA 21
#endif
#ifndef I2C_SCL
#define I2C_SCL 22
#endif
#ifndef WAKE_INTERVAL_S
#define WAKE_INTERVAL_S 900
#endif
#ifndef SOIL_CH
#define SOIL_CH 0
#endif
#ifndef VBAT_CH
#define VBAT_CH 1
#endif

// Mapeo SX1276 en TTGO LoRa32
static constexpr int LORA_SS = 18;
static constexpr int LORA_RST = 14;
static constexpr int LORA_DIO0 = 26;

// SPI (VSPI) ya mapeado a SCK=5, MISO=19, MOSI=27 por defecto en ESP32-ARDUINO

// Sensores I2C
Adafruit_BME280 bme;
Adafruit_ADS1115 ads;

// Contador persistente en deep sleep
RTC_DATA_ATTR uint32_t rtc_seq = 0;

// CRC16-IBM (polinomio 0xA001)
uint16_t crc16_ibm(const uint8_t* data, size_t len) {
  uint16_t crc = 0xFFFF;
  for (size_t i = 0; i < len; ++i) {
    crc ^= data[i];
    for (uint8_t b = 0; b < 8; ++b) {
      if (crc & 1) crc = (crc >> 1) ^ 0xA001;
      else crc >>= 1;
    }
  }
  return crc;
}

// Estructura de trama compacta
#pragma pack(push, 1)
struct FrameV1 {
  uint8_t  pre[2];           // 'A','G'
  uint8_t  ver;              // 0x01
  uint32_t dev;              // 32 bits del MAC (ID)
  uint32_t seq;              // contador
  int16_t  t_c_x100;         // temperatura *100 (°C)
  uint16_t rh_x100;          // humedad *100 (%)
  uint16_t press_hPa_x10;    // presión *10 (hPa)
  uint16_t soil_permille;    // humedad suelo en ‰ (0-1000)
  uint16_t vbat_mV;          // batería en mV
  uint16_t crc;              // CRC16-IBM sobre cabecera+datos
};
#pragma pack(pop)

// Lectura BME280 en modo de baja energía (forced)
bool read_bme280(float &tC, float &rh, float &p_hPa) {
  // Configurar I2C si no está iniciado
  static bool wireBegun = false;
  if (!wireBegun) {
    Wire.begin(I2C_SDA, I2C_SCL);
    wireBegun = true;
  }
  static bool bmeInit = false;
  if (!bmeInit) {
    // Probar 0x76 y 0x77
    if (!bme.begin(0x76) && !bme.begin(0x77)) {
      return false;
    }
    // Configuración mínima: oversampling x1, filtro off, modo FORCED
    bme.setSampling(
      Adafruit_BME280::MODE_FORCED,
      Adafruit_BME280::SAMPLE_X1,   // temp
      Adafruit_BME280::SAMPLE_X1,   // hum
      Adafruit_BME280::SAMPLE_X1,   // pres
      Adafruit_BME280::FILTER_OFF
    );
    bmeInit = true;
  }
  // Disparo de conversión en modo FORCED
  bme.takeForcedMeasurement();
  tC    = bme.readTemperature();          // °C
  rh    = bme.readHumidity();             // %
  p_hPa = bme.readPressure() / 100.0F;    // hPa
  return !(isnan(tC) || isnan(rh) || isnan(p_hPa));
}

// Inicialización ADS1115 en modo lectura single-shot
bool init_ads1115() {
  static bool init = false;
  if (!init) {
    if (!ads.begin(0x48)) return false;
    ads.setGain(GAIN_ONE); // ±4.096 V -> 0.125 mV/LSB
    init = true;
  }
  return true;
}

float read_ads_voltage(uint8_t ch) {
  int16_t counts = ads.readADC_SingleEnded(ch);
  return ads.computeVolts(counts); // Volts referidos a Vdd ADC
}

// Calibración simple para humedad de suelo (ajusta a tu sensor)
uint16_t soil_percent_permille_from_voltage(float v) {
  // Ajusta límites según calibración empírica de tu sonda
  // Ejemplo típico de sensor capacitivo: ~0.5 V seco, ~2.5 V muy húmedo
  const float v_dry = 0.5f;
  const float v_wet = 2.5f;
  float f = (v - v_dry) / (v_wet - v_dry);
  if (f < 0.0f) f = 0.0f;
  if (f > 1.0f) f = 1.0f;
  return (uint16_t)lroundf(f * 1000.0f); // ‰ (0–1000)
}

// ID de dispositivo a partir del MAC
uint32_t device_id32() {
  uint64_t mac = ESP.getEfuseMac();
  return (uint32_t)((mac >> 16) & 0xFFFFFFFF);
}

// Inicialización de la radio LoRa con parámetros de bajo consumo
bool lora_radio_begin(double freqMHz, int sf, int txPower) {
  // Apaga radios del SoC para ahorrar
  WiFi.mode(WIFI_OFF);
  btStop();

  SPI.begin(); // VSPI por defecto
  LoRa.setPins(LORA_SS, LORA_RST, LORA_DIO0);
  if (!LoRa.begin(freqMHz * 1e6)) {
    return false;
  }
  LoRa.setSPIFrequency(8E6);
  LoRa.setTxPower(txPower);          // dBm (máx. 20 con PA_BOOST, cumple normativa local)
  LoRa.setSpreadingFactor(sf);       // 7..12
  LoRa.setSignalBandwidth(125E3);    // 125 kHz (estándar)
  LoRa.setCodingRate4(5);            // 4/5
  LoRa.setPreambleLength(8);         // preámbulo estándar
  LoRa.enableCrc();                  // CRC de payload de la librería (además del nuestro)
  return true;
}

void lora_radio_sleep() {
  LoRa.idle();
  LoRa.sleep(); // SX1276 en sleep (consumo mínimo)
}

// Empaquetado y envío de trama binaria
bool send_frame_once(FrameV1 &frm) {
  // Calcula CRC sobre todo excepto el campo CRC
  frm.crc = 0;
  uint16_t crc = crc16_ibm(reinterpret_cast<const uint8_t*>(&frm), sizeof(frm) - sizeof(frm.crc));
  frm.crc = crc;

  // Emisión
  LoRa.beginPacket();
  LoRa.write(reinterpret_cast<const uint8_t*>(&frm), sizeof(frm));
  int err = LoRa.endPacket(true); // true = TX async (mejor para no bloquear)
  // Espera a que termine
  LoRa.idle();
  return (err == 1);
}

void setup() {
  Serial.begin(115200);
  delay(50);
  Serial.println();
  Serial.println(F("[lora-agro-telemetry-lowpower] Boot"));

  // Lógica de secuencia
  rtc_seq++;

  // I2C
  Wire.begin(I2C_SDA, I2C_SCL);
  if (!init_ads1115()) {
    Serial.println(F("ERR: ADS1115 no detectado en 0x48"));
  }

  // Sensores
  float tC=0, rh=0, p_hPa=0;
  bool bme_ok = read_bme280(tC, rh, p_hPa);
  if (!bme_ok) {
    Serial.println(F("ERR: BME280 no detectado (0x76/0x77)"));
  }

  // Lecturas ADS1115
  float v_soil = read_ads_voltage(SOIL_CH);
  float v_bat_div = read_ads_voltage(VBAT_CH); // miden VBAT/2 por divisor 100k/100k
  float vbat = v_bat_div * 2.0f; // Volts reales

  // Conversión a unidades compactas
  uint16_t soil_permille = soil_percent_permille_from_voltage(v_soil);
  int16_t t_c_x100 = (int16_t)lroundf(tC * 100.0f);
  uint16_t rh_x100 = (uint16_t)lroundf(rh * 100.0f);
  uint16_t press_hPa_x10 = (uint16_t)lroundf(p_hPa * 10.0f);
  uint16_t vbat_mV = (uint16_t)lroundf(vbat * 1000.0f);

  // Construcción de la trama
  FrameV1 frm{};
  frm.pre[0] = 'A'; frm.pre[1] = 'G';
  frm.ver = 0x01;
  frm.dev = device_id32();
  frm.seq = rtc_seq;
  frm.t_c_x100 = t_c_x100;
  frm.rh_x100 = rh_x100;
  frm.press_hPa_x10 = press_hPa_x10;
  frm.soil_permille = soil_permille;
  frm.vbat_mV = vbat_mV;

  Serial.printf("ID=0x%08lX SEQ=%lu T=%.2fC RH=%.2f%% P=%.1fhPa SOIL=%.1f%% VBAT=%.3fV\n",
    (unsigned long)frm.dev, (unsigned long)frm.seq,
    tC, rh, p_hPa, soil_permille/10.0f, vbat);

  // Radio
  if (!lora_radio_begin(LORA_FREQ_MHZ, LORA_SF, LORA_TX_PWR_DBM)) {
    Serial.println(F("ERR: Fallo init LoRa (frecuencia/pines/región)"));
  } else {
    bool ok = send_frame_once(frm);
    Serial.printf("TX %s, len=%u, CRC=0x%04X, F=%.1fMHz SF=%d PWR=%ddBm\n",
      ok ? "OK" : "ERR", (unsigned)sizeof(frm), frm.crc, LORA_FREQ_MHZ, LORA_SF, LORA_TX_PWR_DBM);
  }
  // Duerme la radio
  lora_radio_sleep();

  // Espera corta para drenar UART
  delay(50);

  // Programa deep sleep con temporizador
  esp_sleep_enable_timer_wakeup((uint64_t)WAKE_INTERVAL_S * 1000000ULL);
  Serial.printf("DeepSleep %us...\n", WAKE_INTERVAL_S);
  Serial.flush();
  esp_deep_sleep_start();
}

void loop() {
  // No se usa; el ESP32 nunca entra aquí debido a deep sleep
}

Puntos clave del código:
– Se desconectan WiFi y BT para reducir consumo.
– El BME280 se usa en modo forced, volviendo a sleep tras la medición.
– El ADS1115 realiza lecturas single-shot, que apagan internamente el conversor entre muestras.
– La trama “AG v1” incluye un CRC16-IBM propio y además se habilita el CRC de la librería LoRa.
– Se usa RTC_DATA_ATTR para mantener el contador de secuencia entre ciclos de deep sleep.
– El SX1276 se pone en sleep tras el envío.
– El ESP32 entra en deep sleep durante WAKE_INTERVAL_S (por defecto 900 s = 15 min).

Receptor de validación (opcional, misma TTGO LoRa32)

Para validar por aire, flashea en otra TTGO LoRa32 el siguiente receptor de propósito general. Solo decodifica cabecera y CRC para mostrar los valores.

#include <Arduino.h>
#include <SPI.h>
#include <LoRa.h>

static constexpr int LORA_SS = 18;
static constexpr int LORA_RST = 14;
static constexpr int LORA_DIO0 = 26;

#ifndef LORA_FREQ_MHZ
#define LORA_FREQ_MHZ 868.1
#endif
#ifndef LORA_SF
#define LORA_SF 7
#endif

#pragma pack(push,1)
struct FrameV1 {
  uint8_t  pre[2];
  uint8_t  ver;
  uint32_t dev;
  uint32_t seq;
  int16_t  t_c_x100;
  uint16_t rh_x100;
  uint16_t press_hPa_x10;
  uint16_t soil_permille;
  uint16_t vbat_mV;
  uint16_t crc;
};
#pragma pack(pop)

uint16_t crc16_ibm(const uint8_t* d, size_t n) {
  uint16_t crc=0xFFFF;
  for(size_t i=0;i<n;i++){ crc^=d[i]; for(uint8_t b=0;b<8;b++){ crc=(crc&1)?(crc>>1)^0xA001:(crc>>1);} }
  return crc;
}

void setup() {
  Serial.begin(115200);
  SPI.begin();
  LoRa.setPins(LORA_SS, LORA_RST, LORA_DIO0);
  if (!LoRa.begin(LORA_FREQ_MHZ*1e6)) {
    Serial.println("ERR: LoRa.begin()");
    while(1) delay(1000);
  }
  LoRa.setSpreadingFactor(LORA_SF);
  LoRa.setSignalBandwidth(125E3);
  LoRa.setCodingRate4(5);
  LoRa.enableCrc();
  Serial.println("RX listo");
}

void loop() {
  int packetSize = LoRa.parsePacket();
  if (packetSize == (int)sizeof(FrameV1)) {
    FrameV1 frm{};
    LoRa.readBytes((uint8_t*)&frm, sizeof(frm));
    uint16_t crc = frm.crc; frm.crc = 0;
    uint16_t calc = crc16_ibm((uint8_t*)&frm, sizeof(frm)-2);
    if (crc == calc && frm.pre[0]=='A' && frm.pre[1]=='G' && frm.ver==0x01) {
      float tC = frm.t_c_x100 / 100.0f;
      float rh = frm.rh_x100 / 100.0f;
      float p  = frm.press_hPa_x10 / 10.0f;
      float soilPct = frm.soil_permille / 10.0f;
      float vbat = frm.vbat_mV / 1000.0f;
      Serial.printf("OK dev=0x%08lX seq=%lu T=%.2fC RH=%.2f%% P=%.1fhPa SOIL=%.1f%% VBAT=%.3fV RSSI=%d SNR=%.1f\n",
        (unsigned long)frm.dev, (unsigned long)frm.seq, tC, rh, p, soilPct, vbat, LoRa.packetRssi(), LoRa.packetSnr());
    } else {
      Serial.println("ERR CRC/cabecera");
    }
  }
}

Compilación, flash y ejecución

A continuación los comandos exactos con PlatformIO CLI. Puedes usarlos en cualquier SO con la consola/terminal.

1) Verificar versiones de Python y PlatformIO:

python --version
pio --version

2) Crear el proyecto (en una carpeta nueva):

mkdir -p ~/proyectos/lora-agro-telemetry-lowpower
cd ~/proyectos/lora-agro-telemetry-lowpower
pio project init --board ttgo-lora32-v1

3) Sustituye platformio.ini por el proporcionado en este caso práctico y crea src/main.cpp con el código anterior.

4) Opcional: listar la placa para confirmar:

pio boards | grep -i ttgo

5) Actualizar paquetes y compilar:

pio pkg update
pio run -t clean
pio run

6) Conecta la TTGO LoRa32 por USB. Identifica el puerto:
– Windows: comprueba en el Administrador de dispositivos (COMx).
– Linux: dmesg | grep -i ttyUSB y ls -l /dev/ttyUSB*
– macOS: ls -l /dev/tty.SLAB_USBtoUART

7) Flashear el firmware:

pio run -t upload

8) Abrir monitor serie a 115200 baudios:

pio device monitor --baud 115200 --echo --filter time --filter esp32_exception_decoder

Notas específicas por SO:
– Linux udev: si no tienes permisos, crea /etc/udev/rules.d/99-usb-serial.rules con:
– SUBSYSTEM==»tty», ATTRS{idVendor}==»10c4″, ATTRS{idProduct}==»ea60″, MODE=»0666″, GROUP=»dialout»
– Luego: sudo udevadm control –reload-rules && sudo udevadm trigger
– Windows: si upload falla intermitente, prueba cables USB de calidad y puertos traseros.

Para el receptor opcional, crea otro proyecto (o un environment aparte) y repite los pasos con su main.cpp.

Validación paso a paso

1) Validación de consola del transmisor:
– Tras el reset, deberías ver líneas similares a:
– [lora-agro-telemetry-lowpower] Boot
– ID=0x12AB34CD SEQ=1 T=23.12C RH=45.67% P=1013.2hPa SOIL=56.7% VBAT=4.051V
– TX OK, len=21, CRC=0x5A93, F=868.1MHz SF=7 PWR=14dBm
– DeepSleep 900s…

• SEQ aumentará en cada despertar (1,2,3…).

2) Validación de sensores:
– Si el BME280 no está o su dirección no coincide, verás ERR: BME280 no detectado.
– Si el ADS1115 no responde, verás ERR: ADS1115 no detectado en 0x48.
– Acerca un dedo al sensor de suelo (si está al aire) o insértalo en tierra húmeda; la lectura SOIL deberá aumentar.

3) Validación de radio con receptor (opcional, segunda TTGO LoRa32):
– En el receptor, al abrir el monitor serie deberías ver:
– RX listo
– OK dev=0x12AB34CD seq=1 T=23.12C RH=45.67% P=1013.2hPa SOIL=56.7% VBAT=4.051V RSSI=-72 SNR=9.8
– Comprueba que el dev (ID) y seq coinciden con el transmisor y que los valores son razonables.

4) Validación de consumo (orientativa):
– Con un medidor USB en línea, observa tres fases:
– Pico al transmitir LoRa (decenas de mA, típico 80–120 mA por milisegundos).
– Activo durante sensado y TX (20–70 mA según placa).
– Deep sleep: debería caer significativamente. En TTGO LoRa32, dependiendo del regulador y del SX1276, es habitual ver cientos de µA a ~1–2 mA. Registra el valor.
– Si el consumo en deep sleep no baja de ~5 mA, revisa:
– Que WiFi/BT estén apagados.
– Que no tengas LEDs siempre encendidos.
– Que el sensor de suelo no consuma de forma continua (puede alimentarse desde un GPIO + MOSFET para desconectarlo entre mediciones en una mejora posterior).

5) Validación de payload/CRC:
– Si alteras el código del receptor para forzar un CRC erróneo, debe reportar ERR CRC/cabecera, verificando que el emisor genera CRC correcto.

6) Verificación de duty-cycle:
– Para EU868, con WAKE_INTERVAL_S=900 (15 min), el duty-cycle es seguro. Si reduces el intervalo, asegúrate de cumplir normativa (1% por sub-banda típica).

Troubleshooting

1) No aparece el puerto serie:
– Instala el driver CP210x adecuado.
– Cambia de cable (evita “solo carga”).
– En Linux, añade usuario a dialout y reabre sesión.
– Prueba otro puerto USB (en PC de sobremesa, los traseros suelen ser más fiables).

2) Fallo al entrar en modo programación (upload):
– Mantén pulsado BOOT (GPIO0 a GND) mientras conectas USB, o pulsa RST manteniendo BOOT.
– En PlatformIO, intenta: pio run -t upload –upload-port /dev/ttyUSB0 (ajusta puerto).
– Desconecta otros dispositivos serie que “secuestren” el puerto.

3) LoRa.begin() falla:
– Verifica antena conectada y banda correcta (LORA_FREQ_MHZ).
– Confirma pines del SX1276 (para TTGO: SS=18, RST=14, DIO0=26). Si usas otro modelo, ajusta.
– No mezcles región (EU868 vs US915) con frecuencias no válidas.

4) No se observan lecturas I2C:
– Confirmar 3V3 y GND a los módulos.
– Verifica que BME280 no sea en realidad BMP280 (sin humedad).
– Comprueba direcciones: muchos BME280 vienen a 0x76; si no responde, prueba 0x77 en el código (el ejemplo ya intenta ambas).
– Cableado SDA/SCL correcto (21/22) y longitud/ruido razonables.

5) ADS1115 saturado o lecturas erróneas:
– Revisa GAIN. Con GAIN_ONE (±4.096 V) y VDD de 3.3 V es adecuado; si la señal es baja, podrías usar GAIN_TWO para mejor resolución.
– Asegura masas comunes y que el sensor de suelo se alimenta a 3.3 V (no 5 V).

6) Deep sleep no reduce consumo:
– Asegura que LoRa.sleep() se llama antes de esp_deep_sleep_start().
– Verifica que no haya periferia externa alimentada sin necesidad (sensores).
– Revisa que WiFi.mode(WIFI_OFF) y btStop() se ejecuten sin errores.

7) Mensajes esporádicos “Brownout detector”:
– Batería descargada o picos de corriente durante TX.
– Usa una LiPo en buen estado y un cable corto; considera un condensador adicional de desacoplo (p. ej. 470 µF cerca del módulo LoRa).

8) Cobertura de radio insuficiente:
– Aumenta SF (ej., LORA_SF=9 o 10) a costa de tiempo en aire.
– Mejora antena, eleva el nodo, evita obstáculos.
– Ajusta potencia respetando límites regulatorios (14 dBm EU, 20 dBm en ciertos casos con restricciones).

Mejoras/variantes

• Cortar alimentación al sensor de suelo:
• Controla VCC del sensor con un MOSFET P o un switch de alta/low-side desde un GPIO para apagarlo entre mediciones.
• Encriptación ligera:
• Añade cifrado (p. ej., AES-128 CTR) al payload antes de LoRa.write(); intercambia una clave en el receptor.
• Confirmación y reintentos:
• Implementa ACK ligero con el receptor enviando un paquete corto de vuelta; reintenta si no hay ACK, con contador limitado para no violar duty-cycle.
• LoRaWAN (si tu caso requiere):
• Sustituye LoRa “crudo” por LMIC (MCCI) y gestiona altas en un Network Server (TTN/ChirpStack). Implica más complejidad y consumo.
• ADR y autoajuste:
• Cambia SF en función del RSSI/SNR reportado por el receptor a lo largo del tiempo.
• Medición adicional:
• Usa ADS1115 canales A2/A3 para sensores de pH/EC aislados o tensiómetros, con cuidado de masas y filtrado.
• Optimización de tiempo en aire:
• Compacta más el payload (por ejemplo, delta-encoding y escala fija) y reduce la cadencia en condiciones estables.

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.14 y Python 3.11.6; pio –version responde correctamente.
• [ ] El driver CP210x está instalado y el puerto serie aparece al conectar la TTGO LoRa32.
• [ ] He creado el proyecto con board=ttgo-lora32-v1 y he pegado platformio.ini con versiones y build_flags indicados.
• [ ] He cableado BME280 y ADS1115 a SDA=21 y SCL=22, con 3V3 y GND compartidos.
• [ ] El sensor de suelo está conectado a A0 del ADS1115; el divisor VBAT (100k/100k) a A1.
• [ ] El transmisor compila, flashea y muestra por serie la línea de mediciones y “TX OK”.
• [ ] Puedo ver el incremento de SEQ en cada despertar y cambios en SOIL al humedecer/secar la sonda.
• [ ] En validación por aire (opcional), el receptor TTGO LoRa32 decodifica tramas “AG v1” con CRC OK.
• [ ] El consumo cae notablemente en deep sleep tras unos segundos (verificado con medidor).
• [ ] He ajustado LORA_FREQ_MHZ/SF/PA según mi región y cobertura requerida.

Con este caso práctico tendrás un nodo agrícola de telemetría LoRa de bajo consumo funcionando con el modelo exacto TTGO LoRa32 (ESP32 + SX1276) y sensores BME280 + ADS1115, listo para desplegar en campo y extender con mejoras avanzadas.

Objetivo y caso de uso

Qué construirás: Un sistema avanzado de localización acústica utilizando el ESP32-S3-DevKitC-1 y el micrófono INMP441 para capturar audio estéreo y estimar el tiempo de llegada diferido (TDOA).

Para qué sirve

• Localización de fuentes de sonido en entornos ruidosos utilizando técnicas de beamforming.
• Detección de la dirección de llegada (DoA) de sonidos en aplicaciones de robótica y automatización.
• Implementación de sistemas de seguridad acústica que responden a sonidos específicos.
• Desarrollo de asistentes de voz que mejoran la precisión en la detección de comandos.

Resultado esperado

• Precisión en la localización de fuentes de sonido con un margen de error de menos de 5 grados.
• Latencia de procesamiento de audio de menos de 50 ms para respuestas en tiempo real.
• Capacidad de manejar hasta 10 paquetes de audio por segundo para análisis en tiempo real.
• Consumo de energía optimizado para funcionamiento continuo en dispositivos portátiles.

Público objetivo: Desarrolladores y entusiastas de la electrónica; Nivel: Avanzado

Arquitectura/flujo: Captura de audio estéreo mediante INMP441, procesamiento en ESP32-S3, estimación de TDOA y DoA, salida de datos a través de MQTT.

Nivel: Avanzado

Prerrequisitos

Sistema operativo y herramientas probadas

• Windows 11 23H2 (x64) con PowerShell 7.4
• Ubuntu 22.04 LTS (x86_64) con Bash 5.1
• macOS 13 Ventura (Apple Silicon o Intel) con Terminal zsh 5.8

Toolchain exacta y versiones

• PlatformIO Core 6.1.14 (instalado vía pip)
• Especificaciones de proyecto PlatformIO:
• platform = espressif32@6.5.0
• framework = espidf (ESP-IDF 5.1.2)
• board = esp32-s3-devkitc-1
• platform packages fijados:
  • platformio/toolchain-xtensa-esp32s3@12.2.0+20230208
  • platformio/framework-espidf@5.1.2
  • platformio/tool-esptoolpy@1.40501.0 (esptool.py 4.5.1)
• Python 3.10.x (recomendado 3.10.12) para PlatformIO
• Drivers USB:
• CP210x USB to UART Bridge (si tu placa expone puerto UART vía CP2102N). En Windows, instalar “CP210x Universal Windows Driver v10.1.10” desde Silicon Labs si el Puerto COM no aparece automáticamente.
• En ESP32-S3-DevKitC-1 puedes usar también el puerto USB nativo (GPIO19/20); no requiere driver adicional en macOS/Linux, y en Windows usa WinUSB.

Notas:
– Las versiones arriba listadas son las que se usarán en los comandos y en platformio.ini para reproducibilidad. Si ya tienes PlatformIO en VS Code, asegúrate de que el Core sea 6.1.14 o usa los comandos CLI indicados.

Materiales

• ESP32-S3-DevKitC-1 (modelo exacto de la placa)
• 2x INMP441 I2S mics (micrófonos digitales I2S, cada uno con pines: VDD, GND, SCK, WS, SD, L/R)
• Separador rígido para los micrófonos (barra, regla o impreso 3D) con distancia conocida d entre cápsulas, p. ej. 6.0 cm
• Cables Dupont macho-hembra (mínimo 10)
• Cable USB-C (para la ESP32-S3-DevKitC-1)
• Ordenador con uno de los SO soportados
• Fuente: Velcro/cinta doble cara para fijar los mics a la barra
• Opcional:
• Sonda lógica o analizador para verificar I2S
• Altavoz activo portátil para pruebas de dirección
• Trípode o base para mantener el arreglo en un plano

Objetivo del proyecto: i2s-beamforming-direction-finding con 2 micrófonos INMP441 y una ESP32-S3-DevKitC-1.

Preparación y conexión

Consideraciones de hardware

• El INMP441 es un micrófono digital I2S con salida de 24 bits (justificada a 32 bits en el bus).
• Ambos INMP441 comparten reloj de bit (BCLK, SCK), reloj de palabra (LRCLK/WS) y la línea de datos (SD). Cada micrófono solo conduce la línea SD en su canal (L o R) según el pin L/R:
• L/R = GND → canal Izquierdo (L)
• L/R = VDD → canal Derecho (R)
• Alimentación a 3.3 V. No usar 5 V.

Usaremos un único bus I2S en modo estéreo. El ESP32-S3 lee dos canales simultáneamente (L y R) a 48 kHz.

Mapeo de pines recomendado (ESP32-S3-DevKitC-1)

• Seleccionamos GPIO que no interfieran con el USB nativo ni con señales de arranque. Los siguientes son seguros en la mayoría de revisiones de la DevKitC-1:

Notas:
– Ambos micrófonos comparten SD hacia la entrada DIN del ESP32-S3; no hay conflicto porque cada uno habla solo en su semiperiodo (L o R).
– Si tu placa INMP441 tiene pads de soldadura para L/R, asegúrate de puentear correctamente uno a GND y el otro a 3V3.

Geometría del arreglo

• Distancia entre centros acústicos de los micrófonos, d: 6.0 cm (0.06 m). Mide y anota con precisión (±0.5 mm). Esta distancia se usará en las ecuaciones.
• Arreglo lineal (dos micrófonos en línea recta). Ángulo de llegada (azimut) θ definido respecto al eje normal central, con θ ∈ [−90°, +90°].

Código completo (ESP-IDF con PlatformIO)

El ejemplo está escrito en C usando el driver I2S v2 de ESP-IDF 5.1 y cálculo de TDOA (Time Difference of Arrival) por correlación cruzada en el dominio temporal en una ventana deslizante. A partir de la TDOA se estima el ángulo: θ = arcsin(c·τ/d), donde c ≈ 343 m/s (20 °C), τ es el retardo entre canales y d la separación.

Características:
– Frecuencia de muestreo: 48 kHz
– Profundidad de palabra en bus: 32 bits (los INMP441 entregan 24 bits justificados)
– Ventana de procesamiento: N = 1024 frames (≈21.33 ms)
– Búsqueda de retraso: ±16 muestras (cubre ±9 muestas necesarias para d=6 cm a 48 kHz)
– Normalización previa (quita DC y escala por desviación típica)
– Interpolación parabólica para submuestra

Estructura:
– Inicialización I2S en modo estándar (Philips), RX maestro
– Tarea principal que:
1) Lee bloques del bus I2S
2) Demultiplexa L/R y convierte a float normalizada
3) Calcula TDOA mediante correlación
4) Estima θ y lo imprime por puerto serie

platformio.ini

; platformio.ini — Toolchain y build reproducibles
[env:esp32-s3-devkitc-1]
platform = espressif32@6.5.0
framework = espidf
board = esp32-s3-devkitc-1

; Paquetes fijados (versiones exactas)
platform_packages =
  platformio/toolchain-xtensa-esp32s3@12.2.0+20230208
  platformio/framework-espidf@5.1.2
  platformio/tool-esptoolpy@1.40501.0

; Opciones de build/flash/monitor
monitor_speed = 115200
board_build.flash_mode = qio
build_unflags = -Os
build_flags =
  -O2
  -DLOG_LOCAL_LEVEL=ESP_LOG_INFO

src/main.c

#include <stdio.h>
#include <string.h>
#include <math.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_err.h"
#include "driver/i2s_std.h"
#include "driver/gpio.h"

static const char *TAG = "BF_DF";

// Parámetros físicos
#define SPEED_OF_SOUND      343.0f      // m/s a 20°C
#define MIC_DISTANCE_M      0.06f       // 6 cm entre micrófonos

// Pines I2S (ESP32-S3-DevKitC-1)
#define I2S_BCLK_IO         12
#define I2S_WS_IO           13
#define I2S_SD_IO           14

// I2S y DSP
#define SAMPLE_RATE         48000
#define WORD_BITS           I2S_DATA_BIT_WIDTH_32BIT
#define SLOT_MODE           I2S_SLOT_MODE_STEREO

// Procesamiento
#define FRAME_LEN           1024        // frames estéreo por iteración
#define MAX_LAG_SAMPLES     16          // búsqueda de retardo ±16
#define READ_TIMEOUT_MS     1000

// Buffer I2S: 2 canales * FRAME_LEN * 4 bytes (32 bits)
static int32_t i2s_rx_buf[FRAME_LEN * 2];

// Señales normalizadas
static float xL[FRAME_LEN];
static float xR[FRAME_LEN];

// Canal I2S
static i2s_chan_handle_t rx_chan = NULL;

static esp_err_t i2s_init_std(void)
{
    esp_err_t ret;
    i2s_chan_config_t chan_cfg = {
        .id = I2S_NUM_0,
        .role = I2S_ROLE_MASTER,
        .dma_desc_num = 8,
        .dma_frame_num = 256,
        .auto_clear = true,
        .intr_priority = 0
    };

    ret = i2s_new_channel(&chan_cfg, NULL, &rx_chan);
    if (ret != ESP_OK) return ret;

    i2s_std_config_t std_cfg = {
        .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(SAMPLE_RATE),
        .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(WORD_BITS, SLOT_MODE),
        .gpio_cfg = {
            .mclk = I2S_GPIO_UNUSED,
            .bclk = I2S_BCLK_IO,
            .ws   = I2S_WS_IO,
            .dout = I2S_GPIO_UNUSED,
            .din  = I2S_SD_IO,
            .invert_flags = {
                .mclk_inv = false,
                .bclk_inv = false,
                .ws_inv = false,
            }
        }
    };

    ret = i2s_channel_init_std_mode(rx_chan, &std_cfg);
    if (ret != ESP_OK) return ret;

    ret = i2s_channel_enable(rx_chan);
    return ret;
}

static inline float s32_to_float_norm(int32_t s)
{
    // INMP441: 24 bits justificados en 32; mover 8 bits y normalizar a [-1, 1)
    int32_t v24 = (s >> 8);
    return (float)v24 / 8388608.0f; // 2^23
}

static void preprocess_normalize(const int32_t *src, float *dstL, float *dstR, size_t n)
{
    double meanL = 0.0, meanR = 0.0;
    for (size_t i = 0; i < n; ++i) {
        float l = s32_to_float_norm(src[2*i + 0]);
        float r = s32_to_float_norm(src[2*i + 1]);
        dstL[i] = l;
        dstR[i] = r;
        meanL += l;
        meanR += r;
    }
    meanL /= (double)n;
    meanR /= (double)n;

    double varL = 0.0, varR = 0.0;
    for (size_t i = 0; i < n; ++i) {
        float l = dstL[i] - (float)meanL;
        float r = dstR[i] - (float)meanR;
        dstL[i] = l;
        dstR[i] = r;
        varL += (double)l * (double)l;
        varR += (double)r * (double)r;
    }
    varL /= (double)(n - 1);
    varR /= (double)(n - 1);

    float stdL = (float)sqrt(varL + 1e-12);
    float stdR = (float)sqrt(varR + 1e-12);

    for (size_t i = 0; i < n; ++i) {
        dstL[i] /= stdL;
        dstR[i] /= stdR;
    }
}

// Correlación cruzada restringida a ±MAX_LAG_SAMPLES
static int est_tdoa_lag(const float *x, const float *y, size_t n, int maxLag, float *peakCorr, float *lagFrac)
{
    // Cálculo NCC (Normalized Cross-Correlation) local
    float bestVal = -1e9f;
    int bestLag = 0;

    for (int lag = -maxLag; lag <= maxLag; ++lag) {
        double acc = 0.0;
        size_t count = 0;
        if (lag >= 0) {
            for (size_t i = 0; i + lag < n; ++i) {
                acc += (double)x[i + lag] * (double)y[i];
                count++;
            }
        } else { // lag < 0
            int k = -lag;
            for (size_t i = 0; i + k < n; ++i) {
                acc += (double)x[i] * (double)y[i + k];
                count++;
            }
        }
        float c = (count > 0) ? (float)(acc / (double)count) : 0.0f;
        if (c > bestVal) {
            bestVal = c;
            bestLag = lag;
        }
    }

    // Interpolación parabólica submuestral: usa valores en bestLag-1, bestLag, bestLag+1
    // c(l) ~ a(l - l0)^2 + b
    float c_m1 = -1e6f, c_0 = -1e6f, c_p1 = -1e6f;

    // Calcular c_m1
    {
        double acc = 0.0;
        size_t count = 0;
        int lag = bestLag - 1;
        if (lag >= -maxLag) {
            if (lag >= 0) {
                for (size_t i = 0; i + lag < n; ++i) { acc += (double)x[i + lag] * (double)y[i]; count++; }
            } else {
                int k = -lag;
                for (size_t i = 0; i + k < n; ++i) { acc += (double)x[i] * (double)y[i + k]; count++; }
            }
            c_m1 = (count > 0) ? (float)(acc / (double)count) : -1e6f;
        }
    }
    // Calcular c_0
    c_0 = bestVal;
    // Calcular c_p1
    {
        double acc = 0.0;
        size_t count = 0;
        int lag = bestLag + 1;
        if (lag <= maxLag) {
            if (lag >= 0) {
                for (size_t i = 0; i + lag < n; ++i) { acc += (double)x[i + lag] * (double)y[i]; count++; }
            } else {
                int k = -lag;
                for (size_t i = 0; i + k < n; ++i) { acc += (double)x[i] * (double)y[i + k]; count++; }
            }
            c_p1 = (count > 0) ? (float)(acc / (double)count) : -1e6f;
        }
    }

    float frac = 0.0f; // offset fraccional ∈ [-0.5, 0.5] aprox.
    float denom = (c_m1 - 2.0f*c_0 + c_p1);
    if (fabsf(denom) > 1e-9f) {
        frac = 0.5f * (c_m1 - c_p1) / denom;
        if (frac > 0.5f) frac = 0.5f;
        if (frac < -0.5f) frac = -0.5f;
    }

    if (peakCorr) *peakCorr = bestVal;
    if (lagFrac) *lagFrac = frac;
    return bestLag;
}

static float clampf(float v, float lo, float hi)
{
    if (v < lo) return lo;
    if (v > hi) return hi;
    return v;
}

void app_main(void)
{
    ESP_LOGI(TAG, "Inicializando I2S...");
    ESP_ERROR_CHECK(i2s_init_std());

    ESP_LOGI(TAG, "Iniciando captura a %d Hz, FRAME_LEN=%d", SAMPLE_RATE, FRAME_LEN);

    while (1) {
        size_t to_read = sizeof(i2s_rx_buf);
        size_t bytes_read = 0;
        esp_err_t err = i2s_channel_read(rx_chan, i2s_rx_buf, to_read, &bytes_read, pdMS_TO_TICKS(READ_TIMEOUT_MS));
        if (err != ESP_OK || bytes_read != to_read) {
            ESP_LOGW(TAG, "Lectura I2S incompleta: err=%d, bytes=%u", err, (unsigned)bytes_read);
            continue;
        }

        // Preprocesado: DC removal + normalización de energía
        preprocess_normalize(i2s_rx_buf, xL, xR, FRAME_LEN);

        // Estimar TDOA (lag y)
        float peakCorr = 0.0f, frac = 0.0f;
        int lag = est_tdoa_lag(xL, xR, FRAME_LEN, MAX_LAG_SAMPLES, &peakCorr, &frac);
        float lag_total = (float)lag + frac; // en muestras (submuestra)
        float tau = lag_total / (float)SAMPLE_RATE; // segundos

        // Ángulo de llegada (DoA) en grados
        float argument = clampf((SPEED_OF_SOUND * tau) / MIC_DISTANCE_M, -1.0f, 1.0f);
        float theta_rad = asinf(argument);
        float theta_deg = theta_rad * 180.0f / (float)M_PI;

        // Métrica de confianza simple (pico de correlación)
        // Nota: valores de peakCorr cercanos a 1 implican fuerte correlación
        float conf = clampf((peakCorr + 1.0f) / 2.0f, 0.0f, 1.0f);

        // Salida por serie
        printf("{\"deg\":%.2f,\"lag\":%.3f,\"tau_ms\":%.3f,\"peak\":%.3f}\n",
               theta_deg, lag_total, tau * 1000.0f, peakCorr);

        // Reporte legible
        ESP_LOGI(TAG, "DoA: %7.2f deg | lag: %+6.3f samp | tau: %+7.3f ms | peak: %.3f conf: %.2f",
                 theta_deg, lag_total, tau * 1000.0f, peakCorr, conf);

        // Pequeña pausa (opcional)
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}

Breve explicación de partes clave:
– i2s_init_std: configura I2S en modo estándar (Philips), maestro, estéreo 32-bit por slot, 48 kHz. Se asignan pines GPIO12/13/14 a BCLK/WS/DIN respectivamente.
– preprocess_normalize: convierte 32→24 bits, quita DC (media) y normaliza por desviación típica para aproximar un pre-blanqueo; mejora la robustez de la correlación frente a señales con energía desigual.
– est_tdoa_lag: calcula la correlación cruzada de xL y xR en una ventana y busca el lag de máxima coincidencia en ±16 muestras. Se interpola con una parábola local para obtener submuestra.
– Cálculo de θ: arcsin(c·τ/d), con saturación a [-1,1] para robustez numérica. Se imprime JSON por stdout para facilitar parsing, además de un log humano.
– FRAME_LEN y MAX_LAG_SAMPLES se ajustan a la geometría y Fs. Con d=0.06 m y Fs=48 kHz, el máximo retraso absoluto es ~8.4 muestras; ±16 aporta margen.

Compilación/flash/ejecución

Instalación de PlatformIO Core 6.1.14

• Windows/macOS/Linux:
• Requiere Python 3.10.x disponible como python3 en PATH.

Comandos:

# 1) Crear y activar un entorno (opcional pero recomendado)
python3 -m venv .venv
source .venv/bin/activate   # en Windows: .venv\Scripts\activate

# 2) Instalar PlatformIO Core versión exacta
python3 -m pip install --upgrade pip
python3 -m pip install platformio==6.1.14

# 3) Verificar versión
pio --version
# Debe mostrar: PlatformIO Core, version 6.1.14

Inicializar proyecto y aplicar configuración

# 4) Crear carpeta del proyecto
mkdir esp32s3_i2s_beamforming && cd esp32s3_i2s_beamforming

# 5) Inicializar proyecto para ESP32-S3-DevKitC-1
pio project init --board esp32-s3-devkitc-1

# 6) Sobrescribir platformio.ini con el contenido del bloque anterior
#    (edita con tu editor y pega el contenido exacto)

# 7) Crear carpeta src y archivo main.c (pega el código del bloque anterior)
mkdir -p src
$EDITOR src/main.c

Compilar, flashear y monitorizar

• Conecta la ESP32-S3-DevKitC-1 por USB-C.
• Identifica el puerto serie:
• Windows: Revisar “Puertos (COM y LPT)” en el Administrador de dispositivos (p. ej., COM7).
• macOS: ls /dev/tty.usb* (p. ej., /dev/tty.usbmodemXXXXXXXX)
• Linux: dmesg | tail o ls /dev/ttyACM /dev/ttyUSB.

Comandos:

# 8) Compilación
pio run

# 9) Flasheo (si tu puerto no se detecta automáticamente, especifica --upload-port)
pio run --target upload --upload-port <PUERTO_SERIAL>

# 10) Monitor serie a 115200 baudios
pio device monitor -b 115200

Notas:
– Si usas el USB nativo CDC del S3, puede presentarse como /dev/ttyACM0 (Linux) o tty.usbmodem (macOS).
– Para Windows, si no aparece el COM, instala el CP210x driver.

Validación paso a paso

Objetivo: Confirmar que el sistema estima correctamente la dirección (DoA) de una fuente sonora en el plano del arreglo.

1) Comprobación eléctrica
– Verifica continuidad de:
– BCLK (SCK) común a ambos INMP441 y GPIO12
– LRCLK (WS) común y GPIO13
– SD común y GPIO14
– VDD 3V3 a ambos mics
– GND común entre placa y mics
– Verifica L/R:
– Mic1 L/R a GND (Left)
– Mic2 L/R a 3V3 (Right)

2) Salida básica por consola
– Abre el monitor serie.
– Debes ver líneas como:
– {«deg»:-5.40,»lag»:-0.700,»tau_ms»:-0.015,»peak»:0.312}
– I (BF_DF) DoA: -5.40 deg | lag: -0.700 samp | tau: -0.015 ms | peak: 0.312 conf: 0.66
– Si peak ~ 0 y deg errático, revisa conexiones/ruido amb.

3) Prueba con ruido impulsivo (aplausos)
– Coloca una fuente (tus palmas) a ~0° (frente al centro del arreglo) a 0.5–1 m.
– Esperado: θ cercano a 0°, fluctuando ±5–10°.
– Mueve la fuente a la izquierda (lado del Mic1/L):
– Esperado: θ negativo (por convención usada), p. ej., -30° a -60°.
– Mueve la fuente a la derecha (lado del Mic2/R):
– Esperado: θ positivo, p. ej., +30° a +60°.

4) Prueba con tono continuo
– Usa un altavoz con tono 1 kHz a volumen moderado.
– Colócalo a ~30° respecto al eje. Mantén la distancia y evita reflexiones.
– Esperado: θ estable ±5° con peakCorr más alto (0.4–0.8). Si peak < 0.2, aumenta SNR o reduce reverberación.

5) Verificación de cotas físicas
– Para d=0.06 m y Fs=48000 Hz, TDOA máximo teórico = d/c ≈ 0.000175 s → ~8.4 muestras.
– Observa lag entre ~-8.5 y +8.5. Lag fuera de ese rango indica cableado L/R invertido o error de parámetros.

6) Calibración de distancia
– Si nota sesgo sistemático (p. ej., siempre subestima el ángulo), mide d con más precisión y ajusta MIC_DISTANCE_M en el código.

7) Comprobación de estabilidad
– Observa conf (mapeada a partir de peakCorr). Debe aumentar con señales directas y disminuir con ruido difuso o reverberación.

8) Persistencia de resultados
– Captura 30 s de logs. Exporta a CSV/JSON para graficar θ(t) y evaluar varianza en distintas posiciones.

Troubleshooting

1) No aparece puerto serie
– Solución:
– Cambia de cable USB-C (algunos solo suministran alimentación).
– Instala driver CP210x en Windows.
– Prueba el puerto USB nativo (CDC) de la S3 si tu DevKit lo expone.
– En Linux, agrega tu usuario al grupo dialout: sudo usermod -a -G dialout $USER y reinicia sesión.

2) Lecturas I2S vacías o erráticas (bytes_read < to_read)
– Causas probables:
– Pines BCLK/WS/DIN erróneos.
– SD no compartida correctamente entre los dos micrófonos.
– Timeout por bloqueos en ISR o CPU saturada.
– Soluciones:
– Verifica el cableado y continuidad.
– Reduce temporalmente FRAME_LEN a 512 para probar.
– Asegura que READ_TIMEOUT_MS sea suficiente (>= 1000 ms ya lo es).

3) Canales invertidos o ángulos con signo opuesto
– Causa: L/R mal conectados (ambos a GND o ambos a 3V3).
– Solución:
– Mic1 L/R a GND (L), Mic2 L/R a 3V3 (R).
– Si no puedes re-cablear, intercambia xL y xR en el código.

4) Ángulos saturados cerca de ±90° aun con fuente frontal
– Causas:
– d mal medido (demasiado grande en el código).
– Reverberación fuerte creando falsas correlaciones.
– Soluciones:
– Mide d y ajusta MIC_DISTANCE_M.
– Prueba en espacio menos reverberante; acerca la fuente.

5) Distorsión o clipping en señales
– Causas:
– Sonido excesivamente fuerte en campo cercano.
– Conversión 24→float mal escalada (shift inadecuado).
– Soluciones:
– Aleja la fuente o reduce volumen.
– Ajusta s32_to_float_norm: usa división por 2^23 (8388608.0f), como está en el código.

6) CPU Load alto o watchdog reset
– Causas:
– FRAME_LEN grande combinado con logs intensivos.
– Soluciones:
– Baja la verbosidad (LOG_LOCAL_LEVEL).
– Reduce frecuencia de logs (imprimir 1 de cada 5 iteraciones).
– Ajusta -O2/-O3 en build_flags.

7) “lag” fuera de ±16 con picos falsos
– Causas:
– Señales altamente periódicas (tonos puros) con ambigüedad de fase.
– Soluciones:
– Usa ruido de banda ancha o voz/música.
– Aumenta MAX_LAG_SAMPLES a 24–32 (con coste de CPU) o añade una heurística de banda ancha (filtro pasabanda 300–3400 Hz).

8) Ningún pico (peakCorr ≈ 0)
– Causas:
– SD desconectado, WS/BCLK ausentes.
– Micrófonos defectuosos.
– Soluciones:
– Verifica con analizador lógico que BCLK y WS están presentes (BCLK ≈ 3.072 MHz a 48 kHz con 32 bits*2 canales).
– Cambia micrófono para descartar fallo.

Mejoras/variantes

• GCC-PHAT en frecuencia:
• Sustituir la correlación temporal por GCC-PHAT (FFT → X1·conj(X2)/|X1·conj(X2)| → IFFT → argmax), mejora robustez a reverberación. Puedes integrar kissFFT o esp-dsp (FFT en ESP-IDF).
• Beamforming delay-and-sum:
• Añade un barrido de ángulos θ ∈ [−90°, +90°] y aplica retardos fraccionales (interpolación lineal o Lagrange orden 3) para alinear señales y maximizar energía sumada. El ángulo con máxima SNR define DoA.
• Estimación submuestral avanzada:
• Usa ajuste por correlación generalizada con ventanas (Hann/Blackman) y parabolic peak fitting mejorado (Quinn-Fernandes).
• Calibración de ganancia y fase:
• Compensa diferencias de sensibilidad entre mics aplicando escalado por RMS y compensación de fase/miniretardos medidos con tono de referencia.
• Aumento de Fs y downsampling:
• Captura a 96 kHz y haz decimación por 2 con filtro FIR; incrementa la resolución temporal de TDOA antes de decimar.
• Filtrado adaptativo:
• Pasabanda 300–3400 Hz para voz o 200–8000 Hz para música; mejora correlación y reduce baja frecuencia (ruido HVAC).
• Extensión a N>2 micrófonos:
• Con ESP32-S3 e I2S-TDM (módulos I2S MEMS TDM) puedes formar arreglos lineales/circulares para 2D-DoA y beamforming con mayor directividad.

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.14 con Python 3.10.x.
• [ ] He creado el proyecto con board=esp32-s3-devkitc-1 y platform=espressif32@6.5.0.
• [ ] He copiado el platformio.ini con los platform_packages exactos (toolchain-xtensa-esp32s3 12.2.0+20230208, framework-espidf 5.1.2, esptoolpy 4.5.1).
• [ ] He cableado los dos INMP441 con BCLK→GPIO12, WS→GPIO13, SD→GPIO14, VDD→3V3, GND→GND.
• [ ] L/R de Mic1 a GND (Left), L/R de Mic2 a 3V3 (Right).
• [ ] He fijado la distancia d entre micrófonos (p. ej., 6.0 cm) y la he puesto en MIC_DISTANCE_M.
• [ ] El proyecto compila (pio run) sin errores.
• [ ] El flasheo (pio run –target upload) se completa y el monitor serie muestra registros a 115200 bps.
• [ ] Al aplaudir frente a la pareja de micrófonos, la estimación de ángulo θ está cerca de 0°.
• [ ] Al mover la fuente a izquierda/derecha, θ cambia de signo y magnitud de manera coherente.
• [ ] peakCorr > 0.2 cuando la fuente está clara y cerca; si no, ajusto el entorno/volumen.

Apéndice: Notas prácticas y recomendaciones

• Longitud de cables: Mantén los cables I2S cortos y paralelos. Evita puentes largos y flojos; el SD especialmente debe ser limpio.
• Alimentación limpia: Usa el 3V3 de la DevKitC-1. Si usas protoboard, revisa falsos contactos.
• Protección ESD: Evita tocar los diafragmas de los micrófonos. Manipula por los bordes del PCB.
• Organización de logs: El formato JSON impreso permite que captures datos con pio device monitor –raw > logs.jsonl y luego los analices con Python.
• Temperatura y c: La velocidad del sonido depende de la temperatura. Para precisión, usa c ≈ 331 + 0.6·T(°C). Ajusta SPEED_OF_SOUND si trabajas lejos de 20 °C.
• Saturación por reverberación: En interiores con paredes cercanas, prueba con ventanas más cortas (FRAME_LEN=512) o filtrado pasabanda.

Con estos pasos y el código proporcionado, tendrás un sistema completo de i2s-beamforming-direction-finding con el hardware exacto ESP32-S3-DevKitC-1 + 2x INMP441 I2S mics, listo para medir direcciones de llegada en tiempo casi real y servir como base para beamforming activo (p. ej., rechazo de interferencias fuera de eje o realce de una fuente deseada).

Objetivo y caso de uso

Qué construirás: Un sistema de streaming de video utilizando ESP32-CAM y control de pan-tilt mediante PCA9685.

Para qué sirve

• Monitoreo remoto de espacios utilizando video en tiempo real.
• Control de cámaras en aplicaciones de robótica y drones.
• Implementación de sistemas de seguridad con visualización dinámica.
• Proyectos de domótica para vigilancia y control de áreas específicas.

Resultado esperado

• Streaming de video a 30 FPS con latencia inferior a 200 ms.
• Control de posición del servo con precisión de 1 grado.
• Conexión estable a través de WebSocket con menos de 5% de pérdida de paquetes.
• Tiempo de respuesta en el control de pan-tilt menor a 100 ms.

Público objetivo: Desarrolladores y entusiastas de IoT; Nivel: Avanzado

Arquitectura/flujo: Comunicación entre ESP32-CAM y servidor WebSocket, control de servos mediante PCA9685.

Nivel: Avanzado

Prerrequisitos

Sistemas operativos soportados y herramientas

• Windows 10/11 (64-bit)
• macOS 12/13/14 (Intel o Apple Silicon)
• Ubuntu 22.04 LTS / Debian 12

Toolchain exacta (versionado cerrado)

• IDE/CLI:
• Visual Studio Code 1.93.x (opcional, recomendado para edición)
• PlatformIO Core 6.1.12 (CLI)
• Paquetes PlatformIO:
• Plataforma: espressif32@6.7.0
• Framework Arduino: framework-arduinoespressif32@3.20014.0 (equivale a Arduino-ESP32 2.0.14)
• Compilador: toolchain-xtensa32 provisto por espressif32@6.7.0 (instalado automáticamente por PlatformIO)
• Librerías (resueltas por PlatformIO):
• me-no-dev/AsyncTCP@1.1.1
• me-no-dev/ESP Async WebServer@1.2.3
• adafruit/Adafruit PWM Servo Driver Library@2.4.2
• adafruit/Adafruit BusIO@1.14.5
• Python 3.11.x (requerido por PlatformIO Core)
• Controladores USB-UART (según tu adaptador):
• CP210x (Silicon Labs) o CH340/CH34x (WCH). Instala el driver oficial correspondiente si tu sistema no lo reconoce de forma nativa.

Instalación rápida de PlatformIO Core (CLI)

• Windows/macOS/Linux (asumiendo Python 3.11 disponible en PATH):
• Instalar:
  pip install -U platformio==6.1.12
• Verificar:
  pio --version
  Debe mostrar: PlatformIO Core, version 6.1.12

Materiales

• 1x ESP32-CAM (OV2640) — modelo AI-Thinker con cámara OV2640 integrada
• 1x Módulo PCA9685 16 canales (servo driver I2C)
• 2x Servos para pan-tilt (p. ej., SG90/MG90S). Si usas un soporte mecánico pan-tilt, típicamente canal 0 = pan, canal 1 = tilt
• 1x Adaptador USB–UART 3.3 V (FTDI/CP2102/CH340) para programar la ESP32-CAM
• 1x Fuente 5 V 2 A (para alimentar servos vía V+ del PCA9685)
• Protoboard o base de conexiones y cables Dupont
• 2–3 jumpers para modo de programación:
• GPIO0 a GND (para entrar en bootloader)
• RST a GND (botón o puente momentáneo para reinicio)
• Cables para I2C:
• SDA, SCL entre ESP32-CAM y PCA9685
• Cables para alimentación:
• VCC (3.3 V), 5 V, GND
• Opcional: Estructura mecánica pan-tilt (Smart Car PTZ o similar)

Nota: Este caso práctico está centrado estrictamente en el modelo “ESP32-CAM (OV2640) + PCA9685 servo driver” y el objetivo “ov2640-websocket-pan-tilt”.

Preparación y conexión

En la ESP32-CAM (AI-Thinker), la cámara utiliza una serie de GPIOs internos; evitaremos usar la ranura microSD para poder disponer de GPIO14 y GPIO15 como bus I2C. No usaremos la microSD en este proyecto.

• Bus I2C elegido:
• SDA → GPIO15 de la ESP32-CAM

• SCL → GPIO14 de la ESP32-CAM

• Conexiones USB–UART para programación:

• U0R (GPIO3) ← TX del adaptador USB–UART
• U0T (GPIO1) → RX del adaptador USB–UART
• 5V (ESP32-CAM) ← 5V del adaptador (si entrega suficiente) o fuente externa
• GND (ESP32-CAM) ← GND del adaptador
• GPIO0 ↔ GND (para entrar en modo de programación)

• RST ↔ GND (pulsar momentáneamente para reiniciar)

• PCA9685:

• VCC (lógica) ← 3.3 V de la ESP32-CAM (acepta 3.3–5 V; usar 3.3 V para lógica segura)
• V+ (potencia servos) ← 5 V de la fuente externa
• GND ← GND común (ESP32-CAM, adaptador USB–UART, fuente 5 V)
• SDA ← GPIO15 (ESP32-CAM)
• SCL ← GPIO14 (ESP32-CAM)
• Canales PWM:
  • CH0 (PCA9685) → Señal servo PAN
  • CH1 (PCA9685) → Señal servo TILT
• Alimentación de servos:
  • Rojo (Vcc) → V+ 5 V del PCA9685
  • Marrón/Negro (GND) → GND del PCA9685
  • Amarillo/Blanco (Señal) → CH0/CH1 del PCA9685

Tabla de conexiones detallada:

Advertencias:
– No alimentes los servos desde el pin 5V de la ESP32-CAM. Usa el terminal V+ del PCA9685 con una fuente 5 V adecuada y GND común.
– Evita usar GPIO12 (MTDI) para señales externas; puede causar problemas de arranque.
– Si usas una fuente 5 V separada para V+, une las masas (GND) de fuente, PCA9685 y ESP32-CAM.

Código completo

A continuación se proporciona el proyecto completo con PlatformIO. El objetivo “ov2640-websocket-pan-tilt” crea un servidor WebSocket que:
– Transmite imágenes JPEG de la cámara OV2640 en binario a los clientes conectados.
– Recibe comandos WebSocket de texto para posicionar PAN/TILT mediante el PCA9685.
– Sirve una página HTML con un visor y controles para pan/tilt.

platformio.ini

Incluye versiones fijas y librerías necesarias.

; ov2640-websocket-pan-tilt/platformio.ini
[env:esp32cam]
platform = espressif32@6.7.0
board = esp32cam
framework = arduino
platform_packages =
  framework-arduinoespressif32@3.20014.0
board_build.partitions = huge_app.csv
monitor_speed = 115200
upload_speed = 921600
build_flags =
  -DCORE_DEBUG_LEVEL=1
lib_deps =
  me-no-dev/AsyncTCP@1.1.1
  me-no-dev/ESP Async WebServer@1.2.3
  adafruit/Adafruit PWM Servo Driver Library@2.4.2
  adafruit/Adafruit BusIO@1.14.5

src/main.cpp

Explicación rápida de las partes clave:
– Configuración de cámara para AI-Thinker (OV2640).
– Inicialización de WiFi STA con credenciales.
– Servidor HTTP (AsyncWebServer) y WebSocket en /ws.
– Tarea FreeRTOS que captura frames y los empuja a los clientes vía WebSocket usando buffers seguros.
– Control de servos con PCA9685 a 50 Hz, mapeando ángulos a microsegundos.
– Página HTML embebida con JS para visualizar el stream y emitir comandos PAN/TILT.

// ov2640-websocket-pan-tilt/src/main.cpp
#include <Arduino.h>
#include <WiFi.h>
#include <esp_camera.h>
#include <Wire.h>
#include <Adafruit_PWMServoDriver.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>

// ========= Configuración WiFi =========
static const char* WIFI_SSID = "TU_SSID";
static const char* WIFI_PASS = "TU_PASSWORD";

// ========= Pines cámara AI-Thinker (OV2640) =========
#define PWDN_GPIO_NUM     32
#define RESET_GPIO_NUM    -1
#define XCLK_GPIO_NUM      0
#define SIOD_GPIO_NUM     26
#define SIOC_GPIO_NUM     27
#define Y9_GPIO_NUM       35
#define Y8_GPIO_NUM       34
#define Y7_GPIO_NUM       39
#define Y6_GPIO_NUM       36
#define Y5_GPIO_NUM       21
#define Y4_GPIO_NUM       19
#define Y3_GPIO_NUM       18
#define Y2_GPIO_NUM        5
#define VSYNC_GPIO_NUM    25
#define HREF_GPIO_NUM     23
#define PCLK_GPIO_NUM     22

// ========= I2C PCA9685 =========
// Usamos GPIO15 (SDA) y GPIO14 (SCL) en la ESP32-CAM
#define I2C_SDA 15
#define I2C_SCL 14

// ========= PCA9685 y servo =========
Adafruit_PWMServoDriver pwm = Adafruit_PWMServoDriver(0x40); // Dirección I2C por defecto

// Frecuencia típica servos
const float SERVO_FREQ_HZ = 50.0f;

// Canales
const uint8_t PAN_CH  = 0;
const uint8_t TILT_CH = 1;

// Calibración µs (ajústalo a tus servos/mecánica)
const int SERVO_MIN_US = 500;   // pulso mínimo
const int SERVO_MAX_US = 2500;  // pulso máximo

// Almacenamos ángulos actuales/objetivo para suavizado
volatile int pan_target_deg  = 90;
volatile int tilt_target_deg = 90;

volatile int pan_current_deg  = 90;
volatile int tilt_current_deg = 90;

// ========= Web =========
AsyncWebServer server(80);
AsyncWebSocket ws("/ws");

static const char INDEX_HTML[] PROGMEM = R"HTML(
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<title>ov2640-websocket-pan-tilt</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
 body { font-family: system-ui, sans-serif; margin: 1rem; color: #222; }
 .row { display: flex; gap: 1.5rem; flex-wrap: wrap; }
 .panel { border: 1px solid #ccc; border-radius: 8px; padding: 1rem; }
 #img { width: 100%; max-width: 480px; background: #000; }
 .ctrl label { display:block; margin-top: .5rem; }
 .ctrl input[type=range] { width: 100%; }
 .status { font-size: .9rem; color: #555; }
 button { padding: .5rem 1rem; margin-top: .5rem; }
</style>
</head>
<body>
<h1>ov2640-websocket-pan-tilt</h1>
<div class="row">
  <div class="panel">
    <img id="img" alt="stream" />
    <div class="status" id="st">Conectando…</div>
  </div>
  <div class="panel ctrl">
    <label>Pan: <span id="panv">90</span>°
      <input id="pan" type="range" min="0" max="180" value="90" />
    </label>
    <label>Tilt: <span id="tiltv">90</span>°
      <input id="tilt" type="range" min="0" max="180" value="90" />
    </label>
    <button id="center">Centrar (90°, 90°)</button>
  </div>
</div>
<script>
(() => {
  const img = document.getElementById('img');
  const st  = document.getElementById('st');
  const pan = document.getElementById('pan');
  const tilt= document.getElementById('tilt');
  const panv= document.getElementById('panv');
  const tiltv= document.getElementById('tiltv');
  const center = document.getElementById('center');

  let ws;
  function connect() {
    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
    ws = new WebSocket(`${proto}://${location.host}/ws`);
    ws.binaryType = 'arraybuffer';
    ws.onopen = () => st.textContent = 'Conectado';
    ws.onclose = () => { st.textContent = 'Desconectado. Reintentando…'; setTimeout(connect, 2000); };
    ws.onerror = () => { st.textContent = 'Error WS'; };

    ws.onmessage = (ev) => {
      if (typeof ev.data !== 'string') {
        const blob = new Blob([ev.data], { type: 'image/jpeg' });
        const url = URL.createObjectURL(blob);
        img.onload = () => URL.revokeObjectURL(url);
        img.src = url;
      } else {
        // Mensajes de texto del servidor (estado)
        st.textContent = ev.data;
      }
    };
  }
  connect();

  function sendCmd(cmd) {
    if (ws && ws.readyState === 1) ws.send(cmd);
  }

  pan.addEventListener('input', () => {
    panv.textContent = pan.value;
    sendCmd(`PAN:${pan.value}`);
  });
  tilt.addEventListener('input', () => {
    tiltv.textContent = tilt.value;
    sendCmd(`TILT:${tilt.value}`);
  });
  center.addEventListener('click', () => {
    pan.value = 90; tilt.value = 90;
    panv.textContent = '90'; tiltv.textContent = '90';
    sendCmd('PAN:90'); sendCmd('TILT:90');
  });
})();
</script>
</body>
</html>
)HTML";

// ========= Utilidades =========
static inline int clampi(int v, int lo, int hi) { return v < lo ? lo : (v > hi ? hi : v); }

void setServoAngle(uint8_t ch, int angleDeg) {
  angleDeg = clampi(angleDeg, 0, 180);
  const int us = SERVO_MIN_US + (int)((SERVO_MAX_US - SERVO_MIN_US) * (angleDeg / 180.0f));
  pwm.writeMicroseconds(ch, us);
}

void servoSmootherTask(void* arg) {
  const TickType_t interval = pdMS_TO_TICKS(15); // ~66 actualizaciones/s
  for (;;) {
    int p = pan_current_deg, pt = pan_target_deg;
    int t = tilt_current_deg, tt = tilt_target_deg;

    if (p != pt) {
      p += (pt > p) ? 1 : -1;
      pan_current_deg = p;
      setServoAngle(PAN_CH, p);
    }
    if (t != tt) {
      t += (tt > t) ? 1 : -1;
      tilt_current_deg = t;
      setServoAngle(TILT_CH, t);
    }
    vTaskDelay(interval);
  }
}

void wsOnEvent(AsyncWebSocket * server, AsyncWebSocketClient * client, 
               AwsEventType type, void * arg, uint8_t * data, size_t len) {
  if (type == WS_EVT_CONNECT) {
    client->text("WS conectado. Envíe PAN:<0..180> / TILT:<0..180>");
  } else if (type == WS_EVT_DATA) {
    AwsFrameInfo* info = (AwsFrameInfo*)arg;
    if (info->opcode == WS_TEXT) {
      String msg;
      msg.reserve(len);
      for (size_t i = 0; i < len; i++) msg += (char)data[i];

      // Formato esperado: "PAN:123" o "TILT:45"
      msg.trim();
      int sep = msg.indexOf(':');
      if (sep > 0) {
        String key = msg.substring(0, sep);
        String val = msg.substring(sep + 1);
        int angle = clampi(val.toInt(), 0, 180);
        if (key.equalsIgnoreCase("PAN")) {
          pan_target_deg = angle;
          client->text("PAN->" + String(angle));
        } else if (key.equalsIgnoreCase("TILT")) {
          tilt_target_deg = angle;
          client->text("TILT->" + String(angle));
        } else {
          client->text("CMD desconocido");
        }
      } else {
        client->text("Formato inválido");
      }
    }
  }
}

TaskHandle_t frameTaskHandle = nullptr;

void frameSenderTask(void* arg) {
  const TickType_t period = pdMS_TO_TICKS(100); // ~10 fps
  for (;;) {
    if (ws.count() > 0) {
      camera_fb_t* fb = esp_camera_fb_get();
      if (!fb) {
        // Notificar error eventual
        ws.textAll("Error: no frame");
      } else {
        // Crear buffer gestionado por AsyncWebSocket
        auto buf = ws.makeBuffer(fb->len);
        if (buf) {
          memcpy(buf->get(), fb->buf, fb->len);
          ws.binaryAll(buf);
        }
        esp_camera_fb_return(fb);
      }
    }
    vTaskDelay(period);
  }
}

bool initCamera() {
  camera_config_t config;
  config.ledc_channel = LEDC_CHANNEL_0;
  config.ledc_timer   = LEDC_TIMER_0;
  config.pin_d0       = Y2_GPIO_NUM;
  config.pin_d1       = Y3_GPIO_NUM;
  config.pin_d2       = Y4_GPIO_NUM;
  config.pin_d3       = Y5_GPIO_NUM;
  config.pin_d4       = Y6_GPIO_NUM;
  config.pin_d5       = Y7_GPIO_NUM;
  config.pin_d6       = Y8_GPIO_NUM;
  config.pin_d7       = Y9_GPIO_NUM;
  config.pin_xclk     = XCLK_GPIO_NUM;
  config.pin_pclk     = PCLK_GPIO_NUM;
  config.pin_vsync    = VSYNC_GPIO_NUM;
  config.pin_href     = HREF_GPIO_NUM;
  config.pin_sscb_sda = SIOD_GPIO_NUM;
  config.pin_sscb_scl = SIOC_GPIO_NUM;
  config.pin_pwdn     = PWDN_GPIO_NUM;
  config.pin_reset    = RESET_GPIO_NUM;
  config.xclk_freq_hz = 20000000; // 20 MHz típico
  config.pixel_format = PIXFORMAT_JPEG;

  if (psramFound()) {
    config.frame_size   = FRAMESIZE_QVGA; // 320x240
    config.jpeg_quality = 12;             // 10–20 es razonable
    config.fb_count     = 2;
    config.grab_mode    = CAMERA_GRAB_LATEST;
  } else {
    config.frame_size   = FRAMESIZE_QQVGA; // por si no hay PSRAM
    config.jpeg_quality = 15;
    config.fb_count     = 1;
    config.grab_mode    = CAMERA_GRAB_WHEN_EMPTY;
  }

  esp_err_t err = esp_camera_init(&config);
  if (err != ESP_OK) {
    Serial.printf("camera_init failed: 0x%x\n", err);
    return false;
  }
  sensor_t* s = esp_camera_sensor_get();
  // Ajustes opcionales del sensor
  s->set_brightness(s, 0);
  s->set_contrast(s, 0);
  s->set_saturation(s, 0);
  s->set_framesize(s, config.frame_size);

  return true;
}

void setup() {
  Serial.begin(115200);
  delay(200);

  // I2C para PCA9685
  Wire.begin(I2C_SDA, I2C_SCL, 400000); // 400 kHz
  if (!pwm.begin()) {
    Serial.println("ERROR: PCA9685 no responde en 0x40");
  }
  pwm.setOscillatorFrequency(27000000); // 27 MHz nominal
  pwm.setPWMFreq(SERVO_FREQ_HZ);
  delay(10);
  setServoAngle(PAN_CH, pan_current_deg);
  setServoAngle(TILT_CH, tilt_current_deg);

  // Cámara OV2640
  if (!initCamera()) {
    Serial.println("Fallo al iniciar cámara. Revise cableado y PSRAM.");
    // no return; permitimos que el sistema arranque para debug
  }

  // WiFi
  WiFi.mode(WIFI_STA);
  WiFi.setSleep(false);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  Serial.printf("Conectando a WiFi SSID='%s'\n", WIFI_SSID);
  unsigned long t0 = millis();
  while (WiFi.status() != WL_CONNECTED && millis() - t0 < 20000) {
    delay(300);
    Serial.print(".");
  }
  Serial.println();
  if (WiFi.status() == WL_CONNECTED) {
    Serial.printf("WiFi OK. IP: %s\n", WiFi.localIP().toString().c_str());
  } else {
    Serial.println("WiFi no conectado (timeout). Continúa en AP del router o revise credenciales.");
  }

  // Servidor HTTP y WebSocket
  ws.onEvent(wsOnEvent);
  server.addHandler(&ws);

  server.on("/", HTTP_GET, [](AsyncWebServerRequest *req){
    AsyncWebServerResponse* res = req->beginResponse_P(200, "text/html; charset=utf-8", INDEX_HTML, strlen(INDEX_HTML));
    res->addHeader("Cache-Control", "no-store");
    req->send(res);
  });

  server.on("/favicon.ico", HTTP_GET, [](AsyncWebServerRequest* req){ req->send(204); });

  server.begin();
  Serial.println("Servidor HTTP/WS listo.");

  // Tarea de suavizado servo
  xTaskCreatePinnedToCore(servoSmootherTask, "servoSmoother", 2048, nullptr, 1, nullptr, 1);

  // Tarea de envío de frames
  xTaskCreatePinnedToCore(frameSenderTask, "frameSender", 4096, nullptr, 1, &frameTaskHandle, 1);
}

void loop() {
  // AsyncWebServer no requiere loop pesado; el WS se atiende en callbacks
  delay(50);
}

Puntos clave:
– Se usan GPIO14 (SCL) y GPIO15 (SDA) para I2C, liberados al no usar la microSD.
– La tarea frameSender copia cada JPEG a un buffer administrado por AsyncWebSocket (ws.makeBuffer) antes de enviar, evitando usar el buffer de la cámara tras esp_camera_fb_return.
– Los comandos de control PAN/TILT son texto simple “PAN:<0..180>” y “TILT:<0..180>”.
– Un “servoSmootherTask” evita saltos bruscos en mecánicas pan-tilt.

Compilación, flash y ejecución

Asegúrate de poner GPIO0 a GND y reiniciar (RST→GND momentáneo) para entrar en bootloader antes de cargar el firmware.

1) Crear el proyecto PlatformIO:
– Con PlatformIO Core CLI:
mkdir ov2640-websocket-pan-tilt
cd ov2640-websocket-pan-tilt
pio project init --board esp32cam
– Sustituye el contenido del platformio.ini generado por el provisto en este caso.
– Crea el árbol de fuentes:
mkdir -p src
# Coloca el main.cpp provisto en src/main.cpp

2) Compilar:
pio run

3) Detectar el puerto serie (opcional):
pio device list

4) Poner la ESP32-CAM en modo programación:
– Conectar GPIO0 a GND.
– Reiniciar pulsando RST a GND y soltando.
– Verifica que el adaptador USB–UART está a 3.3 V (nivel lógico), y que TX/RX están cruzados correctamente.

5) Subir firmware:
pio run -t upload

6) Desconectar el modo programación:
– Desconecta GPIO0 de GND.
– Reinicia la placa (RST a GND momentáneo).

7) Monitor serie:
pio device monitor -b 115200
Observa el IP asignado por tu router (p. ej., 192.168.1.123).

8) Abrir la aplicación:
– En tu navegador, accede a:
– http:///
– Debes ver el visor con el streaming y sliders para PAN/TILT.

Notas:
– Si la subida falla, repite el paso 4 y 5. Algunos adaptadores requieren bajar la velocidad de upload:
pio run -t upload --upload-port COMx
o ajusta upload_speed en platformio.ini (p. ej., 460800).

Validación paso a paso

1) Alimentación y conexiones:
– La ESP32-CAM enciende y el LED rojo está estable.
– El PCA9685 recibe 3.3 V en VCC y 5 V en V+, con GND común.
– Los servos están conectados a CH0 y CH1 del PCA9685, con V+ a 5 V.

2) Arranque y logs:
– En el monitor serie, tras un reset sin GPIO0 a GND, verás:
– Mensajes de “Conectando a WiFi…” seguido de “WiFi OK. IP: x.x.x.x”.
– “Servidor HTTP/WS listo.”
– Si la cámara se inicializa: no aparece “camera_init failed”.

3) Acceso web:
– En la URL http:/// se carga la página.
– El estado pasa de “Conectando…” a “Conectado”.
– Debes ver refrescarse la imagen JPEG constantemente (≈10 fps).

4) Control pan-tilt:
– Al mover el slider de “Pan”, el servo correspondiente debe responder con un pequeño retardo (suavizado 1°/15 ms).
– Al mover el slider de “Tilt”, el segundo servo debe responder.
– El botón “Centrar” debe posicionar ambos a 90°.

5) WebSocket:
– Abre las herramientas de desarrollador del navegador (F12 → Network → WS):
– Observa que /ws está en estado abierto.
– Debe recibir frames binarios (tipo ArrayBuffer).
– Los mensajes de texto del servidor confirman cambios (“PAN->X”, “TILT->Y”).

6) Calidad de imagen:
– La imagen debe ser nítida en QVGA (320×240). Si necesitas más, puedes aumentar a VGA, pero observarás mayor latencia/uso de RAM.

7) Temperatura y consumo:
– La ESP32-CAM puede calentarse ligeramente; es normal.
– Los servos no deben zumbar en exceso en reposo. Si lo hacen, reduce el rango o calibra µs.

8) Persistencia:
– Desconecta y reconecta la alimentación. El sistema debe reanudar conexión al WiFi y servir la interfaz sin intervención adicional.

Troubleshooting

1) Error de alimentación/“Brownout detector”
– Síntomas: reinicios, mensajes “Brownout detector was triggered”.
– Causa: Caídas en 5 V cuando los servos arrancan o se bloquean mecánicamente.
– Solución:
– Alimenta los servos desde una fuente 5 V 2 A (mínimo) separada del 5 V del USB.
– Asegura GND común entre ESP32-CAM, PCA9685 y fuente 5 V.
– Añade condensadores cerca del PCA9685 y servos (p. ej., 470–1000 µF en V+ a GND).

2) “camera_init failed: 0x…” o imagen negra
– Revisa el mapeo de pines (este caso usa AI-Thinker por defecto).
– Asegúrate de no usar la ranura microSD en paralelo (hemos tomado GPIO14/15 para I2C).
– Reduce frame_size a QQVGA y/o baja jpeg_quality si hay poca RAM.
– Confirma que la cámara está bien insertada en su conector.

3) El PCA9685 no responde (“ERROR: PCA9685 no responde en 0x40”)
– Comprueba SDA=SDA y SCL=SCL (GPIO15 y GPIO14 respectivamente).
– Verifica VCC=3.3 V y GND.
– Si tu módulo PCA9685 tiene jumpers de dirección A0–A5, confirma que la dirección es 0x40.
– Usa un escáner I2C si es necesario (temporalmente) para listar direcciones.

4) El stream WebSocket se congela o es muy lento
– Baja la resolución a QQVGA o sube jpeg_quality (número mayor reduce tamaño).
– Asegúrate de tener buena señal WiFi; aproxima el router o usa otro canal menos congestionado.
– Controla el periodo de envío (frameSenderTask) para evitar saturación (p. ej., 100–150 ms).

5) Fallo al subir firmware (“A fatal error occurred: Failed to connect to ESP32”)
– Asegúrate de:
– GPIO0 a GND durante la carga.
– Pulsar RST (a GND) justo antes de “upload”.
– RX/TX están cruzados (TX del adaptador a U0R/GPIO3; RX a U0T/GPIO1).
– Baja upload_speed a 460800 o 115200 en platformio.ini si el adaptador es inestable.

6) Servos vibran, zumban o no se mueven correctamente
– Revisa SERVO_MIN_US y SERVO_MAX_US para tu modelo de servo; prueba 600–2400 µs.
– Elimina topes mecánicos: no fuerces el mecanismo más allá de su rango físico.
– Evita enviar comandos a 1000 Hz: el suavizado ya limita la cadencia.
– Asegúrate de V+ estable a 5 V y GND común.

7) La página web carga, pero no hay imagen
– Revisa que el browser no bloquea contenido mixto si accedes vía HTTPS en otra pestaña.
– Verifica en DevTools → Network → WS que /ws está abierto.
– Si hay errores CORS u otros, recarga y limpia cache (Ctrl+F5).

8) Reinicios aleatorios (WDT) al mover sliders
– Asegúrate de no bloquear callbacks WS con lógica pesada.
– El envío de frames usa buffers gestionados; si cambiaste a otra API, cuida la vida de los punteros.
– Verifica que la fuente 5 V no cae con el movimiento de los servos.

Mejoras/variantes

• Streaming MJPEG por HTTP:
• Alternativa a WebSocket binario para compatibilidad con visores MJPEG nativos de navegadores y herramientas. Aumenta la compatibilidad a costa de menos control bidireccional.
• WSS y autenticación:
• Añade TLS con un proxy inverso (Nginx/Caddy) y credenciales para restringir el acceso.
• Controles avanzados:
• Implementar trayectorias suaves (easing) y límites de velocidad/ aceleración para no castigar la mecánica.
• Resoluciones y ROI:
• Cambiar a FRAMESIZE_VGA con PSRAM y reducir fps si tu red lo permite. O implementar región de interés (ROI) si solo interesa una zona.
• Calibración interactiva:
• Permite guardar en NVS los parámetros SERVO_MIN_US/SERVO_MAX_US y ángulos máximos seguros por cada servo.
• OTA (Over-The-Air):
• Agregar ArduinoOTA o AsyncElegantOTA para actualizar sin cable una vez desplegado.
• Telemetría:
• Añade un canal WS de estado (temperatura, fps efectivo, latencia medida por marca de tiempo) para depuración avanzada.
• Node-RED / Control externo:
• Publicar un endpoint WS o HTTP con API para integrar con dashboards externos.

Checklist de verificación

• [ ] Toolchain instalado:
• [ ] PlatformIO Core 6.1.12 (pio –version)
• [ ] Plataforma espressif32@6.7.0 y Arduino-ESP32 2.0.14 (via platformio.ini)
• [ ] Drivers USB–UART instalados (CP210x/CH34x) y puerto visible en “pio device list”
• [ ] Cableado correcto:
• [ ] TX (USB–UART) → U0R (GPIO3), RX (USB–UART) ← U0T (GPIO1)
• [ ] GPIO0 a GND al programar; suelto para ejecutar
• [ ] PCA9685: VCC=3.3 V, V+=5 V, GND común
• [ ] I2C: SDA=GPIO15, SCL=GPIO14
• [ ] Servos: señal en CH0/CH1, V+ a 5 V, GND común
• [ ] Compilación OK: “pio run” sin errores
• [ ] Carga OK: “pio run -t upload” con GPIO0 a GND y reset
• [ ] Monitor serie (115200) muestra IP tras conectar al WiFi
• [ ] Página accesible en http:///
• [ ] WebSocket conectado (“Conectado” en UI)
• [ ] Imagen de la cámara visible y actualizándose
• [ ] Deslizadores mueven PAN/TILT como se espera
• [ ] Sin “Brownout” ni reinicios al mover servos
• [ ] Fuente 5 V disipando adecuadamente y sin calentamiento excesivo

Con este caso práctico has construido un sistema “ov2640-websocket-pan-tilt” completamente reproducible sobre el modelo exacto “ESP32-CAM (OV2640) + PCA9685 servo driver”, usando PlatformIO con versiones fijadas. Has cubierto desde la preparación del entorno, cableado y programación hasta la validación, resolución de problemas y posibles mejoras.

Objetivo y caso de uso

Qué construirás: Un sistema de registro de energía utilizando un ESP32-Ethernet-Kit como maestro Modbus RTU para capturar y exponer datos de consumo energético a través de Ethernet.

Para qué sirve

• Monitoreo en tiempo real de consumo energético en instalaciones industriales.
• Registro de datos históricos para análisis de eficiencia energética.
• Integración con sistemas de gestión de energía mediante protocolo Modbus.
• Control remoto de dispositivos eléctricos basado en datos de consumo.
• Generación de alertas sobre consumos anómalos a través de MQTT.

Resultado esperado

• Captura de datos de consumo en tiempo real con una frecuencia de 1 segundo.
• Latencia de respuesta del sistema inferior a 100 ms en la comunicación Modbus.
• Exposición de datos a través de Ethernet con un throughput de 500 paquetes/s.
• Registro de datos con un margen de error inferior al 1% en comparación con medidores de referencia.
• Generación de informes semanales sobre consumo energético con métricas detalladas.

Público objetivo: Ingenieros y desarrolladores de sistemas embebidos; Nivel: Avanzado

Arquitectura/flujo: Comunicación Modbus RTU sobre RS485 hacia el ESP32, procesamiento de datos y exposición a través de Ethernet.

Nivel: Avanzado

Prerrequisitos

Sistemas operativos soportados y versiones probadas

• Windows 11 Pro 23H2 (build 22631)
• Ubuntu 22.04.5 LTS (Jammy)
• macOS 14.5 (Sonoma)

En los tres entornos se validará compilación, flasheo y monitor serie.

Toolchain exacta (versiones fijas)

• PlatformIO Core (CLI): 6.1.14
• Python: 3.11.6
• Plataforma Espressif32 (PlatformIO): espressif32@6.9.0
• Framework Arduino-ESP32: framework-arduinoespressif32@3.20014.0 (equivale a Arduino-ESP32 2.0.14)
• Toolchain GCC Xtensa (ESP32): toolchain-xtensa-esp32@8.4.0+2021r2-patch5 (gcc 8.4.0)
• esptool.py (empacado por PlatformIO): tool-esptoolpy@1.40501.0 (esptool.py 4.5.1)
• OpenOCD-ESP32 (opcional para debug JTAG): 0.12.0-esp32-20230921 (no necesario para este caso)
• Librerías de proyecto:
• 4-20ma/ModbusMaster@2.0.1
• bblanchon/ArduinoJson@6.21.2

Drivers USB-UART

• El ESP32-Ethernet-Kit suele integrar un puente USB-UART Silicon Labs CP2102/CP210x.
• Alternativamente, algunos kits pueden usar CH34x.
• Instalar drivers:
• Windows: CP210x Universal Windows Driver v10.1.x o CH34x Driver v3.6.x
• macOS: CP210x VCP Driver 6.0.x (firmado) o CH34x 1.7.x
• Linux: normalmente no requiere instalación; verificar permisos udev.

Requisitos de red

• Red Ethernet con DHCP habilitado (recomendado para primeras pruebas).
• Cable RJ45 Cat5e o superior.
• Opcional: IP estática conocida para pruebas posteriores.

Verificaciones rápidas

• Comandos de comprobación (ejecutar en terminal):
• Windows (PowerShell):
  • pio –version
  • python –version
• Linux/macOS:
  • pio –version
  • python3 –version
• Versiones esperadas:
• PlatformIO Core, salida similar a: PlatformIO Core, version 6.1.14
• Python 3.11.6

Materiales

• Placa: ESP32-Ethernet-Kit + LAN8720 + MAX3485 RS485 (exactamente este modelo de dispositivo)
• ESP32-Ethernet-Kit (ESP32-WROOM-32E; PHY LAN8720 en modo RMII; reloj por GPIO17)
• Transceptor RS485: MAX3485 (módulo TTL↔RS485, 3.3 V)
• Cable micro-USB de datos (no solo carga)
• Cable Ethernet RJ45
• Fuente de alimentación 5 V (si no se alimenta por USB)
• Medidor de energía con interfaz Modbus RTU/RS485 (p. ej., Eastron SDM120/SDM230/SDM630 o similar)
• Resistencias de terminación RS485 de 120 Ω (en ambos extremos si el bus lo requiere)
• Cables dupont macho-hembra para conexión del MAX3485 a GPIOs del ESP32
• PC con uno de los OS soportados y PlatformIO instalado

Notas:
– Mantendremos coherencia total con el modelo “ESP32-Ethernet-Kit + LAN8720 + MAX3485 RS485” en conexiones, código y comandos.
– El objetivo del proyecto es “modbus-energy-logger-ethernet”: leer parámetros energéticos vía Modbus RTU/RS485 y publicarlos por Ethernet (HTTP/JSON), con trazas y validación.

Preparación y conexión

Reglas udev (Linux) y puertos serie

• En Linux, añadir reglas udev si no existen:

# Copiar reglas de PlatformIO
wget https://raw.githubusercontent.com/platformio/platformio-core/develop/scripts/99-platformio-udev.rules -O /tmp/99-platformio-udev.rules
sudo cp /tmp/99-platformio-udev.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

• Desconectar y reconectar el ESP32-Ethernet-Kit por USB.
• Verificar puerto (ej.: /dev/ttyUSB0 o /dev/tty.SLAB_USBtoUART en macOS, COMx en Windows).

Mapeo de pines y conexión física

Tabla de pines relevantes en ESP32-Ethernet-Kit (LAN8720 y RS485 con MAX3485):

Conexiones RS485 (MAX3485 ↔ ESP32-Ethernet-Kit):
– MAX3485 DI → ESP32 GPIO4 (TX2)
– MAX3485 RO → ESP32 GPIO5 (RX2)
– MAX3485 DE y RE unidos → ESP32 GPIO15
– MAX3485 VCC → 3.3 V del ESP32-Ethernet-Kit
– MAX3485 GND → GND del ESP32-Ethernet-Kit
– RS485 A ↔ A (D+) del medidor
– RS485 B ↔ B (D−) del medidor
– Terminar bus con 120 Ω en los extremos si la topología lo requiere.

Conexión Ethernet:
– Conectar cable RJ45 al puerto del LAN8720 del ESP32-Ethernet-Kit y al switch/router con DHCP.

Atención a GPIOs reservados por RMII:
– No reusar 17, 18, 19, 21, 22, 23, 25, 26, 27 para otros fines.
– Evitar manipular GPIO0/2/12/15 en el arranque (son strap); en nuestro caso usaremos GPIO15 para DE/RE, manteniéndolo en LOW por defecto durante el boot.

Código completo

A continuación se muestra un proyecto funcional con PlatformIO usando Arduino-ESP32 2.0.14 y las librerías indicadas. Implementa:
– Inicialización Ethernet (LAN8720) con DHCP.
– Maestro Modbus RTU por RS485 (MAX3485) para leer parámetros típicos de un medidor (direcciones compatibles con SDM120/230/630 y similares).
– Servidor HTTP (WebServer) con endpoints:
– / (tabla HTML)
– /json (salida JSON)
– /metrics (formato estilo Prometheus, opcional)
– Bucle de sondeo periódico y cacheo de últimas lecturas.

platformio.ini

[env:esp32-ethernet-kit]
platform = espressif32@6.9.0
board = esp32-ethernet-kit
framework = arduino

platform_packages =
    platformio/tool-esptoolpy @ 1.40501.0
    platformio/toolchain-xtensa-esp32 @ 8.4.0+2021r2-patch5
    platformio/framework-arduinoespressif32 @ 3.20014.0

monitor_speed = 115200

lib_deps =
    4-20ma/ModbusMaster @ 2.0.1
    bblanchon/ArduinoJson @ 6.21.2

src/main.cpp

#include <Arduino.h>
#include <ETH.h>
#include <WebServer.h>
#include <ModbusMaster.h>
#include <ArduinoJson.h>

// -------------------- Configuración de hardware --------------------
static constexpr int PIN_RS485_TX = 4;     // UART2 TX -> MAX3485 DI
static constexpr int PIN_RS485_RX = 5;     // UART2 RX -> MAX3485 RO
static constexpr int PIN_RS485_REDE = 15;  // RS485 DE/RE (unidos) -> control TX/RX

// LAN8720 (ESP32-Ethernet-Kit) - RMII
static constexpr int ETH_PHY_ADDR = 0;               // Dirección por defecto del LAN8720
static constexpr int ETH_POWER_PIN = -1;             // Control de energía no usado (interno)
static constexpr int ETH_MDC_PIN = 23;               // MDC
static constexpr int ETH_MDIO_PIN = 18;              // MDIO
static constexpr eth_phy_type_t ETH_PHY_TYPE = ETH_PHY_LAN8720;
static constexpr eth_clock_mode_t ETH_CLK_MODE = ETH_CLOCK_GPIO17_OUT;

// -------------------- Configuración Modbus y medidor --------------------
// Parámetros de bus Modbus RTU típicos (ajustar si su medidor usa otros):
static uint8_t MODBUS_SLAVE_ID = 1;     // Dirección del medidor en el bus
static uint32_t MODBUS_BAUD = 9600;     // Baud rate
static uint16_t MODBUS_TIMEOUT_MS = 300; // Timeout por transacción

// Registros de ejemplo (Eastron SDM* Input Registers: floats 32-bit, 2 registros cada uno)
static constexpr uint16_t REG_VOLTAGE = 0x0000;      // V (2 regs)
static constexpr uint16_t REG_CURRENT = 0x0006;      // A (2 regs)
static constexpr uint16_t REG_ACTIVE_POWER = 0x000C; // W (2 regs)
static constexpr uint16_t REG_POWER_FACTOR = 0x001E; // PF (2 regs)
static constexpr uint16_t REG_FREQUENCY = 0x0046;    // Hz (2 regs)
static constexpr uint16_t REG_IMPORT_ACTIVE_ENERGY = 0x0048; // kWh (2 regs)

// Endianness común en muchos medidores SDM: word swap (lo-hi o hi-lo).
// Ajuste a true si el medidor requiere intercambiar palabras.
static bool FLOAT_WORD_SWAP = true;

// Periodo de sondeo
static uint32_t POLL_INTERVAL_MS = 1000;

// -------------------- Objetos globales --------------------
HardwareSerial RS485(2);        // UART2
ModbusMaster modbus;            // Maestro Modbus RTU
WebServer server(80);

// Variables de estado Ethernet
volatile bool eth_connected = false;
IPAddress eth_ip;

// Cache de lecturas
struct EnergyData {
  float voltage = NAN;
  float current = NAN;
  float active_power = NAN;
  float power_factor = NAN;
  float frequency = NAN;
  float import_active_energy = NAN;
  uint64_t last_update_ms = 0;
  uint32_t ok_count = 0;
  uint32_t err_count = 0;
} data;

// -------------------- RS485 control --------------------
void preTransmission() {
  digitalWrite(PIN_RS485_REDE, HIGH); // Habilitar TX
  delayMicroseconds(10);
}
void postTransmission() {
  delayMicroseconds(10);
  digitalWrite(PIN_RS485_REDE, LOW); // Volver a RX
}

// -------------------- Utilidades Modbus --------------------
bool readFloatInputRegister(uint16_t reg, float &out) {
  modbus.setSlave(MODBUS_SLAVE_ID);
  uint8_t result = modbus.readInputRegisters(reg, 2);
  if (result == modbus.ku8MBSuccess) {
    uint16_t w0 = modbus.getResponseBuffer(0);
    uint16_t w1 = modbus.getResponseBuffer(1);
    uint32_t raw = 0;
    if (FLOAT_WORD_SWAP) {
      raw = ((uint32_t)w1 << 16) | w0;
    } else {
      raw = ((uint32_t)w0 << 16) | w1;
    }
    float f;
    memcpy(&f, &raw, sizeof(f));
    out = f;
    return true;
  }
  return false;
}

// -------------------- HTTP Handlers --------------------
String htmlEscape(const String &s) {
  String r;
  r.reserve(s.length());
  for (char c : s) {
    switch (c) {
      case '&': r += "&amp;"; break;
      case '<': r += "&lt;"; break;
      case '>': r += "&gt;"; break;
      case '"': r += "&quot;"; break;
      default: r += c;
    }
  }
  return r;
}

void handleRoot() {
  String ip = eth_connected ? eth_ip.toString() : String("desconectado");
  String page;
  page.reserve(2048);
  page += "<!doctype html><html><head><meta charset='utf-8'><title>modbus-energy-logger-ethernet</title>";
  page += "<meta name='viewport' content='width=device-width,initial-scale=1'>";
  page += "<style>body{font-family:system-ui,Arial;margin:20px}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:6px 10px}</style>";
  page += "</head><body>";
  page += "<h1>modbus-energy-logger-ethernet</h1>";
  page += "<p>IP (ETH): " + htmlEscape(ip) + "</p>";
  page += "<table><tr><th>Métrica</th><th>Valor</th><th>Unidad</th></tr>";
  page += "<tr><td>Tensión</td><td>" + String(data.voltage, 3) + "</td><td>V</td></tr>";
  page += "<tr><td>Corriente</td><td>" + String(data.current, 3) + "</td><td>A</td></tr>";
  page += "<tr><td>Potencia Activa</td><td>" + String(data.active_power, 3) + "</td><td>W</td></tr>";
  page += "<tr><td>Factor de Potencia</td><td>" + String(data.power_factor, 3) + "</td><td>pf</td></tr>";
  page += "<tr><td>Frecuencia</td><td>" + String(data.frequency, 3) + "</td><td>Hz</td></tr>";
  page += "<tr><td>Energía Importada</td><td>" + String(data.import_active_energy, 3) + "</td><td>kWh</td></tr>";
  page += "</table>";
  page += "<p>Última actualización: " + String(data.last_update_ms) + " ms desde boot</p>";
  page += "<p>OK: " + String(data.ok_count) + " | ERR: " + String(data.err_count) + "</p>";
  page += "<p><a href='/json'>/json</a> | <a href='/metrics'>/metrics</a></p>";
  page += "</body></html>";
  server.send(200, "text/html; charset=utf-8", page);
}

void handleJSON() {
  StaticJsonDocument<512> doc;
  doc["ip"] = eth_connected ? eth_ip.toString() : "desconectado";
  doc["uptime_ms"] = millis();
  doc["ok_count"] = data.ok_count;
  doc["err_count"] = data.err_count;

  JsonObject m = doc.createNestedObject("metrics");
  m["voltage_V"] = data.voltage;
  m["current_A"] = data.current;
  m["active_power_W"] = data.active_power;
  m["power_factor"] = data.power_factor;
  m["frequency_Hz"] = data.frequency;
  m["import_active_energy_kWh"] = data.import_active_energy;
  m["last_update_ms"] = data.last_update_ms;

  String out;
  serializeJsonPretty(doc, out);
  server.send(200, "application/json; charset=utf-8", out);
}

void handleMetrics() {
  String txt;
  txt.reserve(512);
  txt += "# HELP voltage_V Tensión de línea (V)\n# TYPE voltage_V gauge\n";
  txt += "voltage_V " + String(isnan(data.voltage)?0:data.voltage, 6) + "\n";
  txt += "# HELP current_A Corriente (A)\n# TYPE current_A gauge\n";
  txt += "current_A " + String(isnan(data.current)?0:data.current, 6) + "\n";
  txt += "# HELP active_power_W Potencia activa (W)\n# TYPE active_power_W gauge\n";
  txt += "active_power_W " + String(isnan(data.active_power)?0:data.active_power, 6) + "\n";
  txt += "# HELP power_factor Factor de potencia\n# TYPE power_factor gauge\n";
  txt += "power_factor " + String(isnan(data.power_factor)?0:data.power_factor, 6) + "\n";
  txt += "# HELP frequency_Hz Frecuencia (Hz)\n# TYPE frequency_Hz gauge\n";
  txt += "frequency_Hz " + String(isnan(data.frequency)?0:data.frequency, 6) + "\n";
  txt += "# HELP import_active_energy_kWh Energía importada total (kWh)\n# TYPE import_active_energy_kWh counter\n";
  txt += "import_active_energy_kWh " + String(isnan(data.import_active_energy)?0:data.import_active_energy, 6) + "\n";
  server.send(200, "text/plain; charset=utf-8", txt);
}

void handleNotFound() {
  server.send(404, "text/plain; charset=utf-8", "Not found");
}

// -------------------- Ethernet Events --------------------
void WiFiEvent(WiFiEvent_t event) {
  switch (event) {
    case ARDUINO_EVENT_ETH_START:
      ETH.setHostname("modbus-logger");
      break;
    case ARDUINO_EVENT_ETH_CONNECTED:
      break;
    case ARDUINO_EVENT_ETH_GOT_IP:
      eth_connected = true;
      eth_ip = ETH.localIP();
      break;
    case ARDUINO_EVENT_ETH_DISCONNECTED:
      eth_connected = false;
      break;
    case ARDUINO_EVENT_ETH_STOP:
      eth_connected = false;
      break;
    default:
      break;
  }
}

// -------------------- Setup --------------------
void setup() {
  pinMode(PIN_RS485_REDE, OUTPUT);
  digitalWrite(PIN_RS485_REDE, LOW); // RX por defecto
  Serial.begin(115200);
  delay(200);

  Serial.println();
  Serial.println("=== modbus-energy-logger-ethernet (ESP32-Ethernet-Kit + LAN8720 + MAX3485) ===");

  // UART2 para RS485
  RS485.begin(MODBUS_BAUD, SERIAL_8N1, PIN_RS485_RX, PIN_RS485_TX);

  // ModbusMaster: enlazar a Serial2 y configurar callbacks DE/RE
  modbus.begin(MODBUS_BAUD, RS485);
  modbus.preTransmission(preTransmission);
  modbus.postTransmission(postTransmission);
  modbus.setTimeout(MODBUS_TIMEOUT_MS);

  // Ethernet (LAN8720)
  WiFi.onEvent(WiFiEvent);
  if (!ETH.begin(ETH_PHY_ADDR, ETH_POWER_PIN, ETH_MDC_PIN, ETH_MDIO_PIN, ETH_PHY_TYPE, ETH_CLK_MODE)) {
    Serial.println("[ETH] Fallo al iniciar ETH");
  } else {
    Serial.println("[ETH] Iniciando Ethernet (DHCP)...");
  }

  // Servidor HTTP
  server.on("/", handleRoot);
  server.on("/json", handleJSON);
  server.on("/metrics", handleMetrics);
  server.onNotFound(handleNotFound);
  server.begin();
  Serial.println("[HTTP] Servidor iniciado en :80");
}

// -------------------- Bucle principal --------------------
uint32_t lastPoll = 0;

void loop() {
  server.handleClient();

  uint32_t now = millis();
  if (now - lastPoll >= POLL_INTERVAL_MS) {
    lastPoll = now;

    // Secuencia de lecturas Modbus (Input Registers como float 32b)
    float v;
    if (readFloatInputRegister(REG_VOLTAGE, v)) {
      data.voltage = v;
      data.ok_count++;
    } else {
      data.err_count++;
    }

    float i;
    if (readFloatInputRegister(REG_CURRENT, i)) {
      data.current = i;
      data.ok_count++;
    } else {
      data.err_count++;
    }

    float p;
    if (readFloatInputRegister(REG_ACTIVE_POWER, p)) {
      data.active_power = p;
      data.ok_count++;
    } else {
      data.err_count++;
    }

    float pf;
    if (readFloatInputRegister(REG_POWER_FACTOR, pf)) {
      data.power_factor = pf;
      data.ok_count++;
    } else {
      data.err_count++;
    }

    float f;
    if (readFloatInputRegister(REG_FREQUENCY, f)) {
      data.frequency = f;
      data.ok_count++;
    } else {
      data.err_count++;
    }

    float eimp;
    if (readFloatInputRegister(REG_IMPORT_ACTIVE_ENERGY, eimp)) {
      data.import_active_energy = eimp;
      data.ok_count++;
    } else {
      data.err_count++;
    }

    data.last_update_ms = now;

    // Trazas serie
    Serial.printf("[POLL] V=%.3f V, I=%.3f A, P=%.3f W, PF=%.3f, f=%.3f Hz, Eimp=%.3f kWh | OK=%lu ERR=%lu\n",
      data.voltage, data.current, data.active_power, data.power_factor, data.frequency, data.import_active_energy,
      (unsigned long)data.ok_count, (unsigned long)data.err_count);
  }
}

Breve explicación de partes clave:
– Inicialización ETH con LAN8720 (ETH.begin con parámetros: PHY_ADDR=0, pines MDC=23/MDIO=18, PHY=LAN8720, clock por GPIO17). Se usa DHCP. ETH.setHostname configura el hostname anunciado.
– Modbus RTU maestro sobre UART2 (GPIO4/5) y control half-duplex por GPIO15 (DE/RE). ModbusMaster usa callbacks preTransmission/postTransmission para manejar el transceptor MAX3485.
– Lecturas de registros de entrada (Input Registers) de 32 bits flotantes: se leen 2 registros consecutivos y se reempaquetan a float, con opción de swap de palabras (FLOAT_WORD_SWAP).
– WebServer nativo expone HTML, JSON y métricas de texto para facilitar integración.

Nota sobre direcciones de registros: los offsets son los usados por muchas familias SDM*. Ajuste si su medidor difiere.

Compilación, flasheo y ejecución

Preparar el proyecto

1) Crear directorio de trabajo y plantillas:

mkdir modbus-energy-logger-ethernet
cd modbus-energy-logger-ethernet
pio project init --board esp32-ethernet-kit

2) Sustituir el contenido de platformio.ini por el bloque mostrado en este documento.

3) Crear carpeta src y archivo:
– src/main.cpp con el código provisto.

Construcción

• Instalar dependencias y compilar:

pio pkg install
pio run

Flasheo (upload)

• Conectar el ESP32-Ethernet-Kit por micro-USB.
• Identificar el puerto (ej.: COM5 en Windows, /dev/ttyUSB0 en Linux, /dev/tty.SLAB_USBtoUART en macOS).
• Subir firmware:

# PlatformIO detecta el puerto automáticamente en la mayoría de casos
pio run -t upload
# Si necesitas fijar el puerto:
pio run -t upload --upload-port COM5
# o
pio run -t upload --upload-port /dev/ttyUSB0

Monitor serie

• Abrir monitor a 115200 baudios:

pio device monitor -b 115200

• Deberías ver mensajes tipo:
• [ETH] Iniciando Ethernet (DHCP)…
• evento ETH_GOT_IP con la IP asignada
• [HTTP] Servidor iniciado en :80
• [POLL] con valores de V, I, P, etc.

Pruebas rápidas de red

• Descubrir la IP si no la ves en serie (desde tu router/DHCP) o usa ping:
• Windows: ping
• Linux/macOS: ping -c 4
• Obtener JSON:

curl http://<IP_DEL_ESP32>/json

• Ver HTML:
• Navegador: http:///

Opcional: IP estática

Si tu red no usa DHCP, en setup() después de ETH.begin() puedes fijar IP:

// Sustituye por tu red
IPAddress ip(192,168,1,50);
IPAddress gw(192,168,1,1);
IPAddress mask(255,255,255,0);
IPAddress dns1(8,8,8,8), dns2(1,1,1,1);
ETH.config(ip, gw, mask, dns1, dns2);

Validación paso a paso

1) Verificación de arranque:
– En el monitor serie, confirmar:
– “Iniciando Ethernet (DHCP)…”
– Evento ETH_GOT_IP con una dirección válida (por ejemplo 192.168.1.x).
– “Servidor iniciado en :80”.

2) Link Ethernet:
– LED del puerto Ethernet activo (link/actividad).
– Desde tu PC en la misma red, ping a la IP del ESP32.
– Respuesta < 2 ms en red local típica.

3) Acceso HTTP:
– Abrir http:/// en el navegador y ver una tabla con las métricas energéticas.
– Actualizar manualmente para observar cambios (cada ~1 s se realiza un sondeo).

4) JSON y métricas:
– Ejecutar:
– curl http:///json
– curl http:///metrics
– Confirmar formato y que los valores son coherentes.

5) Validación Modbus:
– Observar en el terminal: líneas [POLL] con lecturas numéricas y contadores OK/ERR.
– Si tienes display en el medidor, comparar:
– Tensión (V)
– Corriente (A)
– Potencia activa (W)
– Frecuencia (Hz)
– PF
– Energía importada (kWh)
– Tolerancias: pequeñas diferencias por muestreo y resolución del medidor.

6) Integridad del bus RS485:
– Si el MAX3485 tiene LEDs, ver actividad en TX/RX durante los sondeos.
– A/B cableados correctamente: valores estables, ERR no aumenta continuamente.

7) Estabilidad:
– Dejar funcionando 10–15 minutos.
– OK_count sube con cada lectura; ERR_count se mantiene cerca de 0.
– Página HTML/JSON responden consistentemente.

Troubleshooting

1) No se obtiene IP (ETH_GOT_IP nunca aparece)
– Causas:
– Cable RJ45 defectuoso o puerto de switch sin enlace.
– DHCP deshabilitado o saturado.
– Pines RMII mal configurados en el código (no usar otros valores en ETH.begin).
– Soluciones:
– Cambiar cable/puerto.
– Probar con IP estática usando ETH.config().
– Verificar que ETH_MDC=23, ETH_MDIO=18, ETH_CLK_MODE=ETH_CLOCK_GPIO17_OUT, PHY_ADDR=0.

2) ETH arranca pero no hay tráfico
– Causas:
– Conmutador en VLAN aislada.
– Duplicación de IP (si IP estática).
– Soluciones:
– Validar segmentación de red.
– Cambiar IP estática o volver a DHCP.

3) Lecturas Modbus fallan (ERR_count sube rápidamente)
– Causas:
– Inversión de líneas RS485 A/B.
– Falta de terminación 120 Ω en extremos.
– No hay masa común entre sistemas.
– Baud/paridad distintos a los del medidor.
– Soluciones:
– Invertir A/B y repetir.
– Añadir/retirar terminación según topología.
– Asegurar GND común.
– Ajustar MODBUS_BAUD y formato (SERIAL_8N1; si tu medidor usa 8E1 o 8O1, cambia en RS485.begin()).

4) Valores incoherentes (p. ej., 65k V o NaN)
– Causa: Endianness de las palabras Modbus distinta.
– Solución: Cambiar FLOAT_WORD_SWAP (true/false) y volver a flashear.

5) El ESP32 no entra en modo programación (upload falla)
– Causas:
– Drivers CP210x/CH34x no instalados (Windows/macOS).
– Cable USB solo carga.
– Conflicto de puerto.
– Soluciones:
– Reinstalar drivers.
– Usar cable de datos y otro puerto USB.
– Especificar –upload-port correctamente.

6) Parpadeo de errores al iniciar (bootloop o mensajes “brownout”)
– Causas:
– Alimentación insuficiente por USB/puerto.
– Cortocircuito en conexiones al MAX3485.
– Soluciones:
– Alimentar con un puerto USB de 1 A mínimo o fuente externa 5 V.
– Revisar cableado y soldaduras.

7) Bloqueos intermitentes en Modbus con cable largo
– Causas:
– Ruido EMI, impedancia de línea, topología en estrella.
– Soluciones:
– Topología en bus, terminaciones en extremos, resistencias de polarización (bias) en A/B si el maestro no las provee, usar cable trenzado y blindado.

8) GPIO15 causa problemas al boot
– Causa:
– GPIO strap sensible; forzar niveles al arranque puede influir.
– Solución:
– Mantener GPIO15 en LOW por defecto (como hace el código). Evitar hardware externo que lo eleve en boot.

Mejoras/variantes

• Push a InfluxDB (v2) o VictoriaMetrics:
• Enviar con HTTP cada N segundos, formateando line protocol:
  • Ejemplo de línea: energy,host=esp32 voltage=230.1,current=1.23,power=283.0 1730800000000

• Añadir una tarea que haga POST a http://influxdb:8086/api/v2/write?org=…&bucket=…&precision=ns con el token en cabecera.

• MQTT sobre Ethernet:

• Publicar en tópicos: telemetry/voltage, telemetry/current, etc., usando una librería MQTT (p. ej., PubSubClient) con ETH.

• NTP y sellado temporal:

• Sincronizar hora vía NTP (configTime) para registrar timestamps reales y mostrarlos en /json.

• Configuración en runtime:

• Exponer UI para cambiar MODBUS_SLAVE_ID, baud, intervalos y endianness desde el navegador y guardar en NVS.

• Registro persistente:

• Grabar CSV en SPIFFS/LittleFS con rotación diaria. Exponer descarga por HTTP.

• Multi-esclavo:

• Sondear varios medidores en el mismo bus ajustando MODBUS_SLAVE_ID para cada ciclo (añadir lista de esclavos).

• Seguridad básica:

• Autenticación HTTP simple para /json y /metrics si se expone fuera de la LAN.

• IP estática por fallback:

• Intentar DHCP y, si falla, aplicar una IP estática de respaldo.

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.14 y Python 3.11.6 (o compatibles) y verifiqué sus versiones.
• [ ] Mi sistema reconoce el USB-UART (CP210x/CH34x) y sé cuál es el puerto.
• [ ] He creado el proyecto con board = esp32-ethernet-kit y usé el platformio.ini provisto con versiones fijas.
• [ ] He cableado el MAX3485 a los pines GPIO4 (TX), GPIO5 (RX) y GPIO15 (DE/RE), con 3V3 y GND.
• [ ] He conectado RS485 A↔A y B↔B entre MAX3485 y medidor, con terminación 120 Ω en los extremos si procede.
• [ ] El cable Ethernet RJ45 está conectado, y el switch/router ofrece DHCP o he configurado IP estática.
• [ ] El firmware compila, se flashea sin errores y el monitor serie muestra ETH_GOT_IP con una IP válida.
• [ ] Puedo abrir http:/// y ver la tabla con las métricas, y /json y /metrics responden correctamente.
• [ ] Los valores leídos son coherentes con el display del medidor, con errores de lectura mínimos (ERR_count ~ 0).
• [ ] Si hay incoherencias en floats, ajusté FLOAT_WORD_SWAP y confirmé la corrección.

Con todo lo anterior, has implementado un “modbus-energy-logger-ethernet” robusto y reproducible usando exactamente el “ESP32-Ethernet-Kit + LAN8720 + MAX3485 RS485” y una toolchain con versiones fijas sobre PlatformIO.

Objetivo y caso de uso

Qué construirás: Un espectrograma de audio en tiempo real utilizando un ESP32 con el micrófono INMP441 y visualización en LEDs WS2812B mediante WebSocket.

Para qué sirve

• Visualización de audio en tiempo real para análisis de frecuencias en entornos musicales.
• Monitoreo de niveles de sonido en aplicaciones de domótica.
• Interacción visual en instalaciones artísticas que responden a audio ambiental.
• Desarrollo de herramientas educativas para enseñar sobre espectros de audio.

Resultado esperado

• Transmisión de datos de audio en tiempo real a través de WebSocket con latencias menores a 50 ms.
• Visualización fluida en LEDs WS2812B con actualizaciones de 30 FPS.
• Medición de frecuencias con precisión de +/- 1 Hz en el rango de 20 Hz a 20 kHz.
• Consumo de memoria RAM del ESP32 por debajo de 80 KB durante la operación.

Público objetivo: Entusiastas avanzados; Nivel: Avanzado

Arquitectura/flujo: Captura de audio con INMP441 → Procesamiento en ESP32 → Transmisión WebSocket → Visualización en WS2812B.

Nivel: Avanzado

Prerrequisitos

Sistema operativo y herramientas

• PC con uno de los siguientes SO (probado):
• Windows 11 23H2 (64-bit)
• Ubuntu 22.04 LTS (x86_64)
• macOS 14 Sonoma (ARM64/Intel)
• Python 3.11.9 instalado y en PATH
• Git 2.46.x (para que PlatformIO pueda resolver dependencias de paquetes opcionales)

Toolchain exacta empleada

• PlatformIO Core (CLI): 6.1.15
• Plataforma ESP32 en PlatformIO: espressif32 @ 6.4.0
• Framework Arduino-ESP32: 3.0.2 (forzado vía platform_packages)
• Compilador Xtensa provisto por platform-espressif32 @ 6.4.0 (GCC 8.4.0 toolchain incluida en la plataforma)
• Librerías Arduino (versiones exactas):
• arduinoFFT @ 2.0.1
• NeoPixelBus by Makuna @ 2.7.6
• arduinoWebSockets (links2004/WebSockets) @ 2.4.1
• WiFi y WebServer incluidas en Arduino-ESP32 3.0.2

Drivers y puertos

• Placa ESP32-DevKitC V4 suele utilizar USB-UART Silicon Labs CP210x
• Windows: instalar “CP210x Universal Windows Driver” v11.3.0 o superior
• macOS/Linux: normalmente no requiere instalación (driver nativo)
• Identificar el puerto serie:
• Windows: COMx (Administrador de dispositivos → Puertos)
• macOS: /dev/tty.SLAB_USBtoUART
• Linux: /dev/ttyUSB0 o /dev/tty.SLAB_USBtoUART

Instalación de PlatformIO CLI (opción reproducible sin IDE)

• Con pipx (recomendado):
• pipx install «platformio==6.1.15»
• Verificar:
• pio –version
• pio system info

Nota: también puede usar Visual Studio Code + extensión PlatformIO IDE, pero los comandos CLI que se listan abajo son canónicos.

Materiales

• ESP32-DevKitC V4 + INMP441 I2S mic + WS2812B LED ring (modelo exacto)
• Cable micro-USB de datos (no solo carga)
• INMP441 (módulo típico con pines: VDD, GND, SCK, WS, SD, L/R)
• Anillo WS2812B de 24 LEDs (si tienes otro número, actualiza LED_COUNT en el código)
• Fuente 5 V para el anillo (puede ser el 5 V del USB si el consumo lo permite; 24 LEDs máx. ~1.4 A a blanco a plena potencia)
• Condensador 1000 µF/6.3 V entre 5V y GND del anillo (recomendado)
• Resistencia serie 330–470 Ω en la línea de datos del WS2812B (recomendada)
• Opcional pero recomendado: conversor de nivel 3.3 V → 5 V (74AHCT125 o similar) para la señal de datos del WS2812B
• Protoboard y cables Dupont macho–hembra

Preparación y conexión

Consideraciones antes de cablear

• INMP441 se alimenta a 3.3 V. No conectarlo a 5 V.
• El WS2812B se alimenta a 5 V. GND del anillo debe estar unido a GND del ESP32.
• Señal de datos WS2812B idealmente a 5 V. En muchos anillos funciona con 3.3 V si la alimentación está cerca de 5 V y los cables son cortos, pero para robustez use un elevador de nivel.
• Evitar pines de arranque conflictivos en el ESP32: GPIO0, GPIO2, GPIO12, GPIO15. No usar estos para señales críticas si no se entiende su efecto en el booteo.

Mapeo de pines propuesto (coherente con el código)

Tabla 1. Conexiones entre ESP32-DevKitC V4, INMP441 y anillo WS2812B

Notas:
– Coloca el condensador de 1000 µF entre 5 V y GND del anillo (cerca del anillo).
– Si usas level shifter: GPIO18 → 74AHCT125 → DIN del anillo.

Código completo

El proyecto realiza:
1) Captura I2S a 16 kHz con el INMP441 (mono).
2) Ventaneo Hann y FFT de 1024 puntos con arduinoFFT.
3) Cálculo de magnitud logarítmica y reducción a bandas.
4) Iluminación del anillo WS2812B mapeando bandas a LEDs en tiempo real.
5) Servidor HTTP (página con canvas) + WebSocket que transmite columnas del espectrograma (arreglo de 64 intensidades 0–255).

Fichero de configuración de PlatformIO

Cree un directorio de proyecto vacío y añada este platformio.ini:

; platformio.ini
[env:esp32dev]
platform = espressif32 @ 6.4.0
platform_packages =
  framework-arduinoespressif32 @ 3.0.2
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_speed = 921600
build_flags =
  -DCORE_DEBUG_LEVEL=0
  -DLED_COUNT=24
  -DLED_PIN=18
  -DI2S_BCLK=26
  -DI2S_LRCLK=25
  -DI2S_DATA=33
  -DSAMPLE_RATE=16000
  -DFFT_N=1024
lib_deps =
  arduinoFFT@2.0.1
  Makuna/NeoPixelBus@2.7.6
  links2004/WebSockets@2.4.1

Código principal (src/main.cpp)

Cree src/main.cpp con este contenido:

#include <Arduino.h>
#include <WiFi.h>
#include <WebServer.h>
#include <WebSocketsServer.h>
#include <driver/i2s.h>
#include <arduinoFFT.h>
#include <NeoPixelBus.h>

// Config WiFi
// Reemplaza por tu red o configura AP si lo prefieres
const char* WIFI_SSID = "ESP32-SPECTRO";
const char* WIFI_PASS = "esp32spectro123";

// Parámetros compilados desde platformio.ini
#ifndef LED_COUNT
#define LED_COUNT 24
#endif
#ifndef LED_PIN
#define LED_PIN 18
#endif
#ifndef I2S_BCLK
#define I2S_BCLK 26
#endif
#ifndef I2S_LRCLK
#define I2S_LRCLK 25
#endif
#ifndef I2S_DATA
#define I2S_DATA 33
#endif
#ifndef SAMPLE_RATE
#define SAMPLE_RATE 16000
#endif
#ifndef FFT_N
#define FFT_N 1024
#endif

// NeoPixelBus con RMT (mejor para ESP32)
NeoPixelBus<NeoGrbFeature, NeoEsp32Rmt0Ws2812xMethod> strip(LED_COUNT, LED_PIN);

// Web
WebServer server(80);
WebSocketsServer wsServer(81);

// FFT
arduinoFFT FFT;
static double vReal[FFT_N];
static double vImag[FFT_N];

// Buffer I2S
static int32_t i2s_raw[FFT_N];

// Control de tiempo
unsigned long lastProcessMs = 0;
const uint16_t FRAME_INTERVAL_MS = 33; // ~30 FPS

// Espectro para WS y LEDs
const uint16_t WS_BINS = 64;  // columnas que se envían por WebSocket
uint8_t spectrum[WS_BINS];

// Ventana Hann precalculada
static double hann[FFT_N];

const char INDEX_HTML[] PROGMEM = R"HTML(
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>ESP32 Spectrogram</title>
<style>
  body { background:#111; color:#eee; font-family:system-ui, sans-serif; margin:0; }
  header { padding:8px 12px; background:#222; position:sticky; top:0; }
  #status { font-size:12px; opacity:.8; }
  canvas { display:block; width:100vw; height:60vh; background:#000; image-rendering:pixelated; }
  #controls { padding:8px 12px; }
  .legend { font-size:12px; color:#aaa; }
</style>
</head>
<body>
  <header>
    <div>ESP32 I2S Spectrogram via WebSocket</div>
    <div id="status">Conectando...</div>
  </header>
  <canvas id="cv" width="512" height="256"></canvas>
  <div id="controls">
    <div class="legend">Cada nueva columna desplaza el espectrograma hacia la izquierda. Intensidad 0–255.</div>
  </div>
<script>
(function() {
  const st = document.getElementById('status');
  const cv = document.getElementById('cv');
  const ctx = cv.getContext('2d');
  const colBins = 64; // Debe coincidir con firmware
  const height = cv.height;

  function drawColumn(arr) {
    // Desplaza la imagen a la izquierda 1 píxel
    const img = ctx.getImageData(1, 0, cv.width-1, cv.height);
    ctx.putImageData(img, 0, 0);

    // Dibuja nueva columna al extremo derecho
    for (let y = 0; y < height; y++) {
      // Mapear y (0 arriba) a índice de frecuencia (bajo abajo)
      const idx = Math.floor((1 - y/height) * (arr.length - 1));
      const v = arr[idx]; // 0-255
      // Paleta: mapa a tono entre azul (bajo) y rojo (alto)
      const r = Math.min(255, Math.max(0, (v - 64) * 3));
      const g = Math.min(255, Math.max(0, v * 2 - 128));
      const b = Math.min(255, 255 - v);
      ctx.fillStyle = `rgb(${r},${g},${b})`;
      ctx.fillRect(cv.width - 1, y, 1, 1);
    }
  }

  function connect() {
    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
    const ws = new WebSocket(`${proto}://${location.hostname}:81/`);
    ws.binaryType = 'arraybuffer';

    ws.onopen = () => st.textContent = 'WebSocket conectado';
    ws.onclose = () => { st.textContent = 'Desconectado. Reintentando...'; setTimeout(connect, 1000); };
    ws.onerror = () => st.textContent = 'Error de WebSocket';
    ws.onmessage = (ev) => {
      try {
        // Esperamos un ArrayBuffer con 64 bytes
        if (ev.data instanceof ArrayBuffer) {
          const arr = new Uint8Array(ev.data);
          if (arr.length === colBins) drawColumn(arr);
        } else {
          // Fallback: si llega JSON
          const o = JSON.parse(ev.data);
          if (o && o.bins) drawColumn(Uint8Array.from(o.bins));
        }
      } catch (e) {
        // Silencioso
      }
    }
  }
  connect();
})();
</script>
</body>
</html>
)HTML";

void i2s_init()
{
  // Configuración I2S para INMP441
  i2s_config_t i2s_config = {
    .mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_RX),
    .sample_rate = SAMPLE_RATE,
    .bits_per_sample = I2S_BITS_PER_SAMPLE_32BIT,
    .channel_format = I2S_CHANNEL_FMT_ONLY_LEFT,
    .communication_format = I2S_COMM_FORMAT_I2S,
    .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
    .dma_buf_count = 8,
    .dma_buf_len = 512,
    .use_apll = false,
    .tx_desc_auto_clear = false,
    .fixed_mclk = 0
  };
  i2s_pin_config_t pin_config = {
    .bck_io_num = I2S_BCLK,
    .ws_io_num = I2S_LRCLK,
    .data_out_num = I2S_PIN_NO_CHANGE,
    .data_in_num = I2S_DATA
  };
  ESP_ERROR_CHECK(i2s_driver_install(I2S_NUM_0, &i2s_config, 0, NULL));
  ESP_ERROR_CHECK(i2s_set_pin(I2S_NUM_0, &pin_config));
  // El INMP441 requiere específica polaridad I2S (I2S standard), ya por defecto
  // Ajuste de tasa exacta
  ESP_ERROR_CHECK(i2s_set_clk(I2S_NUM_0, SAMPLE_RATE, I2S_BITS_PER_SAMPLE_32BIT, I2S_CHANNEL_MONO));
}

void compute_hann()
{
  for (int i = 0; i < FFT_N; i++) {
    hann[i] = 0.5 * (1.0 - cos(2.0 * PI * i / (FFT_N - 1)));
  }
}

void wifi_init_ap()
{
  // Modo AP para evitar depender de una red
  WiFi.mode(WIFI_AP);
  bool ok = WiFi.softAP(WIFI_SSID, WIFI_PASS);
  if (!ok) {
    Serial.println("Fallo al iniciar AP");
  } else {
    Serial.print("AP iniciado: ");
    Serial.print(WIFI_SSID);
    Serial.print("  IP: ");
    Serial.println(WiFi.softAPIP());
  }
}

void handle_root()
{
  server.send_P(200, "text/html", INDEX_HTML);
}

void setup_web()
{
  server.on("/", HTTP_GET, handle_root);
  server.on("/status", HTTP_GET, [](){
    String s = "{";
    s += "\"chip\":\"" + String(ESP.getChipModel()) + "\",";
    s += "\"cpu_mhz\":" + String(ESP.getCpuFreqMHz()) + ",";
    s += "\"sample_rate\":" + String(SAMPLE_RATE) + ",";
    s += "\"fft_n\":" + String(FFT_N) + ",";
    s += "\"bins\":" + String(WS_BINS);
    s += "}";
    server.send(200, "application/json", s);
  });
  server.begin();
  wsServer.begin();
  wsServer.onEvent([](uint8_t num, WStype_t type, uint8_t * payload, size_t length){
    if (type == WStype_CONNECTED) {
      IPAddress ip = wsServer.remoteIP(num);
      Serial.printf("[WS] Cliente %u conectado desde %s\n", num, ip.toString().c_str());
    }
  });
}

inline float fast_log10f(float x) {
  return logf(x) / logf(10.0f);
}

void compute_fft_and_spectrum()
{
  // Leer FFT_N muestras de I2S (32-bit por muestra)
  size_t bytesRead = 0;
  size_t toRead = FFT_N * sizeof(int32_t);
  uint8_t* ptr = (uint8_t*)i2s_raw;
  while (bytesRead < toRead) {
    size_t br = 0;
    i2s_read(I2S_NUM_0, ptr + bytesRead, toRead - bytesRead, &br, portMAX_DELAY);
    bytesRead += br;
  }

  // Convertir a double y aplicar ventana + de-DC
  // INMP441 entrega dato válido en 18-24 bits del entero de 32
  double mean = 0;
  for (int i = 0; i < FFT_N; i++) {
    // Centrar y escalar (ajuste empírico para 18 bits útiles)
    int32_t s = i2s_raw[i] >> 14; // trae a ~18 bits
    mean += (double)s;
  }
  mean /= (double)FFT_N;

  for (int i = 0; i < FFT_N; i++) {
    double s = (double)(i2s_raw[i] >> 14) - mean;
    vReal[i] = s * hann[i];
    vImag[i] = 0.0;
  }

  // FFT
  FFT.Windowing(vReal, FFT_N, FFT_WIN_TYP_RECTANGLE, FFT_FORWARD); // ya aplicamos Hann manual
  FFT.Compute(vReal, vImag, FFT_N, FFT_FORWARD);
  FFT.ComplexToMagnitude(vReal, vImag, FFT_N);

  // vReal[0..FFT_N/2] contiene magnitud. Transformar a dB aprox y normalizar 0-255
  const int nBins = FFT_N / 2; // Nyquist
  static float mag[FFT_N/2];

  float maxv = 1e-6f;
  for (int i = 1; i < nBins; i++) { // ignorar DC en 0
    float m = (float)vReal[i];
    mag[i] = m;
    if (m > maxv) maxv = m;
  }
  // Log scale: 20*log10(m/maxv)
  for (int i = 1; i < nBins; i++) {
    float m = mag[i] / maxv;
    float db = 20.0f * fast_log10f(0.000001f + m); // evitar log(0)
    // Mapear -60..0 dB → 0..1
    float norm = (db + 60.0f) / 60.0f;
    if (norm < 0) norm = 0;
    if (norm > 1) norm = 1;
    mag[i] = norm;
  }

  // Reducir a WS_BINS bandas logarítmicas entre ~80 Hz y 8 kHz
  // Frecuencia por bin FFT i: f = i * SAMPLE_RATE / FFT_N
  for (int b = 0; b < WS_BINS; b++) {
    // Log-space: mapea b∈[0,WS_BINS-1] a f∈[80, 8000]
    float fmin = 80.0f, fmax = SAMPLE_RATE / 2.0f;
    float t = (float)b / (WS_BINS - 1);
    float f = fmin * powf(fmax / fmin, t);
    float f2 = fmin * powf(fmax / fmin, (float)(b+1) / (WS_BINS - 1));
    int i1 = (int)floorf(f * FFT_N / SAMPLE_RATE);
    int i2 = (int)floorf(f2 * FFT_N / SAMPLE_RATE);
    if (i1 < 1) i1 = 1;
    if (i2 >= nBins) i2 = nBins - 1;
    if (i2 < i1) i2 = i1;

    float acc = 0.0f; int cnt = 0;
    for (int i = i1; i <= i2; i++) { acc += mag[i]; cnt++; }
    float val = (cnt > 0) ? acc / cnt : 0.0f;
    // Compresión suave
    val = powf(val, 0.6f);
    spectrum[b] = (uint8_t)roundf(val * 255.0f);
  }

  // Actualizar LEDs
  // Mapear WS_BINS a LED_COUNT (tomamos LED_COUNT bandas equidistantes en spectrum)
  for (int led = 0; led < LED_COUNT; led++) {
    int idx = (int)roundf((float)led / (LED_COUNT - 1) * (WS_BINS - 1));
    uint8_t v = spectrum[idx];
    // Paleta simple (azul->verde->rojo)
    uint8_t r = (uint8_t)min(255, max(0, (int)v - 64) * 2);
    uint8_t g = (uint8_t)min(255, (int)v);
    uint8_t b = (uint8_t)min(255, 255 - v);
    RgbColor color(r, g, b);
    strip.SetPixelColor(led, color);
  }
  strip.Show();

  // Enviar por WebSocket en binario: 64 bytes (0..255)
  wsServer.broadcastBIN(spectrum, WS_BINS);
}

void setup()
{
  Serial.begin(115200);
  delay(200);

  // LEDs
  strip.Begin();
  strip.Show();

  // Ventana Hann
  compute_hann();

  // WiFi AP + Web
  wifi_init_ap();
  setup_web();

  // I2S
  i2s_init();

  Serial.println("Listo. Abre http://192.168.4.1 en tu navegador (conectado al AP).");
  Serial.println("El WebSocket usa puerto 81.");
}

void loop()
{
  server.handleClient();
  wsServer.loop();

  unsigned long now = millis();
  if (now - lastProcessMs >= FRAME_INTERVAL_MS) {
    lastProcessMs = now;
    compute_fft_and_spectrum();
  }
}

Resumen de partes clave:
– Inicialización I2S a 16 kHz, 32 bits, mono, usando pines 26/25/33.
– FFT de 1024 puntos con ventana Hann precalculada, magnitud logarítmica.
– Reducción a 64 bandas logarítmicas y transmisión por WebSocket (binario).
– Iluminación de 24 LEDs con NeoPixelBus (RMT, estable en ESP32 con WiFi activo).
– Servidor HTTP simple embebido en PROGMEM para una sola página cliente con canvas que pinta el espectrograma.

Compilación, flasheo y ejecución

A continuación, comandos reproducibles con PlatformIO CLI:

1) Crear proyecto e instalar dependencias
– pio project init -b esp32dev
– Sustituir el contenido de platformio.ini por el mostrado arriba.
– Crear src/main.cpp con el código.

2) Compilar
– pio run

3) Conectar la placa y detectar puerto
– Windows: revisar el puerto COM en el Administrador de dispositivos
– Linux/macOS (opcional): pio device list

4) Flashear firmware
– pio run -t upload

5) Abrir monitor serie (115200 baudios)
– pio device monitor -b 115200

6) Conectar al punto de acceso del ESP32
– SSID: ESP32-SPECTRO
– Clave: esp32spectro123

7) Navegador
– Acceder a http://192.168.4.1 (la página se sirve localmente).
– La página abre un WebSocket a ws://192.168.4.1:81/ automáticamente.

Notas:
– Si usas VS Code + PlatformIO IDE, el flujo es el mismo desde el panel de tareas.
– Si necesitas subir más rápido: upload_speed = 921600 ya está activado; si falla, baja a 460800.

Validación paso a paso

1) Verificación de arranque:
– En el monitor serie debe aparecer algo como:
– “AP iniciado: ESP32-SPECTRO IP: 192.168.4.1”
– “Listo. Abre http://192.168.4.1…”
– Los LEDs del anillo pueden encenderse brevemente durante la inicialización.

2) Conexión WiFi:
– En tu PC/Smartphone, conéctate a la red “ESP32-SPECTRO” con clave “esp32spectro123”.
– Comprueba que el dispositivo obtiene IP (por ejemplo 192.168.4.x).

3) Carga de la web:
– Abre http://192.168.4.1 en el navegador.
– Debes ver un lienzo negro y el texto “ESP32 I2S Spectrogram via WebSocket”.
– El estado en la cabecera debe cambiar a “WebSocket conectado”.

4) Señal de audio básica:
– Da una palmada cerca del micrófono o habla. Observa:
– El lienzo debe actualizar columnas de colores desplazándose de derecha a izquierda.
– Mayor energía en frecuencias bajas se ve como colores intensos en la parte inferior del canvas.
– Las consonantes agudas resaltan parte superior del espectrograma.

5) Iluminación WS2812B:
– El anillo debe reaccionar a la energía espectral:
– Con voz grave: mayor intensidad hacia LEDs asignados a bandas bajas.
– Con chasquidos/ruidos agudos: más intensidad en LEDs correspondientes a bandas altas.
– Si reduces el ruido ambiental, los LEDs deben atenuarse.

6) Diagnóstico de niveles:
– Si el espectrograma está saturado (todo rojo/amarillo), reduce la ganancia efectiva:
– Edición en compute_fft_and_spectrum: ajusta el shift (>>14) o la compresión powf(val, 0.6).
– Si es muy tenue, prueba a acercarte al micrófono o incrementar la ganancia post-FFT (ajusta la curva de compresión/paletizado).

7) Medida temporal:
– Con FRAME_INTERVAL_MS = 33, deberías ver ~30 columnas por segundo.
– En Serial, puedes instrumentar tiempos si necesitas: medir duración de compute_fft_and_spectrum para comprobar que cabe en 33 ms.

8) Confirmación de WebSocket binario:
– Abre las DevTools del navegador (F12 → Network → WS), selecciona la conexión.
– Debes ver frames binarios de 64 bytes latiendo con la cadencia del espectrograma.

Troubleshooting

1) No se ve la red WiFi “ESP32-SPECTRO”
– Causa: fallo de arranque, consumo excesivo del anillo a 5 V provoca brown-out.
– Solución:
– Desconecta temporalmente el anillo WS2812B y reinicia el ESP32.
– Alimenta el anillo con fuente 5 V externa y une GND con el ESP32.
– Verifica que BOOT/EN no están siendo forzados accidentalmente por cableado.

2) Página carga pero “WebSocket desconectado”
– Causa: bloqueo de puerto 81, firewall o mapeo erróneo de host.
– Solución:
– Asegúrate de abrir la página desde el AP (http://192.168.4.1).
– Comprueba que no hay un proxy activo en el navegador.
– Si usas cliente Android con “datos móviles”, apaga datos para forzar uso de WiFi.

3) El espectrograma no cambia (columna plana)
– Causa: cableado I2S incorrecto (WS/BCLK/SD), L/R sin fijar, o sample rate incompatible.
– Solución:
– Revisa tabla de pines: SCK→GPIO26, WS→GPIO25, SD→GPIO33, L/R a GND.
– Confirma 3V3 y GND correctos al INMP441.
– Rehaz soldaduras si el módulo tiene pads poco firmes.

4) Reset aleatorio al encender LEDs
– Causa: picos de corriente en WS2812B provocan caída de tensión (brown-out).
– Solución:
– Añade condensador 1000 µF entre 5 V y GND del anillo.
– Coloca resistencia 330–470 Ω en la línea de datos.
– Usa fuente 5 V externa adecuada y GND común.
– Reduce el brillo global (opcional: limita color con multiplicador < 1).

5) LEDs parpadean o colores erráticos
– Causa: nivel de señal de datos insuficiente o interferencia por cables largos.
– Solución:
– Usa un level shifter (74AHCT125).
– Acorta la longitud del cable de datos y trénzalo con GND.
– Asegura GND común robusto y alimentación estable.

6) Audio saturado o con “clipping”
– Causa: el INMP441 no requiere ganancia externa, pero el escalado puede saturar.
– Solución:
– Ajusta el desplazamiento (>>14) en la conversión del I2S para adecuar rango.
– Revisa la compresión logarítmica y mapea -80..0 dB si es necesario.
– Evita gritar directamente al micrófono a corta distancia.

7) Compilación falla por librerías
– Causa: versiones no resueltas.
– Solución:
– Ejecuta pio pkg update y pio pkg install –environment esp32dev.
– Verifica platformio.ini exacto (versiones en lib_deps, platform, platform_packages).
– Limpia la caché: pio run -t clean y recompila.

8) El tiempo de cuadro excede 33 ms (audio a tirones)
– Causa: carga de CPU por FFT + WiFi + LEDs.
– Solución:
– Reduce FFT_N a 512 (ajusta defines en build_flags y lógica de código).
– Aumenta FRAME_INTERVAL_MS a 40–50.
– Disminuye WS_BINS a 48 o 32.
– Compila con -O2 (por defecto) y evita logs de Serial en bucles críticos.

Mejoras/variantes

• STFT con solapamiento:
• Implementar solapamiento 50% entre marcos y una ventana Hann superpuesta (OLA) para suavizar las transiciones temporales.
• Formato de transporte eficiente:
• Enviar tramas binarios con cabecera mínima (e.g., 0x53 0x50 0x47 0x01 + payload) y compresión delta u-Law para reducir ancho de banda.
• UI web avanzada:
• Selector de paleta, escala log/lin, control de FPS y tamaño de espectro desde la página (enviar mensajes de control via WebSocket).
• Mapeo LED radial:
• Si tu anillo tiene 24 LEDs, mapear bandas en distribución circular por frecuencia (bajas opuestas a altas, con simetría).
• AGC (control automático de ganancia):
• Calcular nivel RMS por bloque y ajustar una ganancia adaptativa lenta para mantener un rango útil de visualización constante.
• Persistencia y streaming dual:
• Grabar frames de espectrograma en PSRAM o SD y servirlos bajo demanda.
• Exponer un endpoint SSE/HTTP como alternativa al WebSocket.
• Filtrado de banda:
• Añadir un filtro pasaaltos a 80–100 Hz para eliminar ruidos de baja frecuencia no informativos.

Compendio de comandos y opciones

• Inicialización de proyecto:
• pio project init -b esp32dev
• Compilación:
• pio run
• Subida de firmware:
• pio run -t upload
• Monitor serie:
• pio device monitor -b 115200
• Información del sistema PlatformIO:
• pio system info
• Limpieza:
• pio run -t clean
• Actualización de paquetes:
• pio pkg update
• Listado de dispositivos serie:
• pio device list

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.15 y verifiqué pio –version.
• [ ] He creado el proyecto con board esp32dev y he pegado el platformio.ini exacto.
• [ ] He cableado el INMP441: SCK→GPIO26, WS→GPIO25, SD→GPIO33, VDD→3V3, GND→GND, L/R→GND.
• [ ] He cableado el WS2812B: DIN→GPIO18 (con resistencia 330–470 Ω y, si es posible, level shifter), 5V→5V, GND→GND común; condensador 1000 µF en 5 V.
• [ ] He compilado sin errores con pio run.
• [ ] He subido el firmware con pio run -t upload.
• [ ] En el monitor serie veo el AP y la IP 192.168.4.1.
• [ ] Me conecto a la red “ESP32-SPECTRO” y abro http://192.168.4.1.
• [ ] La página muestra “WebSocket conectado”.
• [ ] Al hablar o dar una palmada, el espectrograma se mueve y los LEDs reaccionan.
• [ ] Si noto resets o parpadeos, he revisado alimentación, GND común y la resistencia serie en datos.

Con este caso práctico, has construido un pipeline completo i2s-spectrogram-websocket-neopixel sobre el modelo ESP32-DevKitC V4 + INMP441 I2S mic + WS2812B LED ring, asegurando coherencia en materiales, conexión, código y comandos de despliegue mediante PlatformIO y un conjunto concreto de versiones.

Objetivo y caso de uso

Qué construirás: Un sistema de detección de anomalías utilizando I2S en un ESP32 que envía alertas a través de MQTT y proporciona retroalimentación de audio con indicadores LED.

Para qué sirve

• Monitoreo de calidad de audio en tiempo real mediante análisis de señal.
• Detección de ruidos anómalos en sistemas de audio profesional.
• Alertas automáticas en dispositivos IoT cuando se detectan anomalías.
• Control de iluminación LED en respuesta a eventos de audio específicos.
• Integración con sistemas de domótica para mejorar la seguridad del hogar.

Resultado esperado

• Latencias de respuesta de menos de 100 ms en la detección de anomalías.
• Transmisión de datos a través de MQTT con un throughput de al menos 10 paquetes/s.
• Indicadores LED que reflejan el estado del sistema en tiempo real.
• Mensajes de alerta enviados al broker MQTT en menos de 200 ms tras la detección.
• Capacidad de procesar señales de audio de hasta 48 kHz sin pérdida de calidad.

Público objetivo: Desarrolladores de sistemas embebidos; Nivel: Avanzado

Arquitectura/flujo: Captura de audio con I2S en ESP32 → Análisis de señal → Detección de anomalías → Envío de alertas MQTT → Activación de indicadores LED.

Nivel: Avanzado

Prerrequisitos

Sistemas operativos probados

• Windows 11 Pro 23H2 (build 22631)
• Ubuntu 22.04.4 LTS (kernel 5.15)
• macOS 14.5 (Sonoma)

Toolchain exacta (versiones cerradas y reproducibles)

• Python: 3.11.9
• PlatformIO Core (CLI): 6.1.14
• PlatformIO Platform: espressif32@6.5.0
• Framework Arduino para ESP32 (a través de PlatformIO): 2.0.14
• Compilador xtensa-esp32-elf-gcc: 8.4.0 (incluido por espressif32@6.5.0)
• esptool.py: 4.7
• Controlador USB-UART para Espressif ESP32-DevKitC V4: CP210x (Silicon Labs) v10.1.10 (Windows). En macOS y Linux generalmente no se requiere instalación manual.
• Broker MQTT de referencia para validación: Eclipse Mosquitto 2.0.18 (opcional, para pruebas en PC)
• Bibliotecas del proyecto (se fijan en platformio.ini):
• PubSubClient 2.8 (MQTT)
• Adafruit NeoPixel 1.12.0
• arduinoFFT 1.5.6

Notas:
– Se fuerza el entorno a versiones concretas para favorecer la reproducibilidad.
– El framework Arduino 2.0.14 usa ESP-IDF 4.4.x bajo el capó, con API driver/i2s estable.

Materiales

• Placa de desarrollo: Espressif ESP32-DevKitC V4 (ESP32-WROOM-32)
• Micrófono digital I2S: INMP441 (módulo con pines WS/LRCL, SCK/BCLK, SD/DOUT, L/R)
• Amplificador/DAC I2S: MAX98357A (módulo con BCLK, LRC, DIN, SD/GAIN)
• Tira LED o LED suelto WS2812B (al menos 1 LED)
• Fuente de alimentación:
• USB 5 V para la DevKitC V4
• 5 V para el WS2812B (puede tomarse del mismo USB si la corriente total lo permite)
• Protoboard y cables dupont
• Un altavoz pequeño (4–8 Ω) para el MAX98357A
• Opcional pero recomendado: conversor de nivel lógico 3.3 V→5 V para la data del WS2812B (muchos funcionan sin él a 3.3 V, pero no es lo ideal)

Objetivo del proyecto: i2s-anomaly-detection-mqtt
– Captura de audio con INMP441 vía I2S0
– Generación de tonos con MAX98357A vía I2S1 para feedback acústico
– Detección de anomalías acústicas (basada en características espectrales) en tiempo real
– Telemetría MQTT con puntajes y eventos de anomalía
– Señalización visual con WS2812B (estado/calibración/anomalía)

Preparación y conexión

Consideraciones de pines y buses

• El ESP32 dispone de dos controladores I2S (I2S_NUM_0 e I2S_NUM_1). Usaremos:
• I2S0 para el micrófono (RX)
• I2S1 para el amplificador MAX98357A (TX)
• Evitaremos pines de “strapping” en señales sensibles de arranque (GPIO0, GPIO2, GPIO15) para minimizar riesgos de boot fallido.

Tabla de conexiones

Recomendaciones:
– Conecta todas las tierras en común (ESP32, micrófono, MAX98357A, WS2812B).
– Si tu WS2812B es una tira larga, inyecta 5 V por ambos extremos y añade un condensador electrolítico 1000 µF/6.3 V entre +5 V y GND.
– Coloca una resistencia serie de 220–470 Ω en la línea DIN del WS2812B para mejorar integridad de señal.
– Si el cable entre ESP32 y LED es largo, usa conversor de nivel lógico 3.3→5 V.

Código completo (Arduino + PlatformIO)

A continuación se provee un proyecto mínimo viable completo con:
– Inicialización I2S RX (INMP441) e I2S TX (MAX98357A)
– Extracción de características (RMS y centroide espectral con FFT)
– Calibración de referencia (baseline) durante ~10 s
– Cálculo de puntaje de anomalía (z-score combinado)
– Publicación por MQTT en JSON
– Señalización con WS2812B y beep acústico en anomalías

Estructura propuesta del proyecto (PlatformIO):
– platformio.ini
– src/main.cpp

platformio.ini

; PlatformIO configuration for Espressif ESP32-DevKitC V4 (ESP32-WROOM-32)
[env:esp32dev]
platform = espressif32@6.5.0
board = esp32dev
framework = arduino
platform_packages =
  framework-arduinoespressif32@~2.0.14
monitor_speed = 115200
upload_speed = 921600
board_build.flash_mode = dio
board_build.f_cpu = 240000000L

lib_deps =
  knolleary/PubSubClient@2.8
  adafruit/Adafruit NeoPixel@1.12.0
  kosme/arduinoFFT@1.5.6

build_flags =
  -DWIFI_SSID=\"TU_SSID\"
  -DWIFI_PASS=\"TU_PASSWORD\"
  -DMQTT_HOST=\"192.168.1.50\"
  -DMQTT_PORT=1883
  -DMQTT_CLIENT_ID=\"esp32-devkitc-v4-i2s-anomaly\"
  -DMQTT_TOPIC_PUB=\"esp32/devkitc/anomaly\"
  -DMQTT_TOPIC_STATUS=\"esp32/devkitc/status\"
  -DAUDIO_SAMPLE_RATE=16000
  -DAUDIO_FRAME_SAMPLES=1024
  -DWS2812_PIN=4
  -DWS2812_NUM=1
  -DMAX98357_ENABLE_PIN=27

; Notas de toolchain:
; PlatformIO Core 6.1.14, esptool.py 4.7, xtensa-esp32-elf-gcc 8.4.0 (vía espressif32@6.5.0)

Asegúrate de reemplazar TU_SSID, TU_PASSWORD y MQTT_HOST por tus valores reales.

src/main.cpp

#include <Arduino.h>
#include <WiFi.h>
#include <PubSubClient.h>
#include <Adafruit_NeoPixel.h>
#include "arduinoFFT.h"
#include "driver/i2s.h"

// ======================= Configuración por macros (desde platformio.ini) =======================
#ifndef WIFI_SSID
#define WIFI_SSID "RELLENAR"
#endif
#ifndef WIFI_PASS
#define WIFI_PASS "RELLENAR"
#endif
#ifndef MQTT_HOST
#define MQTT_HOST "192.168.1.50"
#endif
#ifndef MQTT_PORT
#define MQTT_PORT 1883
#endif
#ifndef MQTT_CLIENT_ID
#define MQTT_CLIENT_ID "esp32-devkitc-v4-i2s-anomaly"
#endif
#ifndef MQTT_TOPIC_PUB
#define MQTT_TOPIC_PUB "esp32/devkitc/anomaly"
#endif
#ifndef MQTT_TOPIC_STATUS
#define MQTT_TOPIC_STATUS "esp32/devkitc/status"
#endif
#ifndef AUDIO_SAMPLE_RATE
#define AUDIO_SAMPLE_RATE 16000
#endif
#ifndef AUDIO_FRAME_SAMPLES
#define AUDIO_FRAME_SAMPLES 1024
#endif
#ifndef WS2812_PIN
#define WS2812_PIN 4
#endif
#ifndef WS2812_NUM
#define WS2812_NUM 1
#endif
#ifndef MAX98357_ENABLE_PIN
#define MAX98357_ENABLE_PIN 27
#endif

// ======================= Pines I2S (coherentes con la tabla) =======================
static const i2s_port_t I2S_MIC = I2S_NUM_0;
static const int I2S_MIC_BCLK = 14;   // INMP441 SCK/BCLK
static const int I2S_MIC_LRCL = 13;   // INMP441 WS/LRCL
static const int I2S_MIC_DOUT = 32;   // INMP441 SD/DOUT

static const i2s_port_t I2S_SPK = I2S_NUM_1;
static const int I2S_SPK_BCLK = 26;   // MAX98357A BCLK
static const int I2S_SPK_LRCL = 25;   // MAX98357A LRC
static const int I2S_SPK_DIN  = 22;   // MAX98357A DIN

// ======================= Objetos globales =======================
WiFiClient wifiClient;
PubSubClient mqtt(wifiClient);
Adafruit_NeoPixel pixel(WS2812_NUM, WS2812_PIN, NEO_GRB + NEO_KHZ800);
arduinoFFT FFT = arduinoFFT(); // usaremos interfaz por vectores de doble precisión

// Buffers y variables de audio
static const uint16_t N = AUDIO_FRAME_SAMPLES; // tamaño de ventana FFT (potencia de 2)
int32_t i2s_rx_buffer[N];  // Lectura cruda 32-bit desde I2S
double vReal[N];
double vImag[N];

// Características y baseline
volatile bool baseline_ready = false;
const uint32_t baseline_time_ms = 10000; // 10 s de calibración
uint32_t baseline_start_ms = 0;
uint32_t frames_seen = 0;

double mean_rms = 0.0, var_rms = 0.0;
double mean_cent = 0.0, var_cent = 0.0;

const double anomaly_threshold = 6.0; // suma de |z-scores| de RMS y centroide

// Utilidades LED
void led_color(uint8_t r, uint8_t g, uint8_t b) {
  pixel.setPixelColor(0, pixel.Color(r, g, b));
  pixel.show();
}

// ======================= Inicialización I2S MIC (RX) =======================
bool i2s_mic_init() {
  i2s_config_t cfg = {
    .mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_RX),
    .sample_rate = AUDIO_SAMPLE_RATE,
    .bits_per_sample = I2S_BITS_PER_SAMPLE_32BIT,
    .channel_format = I2S_CHANNEL_FMT_ONLY_LEFT, // INMP441 cableado a canal izquierdo
    .communication_format = I2S_COMM_FORMAT_I2S,
    .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
    .dma_buf_count = 8,
    .dma_buf_len = 256,
    .use_apll = true,
    .tx_desc_auto_clear = false,
    .fixed_mclk = 0
  };
  i2s_pin_config_t pin_cfg = {
    .bck_io_num = I2S_MIC_BCLK,
    .ws_io_num = I2S_MIC_LRCL,
    .data_out_num = I2S_PIN_NO_CHANGE,
    .data_in_num = I2S_MIC_DOUT
  };
  esp_err_t err;
  err = i2s_driver_install(I2S_MIC, &cfg, 0, NULL);
  if (err != ESP_OK) return false;
  err = i2s_set_pin(I2S_MIC, &pin_cfg);
  if (err != ESP_OK) return false;
  err = i2s_set_clk(I2S_MIC, AUDIO_SAMPLE_RATE, I2S_BITS_PER_SAMPLE_32BIT, I2S_CHANNEL_MONO);
  return err == ESP_OK;
}

// ======================= Inicialización I2S SPK (TX) =======================
bool i2s_spk_init() {
  pinMode(MAX98357_ENABLE_PIN, OUTPUT);
  digitalWrite(MAX98357_ENABLE_PIN, LOW); // arranca en mute
  i2s_config_t cfg = {
    .mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_TX),
    .sample_rate = AUDIO_SAMPLE_RATE, // mismo sample rate para simplicidad
    .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT, // el MAX98357A trabaja bien a 16 bits
    .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, // estéreo (duplicaremos)
    .communication_format = I2S_COMM_FORMAT_I2S,
    .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
    .dma_buf_count = 8,
    .dma_buf_len = 256,
    .use_apll = false,
    .tx_desc_auto_clear = true,
    .fixed_mclk = 0
  };
  i2s_pin_config_t pin_cfg = {
    .bck_io_num = I2S_SPK_BCLK,
    .ws_io_num = I2S_SPK_LRCL,
    .data_out_num = I2S_SPK_DIN,
    .data_in_num = I2S_PIN_NO_CHANGE
  };
  if (i2s_driver_install(I2S_SPK, &cfg, 0, NULL) != ESP_OK) return false;
  if (i2s_set_pin(I2S_SPK, &pin_cfg) != ESP_OK) return false;
  if (i2s_set_clk(I2S_SPK, AUDIO_SAMPLE_RATE, I2S_BITS_PER_SAMPLE_16BIT, I2S_CHANNEL_STEREO) != ESP_OK) return false;
  digitalWrite(MAX98357_ENABLE_PIN, HIGH); // habilita amplificador
  return true;
}

// ======================= Generación de beep (feedback) =======================
void beep(uint16_t freq_hz = 880, uint16_t ms = 120, uint16_t amplitude = 4000) {
  const uint32_t samples = (AUDIO_SAMPLE_RATE * ms) / 1000;
  // Estéreo intercalado (L,R) a 16-bit
  for (uint32_t n = 0; n < samples; ++n) {
    float t = (float)n / AUDIO_SAMPLE_RATE;
    int16_t s = (int16_t)(amplitude * sinf(2.0f * PI * freq_hz * t));
    uint32_t twoch = ((uint16_t)s << 16) | ((uint16_t)s); // L=R
    size_t written = 0;
    i2s_write(I2S_SPK, &twoch, sizeof(twoch), &written, portMAX_DELAY);
  }
}

// ======================= Conectividad WiFi + MQTT =======================
void mqtt_reconnect() {
  while (!mqtt.connected()) {
    Serial.print(F("Conectando a MQTT... "));
    if (mqtt.connect(MQTT_CLIENT_ID)) {
      Serial.println(F("OK"));
      mqtt.publish(MQTT_TOPIC_STATUS, "online", true);
    } else {
      Serial.printf("fallo rc=%d, reintento en 3 s\n", mqtt.state());
      delay(3000);
    }
  }
}

void wifi_connect() {
  WiFi.mode(WIFI_STA);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  Serial.printf("Conectando a WiFi SSID=%s\n", WIFI_SSID);
  uint32_t t0 = millis();
  while (WiFi.status() != WL_CONNECTED) {
    delay(300);
    Serial.print(".");
    if (millis() - t0 > 20000) {
      Serial.println("\nTimeout WiFi, reintentando...");
      WiFi.disconnect(true);
      WiFi.begin(WIFI_SSID, WIFI_PASS);
      t0 = millis();
    }
  }
  Serial.printf("\nWiFi conectado: %s (RSSI=%d dBm), IP=%s\n",
                WiFi.SSID().c_str(), WiFi.RSSI(), WiFi.localIP().toString().c_str());
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
}

// ======================= Procesamiento de características =======================
static inline double compute_rms(const double* x, uint16_t len) {
  double acc = 0.0;
  for (uint16_t i = 0; i < len; ++i) acc += x[i] * x[i];
  return sqrt(acc / len);
}

static inline double compute_spectral_centroid(const double* mag, uint16_t bins, double fs) {
  // bins corresponde a N/2 después de FFT
  double num = 0.0, den = 0.0;
  for (uint16_t k = 1; k < bins; ++k) { // evita DC
    double f = (double)k * fs / (2.0 * bins);
    num += f * mag[k];
    den += mag[k];
  }
  return (den > 1e-9) ? (num / den) : 0.0;
}

// Welford para media/varianza en línea
struct OnlineStats {
  double mean = 0.0;
  double M2 = 0.0;
  uint32_t n = 0;
  void add(double x) {
    n++;
    double delta = x - mean;
    mean += delta / n;
    double delta2 = x - mean;
    M2 += delta * delta2;
  }
  double variance() const { return (n > 1) ? (M2 / (n - 1)) : 0.0; }
};

OnlineStats stats_rms, stats_cent;

// ======================= Setup =======================
void setup() {
  Serial.begin(115200);
  delay(200);

  pixel.begin();
  pixel.setBrightness(30); // brillo moderado
  led_color(255, 165, 0);  // naranja: arranque/calibración

  if (!i2s_mic_init()) {
    Serial.println("Error inicializando I2S MIC");
    led_color(255, 0, 255); // magenta error
    while (true) delay(1000);
  }
  if (!i2s_spk_init()) {
    Serial.println("Error inicializando I2S SPK");
    led_color(255, 0, 255);
    while (true) delay(1000);
  }

  wifi_connect();
  mqtt.setBufferSize(1024); // para payload JSON más amplio
  mqtt_reconnect();

  baseline_start_ms = millis();
  Serial.println("Calibración de baseline en curso (~10 s)...");
}

// ======================= Loop principal =======================
void loop() {
  if (WiFi.status() == WL_CONNECTED) {
    if (!mqtt.connected()) mqtt_reconnect();
    mqtt.loop();
  }

  // Leer un frame de AUDIO_FRAME_SAMPLES desde I2S (32-bit)
  size_t bytes_read = 0;
  i2s_read(I2S_MIC, (void*)i2s_rx_buffer, sizeof(i2s_rx_buffer), &bytes_read, portMAX_DELAY);
  uint16_t samples_read = bytes_read / sizeof(int32_t);
  if (samples_read != N) {
    // Ajuste básico; en la práctica debería llegar N por configuración de DMA
    return;
  }

  // Convertir a double, quitar offset y escalar
  // INMP441 a 32-bit, útil tomar los 24 bits superiores (datos suelen venir en MSB)
  static double dc_acc = 0.0;
  for (uint16_t i = 0; i < N; ++i) {
    int32_t s = i2s_rx_buffer[i] >> 8; // 24-bit significativo
    double x = (double)s / 8388608.0;  // normaliza aprox a [-1,1]
    dc_acc += 0.0001 * (x - dc_acc);   // filtro DC lento
    x -= dc_acc;
    // Ventana Hann para FFT
    double w = 0.5 * (1.0 - cos((2.0 * PI * i) / (N - 1)));
    vReal[i] = x * w;
    vImag[i] = 0.0;
  }

  // Característica temporal: RMS (sin ventana)
  double rms = compute_rms(vReal, N);

  // FFT -> magnitud espectral
  FFT.Windowing(vReal, N, FFT_WIN_TYP_RECTANGLE, FFT_FORWARD); // ya aplicamos Hann manual
  FFT.Compute(vReal, vImag, N, FFT_FORWARD);
  FFT.ComplexToMagnitude(vReal, vImag, N);

  // vReal ahora contiene magnitudes. Usar N/2 bins útiles.
  uint16_t bins = N / 2;
  double centroid = compute_spectral_centroid(vReal, bins, (double)AUDIO_SAMPLE_RATE);

  // Acumular baseline durante ~10 s
  if (!baseline_ready) {
    stats_rms.add(rms);
    stats_cent.add(centroid);
    frames_seen++;
    if (millis() - baseline_start_ms >= baseline_time_ms) {
      mean_rms = stats_rms.mean;
      var_rms  = stats_rms.variance();
      mean_cent = stats_cent.mean;
      var_cent  = stats_cent.variance();
      baseline_ready = true;
      Serial.printf("Baseline lista: mean_rms=%.6f, std_rms=%.6f, mean_cent=%.1f Hz, std_cent=%.1f Hz\n",
                    mean_rms, sqrt(var_rms), mean_cent, sqrt(var_cent));
      led_color(0, 255, 0); // verde: listo
      mqtt.publish(MQTT_TOPIC_STATUS, "baseline_ready", true);
    } else {
      // Indicar calibración con pulso suave
      static uint32_t lastBlink = 0;
      if (millis() - lastBlink > 250) {
        lastBlink = millis();
        led_color(255, 165, 0); // naranja
      }
    }
    return;
  }

  // Calcular z-scores y puntaje de anomalía
  double std_rms = sqrt(var_rms);
  double std_cent = sqrt(var_cent);
  double z_rms = (std_rms > 1e-9) ? (rms - mean_rms) / std_rms : 0.0;
  double z_cent = (std_cent > 1e-9) ? (centroid - mean_cent) / std_cent : 0.0;
  double anomaly_score = fabs(z_rms) + fabs(z_cent);
  bool is_anomaly = anomaly_score >= anomaly_threshold;

  // Feedback visual/acústico
  if (is_anomaly) {
    led_color(255, 0, 0);
    beep(880, 90, 3000);
  } else {
    led_color(0, 64, 0); // verde tenue en operación normal
  }

  // Publicar MQTT (JSON compacto)
  static char payload[768];
  snprintf(payload, sizeof(payload),
    "{\"device\":\"%s\",\"ts\":%lu,"
    "\"rms\":%.6f,\"centroid_hz\":%.1f,"
    "\"z_rms\":%.2f,\"z_cent\":%.2f,\"score\":%.2f,"
    "\"anomaly\":%s}",
    MQTT_CLIENT_ID, (unsigned long)millis(),
    rms, centroid,
    z_rms, z_cent, anomaly_score,
    is_anomaly ? "true" : "false"
  );
  mqtt.publish(MQTT_TOPIC_PUB, payload);
}

Breve explicación de partes clave:
– i2s_mic_init / i2s_spk_init: configura controladores I2S separados (RX para INMP441, TX para MAX98357A) con los pines exactos del apartado de conexiones.
– Lectura I2S: se leen 1024 muestras 32-bit, se normalizan y se aplica ventana Hann.
– Extracción de características:
– RMS: energía del frame.
– Centroide espectral: “centro de masa” del espectro, sensible a contenido de alta frecuencia.
– Baseline/calibración: durante 10 s calcula media y varianza (Welford) de RMS y centroide.
– Detección: suma de |z-scores|; si supera 6.0, se marca anomalía.
– Feedback:
– WS2812B: naranja (calibración), verde (normal), rojo (anomalía).
– MAX98357A: beep de ~880 Hz en anomalías.
– MQTT: publica JSON en esp32/devkitc/anomaly con métricas y bandera de anomalía.

Compilación/flash/ejecución

1) Instalar PlatformIO Core (CLI) en Python 3.11.9

• Windows/macOS/Linux:
• Asegúrate de tener Python 3.11 en PATH.
• Instala versión fija:
  python -m pip install --upgrade pip
python -m pip install platformio==6.1.14
pio --version
  Debe imprimir “PlatformIO Core, version 6.1.14”.

2) Inicializar proyecto

• En una carpeta vacía:
  pio project init --board esp32dev
• Sustituye el contenido de platformio.ini por el mostrado arriba.
• Crea src/main.cpp con el código anterior.

3) Drivers USB-UART

• Windows: instala “CP210x Universal Windows Driver v10.1.10” desde Silicon Labs.
• macOS/Linux: normalmente no se requiere. Verifica el puerto:
• macOS: /dev/cu.SLAB_USBtoUART
• Linux: /dev/ttyUSB0 o /dev/ttyUSB1
• Windows: COMx

4) Comandos de build, upload y monitor

• Compilar:
  pio run
• Flashear (conecta la placa por USB):
  pio run -t upload
• Monitor serie (115200 baudios):
  pio device monitor -b 115200

5) Comprobación del broker MQTT (opcional local)

• Instala Mosquitto 2.0.18 (si no tienes broker).
• Suscríbete para ver telemetría:
  mosquitto_sub -h 127.0.0.1 -p 1883 -t esp32/devkitc/anomaly -v
mosquitto_sub -h 127.0.0.1 -p 1883 -t esp32/devkitc/status -v

Asegúrate de que MQTT_HOST en platformio.ini apunte a tu broker.

Validación paso a paso

1) Arranque y calibración
– Abre el monitor serie:
– Debes ver: “Conectando a WiFi…”, RSSI e IP asignada.
– Mensaje “Calibración de baseline en curso (~10 s)…”.
– LED WS2812B:
– Naranja durante la calibración (~10 s).
– MQTT:
– Topic esp32/devkitc/status: “online” y luego “baseline_ready”.

2) Post-calibración (estado normal)
– LED: verde tenue estable (normal).
– En el monitor serie se mostrará el resumen de baseline (mean/std de RMS y centroid).
– En el broker, llegarán mensajes JSON en esp32/devkitc/anomaly cada frame o cada pocos cientos de ms:
– Claves: rms, centroid_hz, z_rms, z_cent, score, anomaly.

3) Forzar una anomalía acústica
– Golpea suavemente la mesa, aplaude cerca o genera un ruido agudo.
– LED: pasa a rojo durante la detección del evento.
– Altavoz: debe sonar un beep breve (~880 Hz).
– MQTT: el JSON debe contener «anomaly»:true y un “score” significativamente > 6.0.

4) Verificación de parámetros
– Observa en JSON cómo varía “centroid_hz” (ruidos agudos subirán el centroide).
– “rms” aumentará con niveles de sonido más altos.
– “z_rms” y “z_cent” deberían acercarse a 0 en condiciones normales; crecerán en anomalías.

5) Suscripción desde PC con mosquitto_sub
– Ejemplo de salida:
esp32/devkitc/anomaly {"device":"esp32-devkitc-v4-i2s-anomaly","ts":10456,"rms":0.012345,"centroid_hz":1450.2,"z_rms":0.22,"z_cent":0.18,"score":0.40,"anomaly":false}
esp32/devkitc/anomaly {"device":"esp32-devkitc-v4-i2s-anomaly","ts":12890,"rms":0.098765,"centroid_hz":3800.5,"z_rms":4.10,"z_cent":3.20,"score":7.30,"anomaly":true}

6) Audio de salida
– Al detectar anomalía, el MAX98357A reproduce un beep corto; si no se escucha, revisa altavoz, cableado y nivel de mute (GPIO27 en alto).

Troubleshooting (errores típicos y soluciones)

1) El ESP32 no aparece como puerto serie o upload falla
– Verifica el cable USB (que sea de datos, no solo carga).
– Instala/actualiza el driver CP210x (Windows).
– Prueba a bajar la velocidad de upload: en platformio.ini usa upload_speed = 460800.
– Pulsa BOOT mientras inicia el upload, o reset si fuera necesario.

2) Boot loop o la placa no arranca tras cableado
– Evita usar pines de strapping (GPIO0, GPIO2, GPIO15) para señales externas. La guía ya los evita.
– Desconecta temporalmente periféricos y prueba solo la placa; si arranca, revisa resistencias/pulls en tu montaje.

3) El micrófono INMP441 no devuelve datos válidos (silencio o valores erráticos)
– Comprueba que L/R esté a GND para canal izquierdo.
– Revisa pines: SD→GPIO32, WS→GPIO13, SCK→GPIO14, VDD→3.3 V.
– Asegura tierra común.
– Mantén sample_rate=16000 y 32 bits en RX; INMP441 suele requerir 24 bits; usamos 32 con desplazamiento.

4) El MAX98357A no emite audio
– Verifica que SD/EN (GPIO27) esté en ALTO tras inicialización.
– Revisa BCLK (GPIO26), LRC (GPIO25), DIN (GPIO22).
– Comprueba el altavoz y su conexión, y que la fuente 5 V esté presente.
– Asegura la coincidencia de sample rate entre TX y la señal generada (usamos AUDIO_SAMPLE_RATE).

5) WS2812B no enciende o parpadea errático
– Añade resistencia serie de 330 Ω en DIN y condensador de 1000 µF en la alimentación de la tira.
– Usa un buen GND común y alimenta a 5 V estable.
– Si el cable DIN es largo, usa conversor de nivel 3.3→5 V.
– Disminuye el brillo (pixel.setBrightness).

6) No conecta a MQTT o se desconecta frecuentemente
– Verifica MQTT_HOST y puerto 1883 (sin TLS en este ejemplo).
– Asegúrate de que el broker permite clientes anónimos o configura usuario/clave en PubSubClient (no cubierto aquí).
– Aumenta keepalive o reduce frecuencia de publicaciones si el broker aplica rate limiting.

7) Anomalías constantes o nunca detecta
– Recalibra baseline en un entorno silencioso (~10 s tras reset).
– Ajusta anomaly_threshold (p. ej., 5.0 para mayor sensibilidad o 8.0 para menos).
– Valida que centroid_hz y rms varíen con estímulos; si no, revisa micrófono.

8) Desbordes/tiempos en MQTT (payload truncado)
– Aumenta mqtt.setBufferSize(1024) como en el código.
– Verifica que la longitud del JSON no exceda el buffer.

Mejoras/variantes

• Modelo TinyML:
• Integrar TensorFlow Lite for Microcontrollers para un autoencoder o detector de anomalías espectral. Preprocesa con mel-espectrogramas y despliega un modelo 1D.
• Persistencia de baseline:
• Guardar mean/std en NVS/Preferences tras calibración y restaurarlos en el arranque para evitar recalibrar cada vez.
• MQTT seguro:
• Migrar a TLS (puerto 8883) con certificados CA. Usar WiFiClientSecure y PubSubClient con setServer(MQTT_HOST, 8883).
• Downsampling/banda de interés:
• Filtrar banda (p. ej., 300–3400 Hz) para voz/máquinas y refinar el centroide o usar centroides por bandas.
• Indicador multicolor más rico:
• WS2812B en patrones animados (pulso, barrido) según severidad del score.
• Buffer circular y detección por ráfagas:
• Aplicar ventana deslizante, agregación de scores y supresión de múltiples eventos por debouncing temporal.
• Telemetría ampliada:
• Publicar espectro reducido (p. ej., 32 bins logarítmicos) o features adicionales: ZCR, entropía espectral, roll-off.

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.14 en Python 3.11.9 y confirmé pio –version.
• [ ] He creado el proyecto con board=esp32dev y sustituido platformio.ini por el proporcionado.
• [ ] He fijado WIFI_SSID, WIFI_PASS y MQTT_HOST en build_flags de platformio.ini.
• [ ] He cableado el INMP441 a GPIO14/13/32 con L/R a GND y alimentación 3.3 V.
• [ ] He cableado el MAX98357A a GPIO26/25/22 y EN en GPIO27, con alimentación 5 V y altavoz conectado.
• [ ] He cableado el WS2812B a GPIO4 con 5 V y GND comunes, preferiblemente con resistencia en DIN.
• [ ] La compilación pio run finaliza sin errores.
• [ ] La carga pio run -t upload se realiza y puedo abrir pio device monitor -b 115200.
• [ ] Veo “baseline_ready” tras ~10 s y LED verde.
• [ ] Al provocar un ruido anómalo, LED rojo + beep, y el topic esp32/devkitc/anomaly publica anomaly=true.
• [ ] En estado normal, el score permanece estable y bajo el umbral.

Con este caso práctico, has implementado un pipeline completo de i2s-anomaly-detection-mqtt en el hardware exacto “Espressif ESP32-DevKitC V4 (ESP32-WROOM-32) + INMP441 + MAX98357A + WS2812B”, con toolchain y versiones fijadas, incluyendo captura I2S, procesamiento básico de audio, notificación MQTT y feedback multimodal.

Objetivo y caso de uso

Qué construirás: Un gateway que conecta redes TWAI/CAN con MQTT utilizando un ESP32-WROOM-32 y un transceptor SN65HVD230.

Para qué sirve

• Integración de vehículos con sistemas IoT mediante la transmisión de datos de sensores a través de MQTT.
• Monitoreo en tiempo real de parámetros de vehículos como velocidad y temperatura a través de una interfaz web.
• Control de dispositivos remotos en el vehículo mediante comandos enviados a través de MQTT.
• Visualización de datos en tiempo real en pantallas OLED utilizando el ESP32.

Resultado esperado

• Latencia de comunicación menor a 100 ms entre el sensor y el broker MQTT.
• Capacidad de manejar hasta 10 paquetes/s de datos desde el bus CAN.
• Mensajes de estado de conexión MQTT con un 99% de disponibilidad.
• Visualización de datos en la pantalla OLED con actualización cada 2 segundos.

Público objetivo: Usuarios avanzados; Nivel: Avanzado

Arquitectura/flujo: Comunicación entre el bus TWAI/CAN y el broker MQTT a través del ESP32, con visualización en OLED.

Nivel: Avanzado

Prerrequisitos

• Sistemas operativos soportados (elige uno):
• Windows 10/11 (64-bit) con derechos de administrador
• macOS 13 Ventura / macOS 14 Sonoma (Apple Silicon o Intel)
• Ubuntu 22.04 LTS / Debian 12 (amd64 o arm64)
• Toolchain exacta (versionado cerrado y reproducible):
• Python 3.10.12 (Ubuntu 22.04) o Python 3.11.x en macOS/Windows
• PlatformIO Core 6.1.12 (CLI)
• Plataforma ESP32 para PlatformIO: espressif32@6.5.0
• Framework Arduino-ESP32 para PlatformIO: framework-arduinoespressif32@3.20014.0 (equivale a Arduino-ESP32 2.0.14)
• Esptool.py 4.5.1 (a través de tool-esptoolpy@1.40501.0 en PlatformIO)
• Librerías de usuario (PlatformIO lib_deps exactas):
  • PubSubClient@2.8 (MQTT)
  • Adafruit SSD1306@2.5.7 (OLED)
  • Adafruit GFX Library@1.11.9 (OLED)
  • ArduinoJson@6.21.5 (parseo/serialización de JSON)
• Broker MQTT:
• Eclipse Mosquitto 2.0.18 (cliente y/o servidor local)
• Drivers USB-UART:
• CP210x USB to UART Bridge VCP Drivers (para la mayoría de ESP32-WROOM-32 DevKitC, chip CP2102N/CP2102)
  • Windows: Versión 10.1.10 o superior
  • macOS/Linux: normalmente no requiere instalación manual

Verificaciones rápidas:
– USB: el puerto serie aparece al conectar el “ESP32-WROOM-32 DevKitC” (ej. COMx en Windows, /dev/tty.SLAB_USBtoUART en macOS, /dev/ttyUSBx en Linux).
– PlatformIO Core: pio –version debe mostrar 6.1.12.
– Mosquitto: mosquitto -h y mosquitto_sub -h no deben dar error.

Materiales

• ESP32-WROOM-32 DevKitC + SN65HVD230 CAN Transceiver + SSD1306 OLED (modelo exacto solicitado)
• Cables dupont macho-hembra
• Bus CAN funcional (al menos otro nodo CAN a 500 kbit/s) y resistencia de terminación 120 Ω en los extremos (si tu transceptor o el otro nodo no la incorporan)
• Fuente de alimentación por USB (5 V) para el DevKitC
• Opcional: protoboard
• Red Wi-Fi 2.4 GHz con acceso al broker MQTT (LAN local o remoto)

Notas de alimentación:
– SN65HVD230: alimentación a 3.3 V (no 5 V). El ESP32 entrega 3.3 V en su pin 3V3.
– SSD1306 I2C: alimentación a 3.3 V (recomendado); muchos módulos soportan 3–5 V, pero con ESP32 usa 3.3 V.

Preparación y conexión

Este proyecto configura un gateway “twai-can-mqtt-gateway”:
– Lado CAN (TWAI del ESP32) con transceptor SN65HVD230 a 500 kbit/s
– Lado MQTT sobre Wi-Fi hacia un broker (ej. Mosquitto)
– OLED SSD1306 muestra estado (Wi-Fi/MQTT, frames RX/TX, estado de bus)

Conexiones recomendadas (coherentes con código, pins y librerías):

Tabla de cableado

Observaciones:
– Asegura que la línea CAN esté terminada con 120 Ω en ambos extremos del bus. Muchas placas SN65HVD230 incluyen un jumper/solder bridge para activar una resistencia de 120 Ω local. Actívala solo si esta placa es un extremo del bus.
– Mantén separados los cables de CAN (CANH/CANL) del resto de señales para minimizar ruido.
– El RS del SN65HVD230 controla standby y control de flanco. A GND entra en modo de velocidad alta (lo recomendado para este caso).
– No mezcles niveles de 5 V en señales lógicas con el ESP32.

Código completo

A continuación se proveen los archivos clave del proyecto PlatformIO. El código implementa:
– Inicialización de TWAI (CAN) a 500 kbit/s, filtros “accept all”
– Suscripción MQTT al tópico “twai/gw/can/tx” para inyectar frames CAN desde JSON
– Publicación de frames recibidos en “twai/gw/can/rx” en formato JSON
– Estadísticas y estado en “twai/gw/status” y “twai/gw/stats”
– OLED SSD1306 con 4 líneas: estado Wi-Fi/MQTT, estado CAN, contadores y broker/ip

platformio.ini

Crea platformio.ini en la raíz del proyecto con el siguiente contenido:

[env:esp32dev]
platform = espressif32@6.5.0
board = esp32dev
framework = arduino
platform_packages =
  framework-arduinoespressif32@3.20014.0
  tool-esptoolpy@1.40501.0
lib_deps =
  knolleary/PubSubClient@2.8
  adafruit/Adafruit SSD1306@2.5.7
  adafruit/Adafruit GFX Library@1.11.9
  bblanchon/ArduinoJson@6.21.5
upload_speed = 921600
monitor_speed = 115200
monitor_filters = time, colorize
build_flags =
  -D CONFIG_ARDUHAL_LOG_DEFAULT_LEVEL=4
  -D WIFI_SSID="\"TU_SSID\""
  -D WIFI_PASS="\"TU_PASSWORD\""
  -D MQTT_HOST="\"192.168.1.10\""
  -D MQTT_PORT=1883

Personaliza WIFI_SSID, WIFI_PASS y MQTT_HOST/MQTT_PORT a tu entorno.

src/main.cpp

Crea src/main.cpp con el contenido completo:

#include <Arduino.h>
#include <WiFi.h>
#include <PubSubClient.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <driver/twai.h>
#include <ArduinoJson.h>

// Pines y parámetros de hardware
#define TWAI_TX_GPIO GPIO_NUM_5   // SN65HVD230 D <- MCU TX
#define TWAI_RX_GPIO GPIO_NUM_4   // SN65HVD230 R -> MCU RX
#define I2C_SDA      21
#define I2C_SCL      22
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET   -1 // SSD1306 sin pin reset dedicado
#define OLED_ADDR    0x3C

// Configuración de red/MQTT (inyectadas por build_flags en platformio.ini)
#ifndef WIFI_SSID
#define WIFI_SSID "TU_SSID"
#endif
#ifndef WIFI_PASS
#define WIFI_PASS "TU_PASSWORD"
#endif
#ifndef MQTT_HOST
#define MQTT_HOST "192.168.1.10"
#endif
#ifndef MQTT_PORT
#define MQTT_PORT 1883
#endif

// Tópicos MQTT
static const char* TOPIC_RX     = "twai/gw/can/rx";
static const char* TOPIC_TX     = "twai/gw/can/tx";
static const char* TOPIC_STATUS = "twai/gw/status";
static const char* TOPIC_STATS  = "twai/gw/stats";
static const char* TOPIC_LOG    = "twai/gw/log";

WiFiClient wifiClient;
PubSubClient mqtt(wifiClient);
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Estado
volatile uint32_t can_rx_count = 0;
volatile uint32_t can_tx_count = 0;
volatile uint32_t can_rx_errors = 0;
volatile uint32_t can_tx_errors = 0;
volatile uint32_t can_bus_offs = 0;

String ipStr;
unsigned long lastStatsMs = 0;

static void oledPrintStatus(const String& line1, const String& line2, const String& line3, const String& line4) {
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println(line1);
  display.setCursor(0, 16);
  display.println(line2);
  display.setCursor(0, 32);
  display.println(line3);
  display.setCursor(0, 48);
  display.println(line4);
  display.display();
}

static void updateOLEDStatus() {
  twai_status_info_t status;
  twai_get_status_info(&status);

  char l1[32], l2[32], l3[32], l4[32];
  snprintf(l1, sizeof(l1), "WiFi:%s MQTT:%s",
           WiFi.isConnected() ? "OK" : "NO",
           mqtt.connected() ? "OK" : "NO");

  const char* st = "BUS_ON";
  if (status.state == TWAI_STATE_BUS_OFF) st = "BUS_OFF";
  else if (status.state == TWAI_STATE_ERROR_PASSIVE) st = "ERR_PASS";
  else if (status.state == TWAI_STATE_RECOVERING) st = "RECOV";

  snprintf(l2, sizeof(l2), "CAN:%s RXQ:%d TXQ:%d", st, status.msgs_to_rx, status.msgs_to_tx);
  snprintf(l3, sizeof(l3), "RX:%lu TX:%lu", (unsigned long)can_rx_count, (unsigned long)can_tx_count);
  snprintf(l4, sizeof(l4), "MQTT:%s %s", MQTT_HOST, ipStr.c_str());

  oledPrintStatus(l1, l2, l3, l4);
}

static void publishStatus() {
  StaticJsonDocument<256> doc;
  doc["wifi"]["connected"] = WiFi.isConnected();
  doc["wifi"]["ip"] = ipStr;
  doc["mqtt"]["connected"] = mqtt.connected();
  twai_status_info_t status;
  twai_get_status_info(&status);
  const char* st = "BUS_ON";
  if (status.state == TWAI_STATE_BUS_OFF) st = "BUS_OFF";
  else if (status.state == TWAI_STATE_ERROR_PASSIVE) st = "ERROR_PASSIVE";
  else if (status.state == TWAI_STATE_RECOVERING) st = "RECOVERING";
  doc["twai"]["state"] = st;
  doc["twai"]["rx_queue"] = status.msgs_to_rx;
  doc["twai"]["tx_queue"] = status.msgs_to_tx;
  doc["twai"]["rx_count"] = can_rx_count;
  doc["twai"]["tx_count"] = can_tx_count;
  doc["twai"]["rx_errs"] = can_rx_errors;
  doc["twai"]["tx_errs"] = can_tx_errors;
  doc["twai"]["bus_offs"] = can_bus_offs;

  char out[384];
  size_t n = serializeJson(doc, out, sizeof(out));
  mqtt.publish(TOPIC_STATUS, out, n);
}

static void publishStats() {
  StaticJsonDocument<192> doc;
  doc["rx"] = can_rx_count;
  doc["tx"] = can_tx_count;
  doc["host"] = MQTT_HOST;
  char out[192];
  size_t n = serializeJson(doc, out, sizeof(out));
  mqtt.publish(TOPIC_STATS, out, n);
}

static String hexBytes(const uint8_t* d, uint8_t len) {
  static const char* hex = "0123456789ABCDEF";
  String s;
  s.reserve(len * 2);
  for (uint8_t i = 0; i < len; i++) {
    s += hex[(d[i] >> 4) & 0xF];
    s += hex[d[i] & 0xF];
  }
  return s;
}

static bool parseHexData(const char* s, uint8_t* buf, uint8_t* out_len) {
  size_t L = strlen(s);
  if (L % 2 != 0) return false;
  size_t bytes = L / 2;
  if (bytes > 8) return false;
  for (size_t i = 0; i < bytes; i++) {
    char c1 = s[2 * i];
    char c2 = s[2 * i + 1];
    auto hv = [](char c) -> int {
      if (c >= '0' && c <= '9') return c - '0';
      if (c >= 'a' && c <= 'f') return c - 'a' + 10;
      if (c >= 'A' && c <= 'F') return c - 'A' + 10;
      return -1;
    };
    int h = hv(c1), l = hv(c2);
    if (h < 0 || l < 0) return false;
    buf[i] = (uint8_t)((h << 4) | l);
  }
  *out_len = (uint8_t)bytes;
  return true;
}

// Envía un frame CAN a partir de JSON recibido en TOPIC_TX
static void handleTxJson(const char* payload, size_t len) {
  StaticJsonDocument<256> doc;
  DeserializationError err = deserializeJson(doc, payload, len);
  if (err) {
    mqtt.publish(TOPIC_LOG, "JSON parse error on TX");
    return;
  }
  twai_message_t m = {};
  m.extd = doc["ext"] | false;
  m.rtr = doc["rtr"] | false;
  m.identifier = doc["id"] | 0;
  if (m.extd) {
    if (m.identifier > 0x1FFFFFFF) m.identifier = 0x1FFFFFFF;
  } else {
    if (m.identifier > 0x7FF) m.identifier = 0x7FF;
  }

  if (!m.rtr) {
    const char* dataHex = doc["data"] | "";
    uint8_t lenParsed = 0;
    uint8_t tmp[8] = {0};
    if (!parseHexData(dataHex, tmp, &lenParsed)) {
      mqtt.publish(TOPIC_LOG, "Invalid hex data");
      return;
    }
    m.data_length_code = doc["dlc"] | lenParsed;
    if (m.data_length_code > lenParsed) m.data_length_code = lenParsed;
    memcpy(m.data, tmp, m.data_length_code);
  } else {
    m.data_length_code = doc["dlc"] | 0;
  }

  esp_err_t res = twai_transmit(&m, pdMS_TO_TICKS(100));
  if (res == ESP_OK) {
    can_tx_count++;
    StaticJsonDocument<192> ack;
    ack["tx_ack"] = true;
    ack["id"] = m.identifier;
    ack["ext"] = (bool)m.extd;
    ack["dlc"] = m.data_length_code;
    char out[192];
    size_t n = serializeJson(ack, out, sizeof(out));
    mqtt.publish("twai/gw/can/tx_ack", out, n);
  } else {
    can_tx_errors++;
    mqtt.publish(TOPIC_LOG, "TX failed");
  }
}

static void mqttCallback(char* topic, byte* payload, unsigned int length) {
  if (strcmp(topic, TOPIC_TX) == 0) {
    handleTxJson((const char*)payload, (size_t)length);
  }
}

static void ensureWifi() {
  if (WiFi.isConnected()) return;
  WiFi.mode(WIFI_STA);
  WiFi.setSleep(false);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  unsigned long start = millis();
  while (WiFi.status() != WL_CONNECTED && millis() - start < 20000) {
    delay(250);
  }
  if (WiFi.isConnected()) {
    ipStr = WiFi.localIP().toString();
  } else {
    ipStr = "0.0.0.0";
  }
}

static void ensureMqtt() {
  if (mqtt.connected()) return;
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  String clientId = String("twai-gw-esp32-") + String((uint32_t)ESP.getEfuseMac(), HEX);
  if (mqtt.connect(clientId.c_str())) {
    mqtt.subscribe(TOPIC_TX);
    mqtt.publish(TOPIC_LOG, "MQTT connected");
  }
}

// Tarea de recepción CAN → MQTT
void can_rx_task(void* arg) {
  while (true) {
    twai_message_t m;
    esp_err_t res = twai_receive(&m, pdMS_TO_TICKS(100));
    if (res == ESP_OK) {
      can_rx_count++;
      StaticJsonDocument<256> doc;
      doc["id"] = m.identifier;
      doc["ext"] = (bool)m.extd;
      doc["rtr"] = (bool)m.rtr;
      doc["dlc"] = m.data_length_code;
      if (!m.rtr && m.data_length_code <= 8) {
        doc["data"] = hexBytes(m.data, m.data_length_code);
      }
      char out[256];
      size_t n = serializeJson(doc, out, sizeof(out));
      mqtt.publish(TOPIC_RX, out, n);
    } else if (res == ESP_ERR_TIMEOUT) {
      // Nada en cola; continúa
    } else if (res == ESP_ERR_INVALID_STATE) {
      // Driver detenido/bus_off; cuenta y espera
      can_bus_offs++;
      vTaskDelay(pdMS_TO_TICKS(100));
    } else {
      can_rx_errors++;
    }
  }
}

// Inicializa TWAI (CAN) a 500 kbit/s
static bool initTWAI() {
  twai_general_config_t g_config = TWAI_GENERAL_CONFIG_DEFAULT(TWAI_TX_GPIO, TWAI_RX_GPIO, TWAI_MODE_NORMAL);
  twai_timing_config_t  t_config = TWAI_TIMING_CONFIG_500KBITS();
  twai_filter_config_t  f_config = TWAI_FILTER_CONFIG_ACCEPT_ALL();

  if (twai_driver_install(&g_config, &t_config, &f_config) != ESP_OK) {
    Serial.println("twai_driver_install failed");
    return false;
  }
  if (twai_start() != ESP_OK) {
    Serial.println("twai_start failed");
    return false;
  }
  // Opcional: fijar alertas (no indispensable en este caso)
  return true;
}

void setup() {
  Serial.begin(115200);
  delay(100);

  // I2C + OLED
  Wire.begin(I2C_SDA, I2C_SCL);
  display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR);
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("twai-can-mqtt-gateway");
  display.println("Init...");
  display.display();

  // Wi-Fi
  ensureWifi();

  // MQTT
  mqtt.setCallback(mqttCallback);
  ensureMqtt();

  // TWAI
  if (!initTWAI()) {
    oledPrintStatus("TWAI init FAILED", "", "", "");
    while (true) { delay(1000); }
  }

  // Tarea de recepción CAN
  xTaskCreatePinnedToCore(can_rx_task, "can_rx_task", 4096, nullptr, 10, nullptr, 1);

  updateOLEDStatus();
  publishStatus();
}

void loop() {
  // Mantener Wi-Fi/MQTT
  if (!WiFi.isConnected()) {
    ensureWifi();
  }
  if (WiFi.isConnected() && !mqtt.connected()) {
    ensureMqtt();
  }
  mqtt.loop();

  // Estadísticas cada 1 s
  unsigned long now = millis();
  if (now - lastStatsMs > 1000) {
    lastStatsMs = now;
    updateOLEDStatus();
    if (mqtt.connected()) {
      publishStatus();
      publishStats();
    }
  }

  delay(10);
}

Explicación de partes clave:
– TWAI a 500 kbit/s: TWAI_GENERAL_CONFIG_DEFAULT con GPIO 5 (TX) y 4 (RX). Timing con TWAI_TIMING_CONFIG_500KBITS(), filtro de aceptación total.
– MQTT PubSubClient: publica frames RX en JSON y escucha en el tópico de TX para inyectar frames.
– ArduinoJson: garantiza parseo/serialización robusto y limitado en memoria (documentos estáticos).
– OLED: muestra estado en tiempo real (Wi-Fi/MQTT, estado del controlador TWAI, contadores, host del broker e IP).
– Tareas: can_rx_task en núcleo 1 evita bloquear el loop principal que se encarga de Wi-Fi/MQTT.

Formato de JSON para transmisión (tópico twai/gw/can/tx):
– id: entero (11 bits si ext=false, 29 bits si ext=true)
– ext: booleano (false por defecto)
– rtr: booleano (false por defecto)
– dlc: 0–8 (opcional; si no se provee, se infiere de la longitud de ‘data’)
– data: string hex (hasta 16 chars para 8 bytes; p.ej. «112233AABBCCDD00»)

Ejemplo:
{«id»: 291, «ext»: false, «rtr»: false, «dlc»: 8, «data»: «1122334455667788»}

Compilación/flash/ejecución

Asumiendo PlatformIO Core 6.1.12 instalado y en PATH.

1) Crear proyecto

• Usando CLI:

# Linux/macOS
mkdir -p ~/projects/twai-can-mqtt-gateway
cd ~/projects/twai-can-mqtt-gateway
pio project init --board esp32dev --project-option "platform=espressif32@6.5.0" --project-option "framework=arduino"

# Windows PowerShell
mkdir $env:USERPROFILE\projects\twai-can-mqtt-gateway
cd $env:USERPROFILE\projects\twai-can-mqtt-gateway
pio project init --board esp32dev --project-option "platform=espressif32@6.5.0" --project-option "framework=arduino"

• Sustituye el contenido de platformio.ini por el dado anteriormente.
• Crea src/main.cpp con el código completo mostrado.

2) Instalar dependencias

PlatformIO las bajará en el primer build, pero puedes forzar:

pio pkg update
pio lib -e esp32dev install "knolleary/PubSubClient@2.8"
pio lib -e esp32dev install "adafruit/Adafruit SSD1306@2.5.7"
pio lib -e esp32dev install "adafruit/Adafruit GFX Library@1.11.9"
pio lib -e esp32dev install "bblanchon/ArduinoJson@6.21.5"

3) Compilar

pio run

4) Conectar el ESP32-WROOM-32 DevKitC por USB

• Identifica el puerto (ejemplos):
• Windows: COM5
• macOS: /dev/tty.SLAB_USBtoUART
• Linux: /dev/ttyUSB0

5) Flashear

pio run -t upload

Si necesitas especificar puerto:

pio run -t upload --upload-port /dev/ttyUSB0

6) Monitor serie

pio device monitor -b 115200

Deberías ver logs de conexión Wi-Fi, conexión MQTT y arranque de TWAI.

7) Broker MQTT (Mosquitto 2.0.18)

• Ubuntu 22.04:

sudo apt-get update
sudo apt-get install -y mosquitto=2.0.18-0mosquitto1~jammy1 mosquitto-clients=2.0.18-0mosquitto1~jammy1
sudo systemctl enable --now mosquitto

• Verificación:

mosquitto -h | head -n 3
mosquitto_sub -h 127.0.0.1 -t "#" -v

• Alternativa con Docker:

docker run --rm -it -p 1883:1883 eclipse-mosquitto:2.0.18

Ajusta MQTT_HOST del proyecto (platformio.ini) a la IP del broker.

Validación paso a paso

1) Verifica alimentación y cableado:
– SN65HVD230: VCC a 3V3; GND a GND; RS a GND; D a GPIO 5; R a GPIO 4.
– SSD1306: VCC a 3V3; GND a GND; SDA a GPIO 21; SCL a GPIO 22.
– CANH/CANL conectados al bus y terminación 120 Ω presente en extremos.

2) Arranque:
– En el monitor serie deben aparecer mensajes como “MQTT connected” y “twai_start OK”.
– En la OLED:
– Línea 1: WiFi:OK MQTT:OK (tras conexión)
– Línea 2: CAN:BUS_ON RXQ:0 TXQ:0 (al inicio)
– Línea 3: RX:0 TX:0 (contadores)
– Línea 4: MQTT:192.168.1.10 192.168.1.xx (IP del ESP32)

3) Suscríbete a los tópicos desde tu PC:

mosquitto_sub -h 192.168.1.10 -t 'twai/gw/#' -v

4) Inyecta un frame desde MQTT hacia CAN (si tienes otro nodo escuchando en el bus):

mosquitto_pub -h 192.168.1.10 -t 'twai/gw/can/tx' -m '{"id":291,"ext":false,"rtr":false,"dlc":8,"data":"1122334455667788"}'

• Esperado:
• Publicación ACK en “twai/gw/can/tx_ack” con id=291 y dlc=8
• OLED incrementa TX
• El otro nodo CAN debe recibir el frame (si lo monitorizas con equipo externo o un segundo nodo ESP32)

5) Ingresos desde el bus a MQTT:
– Genera frames desde otro nodo CAN a 500 kbit/s y observa en:

mosquitto_sub -h 192.168.1.10 -t 'twai/gw/can/rx' -v

• El payload JSON debe mostrar id, ext, rtr, dlc y data en hex.

6) Estado y estadísticas:

mosquitto_sub -h 192.168.1.10 -t 'twai/gw/status' -v
mosquitto_sub -h 192.168.1.10 -t 'twai/gw/stats' -v

• Debe mostrar bus_on o estados de error si los hubiera, colas, contadores y dirección IP.

7) Robustez:
– Apaga el broker y vuelve a encenderlo: observa reconexión automática (OLED: MQTT:NO → OK).
– Desconecta el bus CAN o genera errores: observa cambios de estado (ERROR_PASSIVE, RECOVERING, BUS_OFF) en status.

Troubleshooting

1) No aparece puerto serie:
– Windows: instala/reinstala “CP210x VCP Drivers” (Silicon Labs), usa otro cable USB de datos, prueba otro puerto.
– macOS/Linux: revisa permisos del puerto (/dev/ttyUSBx o /dev/tty.SLAB_USBtoUART). En Linux, añade tu usuario al grupo dialout: sudo usermod -aG dialout $USER y reloguea.

2) Fallo de flasheo (Timed out waiting for packet header):
– Mantén pulsado BOOT mientras reseteas (EN) el ESP32 y suelta tras iniciar upload.
– Reduce upload_speed en platformio.ini a 460800 o 115200.

3) OLED sin imagen:
– Revisa dirección I2C (0x3C es común; algunos módulos usan 0x3D). Ajusta OLED_ADDR en el código si es necesario.
– Verifica SDA/SCL (GPIO 21/22) y alimentación a 3.3 V.
– Comprueba que display.begin(…) no falle (muestra mensaje en Serial si quieres depurar).

4) MQTT no conecta:
– Verifica MQTT_HOST y MQTT_PORT. Comprueba reachability: ping MQTT_HOST y telnet MQTT_HOST 1883 (o nmap).
– Si el broker requiere autenticación/TLS, ajusta PubSubClient (no cubierto aquí). Para broker local, desactiva listeners TLS.

5) No recibo frames en twai/gw/can/rx:
– Revisa bitrate del bus (500 kbit/s en ambos nodos).
– Asegura terminaciones 120 Ω.
– Cruza CANH/CANL correctamente (no inviertas polaridad).
– Confirma que SN65HVD230 está a 3.3 V y RS a GND (standby desactivado).

6) TX falla (TX failed) o contador de errores sube:
– La línea CAN puede estar desconectada o en BUS_OFF. Verifica estado en tópico twai/gw/status.
– Comprueba que exista al menos otro nodo activo en el bus (CAN requiere confirmación de ACK por otro nodo).
– Revisa longitud del cableado y calidad del par CAN.

7) Congestión MQTT o reinicios:
– Reduce tasa de frames o filtra por IDs (modifica filtro y/o publica con QoS 0).
– Asegura buena cobertura Wi-Fi y alimentación estable (USB 5 V robusto).

8) JSON inválido o data hex incorrecta:
– Asegúrate de pares hex válidos (0–9, A–F). Longitud máxima 16 caracteres para 8 bytes.
– Si usas RTR, normalmente dlc>0 y sin campo data.

Mejoras/variantes

• Seguridad y robustez:
• Añadir autenticación MQTT (usuario/contraseña) y reconexión con backoff exponencial.
• TLS con certificados (usar WiFiClientSecure y broker TLS en 8883).
• Filtrado y enrutado:
• Implementar listas de IDs permitidos/denegados y mapeo de tópicos por ID (p.ej. twai/gw/can/rx/0x123).
• Añadir soporte para CAN FD (no soportado por ESP32 clásico; requeriría hardware diferente).
• Métricas y telemetría:
• Publicar tasa de frames (frames/s), errores acumulados por tipo, estado de alertas TWAI.
• Persistencia/config:
• Guardar configuración Wi-Fi/MQTT/bitrate en NVS y exponer comandos por MQTT para cambiarlos en caliente.
• Interfaz de usuario:
• Páginas en OLED para ver últimas tramas, ID más frecuente, tiempo desde última RX/TX.
• Integración:
• Contenedor Docker para broker y dashboard (Node-RED + Mosquitto + InfluxDB + Grafana).
• Diagnóstico:
• Añadir tópico para reiniciar controlador TWAI en BUS_OFF y medir recuperación.

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.12 y verifico pio –version
• [ ] He configurado platformio.ini con:
• [ ] platform espressif32@6.5.0
• [ ] framework-arduinoespressif32@3.20014.0
• [ ] tool-esptoolpy@1.40501.0
• [ ] lib_deps con versiones: PubSubClient@2.8, Adafruit SSD1306@2.5.7, Adafruit GFX@1.11.9, ArduinoJson@6.21.5
• [ ] He cableado exactamente: SN65HVD230 D→GPIO5, R→GPIO4, RS→GND, VCC→3V3; SSD1306 SDA→GPIO21, SCL→GPIO22, VCC→3V3
• [ ] He verificado terminación 120 Ω en los extremos del bus CAN
• [ ] He ajustado WIFI_SSID, WIFI_PASS, MQTT_HOST, MQTT_PORT en platformio.ini
• [ ] El proyecto compila con pio run sin errores
• [ ] Se programa con pio run -t upload y se abre monitor con pio device monitor -b 115200
• [ ] En OLED veo WiFi:OK y MQTT:OK y estado CAN:BUS_ON
• [ ] Puedo suscribirme a twai/gw/can/rx y ver frames al inyectar desde otro nodo
• [ ] Puedo publicar en twai/gw/can/tx con JSON válido y ver ACK y aumento del contador TX
• [ ] En caso de problemas, he revisado la sección Troubleshooting

Con esta guía avanzada has montado un gateway “twai-can-mqtt-gateway” totalmente reproducible sobre el hardware exacto ESP32-WROOM-32 DevKitC + SN65HVD230 CAN Transceiver + SSD1306 OLED, utilizando una toolchain definida y versiones concretas de framework y librerías, con rutas, comandos y validación paso a paso.

Objetivo y caso de uso

Qué construirás: Un sistema de detección de vibraciones predictivo utilizando LoRa y ESP32-S3 para monitorizar maquinaria industrial.

Para qué sirve

• Monitoreo continuo de vibraciones en motores eléctricos para prevenir fallos.
• Detección temprana de desbalance en ejes rotativos en fábricas.
• Transmisión de datos de vibración en tiempo real a través de LoRa para análisis remoto.
• Integración con sistemas de gestión de mantenimiento para optimizar intervenciones.

Resultado esperado

• Reducción del 30% en tiempos de inactividad no planificada.
• Latencia de transmisión de datos menor a 5 segundos.
• Capacidad de enviar hasta 100 paquetes de datos por hora.
• Precisión en la medición de vibraciones de ±0.1 g.

Público objetivo: Ingenieros de mantenimiento; Nivel: alto

Arquitectura/flujo: Sensores ICM-42688-P conectados al ESP32-S3, que envían datos a través de LoRa a un servidor para análisis.

Nivel: alto

Prerrequisitos

• Sistema operativo (elige uno; todos probados con las versiones indicadas):
• Windows 11 23H2 (Build 22631)
• Ubuntu 22.04.4 LTS

• macOS 14 Sonoma

• Toolchain exacta:

• Python 3.10.x (Ubuntu/macOS) o Python 3.11.x (Windows, vía Microsoft Store). Verifica con: python –version
• PlatformIO Core 6.1.15 (CLI) y PlatformIO IDE 3.1.1 (VS Code 1.93+)
• Verifica: pio –version → PlatformIO Core, Home y Python
• Plataforma ESP32 para PlatformIO:
• platform = espressif32 @ 6.6.0
• framework-arduinoespressif32 @ 3.0.7 (Arduino-ESP32 basado en ESP-IDF 5.x)
• toolchain-xtensa-esp32s3 @ 12.2.0+2023r1 (xtensa-esp32s3-elf-gcc 12.2.0)
• Librerías Arduino (fijadas para reproducibilidad):
• RadioLib @ 6.5.0 (manejo SX1276/RFM95W)
• hideakitai/ICM42688 @ 0.2.2 (ICM-42688-P por I2C)
• arduinoFFT @ 2.0.3 (FFT en punto flotante)
• cryptoauthlib @ 3.3.3 (Microchip ATECC608A)
• Controladores USB:
• ESP32-S3-DevKitC-1 usa USB nativo CDC/JTAG; en Windows y macOS, no se requieren drivers adicionales.
• Si usas un adaptador USB-UART alternativo: CP210x v10.1.12 (Windows) / v6.0.1 (macOS), o CH34x v1.7 (Windows/macOS).

Notas:
– La ESP32-S3-DevKitC-1 suele programarse por USB nativo (Type-C). Asegúrate de que el “USB CDC On Boot” está activo (lo fijaremos desde PlatformIO).
– En Linux, añade tu usuario a dialout para acceder a /dev/ttyACM*: sudo usermod -a -G dialout $USER y relogin.

Materiales

• Conjunto exacto:
• 1 × ESP32-S3-DevKitC-1 (ESP32-S3)
• 1 × RFM95W (SX1276) 868/915 MHz (elige la variante para tu región, p. ej. 868 MHz para EU868)
• 1 × ICM-42688-P (IMU 6 DoF; breakout típico: GND/VCC/SDA/SCL/AD0 exponiendo I2C)
• 1 × ATECC608A (co-procesador criptográfico I2C; breakout típico con GND/VCC/SDA/SCL)
• Cables dupont macho-macho

• 1 × Cable USB-C de datos

• Opcionales para validación adicional:

• 1 × Segundo nodo LoRa (otro ESP32 + RFM95W) para actuar como receptor
• Analizador lógico o SDR (para verificar radiofrecuencia)
• Acelerómetro calibrado o fuente de vibración (motor desbalanceado, mesa vibratoria)

Preparación y conexión

Mapa de pines y buses

• Buses elegidos (coherentes con ESP32-S3-DevKitC-1 y el objetivo):
• I2C0 para IMU y ATECC608A a 400 kHz
• SDA = GPIO 8
• SCL = GPIO 9
• SPI para LoRa RFM95W (SX1276)
• SCK = GPIO 12
• MISO = GPIO 13
• MOSI = GPIO 11
• NSS/CS = GPIO 10
• RST = GPIO 18
• DIO0 = GPIO 17 (IRQ principal)

• DIO1 = GPIO 16 (IRQ adicional, opcional)

• Alimentación:

• 3V3 desde la DevKitC-1 para RFM95W, ICM-42688-P y ATECC608A

• GND común para todos

• Dirección I2C:

• ICM-42688-P en 0x68 (AD0 a GND; si AD0 a VCC → 0x69)
• ATECC608A en 0x60 (típico)

Tabla de conexiones

Notas:
– Evitamos pines de “strap” del ESP32-S3 (GPIO0, GPIO3, GPIO45, GPIO46) para señales que puedan quedar forzadas al arranque.
– USB nativo del S3 usa GPIO19/20 internamente; no los empleamos.
– Mantén cables SPI cortos y con GND cercano para LoRa. Para I2C, 10–20 cm máximo a 400 kHz.

Código completo

A continuación encontrarás:
1) platformio.ini con versiones fijadas y banderas clave para USB CDC.
2) main.cpp con:
– Inicialización del I2C, IMU ICM-42688-P.
– Inicialización de ATECC608A y lectura de número de serie (para ID de dispositivo).
– Inicialización de LoRa (SX1276) con RadioLib.
– Muestreo a ~1.6 kS/s, cálculo de características (RMS, crest factor, kurtosis, centróide espectral) usando arduinoFFT.
– Detección de anomalías por z-score vs. baseline.
– Envío LoRa de un payload binario compacto con ID, contador, features y flag.

platformio.ini

; platformio.ini — lora-predictive-vibration-icm42688
[env:esp32-s3-devkitc-1]
platform = espressif32 @ 6.6.0
board = esp32-s3-devkitc-1
framework = arduino

; Paquetes y toolchain fijados para reproducibilidad
platform_packages =
  framework-arduinoespressif32 @ 3.0.7
  toolchain-xtensa-esp32s3 @ 12.2.0+2023r1

; Librerías específicas
lib_deps =
  jgromes/RadioLib @ 6.5.0
  hideakitai/ICM42688 @ 0.2.2
  arduinoFFT @ 2.0.3
  microchip/cryptoauthlib @ 3.3.3

; Velocidad de monitor
monitor_speed = 115200

; Habilitar USB CDC en boot y seleccionar Serial por USB nativo
build_flags =
  -DARDUINO_USB_MODE=1
  -DARDUINO_USB_CDC_ON_BOOT=1
  -DCORE_DEBUG_LEVEL=3

; Región LoRa (ajusta a tu país/región)
; EU868: 868.1 MHz; US915: 915.0 MHz
build_unflags = -Werror

; Subir por USB (CDC)
upload_protocol = esptool
; En Linux suele ser /dev/ttyACM0 o /dev/ttyACM1
; upload_port = /dev/ttyACM0
; monitor_port = /dev/ttyACM0

; Fijar frecuencia de CPU si necesitas determinismo extra (opcional)
; board_build.f_cpu = 240000000L

src/main.cpp

#include <Arduino.h>
#include <Wire.h>
#include <SPI.h>
#include <RadioLib.h>
#include <ICM42688.h>     // hideakitai/ICM42688
#include <arduinoFFT.h>   // v2.0.3
#include "cryptoauthlib.h"

// ---------------------- Pines ----------------------
#define LORA_SCK   12
#define LORA_MISO  13
#define LORA_MOSI  11
#define LORA_CS    10
#define LORA_RST   18
#define LORA_DIO0  17
#define LORA_DIO1  16

#define I2C_SDA     8
#define I2C_SCL     9

// ---------------------- Config LoRa ----------------
#ifndef LORA_FREQ_MHZ
  #define LORA_FREQ_MHZ 868.1  // Ajusta a tu región (EU868). US915 -> 915.0
#endif

// RadioLib: crear módulo SX1276 con SPI global y mapeo de pines
Module loraModule(LORA_CS, LORA_DIO0, LORA_RST, LORA_DIO1);
SX1276 radio(&loraModule);

// ---------------------- IMU ICM-42688-P -----------
ICM42688 imu(Wire);  // hideakitai: constructor por I2C
static const uint8_t ICM42688_ADDR = 0x68;  // AD0 a GND

// ---------------------- FFT y señal ----------------
constexpr size_t N_SAMPLES = 512;    // ventana (potencia de 2 para FFT)
constexpr float FS_HZ = 1600.0f;     // tasa de muestreo (IMU ODR >= 1.6kHz)
double vReal[N_SAMPLES];
double vImag[N_SAMPLES];
arduinoFFT FFT(vReal, vImag, N_SAMPLES, FS_HZ);

// ---------------------- Baseline/anomalía ----------
struct Features {
  float rms;
  float crest_factor;
  float kurtosis;
  float spectral_centroid;
};

// Baseline estadístico simple
Features baselineMean = {0};
Features baselineStd  = {1,1,1,1};
bool baselineReady = false;
uint16_t baselineWindows = 0;
const uint16_t WARMUP_WINDOWS = 20; // primeras ventanas para baseline

// ---------------------- ATECC608A ------------------
bool ateccReady = false;
uint8_t ateccSerial[9] = {0}; // 9 bytes serial

// ---------------------- Utilidad -------------------
uint32_t frameCounter = 0;

// Cuantización de features para payload
int16_t q15_from_float(float x, float scale) {
  float v = x * scale;
  if (v > 32767.0f) v = 32767.0f;
  if (v < -32768.0f) v = -32768.0f;
  return (int16_t)lroundf(v);
}

// ---------------------- ATECC: init y serial -------
bool initATECC() {
  ATCAIfaceCfg cfg = cfg_ateccx08a_i2c_default();
  // Ajustar I2C en ESP32-S3
  cfg.atcai2c.address = 0x60;
  cfg.atcai2c.bus = 0;      // Wire
  cfg.atcai2c.baud = 400000;

  ATCA_STATUS s = atcab_init(&cfg);
  if (s != ATCA_SUCCESS) {
    Serial.printf("ATECC init fallo: %d\n", s);
    return false;
  }
  s = atcab_read_serial_number(ateccSerial);
  if (s != ATCA_SUCCESS) {
    Serial.printf("ATECC read serial fallo: %d\n", s);
    return false;
  }
  Serial.print("ATECC608A S/N: ");
  for (int i = 0; i < 9; i++) {
    Serial.printf("%02X", ateccSerial[i]);
  }
  Serial.println();
  return true;
}

// ---------------------- IMU: init -------------------
bool initIMU() {
  Wire.begin(I2C_SDA, I2C_SCL, 400000); // 400 kHz
  delay(10);
  if (!imu.begin(ICM42688_ADDR)) {
    Serial.println("ICM-42688-P no responde en 0x68. Revisa cableado/AD0.");
    return false;
  }
  // Configurar ODR y rangos (consulta API de hideakitai/ICM42688)
  imu.setAccelODR(ICM42688::odr::odr1k6); // ~1.6 kHz
  imu.setGyroODR(ICM42688::odr::odr1k6);
  imu.setAccelRange(ICM42688::accel_range::g16); // mayor rango para vibración
  imu.setGyroRange(ICM42688::gyro_range::dps2000);
  imu.setAccelLPF(ICM42688::accel_lpf::lpf_180Hz);
  imu.setGyroLPF(ICM42688::gyro_lpf::lpf_180Hz);
  imu.enableAccel(true);
  imu.enableGyro(false); // enfocamos vibración en acelerómetro
  delay(50);
  Serial.println("ICM-42688-P inicializado.");
  return true;
}

// ---------------------- LoRa: init ------------------
bool initLoRa() {
  // Inicializar SPI con pines definidos
  SPI.begin(LORA_SCK, LORA_MISO, LORA_MOSI, LORA_CS);

  int8_t state = radio.begin(LORA_FREQ_MHZ, 125.0, 9, 5, 0x34, 14, 8, 0);
  // Parámetros: freq MHz, BW kHz, SF, CR denom, syncWord, power dBm, preamble len, gain
  // Ajustados a SF9 para sensibilidad/balance
  if (state != RADIOLIB_ERR_NONE) {
    Serial.printf("LoRa init fallo, code %d\n", state);
    return false;
  }
  // Opcionales: fijar tiempo de transmisión (TCXO no usado), cabecera explícita, CRC
  radio.setCRC(true);
  Serial.println("SX1276 (RFM95W) inicializado.");
  return true;
}

// ------------------- Muestreo y features ------------
// Calcula features sobre vReal (una ventana) y rellena spectral centroid
Features computeFeatures() {
  // 1) RMS, crest factor, kurtosis (dominio tiempo)
  double mean = 0, sum2 = 0, maxAbs = 0, sum4 = 0;
  for (size_t i = 0; i < N_SAMPLES; i++) {
    double x = vReal[i];
    mean += x;
    sum2 += x * x;
    double ax = fabs(x);
    if (ax > maxAbs) maxAbs = ax;
  }
  mean /= N_SAMPLES;
  double var = 0;
  for (size_t i = 0; i < N_SAMPLES; i++) {
    double d = vReal[i] - mean;
    var += d * d;
    sum4 += d * d * d * d;
  }
  var /= N_SAMPLES;
  double rms = sqrt(sum2 / N_SAMPLES);
  double sigma = sqrt(var + 1e-12);
  double kurt = (sum4 / N_SAMPLES) / (pow(sigma, 4) + 1e-12);

  // crest factor = max(|x|)/RMS
  double crest = (rms > 1e-9) ? (maxAbs / rms) : 0.0;

  // 2) FFT y centróide espectral
  // Copiamos vReal a arrays de FFT (ya en vReal, vImag=0)
  for (size_t i = 0; i < N_SAMPLES; i++) vImag[i] = 0.0;
  // Ventana Hanning para reducir leakage
  for (size_t i = 0; i < N_SAMPLES; i++) {
    double w = 0.5 * (1 - cos(2.0 * PI * i / (N_SAMPLES - 1)));
    vReal[i] = vReal[i] * w;
  }
  FFT.windowing(FFT_WIN_TYP_RECTANGLE, FFT_FORWARD); // ya aplicamos Hanning manual, mantenemos RECT
  FFT.compute(FFT_FORWARD);
  FFT.complexToMagnitude();

  double num = 0, den = 0;
  const double binHz = FS_HZ / N_SAMPLES;
  // Usamos bins 1..N/2-1 (excluye DC y Nyquist)
  for (size_t k = 1; k < N_SAMPLES/2; k++) {
    double f = k * binHz;
    double a = vReal[k];
    num += f * a;
    den += a + 1e-12;
  }
  double sc = num / den;

  Features feat;
  feat.rms = (float)rms;
  feat.crest_factor = (float)crest;
  feat.kurtosis = (float)kurt;
  feat.spectral_centroid = (float)sc;
  return feat;
}

// Z-score simple por campo
float zscore(float x, float mu, float sigma) {
  return (x - mu) / (sigma + 1e-9f);
}

void updateBaseline(const Features& f) {
  // Promedio incremental y desviación (Welford simplificado por campo)
  // Para robustez en demo, asumimos baselineStd constante aprox. y la recalculamos tras calentamiento.
  baselineWindows++;
  // Media incremental
  baselineMean.rms += (f.rms - baselineMean.rms) / baselineWindows;
  baselineMean.crest_factor += (f.crest_factor - baselineMean.crest_factor) / baselineWindows;
  baselineMean.kurtosis += (f.kurtosis - baselineMean.kurtosis) / baselineWindows;
  baselineMean.spectral_centroid += (f.spectral_centroid - baselineMean.spectral_centroid) / baselineWindows;

  // Tras WARMUP, podrías recalcular std con un buffer. Aquí, aproximamos tras estabilizar:
  if (baselineWindows == WARMUP_WINDOWS) {
    // Marcamos baseline ready; en práctica, acumula ventanas para std real.
    baselineStd = { baselineMean.rms * 0.1f + 1e-3f,
                    baselineMean.crest_factor * 0.1f + 1e-3f,
                    baselineMean.kurtosis * 0.1f + 1e-3f,
                    baselineMean.spectral_centroid * 0.1f + 1e-3f };
    baselineReady = true;
    Serial.println("Baseline listo.");
  }
}

// ---------------------- Payload ---------------------
// Estructura binaria compacta (little-endian)
// [0..3]   dev_id (uint32)   -> derivado de serial ATECC
// [4..7]   frameCounter (u32)
// [8..9]   q_rms (q15, *1000)
// [10..11] q_crest (q15, *1000)
// [12..13] q_kurt (q15, *1000)
// [14..15] q_sc (q15, *1)  (Hz, recortado/escala adecuada)
// [16]     flags (bit0=anomaly)
// Longitud: 17 bytes
struct __attribute__((packed)) Packet {
  uint32_t dev_id;
  uint32_t frame;
  int16_t q_rms;
  int16_t q_crest;
  int16_t q_kurt;
  int16_t q_sc;
  uint8_t flags;
};

uint32_t devIdFromATECC() {
  // Usa 4 bytes del serial (evita 0)
  uint32_t id = 0xA5A50000;
  if (ateccReady) {
    id = ((uint32_t)ateccSerial[5] << 24) |
         ((uint32_t)ateccSerial[6] << 16) |
         ((uint32_t)ateccSerial[7] << 8)  |
         ((uint32_t)ateccSerial[8]);
  }
  if (id == 0) id = 0xA5A5DEAD;
  return id;
}

// ---------------------- Setup/Loop ------------------
void setup() {
  Serial.begin(115200);
  delay(200);
  Serial.println("\n[ESP32-S3] lora-predictive-vibration-icm42688");

  // I2C + IMU
  if (!initIMU()) {
    Serial.println("Fallo IMU. Corrige y reinicia.");
  }

  // ATECC608A
  ateccReady = initATECC();

  // LoRa
  if (!initLoRa()) {
    Serial.println("Fallo LoRa. Corrige y reinicia.");
  }

  // Sincroniza primer baseline
  baselineWindows = 0;
  baselineReady = false;
}

void loop() {
  // 1) Muestreo N_SAMPLES a ~FS_HZ usando lectura rápida del acelerómetro
  const float Ts_us = 1e6f / FS_HZ;
  uint32_t t0 = micros();
  for (size_t i = 0; i < N_SAMPLES; i++) {
    // Lectura de aceleración (g). Con hideakitai/ICM42688: imu.getAccelX/Y/Z()
    imu.update(); // refresca datos internamente
    float ax = imu.getAccelX(); // g
    // Puedes combinar magnitud o eje con mayor energía. Usamos |ax| centrado.
    vReal[i] = (double)ax; // g
    vImag[i] = 0.0;
    // Espera cronometrada
    uint32_t tNext = t0 + (uint32_t)((i + 1) * Ts_us);
    while ((int32_t)(micros() - tNext) < 0) { /* busy-wait corto */ }
  }

  // 2) Calcular features
  Features f = computeFeatures();

  // 3) Actualizar baseline (fase de calentamiento)
  if (!baselineReady) {
    updateBaseline(f);
  }

  // 4) Detección de anomalía simple (z-score combinado)
  float zr = zscore(f.rms, baselineMean.rms, baselineStd.rms);
  float zc = zscore(f.crest_factor, baselineMean.crest_factor, baselineStd.crest_factor);
  float zk = zscore(f.kurtosis, baselineMean.kurtosis, baselineStd.kurtosis);
  float zs = zscore(f.spectral_centroid, baselineMean.spectral_centroid, baselineStd.spectral_centroid);

  // Umbral combinado (p. ej., cualquier |z| > 3)
  bool anomaly = baselineReady && (fabs(zr) > 3.0f || fabs(zc) > 3.0f || fabs(zk) > 3.0f || fabs(zs) > 3.0f);

  // 5) Construir y enviar payload LoRa
  Packet pkt;
  pkt.dev_id = devIdFromATECC();
  pkt.frame = frameCounter++;
  pkt.q_rms   = q15_from_float(f.rms, 1000.0f);           // g -> mg
  pkt.q_crest = q15_from_float(f.crest_factor, 1000.0f);  // adim
  // limita kurtosis razonable (0..20)
  float kurt_limited = fminf(fmaxf(f.kurtosis, 0.0f), 20.0f);
  pkt.q_kurt  = q15_from_float(kurt_limited, 1000.0f);
  // centróide en Hz, suponiendo < 1600 Hz -> escala 1
  float sc_limited = fminf(fmaxf(f.spectral_centroid, 0.0f), 1600.0f);
  pkt.q_sc    = q15_from_float(sc_limited, 1.0f);
  pkt.flags   = (anomaly ? 0x01 : 0x00);

  int16_t state = radio.transmit((uint8_t*)&pkt, sizeof(pkt));
  if (state == RADIOLIB_ERR_NONE) {
    Serial.printf("#%lu LoRa TX OK | RMS=%.4f g, CF=%.3f, K=%.3f, SC=%.1f Hz | anomaly=%d\n",
      (unsigned long)pkt.frame, f.rms, f.crest_factor, f.kurtosis, f.spectral_centroid, anomaly);
  } else {
    Serial.printf("LoRa TX fallo, code %d\n", state);
  }

  // 6) Respeta duty-cycle (ej., 1 envío por segundo aprox.)
  delay(1000);
}

Explicación breve de partes clave:
– Configuración de pines/buses: se fija I2C en SDA=8, SCL=9; y SPI en SCK=12/MISO=13/MOSI=11/CS=10, con RST y DIOs para el RFM95W.
– IMU: se configura ODR de 1.6 kHz y se habilita acelerómetro con LPF ~180 Hz para capturar vibraciones relevantes (puedes modificar ODR/LPF según tu máquina).
– Muestreo: se adquiere N_SAMPLES=512 puntos a ~1.6 kHz (≈320 ms de ventana).
– Features: se calculan RMS, crest factor, kurtosis (dominio del tiempo) y centróide espectral (dominio de frecuencia mediante FFT).
– Baseline: primeras 20 ventanas estiman medias y desviaciones, para luego calcular z-scores.
– Anomalía: gatilla si cualquier |z| > 3.
– ATECC608A: se lee el número de serie para derivar un dev_id estable. Si ya tienes el ATECC provisionado con clave, puedes firmar el hash del payload antes de transmitir (se deja fuera por simplicidad operativa).
– LoRa: RadioLib facilita setear frecuencia, BW=125 kHz, SF=9 (ajusta según SNR/datarate necesarios).

Compilación, flash y ejecución

1) Instala PlatformIO Core (CLI) si aún no lo tienes:
– Windows:
– pipx install platformio o py -m pip install –user platformio
– Ubuntu/macOS:
– python3 -m pip install –user platformio
– Verifica:
– pio –version → debería mostrar “PlatformIO Core, Home, Python…”

2) Crea el proyecto:
– pio project init –board esp32-s3-devkitc-1
– Sustituye el platformio.ini generado por el que se muestra arriba.
– Crea src/main.cpp y pega el código anterior.

3) Conecta la ESP32-S3-DevKitC-1 por USB-C. En Linux:
– ls /dev/ttyACM* → debería ver /dev/ttyACM0
– Si no, agrega permisos: sudo usermod -a -G dialout $USER y relogin.

4) Compila:
– pio run

5) Sube firmware:
– pio run -t upload
– Si necesitas especificar puerto: pio run -t upload -e esp32-s3-devkitc-1 –upload-port /dev/ttyACM0

6) Abre monitor serie:
– pio device monitor –baud 115200
– Si el puerto cambia tras reset, especifica: pio device monitor –port /dev/ttyACM0 –baud 115200

7) Salida esperada al iniciar:
– [ESP32-S3] lora-predictive-vibration-icm42688
– ICM-42688-P inicializado.
– ATECC608A S/N: XXXXXXX…
– SX1276 (RFM95W) inicializado.
– Baseline listo. (tras ~20 ventanas)

Validación paso a paso

1) Validación de hardware (sin firmware):
– Verifica continuidad GND común.
– Verifica 3V3 estable en VCC de RFM95W, ICM-42688-P y ATECC608A.
– Comprueba la dirección I2C con un escáner simple (opcional): debería ver 0x68 y 0x60.

2) Validación de inicialización:
– En el monitor serie, confirma los mensajes:
– “ICM-42688-P inicializado.”
– “ATECC608A S/N: …”
– “SX1276 (RFM95W) inicializado.”
– Si falla alguno, revisa el apartado Troubleshooting.

3) Validación de muestreo/FFT:
– Con el dispositivo inmóvil, observa:
– RMS bajo (p. ej., < 0.02 g), centróide ~ muy bajo (ruido).
– Kurtosis cerca de 3 (gaussiano ideal).
– Induce vibración (pe. motor con desequilibrio, golpe suave):
– RMS sube.
– Crest factor sube si hay picos.
– Centróide se desplaza hacia la frecuencia dominante.

4) Validación de baseline/anomalía:
– Tras “Baseline listo.”, repite la inducción de vibración:
– Observa anomaly=1 cuando el z-score supera el umbral.
– Si no se gatilla, incrementa sensibilidad (reduce baselineStd o baja umbral a 2.5).

5) Validación de LoRa TX:
– En el monitor serie: “LoRa TX OK” por cada frame.
– Con un receptor LoRa (opcional), configura la misma modulación (BW=125 kHz, SF=9, CR=4/5, SyncWord=0x34, frecuencia regional) y captura payload de 17 bytes.
– Decodifica el payload (dev_id, frame, q_rms mg, q_crest1e-3, q_kurt1e-3, q_sc Hz, flags).
– Si no tienes receptor, al menos confirma que la transmisión no da error y que el LED en el RFM95W (si existe) muestra actividad RF (no todos los módulos tienen LED).

6) Validación de ATECC:
– Verifica que el S/N impreso permanece constante entre reinicios.
– Opcional: prueba una llamada atcab_random() y muestra 32 bytes aleatorios (para confirmar crypto HAL). No usado en el payload base.

7) Medidas cuantitativas de referencia:
– Inmóvil:
– RMS ~ 0.005–0.02 g
– CF ~ 1.2–2.0
– K ~ 2.5–3.5
– SC ~ < 50 Hz
– Vibrando:
– RMS > 0.05 g (según condición)
– CF puede subir a 3–8 si hay impactos.
– SC tiende a la frecuencia de vibración (100–300 Hz típico en pequeños motores, o acorde a tu excitación).

Troubleshooting

1) No aparece puerto serie / no sube el firmware:
– Revisa cable USB (que soporte datos).
– Prueba otro puerto USB del equipo.
– Mantén pulsado BOOT al reset para forzar modo descarga (si aplica).
– En Linux: agrega tu usuario a dialout; asegura permisos en /dev/ttyACM*.
– En macOS, cierra apps que capturan el puerto (p. ej., otro monitor serie).

2) “ICM-42688-P no responde en 0x68”:
– Revisa SDA=GPIO8, SCL=GPIO9, VCC=3V3, GND.
– Asegúrate de que AD0 está a GND si usas 0x68 (o cambia la dirección en el código a 0x69).
– Verifica que Wire.begin(I2C_SDA, I2C_SCL, 400000) no sea llamado dos veces con otros pines.
– Baja la velocidad I2C a 100 kHz en casos de cables largos.

3) ATECC init fallo (códigos – falla en atcab_init o read serial):
– Confirma SDA/SCL compartidos correctamente con IMU.
– Verifica dirección 0x60.
– Algunos breakouts requieren pull-ups a 3.3V (4.7 kΩ). Asegura que existan (al menos en un dispositivo del bus).
– Si persiste, prueba a inicializarlo antes del IMU (orden de init a veces afecta en bus compartido).

4) LoRa init fallo, code -2/-5 (RadioLib):
– Verifica cableado SPI (SCK=12, MISO=13, MOSI=11, CS=10, RST=18, DIO0=17).
– Asegura que SPI.begin() usa esos pines.
– Revisa que VCC=3.3V (no 5V) y consumo suficiente (≈120 mA en TX).
– Cambia la frecuencia a la adecuada para tu módulo/región (p. ej., 915.0 para US).

5) LoRa TX fallo al transmitir:
– Reduce potencia (radio.setOutputPower(10)) si tu alimentación es marginal.
– Aumenta preámbulo (radio.setPreambleLength(12)) para robustez.
– Asegura antena adecuada a la banda (SWR razonable).

6) Lecturas de IMU ruidosas o saturadas:
– Baja el rango a ±4 g si saturas menos (setAccelRange(g4)) o súbelo a ±16 g si saturas por impactos.
– Ajusta LPF (100–180 Hz típicos, según vibración de interés).
– Monta mecánicamente la IMU con tornillos o cinta de espuma para evitar resonancias parásitas.

7) Baseline nunca “listo” o demasiados falsos positivos:
– Aumenta WARMUP_WINDOWS (p. ej., 50).
– Calcula std real con un buffer deslizante (mejora sugerida abajo).
– Subir umbral a 3.5 o 4 si hay demasiado ruido.

8) El monitor serie no muestra nada:
– Asegura build_flags con USB CDC on boot.
– Cambia monitor_port al dispositivo correcto (Windows: COMx; Linux: /dev/ttyACM0).
– Pulsa RESET y reabre monitor.

Mejoras/variantes

• LoRaWAN (The Things Network):
• Sustituir RadioLib por una pila LoRaWAN (p. ej., mcci-catena LMIC o RadioLib LoRaWAN si soportado).
• ATECC608A para almacenar AppKey/NwkKey y hacer join seguro.

• Cuidado con duty-cycle y tamaño de payload (codificar features de manera compacta).

• Mejor baseline/anomalía:

• Mantener un buffer circular de M ventanas y calcular media/desviación robustas (mediana/MAD).
• Modelado espectral: comparar picos dominantes y su desplazamiento a lo largo del tiempo.

• One-class SVM o autoencoders con cuantización fija (TinyML). EloquentTinyML o TFLM si te mantienes en 20–30 kB de RAM para el modelo.

• Ampliación de características:

• Band energy ratios (BER) para bandas [0–100, 100–300, 300–600 Hz…].
• Envolvente Hilbert o demodulación para vibración de rodamientos.

• Kurtosis espectral, skewness, picos armónicos.

• ATECC608A: autenticidad e integridad:

• Firmar SHA-256 del payload con atcab_sign() si la clave privada está provisionada en Slot 0.
• En el receptor, validar con la clave pública correspondiente.

• Añadir un nonce/challenge para evitar repetición.

• Gestión de energía:

• Dormir entre ventanas y despertar con temporizador.

• Ajustar potencia LoRa y SF según calidad de enlace medido.

• Robustez RF:

• Saltos de frecuencia (FHSS simple a nivel de aplicación).

• Retransmisión con ACK por un receptor si implementas enlace a medida.

• Calibración y alineación:

• Compensación de gravedad (restar media DC por eje).
• Montaje con orientación conocida (usar combinaciones ax/ay/az o magnitud sqrt).

Checklist de verificación

• [ ] He instalado PlatformIO Core 6.1.15 y verificado pio –version.
• [ ] platformio.ini usa platform = espressif32 @ 6.6.0 y framework-arduinoespressif32 @ 3.0.7.
• [ ] He cableado I2C en SDA=GPIO8, SCL=GPIO9 para ICM-42688-P (0x68) y ATECC608A (0x60).
• [ ] He cableado SPI LoRa con SCK=12, MISO=13, MOSI=11, CS=10, RST=18, DIO0=17, DIO1=16.
• [ ] Compila sin errores: pio run OK.
• [ ] Carga sin errores: pio run -t upload OK.
• [ ] Monitor serie muestra inicializaciones correctas (IMU, ATECC S/N, LoRa).
• [ ] Tras 20 ventanas, aparece “Baseline listo.”.
• [ ] Induciendo vibración, veo RMS/CF/SC aumentar y a veces anomaly=1.
• [ ] Veo “LoRa TX OK” por frame (1 Hz aprox.).
• [ ] (Opcional) Un receptor LoRa con misma modulación ve payloads de 17 bytes coherentes.

---

Notas finales:
– Este caso práctico mantiene coherencia total con el hardware “ESP32-S3-DevKitC-1 + RFM95W (SX1276) + ICM-42688-P + ATECC608A”, en materiales, conexiones, código y comandos.
– La cadena de herramientas exacta y las versiones fijadas garantizan reproducibilidad. Si alguna versión cambia, mantén los mismos números en platformio.ini para evitar variaciones del entorno.
– Ajusta la frecuencia LoRa a tu región y respeta la normativa local (duty-cycle, potencia, bandas).

Objetivo y caso de uso

Qué construirás: Un rover autoequilibrado utilizando un Arduino Nano 33 BLE Sense, un controlador TB6612FNG y un sensor AS5600 para la detección de posición.

Para qué sirve

• Control de equilibrio en tiempo real para vehículos robóticos.
• Aplicaciones en robótica educativa para enseñar principios de control y estabilidad.
• Integración de sensores para mejorar la navegación autónoma en entornos complejos.
• Prototipos de vehículos que requieren ajuste dinámico de posición.

Resultado esperado

• Estabilidad del rover con un tiempo de respuesta de menos de 100 ms.
• Latencia en la comunicación entre el IMU y el controlador de motor inferior a 50 ms.
• Capacidad de mantener el equilibrio en superficies inclinadas de hasta 15 grados.
• Medición de la posición angular con una precisión de ±1 grado utilizando el AS5600.

Público objetivo: Estudiantes y profesionales en robótica; Nivel: Avanzado

Arquitectura/flujo: Sensor IMU (LSM9DS1) -> Procesador (nRF52840) -> Controlador de motor (TB6612FNG) -> Actuadores (motores del rover).

Nivel: Avanzado

Prerrequisitos

Sistema operativo y herramientas (versiones probadas)

• Windows 11 23H2, macOS 14.5 (Sonoma) o Ubuntu 22.04 LTS.
• Git 2.44.0 o superior.
• Python 3.11.x (probado con 3.11.9).
• PlatformIO Core 6.1.15 (CLI). Nota: Usaremos PlatformIO para la placa Arduino Nano 33 BLE Sense (nRF52840, Mbed OS). No usaremos Arduino IDE/GUI.

Toolchain concreta (con versiones)

• PlatformIO Core (pio) 6.1.15.
• Plataforma: nordicnrf52 @ 10.3.1 (pinned).
• Board ID: nano33ble (compatible con Arduino Nano 33 BLE y BLE Sense, MCU nRF52840).
• Framework: arduino (Mbed OS para Nano 33 BLE Sense).
• Paquete del compilador: toolchain-gccarmnoneeabi@1.90301.0 (GCC 9-2019-q4-major) fijado para reproducibilidad.
• Librerías de proyecto (pinned):
• Arduino_LSM9DS1@1.1.0 (IMU de Nano 33 BLE Sense Rev1).
• AS5600@0.4.1 (librería de Rob Tillaart para encoder magnético).
• ArduinoBLE@1.3.5 (opcional si luego quieres telemetría BLE; aquí la dejaremos como comentada).

Nota importante sobre IMU: Este caso práctico utiliza la IMU LSM9DS1 (Nano 33 BLE Sense Rev1). Si dispones de un Nano 33 BLE Sense Rev2 (LSM6DSOX), sustituye la librería por Arduino_LSM6DSOX y adapta las llamadas. Más adelante se indica la variante.

Materiales

• 1 x Arduino Nano 33 BLE Sense (modelo con IMU LSM9DS1).
• 1 x Driver de motor TB6612FNG (placa breakout doble canal A/B).
• 1 x Sensor AS5600 (encoder magnético absoluto I2C, 12 bits, dirección 0x36).
• 2 x Motores DC con caja reductora, 6–12 V, con ruedas (igualados).
• 1 x Batería LiPo 2S (7.4 V) con interruptor.
• 1 x Imán diametral para el AS5600 (6–8 mm), montado en eje de rueda o eje intermedio.
• Cables de puente macho-macho y macho-hembra.
• Porta-baterías o cinta de fijación.
• Soporte temporal para pruebas (p. ej., varillas o un marco que impida caídas mientras ajustas el control).
• 1 x Convertidor buck si necesitas derivar 5 V auxiliares (no requerido para la lógica: el Nano 33 BLE Sense funciona a 3.3 V y se alimenta por USB durante el desarrollo).
• Elementos de seguridad: gafas, superficie acolchada para evitar daños al robot durante el ajuste.

Preparación y conexión

Consideraciones de alimentación

• TB6612FNG:
• VM (potencia motores): 6–12 V desde la batería (recomendado 2S LiPo).
• VCC (lógica): 3.3 V desde el pin 3V3 del Nano 33 BLE Sense.

• GND común: une GND del driver, GND del Arduino y GND de la batería.

• Arduino Nano 33 BLE Sense: durante el desarrollo, aliméntalo via USB. En modo autónomo, puedes alimentar por VIN (5–21 V) si la batería lo permite, o usar un regulador DC/DC a 5 V/USB.

• AS5600: se alimenta con 3.3 V. Asegúrate de que la placa del AS5600 soporte 3.3 V en VCC y que I2C sea 3.3 V.

Tabla de conexiones

La siguiente tabla asigna pines del Nano 33 BLE Sense a TB6612FNG y AS5600. Las líneas PWM deben ser pines con soporte PWM en el Nano 33 BLE.

Notas:
– Comprueba el mapping físico de SDA/SCL en tu placa; en Nano 33 BLE Sense suelen estar serigrafiados como SDA/SCL y corresponden a A4/A5.
– Si inviertes los cables del motor, solo tendrás que corregir “signos” en software (o viceversa).
– Montaje AS5600: el imán debe estar centrado con el chip, a ~2 mm de distancia. Fija mecánicamente para evitar variaciones.

Orientación del IMU

Para este proyecto, asume:
– La placa se monta verticalmente formando el “cuerpo” del rover.
– El eje de pitch (inclinación hacia adelante/atrás) es el eje X del IMU.
– USB mirando hacia la izquierda del rover y el conector de pines hacia arriba.
Si tu montaje difiere, ajusta el cálculo de ángulos (mapear ejes o cambiar signos).

Código completo

A continuación, el firmware en C++ (framework Arduino) que:
– Lee IMU (LSM9DS1) y filtra el ángulo de pitch con un filtro complementario.
– Lee ángulo del AS5600 para estimar velocidad de rueda.
– Ejecuta un control PID de equilibrio con término de velocidad de rueda como “damping” adicional.
– Comanda los motores vía TB6612FNG.

Archivo: src/main.cpp

#include <Arduino.h>
#include <Wire.h>
#include <AS5600.h>            // Rob Tillaart AS5600 library
#include <Arduino_LSM9DS1.h>   // IMU Arduino Nano 33 BLE Sense (Rev1)

// -------------------- Configuración de pines TB6612FNG --------------------
constexpr uint8_t PIN_STBY = 8;
constexpr uint8_t PIN_AIN1 = 4;
constexpr uint8_t PIN_AIN2 = 5;
constexpr uint8_t PIN_PWMA = 9;    // PWM
constexpr uint8_t PIN_BIN1 = 6;
constexpr uint8_t PIN_BIN2 = 7;
constexpr uint8_t PIN_PWMB = 10;   // PWM

// -------------------- Parámetros de control --------------------
static float loop_hz = 500.0f;     // Frecuencia de control (Hz)
static float dt = 1.0f / 500.0f;
static const float alpha = 0.98f;  // Filtro complementario

// PID del ángulo (pitch)
volatile float Kp = 24.0f;
volatile float Ki = 2.0f;
volatile float Kd = 0.35f;

// “Damping” adicional con velocidad de rueda estimada (AS5600)
volatile float Kv = 0.05f;

// Límites de salida
static const int16_t PWM_MAX = 255;    // Máx. 8 bits (PlatformIO mapea a 0-255)
static const float ANGLE_LIMIT_DEG = 20.0f; // Apagar si sobrepasa

// -------------------- Estado --------------------
AS5600 as5600;            // I2C addr 0x36 por defecto
float as5600_prev_angle = 0.0f;  // [rad], absoluto 0..2π
unsigned long as5600_prev_ms = 0;

// Offset y escala IMU
float gyro_bias_x = 0.0f, gyro_bias_y = 0.0f, gyro_bias_z = 0.0f; // [dps]
float pitch_deg = 0.0f;                 // Ángulo estimado [deg]
float pitch_rate_dps = 0.0f;            // Velocidad angular [deg/s]

// PID internals
float err_int = 0.0f;
float err_prev = 0.0f;

// Dirección de motores (puede ajustarse según cableado)
int motor_sign_left = +1;
int motor_sign_right = +1;

// -------------------- Utilidades TB6612FNG --------------------
void tb6612_init() {
  pinMode(PIN_STBY, OUTPUT);
  pinMode(PIN_AIN1, OUTPUT);
  pinMode(PIN_AIN2, OUTPUT);
  pinMode(PIN_PWMA, OUTPUT);
  pinMode(PIN_BIN1, OUTPUT);
  pinMode(PIN_BIN2, OUTPUT);
  pinMode(PIN_PWMB, OUTPUT);
  digitalWrite(PIN_STBY, HIGH); // Habilitar
}

void setMotorRaw(bool chA, int16_t pwm) {
  // pwm en rango [-255, 255], signo = sentido
  uint8_t pinIn1 = chA ? PIN_AIN1 : PIN_BIN1;
  uint8_t pinIn2 = chA ? PIN_AIN2 : PIN_BIN2;
  uint8_t pinPWM = chA ? PIN_PWMA : PIN_PWMB;

  int16_t val = constrain(pwm, -PWM_MAX, PWM_MAX);
  if (val > 0) {
    digitalWrite(pinIn1, HIGH);
    digitalWrite(pinIn2, LOW);
    analogWrite(pinPWM, val);
  } else if (val < 0) {
    digitalWrite(pinIn1, LOW);
    digitalWrite(pinIn2, HIGH);
    analogWrite(pinPWM, -val);
  } else {
    // freno libre: IN1=LOW, IN2=LOW (coast) o freno activo IN1=HIGH, IN2=HIGH
    digitalWrite(pinIn1, LOW);
    digitalWrite(pinIn2, LOW);
    analogWrite(pinPWM, 0);
  }
}

void setMotors(int16_t left, int16_t right) {
  setMotorRaw(true,  motor_sign_left * left);
  setMotorRaw(false, motor_sign_right * right);
}

// -------------------- IMU --------------------
bool imu_init_and_calibrate() {
  if (!IMU.begin()) {
    return false;
  }
  delay(50);

  // Intentar fijar tasa de muestreo razonable si está disponible
  // Nota: Arduino_LSM9DS1 no expone fácilmente ODR desde el wrapper Arduino;
  // trabajamos con lectura en bucle fijo y dt estable.
  // Calibración de offset giroscópico:
  const int N = 2000; // ~4 s @500 Hz
  gyro_bias_x = gyro_bias_y = gyro_bias_z = 0.0f;
  int count = 0;

  while (count < N) {
    float gx, gy, gz, ax, ay, az;
    bool ok = IMU.gyroscopeAvailable() && IMU.accelerationAvailable();
    if (ok) {
      IMU.readGyroscope(gx, gy, gz);        // dps
      IMU.readAcceleration(ax, ay, az);     // g
      gyro_bias_x += gx;
      gyro_bias_y += gy;
      gyro_bias_z += gz;
      count++;
    }
    delayMicroseconds(1000); // ~1 kHz loop en calibración
  }
  gyro_bias_x /= N; gyro_bias_y /= N; gyro_bias_z /= N;

  // Inicializa pitch con acelerómetro (suponiendo montaje vertical)
  float ax, ay, az;
  if (IMU.accelerationAvailable()) {
    IMU.readAcceleration(ax, ay, az);
    // Pitch ≈ atan2(-ax, sqrt(ay^2 + az^2)) en grados (depende de orientación)
    float pitch0 = atan2f(-ax, sqrtf(ay*ay + az*az)) * 180.0f / PI;
    pitch_deg = pitch0;
  }
  return true;
}

// Lee sensores y actualiza pitch
void imu_step() {
  float gx, gy, gz, ax, ay, az;
  if (IMU.gyroscopeAvailable()) {
    IMU.readGyroscope(gx, gy, gz);
    gx -= gyro_bias_x;
    gy -= gyro_bias_y;
    gz -= gyro_bias_z;
  } else {
    gx = gy = gz = 0.0f;
  }
  if (IMU.accelerationAvailable()) {
    IMU.readAcceleration(ax, ay, az);
  } else {
    ax = ay = 0.0f; az = 1.0f;
  }

  // Velocidad de pitch (deg/s): asumir eje de pitch = X
  pitch_rate_dps = gx;

  // Ángulo de pitch desde acelerómetro (grados)
  float pitch_acc_deg = atan2f(-ax, sqrtf(ay*ay + az*az)) * 180.0f / PI;

  // Filtro complementario
  pitch_deg = alpha * (pitch_deg + pitch_rate_dps * dt) + (1.0f - alpha) * pitch_acc_deg;
}

// -------------------- AS5600 --------------------
bool as5600_init() {
  Wire.begin();
  // Librería Rob Tillaart: setup básico
  if (!as5600.begin(AS5600_DEFAULT_ADDRESS)) {
    return false;
  }
  // Modo de potencia normal
  as5600.setPowerMode(AS5600_NORMAL);
  // Guardar ángulo inicial como referencia
  as5600_prev_angle = as5600.getRadians();
  as5600_prev_ms = millis();
  return true;
}

float as5600_wheel_speed_rads() {
  // Diferencia de ángulo con “unwrap” simple
  float angle = as5600.getRadians(); // 0..2π
  float da = angle - as5600_prev_angle;
  // unwrapping
  if (da > PI)  da -= 2.0f * PI;
  if (da < -PI) da += 2.0f * PI;
  unsigned long now = millis();
  float dt_s = (now - as5600_prev_ms) / 1000.0f;
  if (dt_s <= 0) dt_s = 1e-3f;

  float omega = da / dt_s; // rad/s

  as5600_prev_angle = angle;
  as5600_prev_ms = now;
  return omega;
}

// -------------------- Control --------------------
void safety_stop() {
  setMotors(0, 0);
  // Mantener STBY en alto, pero sin PWM
}

int16_t control_step(float pitch_setpoint_deg, float wheel_vel_rads) {
  float err = pitch_setpoint_deg - pitch_deg;
  err_int += err * dt;

  // Derivada sobre la medida (para reducir ruido)
  float err_der = -(pitch_rate_dps);

  // PID del ángulo
  float u = Kp * err + Ki * err_int + Kd * err_der;

  // Damping con velocidad de rueda (reduce oscilaciones)
  u -= Kv * wheel_vel_rads;

  // Anti-windup simple: limitar integral si saturamos
  float u_sat = constrain(u, -PWM_MAX, PWM_MAX);
  if (u != u_sat) {
    // retrocálculo proporcional
    err_int -= 0.1f * (u - u_sat) / max(1.0f, Ki);
  }
  return (int16_t)u_sat;
}

// -------------------- Setup y loop --------------------
void setup() {
  Serial.begin(115200);
  while (!Serial && millis() < 2000) { /* wait up to 2s */ }

  tb6612_init();
  setMotors(0, 0);

  if (!as5600_init()) {
    Serial.println("ERROR: AS5600 no encontrado (I2C 0x36). Revisa SDA/SCL/3V3/GND.");
    // seguimos, pero sin damping por rueda
  } else {
    Serial.println("AS5600 OK");
  }

  if (!imu_init_and_calibrate()) {
    Serial.println("ERROR: IMU no inicializada. Revisa Arduino_LSM9DS1 y alimentación.");
    while (true) { delay(1000); }
  }
  Serial.println("IMU calibrada. Iniciando control...");

  // Configurar la frecuencia de control
  dt = 1.0f / loop_hz;
}

void loop() {
  static unsigned long last_us = micros();
  unsigned long now_us = micros();
  float elapsed = (now_us - last_us) / 1000000.0f;
  if (elapsed < dt) {
    // esperar el siguiente tick
    delayMicroseconds(100);
    return;
  }
  last_us = now_us;

  // Leer sensores
  imu_step();
  float wheel_vel = as5600_prev_ms ? as5600_wheel_speed_rads() : 0.0f;

  // Seguridad por ángulo excesivo
  if (fabs(pitch_deg) > ANGLE_LIMIT_DEG) {
    safety_stop();
    // Indicar estado por serial
    static uint32_t t0 = 0;
    if (millis() - t0 > 200) {
      Serial.println("Fuera de rango. Coloca el rover vertical y reinicia.");
      t0 = millis();
    }
    return;
  }

  // Setpoint de pitch
  float pitch_sp = 0.0f; // vertical

  // Control
  int16_t u = control_step(pitch_sp, wheel_vel);

  // Reparto simétrico a ambos motores
  setMotors(u, u);

  // Telemetría básica
  static uint32_t last_print = 0;
  if (millis() - last_print > 50) { // 20 Hz
    Serial.print("pitch=");
    Serial.print(pitch_deg, 2);
    Serial.print(" dps=");
    Serial.print(pitch_rate_dps, 1);
    Serial.print(" wheel_radps=");
    Serial.print(wheel_vel, 2);
    Serial.print(" u=");
    Serial.println(u);
    last_print = millis();
  }
}

Explicación breve de partes clave

• Filtro complementario (alpha=0.98): combina giroscopio (integración rápida) y acelerómetro (referencia de gravedad) para estimar pitch robusto y con baja deriva.
• Calibración de giroscopio: promedia lecturas en reposo para eliminar bias; mejora notablemente el control.
• Control PID: salida en unidades de PWM. El término derivativo usa la velocidad de pitch medida (sobre la medida) para mitigar ruido. El término Ki integra lentamente para corregir pequeñas desviaciones.
• Damping por velocidad de rueda (Kv): reduce el “péndulo” aprovechando el AS5600; si no hay AS5600 disponible/funcional, Kv puede ponerse a 0.
• Safety: si |pitch| > 20°, se desactiva PWM para evitar caídas violentas.
• setMotors: encapsula la lógica de dirección y PWM para TB6612FNG por canal.

Variante para Nano 33 BLE Sense Rev2 (LSM6DSOX)

• Sustituye en platformio.ini la librería Arduino_LSM9DS1 por Arduino_LSM6DSOX.
• Cambia include y lectura de IMU:
• #include <Arduino_LSM6DSOX.h>
• Reemplaza IMU por IMU (misma API: IMU.begin(), IMU.gyroscopeAvailable(), IMU.accelerationAvailable(), etc.). La API Arduino es casi equivalente.

Compilación, carga y ejecución

Estructura mínima del proyecto

• platformio.ini
• src/main.cpp

Archivo: platformio.ini

[env:nano33ble]
platform = nordicnrf52@10.3.1
board = nano33ble
framework = arduino
platform_packages =
  toolchain-gccarmnoneeabi@1.90301.0
lib_deps =
  arduino-libraries/Arduino_LSM9DS1@1.1.0
  robtillaart/AS5600@0.4.1
;  arduino-libraries/ArduinoBLE@1.3.5
monitor_speed = 115200
monitor_filters = time, default
build_flags =
  -DCORE_DEBUG_LEVEL=0

Instalación de PlatformIO Core (si no lo tienes)

• Windows/macOS/Linux con Python 3.11.x:
• pipx recomendado:
  • pipx install platformio
• o con pip:
  • python -m pip install --user platformio

Verifica la versión:

pio --version

Debe mostrar 6.1.15.

Inicializar proyecto y dependencias

1. Crea directorio:
   mkdir imu-self-balancing-rover && cd imu-self-balancing-rover
2. Inicializa proyecto:
   pio project init --board nano33ble
3. Sustituye platformio.ini por el mostrado arriba.
4. Copia el código a src/main.cpp.
5. Instala dependencias explícitamente (opcional; PlatformIO las resuelve en el primer build):
   pio pkg install --library "arduino-libraries/Arduino_LSM9DS1@1.1.0"
pio pkg install --library "robtillaart/AS5600@0.4.1"

Compilación

pio run

Carga (upload)

• Conecta el Nano 33 BLE Sense por USB. En Windows aparecerá un puerto COM; en macOS/Linux /dev/ttyACM0 o similar.
• En Linux, si recibes error de permisos en /dev/ttyACM0:
• sudo usermod -aG dialout $USER
• Cierra sesión y vuelve a entrar.
• Carga el firmware:
  pio run -t upload --upload-port /dev/ttyACM0
  Sustituye el puerto si es necesario (Windows: COM7, p. ej.).

Monitor serie

pio device monitor -b 115200 --eol LF

Verás líneas tipo:

AS5600 OK
IMU calibrada. Iniciando control...
[12:34:56.789] pitch=0.45 dps=0.2 wheel_radps=0.01 u=5

Validación paso a paso

1) Validar IMU en reposo

• Coloca el rover en un soporte vertical, quieto.
• Conecta el monitor serie.
• Observa:
• “IMU calibrada. Iniciando control…”
• pitch ≈ 0 ± 1.5° en reposo.
• dps cercano a 0 (|dps| < 0.5).
• Si no, revisa calibración (repetir reset con el rover completamente quieto).

2) Validar AS5600

• Gira lentamente la rueda con el imán.
• En telemetría, wheel_radps debe ser distinto de 0 y cambiar de signo según sentido.
• Gira continuamente: se esperan valores típicos entre ±5 rad/s para ruedas lentas, más si giras rápido.

3) Validar drivers de motor (sin control)

• Temporalmente, comenta la lógica de safety y control y fija un PWM bajo para probar sentidos (por ejemplo, en setup tras tb6612_init()):
• setMotors(+60, +60); delay(1000); setMotors(-60, -60); delay(1000); setMotors(0,0);
• Comprueba que ambos motores giran y que con el mismo signo giran hacia adelante. Si no, invierte motor_sign_left/right o intercambia cables.

4) Validación del bucle de control en soporte

• Habilita el código original.
• Sostén el rover vertical sobre un soporte que permita pequeñas oscilaciones sin caídas.
• Al soltar suavemente, debe intentar mantenerse, aplicando correcciones (escucharás el zumbido PWM).
• Observa telemetría: cuando se inclina hacia adelante (pitch positivo, por ejemplo), la salida u debe ir en el sentido que empuja hacia atrás para recuperar.

5) Ajuste inicial de PID

• Si oscila poco y cae, aumenta Kp en pasos de +2 hasta que “reaccione” con rapidez pero sin excederse.
• Si ves oscilación sostenida, aumenta Kd de 0.35 a 0.5–0.8 en pequeños pasos.
• Ki modera el error estático; sube lentamente (2.0 → 3.0 → 4.0). Si ves “deriva” de salida o overshoot lento, reduce Ki.
• Kv (damping por rueda): si el AS5600 reporta velocidad confiable, prueba subir Kv a 0.1–0.2 para amortiguar.

6) Validación en suelo

• Usa una superficie lisa y despejada.
• Enciende con el rover sujetado en vertical; suelta suavemente.
• Debe mantenerse unos segundos; afina PID para incrementar tiempo de equilibrio.
• Métrica: tiempo en equilibrio (>10 s), amplitud de oscilación (<±5°), deriva longitudinal aceptable.

7) Pruebas de seguridad

• Inclina deliberadamente más de 20°. Debe cortar motores (“Fuera de rango…”).
• Verifica que al volver a vertical y reiniciar, retoma el control.

Troubleshooting

1) No compila por librerías IMU
– Síntoma: error “Arduino_LSM9DS1.h not found”.
– Causa: librería no instalada o tienes un Nano 33 BLE Sense Rev2.
– Solución:
– Instala la librería: pio pkg install --library "arduino-libraries/Arduino_LSM9DS1@1.1.0".
– Si tu placa es Rev2, usa Arduino_LSM6DSOX y ajusta el include y lib_deps.

2) Error de puerto serie en Linux (permiso denegado)
– Síntoma: “Permission denied: /dev/ttyACM0”.
– Solución:
– sudo usermod -aG dialout $USER y reinicia sesión.
– Verifica pertenencia al grupo: groups.

3) Sin lectura de AS5600 (siempre 0)
– Síntoma: “ERROR: AS5600 no encontrado”.
– Causas:
– SDA/SCL intercambiados o sin pull-ups (las placas Nano 33 BLE Sense ya llevan pull-ups).
– VCC del AS5600 a 5 V en una placa que no lo soporta.
– Imán mal centrado o demasiado lejos.
– Soluciones:
– Verifica conexiones según la tabla.
– Alimenta a 3.3 V, comparte GND.
– Ajusta la distancia del imán (1.5–3 mm) y céntralo.
– Prueba un escáner I2C para ver 0x36 presente.

4) Motores no giran
– Síntoma: PWM u ≠ 0 en serie, pero motores parados.
– Causas:
– STBY en LOW; VM sin tensión; GND no común.
– PWM en pines sin soporte o soldaduras flojas.
– Soluciones:
– Comprueba D8 = HIGH (STBY).
– Mide VM con multímetro (6–12 V).
– Verifica que D9 y D10 son PWM y tienen continuidad.

5) Robo “tiembla” y cae
– Síntoma: vibración fuerte y pérdida de equilibrio.
– Causas:
– Kp muy alto, Kd muy bajo, fricción o backlash mecánico.
– Soluciones:
– Reduce Kp, aumenta Kd.
– Incrementa Kv si AS5600 está bien montado.
– Revisa holguras mecánicas y aprieta sujecciones.

6) Deriva constante hacia adelante/atrás
– Síntoma: mantiene equilibrio pero se desplaza.
– Causas:
– Bias residual del giroscopio; offset de pitch no centrado; ruedas con radios distintos.
– Soluciones:
– Repite calibración: enciende sin tocar el robot, sobre un soporte estable.
– Añade corrección de offset de pitch (sumar un pequeño bias al setpoint, p. ej., +0.3°).
– Igualar ruedas y presión.

7) Lecturas IMU ruidosas
– Síntoma: pitch “salta” o telemetría errática.
– Causas:
– Vibraciones de motor, cables cercanos a IMU, dt inestable.
– Soluciones:
– Añade espuma antivibración bajo la placa.
– Asegura dt constante (este código ya fuerza un intervalo).
– Baja loop_hz a 250 Hz y prueba alpha=0.97.

8) Se resetea al acelerar
– Síntoma: reinicios cuando la demanda de motor sube.
– Causas:
– Caída de tensión; ruido EMI; masa mal distribuida.
– Soluciones:
– Añade condensadores en VM (100 µF + 1 µF cerámico).
– Cables de potencia trenzados y separados de señales.
– Usa un buck dedicado para VIN del Arduino si alimentas todo de la misma batería.

Mejoras/variantes

• Segunda rueda con AS5600: añade otro AS5600 para estimar velocidad diferencial y mejorar control de trayectoria.
• Telemetría BLE: habilita ArduinoBLE para monitorizar pitch, PWM, tuning Kp/Ki/Kd desde una app móvil.
• Estimación avanzada de actitud: Madgwick/Mahony para mejorar frente a vibraciones, o un Kalman discreto.
• Control cascada completo:
• Lazo interno: pitch (rápido).
• Lazo externo: velocidad/posición (lento) con encoders (AS5600 x2).
• Modo “arranque asistido”: un algoritmo que detecte verticalidad, aplica rampas suaves de PWM.
• Limitación de corriente: mide corriente del motor (sensor ACS o shunt + ADC) y modula PWM para proteger.
• Modo “seguimiento”: añade un sensor de distancia (ToF o ultrasonidos) y controla desplazamiento manteniendo equilibrio.
• Ahorro energético: reduce PWM cuando el robot está estable; duerme IMU si queda inclinado y sin intento de recuperación.

Checklist de verificación

• [ ] Sistema operativo y Python 3.11.x instalados.
• [ ] PlatformIO Core 6.1.15 verificado con pio –version.
• [ ] Proyecto creado con board nano33ble y platform = nordicnrf52@10.3.1.
• [ ] platformio.ini con toolchain-gccarmnoneeabi@1.90301.0 y lib_deps fijados.
• [ ] Cableado conforme a la tabla (STBY→D8, PWMA→D9, PWMB→D10, etc.), GND común.
• [ ] AS5600 alimentado a 3.3 V, SDA→A4, SCL→A5, imán centrado.
• [ ] Compila sin errores: pio run.
• [ ] Carga correcta: pio run -t upload –upload-port .
• [ ] Monitor serie operativo a 115200 bps.
• [ ] IMU calibrada con el robot quieto al encender.
• [ ] Lecturas de pitch estables en reposo (±1.5°).
• [ ] Motores probados en ambos sentidos con PWM bajo.
• [ ] Control mantiene el equilibrio en soporte y luego en suelo.
• [ ] Ajuste Kp/Ki/Kd/Kv documentado y valores anotados finales.
• [ ] Prueba de seguridad: corte por |pitch| > 20° funciona.

---

Apéndice: comandos útiles de PlatformIO

• Limpiar build:
  pio run -t clean
• Reconocer puertos serie:
  pio device list
• Monitor con timestamp y reset a DTR desactivado:
  pio device monitor -b 115200 --eol LF --rts=0 --dtr=0

Notas finales de coherencia hardware/software

• Este caso práctico está diseñado específicamente para:
• Arduino Nano 33 BLE Sense (nRF52840, Mbed; usamos IMU LSM9DS1).
• Driver TB6612FNG para dos motores DC.
• Encoder magnético AS5600 por I2C para estimar velocidad de una rueda.
• Toda la toolchain, comandos y librerías están alineados con esa combinación.
• Si migras a Nano 33 BLE Sense Rev2, ajusta únicamente la librería IMU y mantén el resto igual.

Con esto dispones de un rover autoequilibrado funcional, reproducible con versiones fijadas y preparado para iterar en control, sensorización y robustez mecánica.

Objetivo y caso de uso

Qué construirás: Un registrador de calidad del aire de bajo consumo utilizando Arduino Nano 33 IoT, un display e-Paper de Waveshare y un sensor BME680.

Para qué sirve

• Monitoreo continuo de la calidad del aire en entornos urbanos.
• Visualización de datos de calidad del aire en tiempo real en un display e-Paper.
• Registro de datos históricos para análisis de tendencias de contaminación.
• Integración con sistemas de alerta mediante MQTT para notificaciones en tiempo real.

Resultado esperado

• Datos de calidad del aire actualizados cada 10 segundos con latencia mínima.
• Visualización de niveles de CO2, temperatura y humedad en el display e-Paper.
• Envío de datos a un servidor MQTT con una frecuencia de 1 paquete cada 30 segundos.
• Capacidad de operar con una duración de batería de más de 6 meses en modo de bajo consumo.

Público objetivo: Ingenieros y entusiastas de IoT; Nivel: Avanzado

Arquitectura/flujo: Arduino Nano 33 IoT -> BME680 -> e-Paper -> MQTT.

Nivel: Avanzado

Prerrequisitos

Sistema operativo y herramientas

• Sistemas operativos soportados:
• Linux: Ubuntu 22.04 LTS x86_64
• macOS: 13 Ventura o 14 Sonoma (Intel/Apple Silicon)

• Windows 11 Pro/Enterprise (x64)

• Toolchain exacta:

• Arduino CLI 0.35.3
• Core de placa: Arduino SAMD Boards 1.8.14
• Bibliotecas Arduino (vía Library Manager):
• GxEPD2 1.5.9
• Adafruit GFX Library 1.11.9
• Adafruit BME680 Library 2.0.3
• Adafruit Unified Sensor 1.1.14
• Adafruit BusIO 1.14.1
• ArduinoLowPower 1.2.2
• FlashStorage_SAMD 1.3.2

Notas:
– El Arduino Nano 33 IoT usa USB nativo. No requiere drivers en macOS ni Linux. En Windows 10/11 se instala como “USB Serial Device (COMx)”; no se necesitan drivers externos.
– Se usa Arduino CLI (no el IDE GUI) para todo el flujo: instalación del core, dependencias, compilación y subida.

Verificación del hardware y entorno

• Confirmar el puerto serie:
• Linux/macOS: típico /dev/ttyACM0 o /dev/tty.usbmodemXXXX
• Windows: COM3, COM4, etc. (ver en “Administrador de dispositivos”)
• Conexión a Internet para descargar cores y bibliotecas.
• Cable micro‑USB de datos (no solo carga).

Materiales

• 1x Arduino Nano 33 IoT (modelo exacto)
• 1x Módulo Waveshare 2.9″ e‑Paper monocromo con controlador SSD1680 (modelo exacto; versión b/w V2 con SSD1680)
• 1x Sensor ambiental BME680 (I2C)
• Cables Dupont macho‑hembra
• Protoboard (opcional, para ordenar cableado)

Observación sobre alimentación y niveles:
– El Nano 33 IoT funciona a 3.3 V lógicos, compatibles con la pantalla e‑Paper SSD1680 y con el BME680. No usar 5 V en señales.

Preparación y conexión

Disposición de pines y cableado

Para la pantalla Waveshare 2.9″ e‑Paper (SSD1680) se usará SPI. El módulo típico expone: VCC, GND, DIN (MOSI), CLK (SCK), CS, DC, RST, BUSY. No se usa MISO en el panel b/w.

Para el BME680 se usará I2C con alimentación a 3.3 V. La mayoría de breakout boards vienen con regulador y pull‑ups integradas; verificar el serigrafiado de su módulo.

Tabla de conexiones (Nano 33 IoT ↔ periféricos):

Indicaciones:
– Conecte el BME680 a los pines etiquetados “SDA” y “SCL” del Nano 33 IoT (no confundir con A4/A5 propios de placas AVR).
– La pantalla e‑Paper debe alimentarse con 3.3 V. No usar 5 V en VCC ni en señales.
– Mantenga cortos los cables SPI de la e‑Paper para minimizar ruido y artefactos de actualización.

Preparación del entorno de compilación

1) Descargar e instalar Arduino CLI 0.35.3:
– Linux:
– curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
– Verifique versión: arduino-cli version (debe mostrar 0.35.3)
– macOS:
– brew update && brew install arduino-cli
– Verifique: arduino-cli version
– Windows:
– Descargue el binario .exe de Arduino CLI 0.35.3 y añádalo al PATH.
– Verifique: arduino-cli version

2) Instalar el core de la placa SAMD (exacto):
– arduino-cli core update-index
– arduino-cli core install arduino:samd@1.8.14

3) Instalar bibliotecas exactas:
– arduino-cli lib install «GxEPD2@1.5.9»
– arduino-cli lib install «Adafruit GFX Library@1.11.9»
– arduino-cli lib install «Adafruit BME680 Library@2.0.3»
– arduino-cli lib install «Adafruit Unified Sensor@1.1.14»
– arduino-cli lib install «Adafruit BusIO@1.14.1»
– arduino-cli lib install «ArduinoLowPower@1.2.2»
– arduino-cli lib install «FlashStorage_SAMD@1.3.2»

4) Verificar que el FQBN esté disponible:
– arduino-cli board listall | grep -i «Nano 33 IoT»
– Debe listar: arduino:samd:nano_33_iot

Código completo

A continuación se entrega el sketch “epaper-air-quality-logger.ino”. El objetivo:
– Leer cada minuto el BME680 (T, H, P, gas).
– Calibrar un valor de baseline de gas durante los primeros 5 minutos.
– Calcular un índice simple de calidad de aire (IAQ%) basado en gas y humedad.
– Mostrar en e‑Paper: valores actuales y una minigráfica histórica.
– Registrar datos en memoria flash del SAMD21 con un buffer circular persistente.
– Permitir volcado de registros por Serial en CSV cuando se envía el comando “DUMP”.

Notas importantes para el display:
– Para Waveshare 2.9″ b/w V2 (SSD1680) usar la clase GxEPD2_290_T5 (128×296).
– Configuramos pines CS/DC/RST/BUSY según la tabla de conexión.

// epaper-air-quality-logger.ino
// Dispositivo: Arduino Nano 33 IoT + Waveshare 2.9" e-Paper (SSD1680) + BME680
// Toolchain: Arduino CLI 0.35.3, Core SAMD 1.8.14
// Bibliotecas: ver versiones en la sección de prerrequisitos

#include <Arduino.h>
#include <Wire.h>
#include <SPI.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME680.h>
#include <Adafruit_GFX.h>
#include <GxEPD2_BW.h>
#include <Fonts/FreeSans9pt7b.h>
#include <ArduinoLowPower.h>
#include <FlashStorage_SAMD.h>

// Pines e-Paper
#define EPD_CS   10
#define EPD_DC    9
#define EPD_RST   8
#define EPD_BUSY  7

// Instancia display: Waveshare 2.9" V2 (SSD1680) -> GxEPD2_290_T5 128x296
// Nota: GxEPD2 usa Adafruit_GFX como backend gráfico
#include <GxEPD2_3C.h>   // no se usará color; se incluye por compatibilidad
#include <GxEPD2_290.h>  // headers base
// Para SSD1680 (GDEW029T5 o equivalente):
class GxEPD2_290_T5; // forward decl. (incluido en librería)
GxEPD2_BW<GxEPD2_290_T5, GxEPD2_290_T5::HEIGHT> display(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY);

// BME680 por I2C
Adafruit_BME680 bme(&Wire);

// Configuración de logging y almacenamiento persistente
#define LOG_CAPACITY 288  // 288 muestras ~ 24 h si muestreamos cada 5 min (ajustable)
#define SAMPLE_PERIOD_MS (60UL * 1000UL)  // 60 s
#define CALIBRATION_TIME_MS (5UL * 60UL * 1000UL)  // 5 min de baseline

struct Measurement {
  uint32_t t_ms;   // tiempo desde arranque (ms)
  float temp;      // °C
  float hum;       // %RH
  float pres;      // hPa
  float gas;       // ohmios
  float iaq;       // 0..100 índice simple (no BSEC)
};

struct LogStore {
  uint32_t magic;     // firma para validar
  uint16_t head;      // próxima posición de escritura
  uint16_t count;     // nº de muestras válidas (<= LOG_CAPACITY)
  float gas_baseline; // baseline persistente del gas
  Measurement data[LOG_CAPACITY];
};

FlashStorage(log_store, LogStore);

static const uint32_t MAGIC = 0xA1Q1E0FF;

LogStore store;
uint32_t last_sample_ms = 0;
bool baseline_locked = false;

// Utilidades de mapeo/clamp
static inline float clampf(float v, float lo, float hi) {
  if (v < lo) return lo;
  if (v > hi) return hi;
  return v;
}

// Cálculo de IAQ simple (0-100) no equivalente a BSEC
float compute_iaq_percent(float gas, float gas_baseline, float humidity) {
  if (gas_baseline <= 0) return 0;
  // Puntuación de gas: mayor resistencia -> mejor aire (menos VOC)
  float gas_score = (gas / gas_baseline) * 100.0f;
  gas_score = clampf(gas_score, 0.0f, 100.0f);

  // Humedad ideal ~ 40% (penaliza desviaciones)
  float hum_score = 100.0f - fabsf(humidity - 40.0f) * 2.5f; // ±40% -> 0
  hum_score = clampf(hum_score, 0.0f, 100.0f);

  // Fusión ponderada (más peso a gas)
  float iaq = 0.75f * gas_score + 0.25f * hum_score;
  return clampf(iaq, 0.0f, 100.0f);
}

void drawHeader() {
  display.setFont(&FreeSans9pt7b);
  display.setTextColor(GxEPD_BLACK);
  display.setCursor(4, 16);
  display.print("epaper-air-quality-logger");
  display.setFont(); // volver a font por defecto para cuerpo
}

void drawReadings(const Measurement& m) {
  char line[48];

  snprintf(line, sizeof(line), "T: %.2f C  H: %.1f %%", m.temp, m.hum);
  display.setCursor(4, 36);
  display.print(line);

  snprintf(line, sizeof(line), "P: %.1f hPa  Gas: %.0f ohm", m.pres, m.gas);
  display.setCursor(4, 52);
  display.print(line);

  snprintf(line, sizeof(line), "IAQ*: %.1f /100  (baseline: %.0f)", m.iaq, store.gas_baseline);
  display.setCursor(4, 68);
  display.print(line);

  display.setCursor(4, 84);
  display.print("*Indice simplificado (no BSEC)");
}

void drawSparkline() {
  // Área de la minigráfica: x=4..292, y=90..120 (altura ~30 px)
  const int x0 = 4, y0 = 120, w = 288, h = 28;
  display.drawRect(x0-1, y0-h-1, w+2, h+2, GxEPD_BLACK);

  if (store.count == 0) {
    display.setCursor(x0, y0 - 8);
    display.print("Sin datos suficientes para graficar.");
    return;
  }

  // Graficar IAQ en 0..100 mapeado a altura
  int points = min((int)store.count, w);
  // Recorremos el log desde el más reciente hacia atrás
  int idx = (int)store.head - 1;
  if (idx < 0) idx = LOG_CAPACITY - 1;

  for (int i = 0; i < points; i++) {
    const Measurement& m = store.data[idx];
    float iaq = clampf(m.iaq, 0.0f, 100.0f);
    int y = y0 - (int)((iaq / 100.0f) * (float)h);
    int x = x0 + (w - 1 - i);
    display.drawPixel(x, y, GxEPD_BLACK);
    if (--idx < 0) idx = LOG_CAPACITY - 1;
  }
}

void epaperFullRefresh(const Measurement& last) {
  display.setFullWindow();
  display.firstPage();
  do {
    display.fillScreen(GxEPD_WHITE);
    drawHeader();
    drawReadings(last);
    drawSparkline();
  } while (display.nextPage());
}

void initStorage() {
  store = log_store.read();
  if (store.magic != MAGIC) {
    memset(&store, 0, sizeof(store));
    store.magic = MAGIC;
    store.head = 0;
    store.count = 0;
    store.gas_baseline = 0.0f;
    log_store.write(store);
  }
}

void appendMeasurement(const Measurement& m) {
  store.data[store.head] = m;
  store.head = (store.head + 1) % LOG_CAPACITY;
  if (store.count < LOG_CAPACITY) store.count++;
  // Escribimos bloque completo (flash) de forma conservadora (1/min)
  log_store.write(store);
}

bool setupBME680() {
  if (!bme.begin(0x76)) {         // la mayoría de BME680 usan 0x76
    if (!bme.begin(0x77)) {       // fallback si el jumper de su módulo selecciona 0x77
      return false;
    }
  }
  bme.setTemperatureOversampling(BME680_OS_8X);
  bme.setHumidityOversampling(BME680_OS_2X);
  bme.setPressureOversampling(BME680_OS_4X);
  bme.setIIRFilterSize(BME680_FILTER_SIZE_3);
  bme.setGasHeater(320, 150); // 320 C durante 150 ms
  return true;
}

bool readBME680(Measurement& m) {
  if (!bme.performReading()) return false;
  m.t_ms = millis();
  m.temp = bme.temperature;          // °C
  m.hum  = bme.humidity;             // %RH
  m.pres = bme.pressure / 100.0f;    // Pa -> hPa
  m.gas  = bme.gas_resistance;       // ohmios
  // Base line: primeras muestras (5 min) para calibrar gas
  if (!baseline_locked && m.t_ms < CALIBRATION_TIME_MS) {
    // Promedio incremental simple
    if (store.gas_baseline <= 0.0f) {
      store.gas_baseline = m.gas;
    } else {
      store.gas_baseline = (store.gas_baseline * 0.99f) + (m.gas * 0.01f);
    }
  } else if (!baseline_locked) {
    baseline_locked = true;
    // Persistir baseline tras calibración
    log_store.write(store);
  }

  float base = (store.gas_baseline > 0.0f) ? store.gas_baseline : m.gas;
  m.iaq = compute_iaq_percent(m.gas, base, m.hum);
  return true;
}

void dumpCSV() {
  Serial.println(F("#epaper-air-quality-logger CSV"));
  Serial.println(F("#t_ms,temp_c,hum_pct,pres_hpa,gas_ohm,iaq_pct"));
  int idx = store.head - store.count;
  if (idx < 0) idx += LOG_CAPACITY;
  for (int i = 0; i < store.count; i++) {
    const Measurement& m = store.data[idx];
    Serial.print(m.t_ms); Serial.print(',');
    Serial.print(m.temp, 2); Serial.print(',');
    Serial.print(m.hum, 1); Serial.print(',');
    Serial.print(m.pres, 1); Serial.print(',');
    Serial.print(m.gas, 0); Serial.print(',');
    Serial.println(m.iaq, 1);
    if (++idx >= LOG_CAPACITY) idx = 0;
  }
  Serial.println(F("#END"));
}

void setup() {
  Serial.begin(115200);
  while (!Serial && millis() < 3000) { } // breve ventana para consola

  initStorage();

  Wire.begin();
  if (!setupBME680()) {
    Serial.println(F("Error: BME680 no encontrado en 0x76/0x77"));
    // Seguimos para mostrar error en pantalla
  }

  // Inicialización del e-Paper
  display.init(115200); // SPI a 115200kHz internamente optimiza; se usa para debug
  display.setRotation(1); // apaisado (ancho 296, alto 128)
  // Pantalla inicial
  display.setFullWindow();
  display.firstPage();
  do {
    display.fillScreen(GxEPD_WHITE);
    drawHeader();
    display.setCursor(4, 40);
    display.print("Inicializando sensores...");
  } while (display.nextPage());

  last_sample_ms = 0;
}

void loop() {
  // Comandos por Serial
  if (Serial.available()) {
    int c = Serial.read();
    if (c == 'D' || c == 'd') {
      dumpCSV();
    }
  }

  uint32_t now = millis();
  if (now - last_sample_ms >= SAMPLE_PERIOD_MS || last_sample_ms == 0) {
    last_sample_ms = now;

    Measurement m{};
    if (readBME680(m)) {
      appendMeasurement(m);
      epaperFullRefresh(m);
      Serial.print(F("OK: T=")); Serial.print(m.temp, 2);
      Serial.print(F("C H=")); Serial.print(m.hum, 1);
      Serial.print(F("% P=")); Serial.print(m.pres, 1);
      Serial.print(F("hPa GAS=")); Serial.print(m.gas, 0);
      Serial.print(F("ohm IAQ=")); Serial.print(m.iaq, 1);
      Serial.println(F("%"));
    } else {
      // Reporte de error y mostrar en e-Paper
      Serial.println(F("Error: performReading() BME680"));
      display.setFullWindow();
      display.firstPage();
      do {
        display.fillScreen(GxEPD_WHITE);
        drawHeader();
        display.setCursor(4, 48);
        display.print("Error lectura BME680");
      } while (display.nextPage());
    }
  }

  // Bajo consumo entre muestras
  LowPower.sleep(1000); // Sleep ligero 1s, repite hasta llegar al minuto
}

Explicación breve de partes clave:
– Baseline del gas: se promedia durante 5 minutos al arranque para normalizar la resistencia del sensor (que varía entre unidades y con el entorno). Luego se “congela” y se persiste.
– IAQ simplificado: no usa BSEC (Bosch), pero ofrece una métrica cualitativa de 0 a 100 que combina gas y humedad.
– e‑Paper: se usa un refresco completo por ciclo para simplificar. En mejoras proponemos pasar a parciales.
– Persistencia: usamos FlashStorage_SAMD para almacenar un buffer circular. Es un ejemplo didáctico: escribir flash con frecuencia conlleva desgaste; más abajo damos recomendaciones para mitigar.

Compilación, flasheo y ejecución

Se asume que el sketch está en un directorio llamado “epaper-air-quality-logger”.

Estructura sugerida:
– epaper-air-quality-logger/
– epaper-air-quality-logger.ino

Pasos:

1) Preparar el core y libs (si no lo hizo antes):

arduino-cli core update-index
arduino-cli core install arduino:samd@1.8.14
arduino-cli lib install "GxEPD2@1.5.9"
arduino-cli lib install "Adafruit GFX Library@1.11.9"
arduino-cli lib install "Adafruit BME680 Library@2.0.3"
arduino-cli lib install "Adafruit Unified Sensor@1.1.14"
arduino-cli lib install "Adafruit BusIO@1.14.1"
arduino-cli lib install "ArduinoLowPower@1.2.2"
arduino-cli lib install "FlashStorage_SAMD@1.3.2"

2) Compilar para Nano 33 IoT:

arduino-cli compile --fqbn arduino:samd:nano_33_iot epaper-air-quality-logger

3) Identificar el puerto (ejemplos):
– Linux: ls /dev/ttyACM
– macOS: ls /dev/tty.usbmodem
– Windows: mode | findstr COM (o ver en el Administrador de dispositivos)

4) Subir el binario:
– Linux/macOS:

arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:nano_33_iot epaper-air-quality-logger

• Windows (ajuste COMx):

arduino-cli upload -p COM4 --fqbn arduino:samd:nano_33_iot epaper-air-quality-logger

5) Abrir monitor serie a 115200 baudios:

arduino-cli monitor -p /dev/ttyACM0 -c baudrate=115200

En Windows:

arduino-cli monitor -p COM4 -c baudrate=115200

Validación paso a paso

1) Validación de arranque:
– La pantalla e‑Paper debe mostrar “epaper-air-quality-logger” y el texto “Inicializando sensores…” durante el primer ciclo.
– En el monitor serie, verá un mensaje de estado o un error del BME680 si no está detectado.

2) Detección del BME680:
– Si todo va bien, al cabo de ~1 minuto, se imprimirá por serie una línea con T, H, P, GAS e IAQ.
– La pantalla hará un refresco completo mostrando:
– Temperatura, humedad, presión
– Resistencia de gas
– IAQ (%) y el valor de baseline
– Un recuadro en la parte inferior para la minigráfica (al principio con pocos puntos)

3) Calibración de baseline:
– Durante los primeros 5 minutos, el baseline de gas se ajusta (valor fluctúa hacia un promedio).
– El campo “baseline” en la pantalla se estabilizará.
– baseline_locked pasa a true internamente y el valor queda persistido.

4) Registro en flash:
– Tras varios minutos, envíe “d” o “D” por el monitor serie.
– Debe aparecer un CSV con encabezado y filas: t_ms,temp_c,hum_pct,pres_hpa,gas_ohm,iaq_pct.
– Reinicie la placa (botón reset) y vuelva a pedir “DUMP”: la data debe persistir (no se pierde tras reset).

5) Minigráfica:
– A partir de ~10 muestras, la línea en el recuadro inferior debe mostrar una tendencia de IAQ (0..100) desplazándose hacia la izquierda con el tiempo.

6) Comprobación visual y numérica:
– Compare temperatura y humedad con otro termohigrómetro para validar orden de magnitud.
– Alterar el ambiente:
– Exponer brevemente a alcohol isopropílico o aliento cerca del sensor (sin tocar): la resistencia de gas bajará y el IAQ tenderá a disminuir (peor “calidad”).
– Volver a aire limpio: el IAQ se recupera gradualmente.

Troubleshooting

1) La pantalla e‑Paper no muestra nada / se queda en blanco
– Causas probables:
– Pines mal conectados (DC/CS/RST/BUSY invertidos).
– Falta de 3.3 V o masa común.
– Clase de panel incorrecta en GxEPD2.
– Solución:
– Verifique la tabla de pines. Asegure EPD_CS=10, EPD_DC=9, EPD_RST=8, EPD_BUSY=7.
– Confirme que su Waveshare es 2.9″ b/w V2 (SSD1680). La clase GxEPD2_290_T5 es la adecuada para SSD1680.
– Pruebe display.setRotation(0/1/2/3) por si el mapeo afecta coordenadas visibles.

2) BME680 no detectado en 0x76/0x77
– Causas:
– Cableado SDA/SCL invertido o en pines incorrectos.
– Alimentación a 5 V en lugar de 3.3 V o GND suelta.
– Dirección I2C configurada por puente a otra distinta.
– Solución:
– Conectar a los pines etiquetados SDA/SCL del Nano 33 IoT (no A4/A5).
– Usar un escáner I2C para confirmar dirección.
– Revisar soldaduras o jumpers en el módulo BME680.

3) Ghosting o artefactos en e‑Paper
– Causas:
– Actualizaciones muy frecuentes sin refresco completo.
– Cables SPI largos o ruidosos.
– Solución:
– Mantener el refresco completo cada cierto número de ciclos.
– Reducir longitud de cables y retorcer MOSI/SCK con GND cercano para minimizar ruido.

4) Subida falla: “No device found on…”
– Causas:
– Puerto incorrecto.
– El bootloader solo está activo unos segundos tras reset.
– Solución:
– Identificar el puerto correcto con arduino-cli board list.
– Pulsar reset doblemente para entrar en “modo bootloader” y reintentar upload.

5) Mensajes “Error lectura BME680”
– Causas:
– Tiempos de calentamiento del gas no satisfechos.
– Interferencias I2C o alimentación inestable.
– Solución:
– Verificar alimentación 3.3 V estable.
– Aumentar delay entre lecturas o revisar setGasHeater(320, 150).

6) Desgaste de flash evidente / errores de escritura
– Causas:
– Frecuencia de escritura muy alta.
– Solución:
– Incrementar intervalo de muestreo (p. ej., 5 minutos).
– Escribir en flash cada N muestras en lugar de cada vez (buffer RAM + commit).

7) e‑Paper parpadea demasiado
– Causa:
– Refresco completo en cada ciclo.
– Solución:
– Migrar a actualizaciones parciales para datos pequeños (ver mejoras).
– Usar full refresh cada X ciclos para “limpiar”.

8) IAQ no parece realista
– Causa:
– El IAQ simplificado no es equivalente a BSEC.
– Solución:
– Aplique BSEC2 de Bosch para IAQ calibrado y métricas como eCO2/VOC Index (ver mejoras).

Mejoras y variantes

• IAQ profesional con BSEC2:
• Sustituir el cálculo simple por Bosch BSEC2 para obtener IAQ, eCO2, bVOC con calibración robusta.

• Asegurarse de la compatibilidad de BSEC2 con SAMD21 y uso de licencias.

• Reducción de desgaste de flash:

• Implementar un buffer en RAM para N muestras (p. ej., 12) y escribir en flash en bloques.

• Reducir el muestreo a cada 5 minutos y LOG_CAPACITY = 288 para ~24 h.

• Actualización parcial de e‑Paper:

• Usar “setPartialWindow” y dibujar solo las áreas cambiadas (número IAQ/última barra del sparkline).

• Hacer un full-refresh cada 10 parciales para evitar ghosting.

• Exportación de datos:

• Implementar un comando “DUMPJSON” con ArduinoJson para exportar en JSON.

• Guardar en archivo CSV en microSD (si se añade un módulo microSD por SPI con su propio CS).

• Integración IoT:

• Publicar mediciones por WiFi (Nano 33 IoT) a MQTT/InfluxDB y mantener la e‑Paper como tablero local.

• Sincronizar hora por NTP y almacenar timestamps UNIX en el log.

• Energía:

• Usar “LowPower.deepSleep” con alarma RTC para ciclos de muestreo largos.

• Apagar periféricos entre muestras (p. ej., desalimentar BME680 con transistor p‑MOS si el diseño lo permite).

• Visual:

• Cambiar la tipografía por fuentes GFX más grandes/bold para legibilidad.
• Añadir iconos según rangos de IAQ con bitmap monocromo.

Checklist de verificación

• [ ] He instalado Arduino CLI 0.35.3 y el core arduino:samd@1.8.14.
• [ ] He instalado las bibliotecas exactas: GxEPD2 1.5.9, Adafruit GFX 1.11.9, Adafruit BME680 2.0.3, Adafruit Unified Sensor 1.1.14, Adafruit BusIO 1.14.1, ArduinoLowPower 1.2.2, FlashStorage_SAMD 1.3.2.
• [ ] He cableado correctamente e‑Paper: CS=10, DC=9, RST=8, BUSY=7; MOSI=D11, SCK=D13; 3V3 y GND comunes.
• [ ] He cableado correctamente BME680 por I2C: SDA y SCL a los pines SDA/SCL del Nano 33 IoT; 3V3 y GND.
• [ ] El sketch compila con: arduino-cli compile –fqbn arduino:samd:nano_33_iot epaper-air-quality-logger.
• [ ] El sketch sube con: arduino-cli upload -p –fqbn arduino:samd:nano_33_iot epaper-air-quality-logger.
• [ ] Veo en la e‑Paper el título y, tras ~1 min, los valores de T/H/P/GAS/IAQ y la minigráfica.
• [ ] Tras 5 min, el baseline de gas se estabiliza y el IAQ varía con el ambiente.
• [ ] Al enviar “D” por el monitor serie, recibo el CSV con registros.
• [ ] Tras un reset, el log sigue presente (persistencia OK).

---

Apéndice: comandos de referencia compactos

• Instalar core SAMD y libs:

arduino-cli core update-index
arduino-cli core install arduino:samd@1.8.14
arduino-cli lib install "GxEPD2@1.5.9" "Adafruit GFX Library@1.11.9" "Adafruit BME680 Library@2.0.3" "Adafruit Unified Sensor@1.1.14" "Adafruit BusIO@1.14.1" "ArduinoLowPower@1.2.2" "FlashStorage_SAMD@1.3.2"

• Compilar y subir:

arduino-cli compile --fqbn arduino:samd:nano_33_iot epaper-air-quality-logger
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:nano_33_iot epaper-air-quality-logger
arduino-cli monitor -p /dev/ttyACM0 -c baudrate=115200

Nota final

Este caso práctico está específicamente enfocado al modelo “Arduino Nano 33 IoT + Waveshare 2.9in e‑Paper (SSD1680) + BME680” con la toolchain y versiones indicadas. Todo el cableado, el código y los comandos han sido diseñados para esta combinación concreta a fin de lograr un “epaper-air-quality-logger” reproducible y validable.