Sistema de Monitoreo Energético — Raspberry Pi

Monitor de variables eléctricas AC (voltaje, corriente, potencia) con registro histórico en CSV vinculado al reloj en tiempo real DS3231.

---

Estructura del Proyecto

energy_monitor/
│
├── main.py                      ← Punto de entrada (ejecutar esto)
├── config.py                    ← Todos los parámetros ajustables
│
├── sensors/
│   ├── rtc_sensor.py            ← DS3231  (fecha/hora)
│   ├── dht_sensor.py            ← DHT22   (temperatura y humedad)
│   ├── voltage_sensor.py        ← ZMPT101B (voltaje AC via MCP3008 CH0)
│   └── current_sensor.py        ← WCS1600  (corriente AC via MCP3008 CH1)
│
├── data/
│   ├── logger.py                ← Escritura de CSV por sesión
│   └── sessions/                ← Archivos CSV generados automáticamente
│       └── 2025-06-14_09-30-01.csv
│
├── display/
│   └── terminal_ui.py           ← Dashboard en terminal con historial
│
└── utils/
    └── timing.py                ← micros() / millis() de alta resolución

---

Conexiones de Hardware

MCP3008 → Raspberry Pi (SPI)

MCP3008	RPi Pin	Función
VDD	3.3V	Alimentación
VREF	3.3V	Referencia ADC
AGND	GND	Tierra analógica
CLK	GPIO11	SPI SCLK
DOUT	GPIO9	SPI MISO
DIN	GPIO10	SPI MOSI
CS/SHDN	GPIO8	SPI CE0
DGND	GND	Tierra digital

Sensores → MCP3008

Sensor	Canal MCP3008	Variable
ZMPT101B	CH0	Voltaje
WCS1600	CH1	Corriente

DHT22 → Raspberry Pi (GPIO directo)

DHT22	RPi
VCC	3.3V o 5V
DATA	GPIO4 (D4)
GND	GND

DS3231 → Raspberry Pi (I2C)

DS3231	RPi
VCC	3.3V
GND	GND
SDA	GPIO2
SCL	GPIO3

---

Instalación de Dependencias

# Habilitar SPI e I2C en la Raspberry Pi
sudo raspi-config
# → Interface Options → SPI → Enable
# → Interface Options → I2C → Enable

# Instalar librerías Python
pip install spidev
pip install adafruit-circuitpython-ds3231
pip install adafruit-circuitpython-dht
sudo apt-get install libgpiod2

---

Uso

# Desde la carpeta raíz del proyecto
python3 main.py

# Detener el monitoreo
Ctrl+C    # Guarda el CSV y cierra correctamente

---

Archivos CSV Generados

Cada ejecución crea un archivo CSV en data/sessions/:

timestamp,hour,voltage_v,current_a,power_w,temperature_c,humidity_pct,zero_current_mv
2025-06-14 09:30:01,9,118.45,0.000,0.00,29.4,65.7,2555.53
2025-06-14 09:30:02,9,118.62,0.832,98.69,29.4,65.7,2555.53

Análisis con pandas (Python)

import pandas as pd

df = pd.read_csv("data/sessions/2025-06-14_09-30-01.csv")
df['timestamp'] = pd.to_datetime(df['timestamp'])

# Consumo promedio por hora del día
print(df.groupby('hour')['power_w'].mean())

# Pico de corriente
print(f"Pico: {df['current_a'].max():.3f} A")

---

Parámetros de Calibración (config.py)

Parámetro	Default	Descripción
SENSITIVITY_MV_A	24.0	Sensibilidad del WCS1600 (mV/A del datasheet)
CALIBRATION_FACTOR	0.392	Ajustar midiendo con pinza amperimétrica
CURRENT_GATE_A	0.50	Noise gate: cargas menores se reportan como 0
NOISE_FLOOR_RMS_A	0.15	Ruido de piso del sensor (A)
VOLTAGE_SCALE_FACTOR	1.5	Ajustar midiendo con multímetro calibrado

---

Proceso de Calibración de Corriente

1. Sin carga: arrancar el sistema → current.calibrate() mide el punto cero
2. Con carga conocida: conectar una carga de potencia conocida (ej: foco 100W)
3. Medir con pinza amperimétrica: anotar el valor real
4. Calcular el factor: CALIBRATION_FACTOR = I_real / I_medida
5. Actualizar config.py con el nuevo valor

---

Diagrama de Flujo

                    ┌─────────────┐
                    │   main.py   │
                    └──────┬──────┘
                           │ instancia
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   VoltageSensor    CurrentSensor      RTCSensor
   (ZMPT101B)       (WCS1600)          (DS3231)
          │                │                │
          └────────────────┤                │
                     cada 1 ms             │
                    sample()               │ timestamp
                           │               │
                    cada 1000 ms           │
                    compute_rms() ◄────────┘
                           │
                    ┌──────┴──────┐
                    │             │
               DataLogger   TerminalUI
               (CSV)        (pantalla)

---

Diagramas de arquitectura (añadidos)

A continuación se incluyen tres diagramas que muestran la integración entre la Raspberry Pi, el servidor MCP y Claude Desktop (a través de un túnel HTTPS como ngrok). Las herramientas expuest[...]

graph TB
    subgraph "💻 Tu PC Windows"
        CD[Claude Desktop]
        CF[claude_desktop_config.json]
    end
    
    subgraph "☁️ Internet"
        NG[ngrok Tunnel<br/>HTTPS]
    end
    
    subgraph "🍓 Raspberry Pi 4"
        subgraph "Servidor MCP"
            MS[FastMCP Server<br/>Puerto 8000]
            TL[Tools Layer<br/>5 herramientas]
        end
        
        subgraph "Datos"
            CS[CSV Sessions<br/>data/sessions/]
            PD[Pandas DataFrames]
        end
        
        subgraph "Sensores"
            SN[Sensor<br/>Voltaje/Corriente]
        end
    end
    
    CD -->|HTTP/SSE| NG
    NG -->|Túnel Seguro| MS
    CF -.->|Configura| CD
    MS --> TL
    TL --> PD
    PD --> CS
    SN --> CS

sequenceDiagram
    actor User as 👤 Usuario
    participant CD as Claude Desktop
    participant NG as ngrok
    participant MCP as MCP Server
    participant TL as Tools
    participant PD as Pandas
    participant CSV as CSV Files
    
    User->>CD: "¿Cuánta energía consumí?"
    CD->>NG: POST /mcp<br/>get_energy_consumption_tool
    NG->>MCP: Forward request
    MCP->>TL: get_energy_consumption()
    TL->>PD: read_csv + filtrar power>0
    PD->>CSV: Leer archivos session
    CSV-->>PD: Datos crudos
    PD-->>TL: DataFrame procesado
    TL->>TL: Calcular kWh, costos,<br/>proyecciones
    TL-->>MCP: Dict con resultados
    MCP-->>NG: JSON response
    NG-->>CD: JSON response
    CD->>CD: Claude interpreta datos
    CD-->>User: "Consumiste 0.45 kWh<br/>Costo: $405 COP"

¿Qué hace este proyecto?
Este proyecto es un sistema de monitoreo eléctrico en tiempo real embebido en una Raspberry Pi 4B, capaz de medir voltaje AC (110–120 V), corriente AC, potencia, temperatura y humedad ambiente. Los datos se almacenan localmente en archivos CSV por sesión, y se exponen a Claude Desktop mediante un servidor MCP (Model Context Protocol), permitiendo que una IA analice, compare y visualice el historial energético del entorno.

Objetivo principal: Convertir señales eléctricas del mundo físico en inteligencia accionable, accesible conversacionalmente desde Claude Desktop.

Arquitectura General (de entrada a salida)
El sistema opera en tres capas bien diferenciadas:

┌─────────────────────────────────────────────────────────────┐
│  CAPA 1: HARDWARE (Raspberry Pi 4B)                          │
│                                                              │
│  Red 110–120V AC                                            │
│       │                                                      │
│  ZMPT101B ──► CH0 ─┐                                        │
│  (Voltaje)          ├──► MCP3008 ADC (SPI 500 kHz)          │
│  WCS1600   ──► CH1 ─┘    │ 32× oversampling, SNR +19 dB     │
│  (Corriente)              │                                  │
│                           ▼                                  │
│  DHT22 ──► GPIO 27   Raspberry Pi 4B                        │
│  (Temp/Hum)               │                                  │
│  DS3231 ──► I2C      monitor.py (adquisición + RMS calc)    │
│  (RTC)                    │                                  │
│                           ▼                                  │
│              data/sessions/YYYY-MM-DD_HH-MM-SS.csv          │
└───────────────────────────┬─────────────────────────────────┘
                            │ CSV files (8 columnas)
┌───────────────────────────▼─────────────────────────────────┐
│  CAPA 2: SERVIDOR MCP (mcp_server/server.py)                      │
│                                                                   │
│  FastMCP (streamable-http, puerto 8000)                           │
│  5 herramientas expuestas:                                        │
│    list_sessions_tool · get_session_data_tool · get_session_stats_tool │
│    get_energy_consumption_tool · compare_all_sessions_tool        │
│                                                                  │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTPS (ngrok tunnel)
┌───────────────────────────▼─────────────────────────────────┐
│  CAPA 3: INTERFAZ DE ANÁLISIS (Claude Desktop)               │
│                                                              │
│  El usuario conversa con Claude en lenguaje natural.         │
│  Claude invoca las herramientas MCP automáticamente,         │
│  analiza los resultados y devuelve conclusiones.             │
└─────────────────────────────────────────────────────────────┘

---

Servidor MCP — Herramientas expuestas

El servidor MCP (mcp_server/server.py) expone un conjunto de herramientas que permiten consultar y procesar las sesiones almacenadas en data/sessions/. Estas herramientas están pensadas para ser invocadas por clientes como Claude Desktop.

Herramientas disponibles (nombres tal como aparecen en el repositorio):

Herramienta	Descripción	Parámetros
list_sessions_tool	Lista todas las sesiones CSV	Ninguno
get_session_data_tool	Lee datos de una sesión	session_name, max_rows
get_session_stats_tool	Estadísticas eléctricas detalladas	session_name
get_energy_consumption_tool	Energía, costos y proyecciones	session_name, cost_per_kwh
compare_all_sessions_tool	Comparativa de todas las sesiones	cost_per_kwh

Ejemplo de invocación (curl, adaptalo según la configuración del servidor):

curl -X POST "http://RASPBERRY_PI_IP:8000/mcp" \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_energy_consumption_tool", "params": {"session_name": "2025-06-14_09-30-01.csv", "cost_per_kwh": 900}}'

Respuesta esperada (ejemplo JSON):

{
  "tool": "get_energy_consumption_tool",
  "result": {
    "session_name": "2025-06-14_09-30-01.csv",
    "energy": {
      "total_active_wh": 450.0,
      "total_active_kwh": 0.45,
      "avg_power_w": 98.69,
      "peak_power_w": 150.0,
      "load_factor_pct": 65.0
    },
    "costs": {
      "cost_per_kwh_cop": 900,
      "session_cost_cop": 405.0,
      "projected_monthly_cop": 12150.0
    }
  },
  "meta": {"session":"2025-06-14_09-30-01.csv"}
}

Notas importantes:

• El túnel HTTPS (ngrok) se utiliza para exponer el servidor MCP a Claude Desktop sin exponer directamente la Raspberry Pi a Internet.
• Claude Desktop puede orquestar llamadas a las herramientas y luego interpretar/visualizar los resultados en lenguaje natural.
• Revisa mcp_server/config.py y mcp_server/server.py para ajustar rutas, puerto y comportamiento exacto de serialización.

---

Contribuciones

Si encuentras errores o quieres proponer mejoras en las herramientas MCP, crea un issue o un PR explicando el cambio propuesto.

---