# ShellyDash ⚡

Dashboard web per il monitoraggio in tempo reale di un impianto fotovoltaico con **Shelly EM Gen3**.

Legge i dati da un Shelly EM (2 pinze: produzione pannelli e consumo casa/rete) via **Shelly Cloud API v2**, li memorizza su SQLite e li visualizza su una dashboard con gauge a lancetta semi-circolare e grafico storico.

## Funzionalità

- **Due gauge analogici**: produzione pannelli (0–6000W, verde) e consumo casa (0–3000W, ambra), con scala graduata e lancetta
- **Surplus/deficit** istantaneo: produzione − consumo
- **Energia odierna**: prodotto, consumato, immesso in rete
- **Grafico storico**: 24h / 3gg / 7gg produzione + consumo
- **API REST JSON** per automazioni e integrazioni
- **Auto-refresh** ogni 15 secondi
- **Tema scuro**, UI in italiano

## Architettura

```
shellydash/
├── app.py               ← Entrypoint Flask (6 route API + serve frontend)
├── shelly_client.py     ← Client HTTP per Shelly Cloud API v2
├── database.py          ← SQLite (WAL mode), schema readings
├── poller.py            ← Thread background polling periodico
├── templates/
│   └── index.html       ← Dashboard: gauge Chart.js custom + grafico storico
├── data/
│   └── shellydash.db    ← SQLite (gitignorato)
├── .env                 ← Credenziali Shelly (gitignorato)
├── AGENTS.md            ← Istruzioni per AI agent
└── requirements.txt     ← flask, requests, python-dotenv
```

### Flusso dati

```
Shelly Cloud
    ↕ HTTP POST (auth_key)
poller.poll_once()          ← ogni 15s (thread background)
    ↕
shelly_client.py            ← parse readings (em1:0, em1:1)
    ↕
database.py (SQLite)        ← INSERT storico
    ↕
app._latest_parsed (dict)   ← cache in-memory per /api/status
    ↕
app.py → /api/status        ← da cache (risposta immediata)
       → /api/history       ← da DB (storico)
       → /api/energy/*      ← da DB (aggregazioni)
       → /                  → templates/index.html
```

## Setup

### Prerequisiti

- Python 3.14+
- Shelly EM Gen3 connesso al cloud Shelly
- Chiave API Cloud (trovabile in App Shelly → Impostazioni → Casa → Cloud)

### Installazione

```bash
cd /home/codex/shellydash
python3 -m venv venv
venv/bin/pip install -r requirements.txt
```

### Configurazione

Crea un file `.env` nella root del progetto (non tracciato in git):

```env
SHELLY_SERVER="https://shelly-255-eu.shelly.cloud"
SHELLY_AUTH_KEY="la_tua_auth_key"
SHELLY_DEVICE_ID="id_dispositivo"
POLL_INTERVAL=15
FLASK_PORT=5050
FLASK_HOST="0.0.0.0"
```

### Avvio

```bash
venv/bin/python3 app.py
```

Apri il browser su `http://localhost:5050`.

## API REST

Tutte le API restituiscono JSON con campo `ok` booleano.

### `GET /api/status`
Letture live in tempo reale (dalla cache del poller).

```json
{
  "ok": true,
  "ts": 1722520000,
  "production_w": 1735.4,
  "consumption_w": 134.4,
  "delta_w": 1601.0,
  "voltage": 229.8,
  "ch0_current": 7.55,
  "ch1_current": 0.59,
  "ch0_pf": 0.99,
  "ch1_pf": 0.85,
  "temperature": 59.6,
  "wifi_rssi": -67,
  "online": true
}
```

### `GET /api/history?hours=24`
Array di readings storici dal database.

### `GET /api/energy/today`
Energia odierna in kWh.

### `GET /api/energy/monthly`
Breakdown giornaliero del mese corrente.

### `GET /api/delta`
Surplus/deficit booleano (utile per automazioni).

```json
{
  "ok": true,
  "delta_w": 1601.0,
  "production_w": 1735.4,
  "consumption_w": 134.4,
  "surplus": true
}
```

## Shelly EM — Configurazione canali

Il progetto è tarato su un **Shelly EM Gen3** (S3EM-002CXCEU) con una singola unità e **due pinze**:

| Canale | ID | Misura | Segno |
|---|---|---|---|
| Produzione | `em1:0` | Uscita inverter → potenza generata | Sempre positivo |
| Consumo | `em1:1` | Ingresso inverter → prelievo/rete | Negativo = consumo, Positivo = immissione |

L'API normalizza automaticamente: `consumption_w = abs(ch1)` quando ch1 è negativo.

## Frontend

- **Framework**: nessuno — vanilla JavaScript
- **Grafici**: Chart.js 4.4.7 via CDN
- **Gauge**: plugin Chart.js custom (`gaugePlugin`) con disegno su canvas di:
  - Scala graduata (tacche maggiori ogni 1000W, minori ogni 500W)
  - Lancetta rotante
  - Valore numerico al centro
- **Tema**: scuro (#0f172a sfondo)
- **Refresh**: `setInterval(refreshAll, 15000)`

## Stack tecnologico

| Componente | Tecnologia |
|---|---|
| Backend | Python 3.14, Flask 3.1 |
| Database | SQLite (WAL mode) |
| Cloud API | Shelly Cloud Control API v2 |
| Frontend | HTML5, CSS3, Chart.js 4.4 (CDN) |
| Ambiente | venv |

## Licenza

Progetto privato — uso personale.