# 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

```bash
# 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

```bash
# 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)
```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[...]

```mermaid
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
```

```sequence
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):

```bash
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):

```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.

---