# Cariflex - Architecture d'Intégration EMS

> Documentation de l'architecture Cariflex - Plateforme d'Energy Management System

## 1. Vue d'ensemble

Cariflex est une plateforme EMS (Energy Management System) pour la Martinique, intégrant :

- **FlexMeasures** : Moteur central de forecasting, scheduling et ingestion
- **CitrineOS** : Charge Station Management System (CSMS) pour bornes EV
- **EVerest** : Middleware de communication avec les bornes (OCPP/ISO 15118)
- **Grid Singularity** : Plateforme de marché énergétique peer-to-peer
- **OPLEM** : Optimisation des marchés locaux d'énergie
- **HAMLET** : Simulation multi-agents pour LEM (Local Energy Market)
- **OpenLEADR** : Communication OpenADR avec le DSO

---

## 2. Architecture Fonctionnelle

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              CARIFLEX EMS                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                         EXTERNAL DATA SOURCES                         │   │
│  │                                                                        │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐     │   │
│  │  │ EPEX SPOT  │  │  ENTSO-E   │  │  Weather   │  │    DSO     │     │   │
│  │  │ Day-ahead  │  │ Prices/CO2 │  │   API      │  │  OpenADR   │     │   │
│  │  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘     │   │
│  └────────┼───────────────┼───────────────┼───────────────┼────────────┘   │
│           │               │               │               │                │
│           ▼               ▼               ▼               ▼                │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                          FLEXMEASURES EMS                             │   │
│  │                                                                        │   │
│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
│  │  │                         INGESTION                               │  │   │
│  │  │                                                                  │  │   │
│  │  │  Sources:                                                        │  │   │
│  │  │  • Simulator Cariflex (API REST, 30s interval)                  │  │   │
│  │  │  • MQTT brokers (Smart City format → FM format)                │  │   │
│  │  │  • CitrineOS (OCPP 2.0.1 → FM API)                             │  │   │
│  │  │  • Weather API (Solcast/Météo)                                  │  │   │
│  │  │  • EPEX SPOT (Day-ahead prices via entsoe-py)                   │  │   │
│  │  │                                                                  │  │   │
│  │  │  Data Model:                                                     │  │   │
│  │  │  Assets (40) ──► Sensors (40) ──► Beliefs (timed values)       │  │   │
│  │  │  • 10 PV (sensors 41-50)                                        │  │   │
│  │  │  • 10 Batteries (sensors 51-60)                                 │  │   │
│  │  │  • 10 EV Chargers (sensors 61-70)                               │  │   │
│  │  │  • 10 EVs V2G (sensors 71-80)                                   │  │   │
│  │  └────────────────────────────────────────────────────────────────┘  │   │
│  │                                                                        │   │
│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
│  │  │                          FORECASTING                            │  │   │
│  │  │                                                                  │  │   │
│  │  │  Current:                                                        │  │   │
│  │  │  • CLI: `flexmeasures add forecasts --sensor <id>`              │  │   │
│  │  │  • 82 forecast beliefs per PV sensor (24h horizon)              │  │   │
│  │  │  • Autoregressive model (TrainPredictPipeline)                  │  │   │
│  │  │                                                                  │  │   │
│  │  │  TODO:                                                           │  │   │
│  │  │  • Automatic forecasting via cron job                           │  │   │
│  │  │  • Weather-based PV forecasting (Solcast API)                   │  │   │
│  │  │  • Price forecasting (EPEX SPOT via entsoe-py)                  │  │   │
│  │  │  • CO2 intensity forecasting (ENTSO-E)                          │  │   │
│  │  └────────────────────────────────────────────────────────────────┘  │   │
│  │                                                                        │   │
│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
│  │  │                           SCHEDULING                            │  │   │
│  │  │                                                                  │  │   │
│  │  │  Current:                                                        │  │   │
│  │  │  • StorageScheduler (batteries, EVs)                             │  │   │
│  │  │  • Flex-model: soc_min, soc_max, power_capacity, efficiency    │  │   │
│  │  │                                                                  │  │   │
│  │  │  TODO:                                                           │  │   │
│  │  │  • Automatic scheduling via API trigger                         │  │   │
│  │  │  • Grid services scheduling (OpenADR ↔ DSO)                     │  │   │
│  │  │  • Market-based scheduling (Grid Singularity integration)       │  │   │
│  │  └────────────────────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                            DEVICE LAYER                                │   │
│  │                                                                        │   │
│  │  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────┐  │   │
│  │  │     CITRINEOS      │  │      EVEREST       │  │   OPENLEADR    │  │   │
│  │  │     (CSMS)         │  │    (Middleware)    │  │   (VEN Client) │  │   │
│  │  │                    │  │                    │  │                │  │   │
│  │  │ • OCPP 2.0.1       │  │ • ISO 15118-2     │  │ • OpenADR 2.0b│  │   │
│  │  │ • Charge Points    │  │ • OCPP 1.6/2.0.1  │  │ • DSO signals │  │   │
│  │  │ • Transactions     │  │ • Smart Charging   │  │ • Flexibility │  │   │
│  │  │ • Remote control   │  │ • Power mgmt       │  │   requests     │  │   │
│  │  │                    │  │                    │  │                │  │   │
│  │  │ → FM API           │  │ → CitrineOS OCPP  │  │ → FM API      │  │   │
│  │  └────────────────────┘  └────────────────────┘  └────────────────┘  │   │
│  │                                                                        │   │
│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
│  │  │                            DEVICES                              │  │   │
│  │  │                                                                  │  │   │
│  │  │  10 PV Panels (5kWc)    │  Modbus TCP                           │  │   │
│  │  │  10 Batteries (100kWh)  │  Modbus TCP                           │  │   │
│  │  │  10 EV Chargers (22kW)  │  OCPP 2.0.1 (CitrineOS)              │  │   │
│  │  │  10 EVs (75kWh V2G)     │  ISO 15118 (EVerest)                  │  │   │
│  │  └────────────────────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                           MARKET LAYER (R&D)                          │   │
│  │                                                                        │   │
│  │  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────┐  │   │
│  │  │  GRID SINGULARITY  │  │       OPLEM        │  │     HAMLET      │  │   │
│  │  │  gsy-e (88 stars)  │  │  oplem (pip)       │  │  (conda hamlet) │  │   │
│  │  │                    │  │                    │  │                 │  │   │
│  │  │ • P2P energy       │  │ • Local market     │  │ • Multi-agent   │  │   │
│  │  │   trading          │  │   optimization     │  │   simulation    │  │   │
│  │  │ • Market clearing  │  │ • Prosumer         │  │ • Battery/EV    │  │   │
│  │  │ • Price discovery  │  │   optimization     │  │   agents        │  │   │
│  │  │                    │  │                    │  │                 │  │   │
│  │  │ ← FM schedules     │  │ ← FM sensor data   │  │ ← FM forecasts  │  │   │
│  │  └────────────────────┘  └────────────────────┘  └────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                         VISUALIZATION LAYER                           │   │
│  │                                                                        │   │
│  │  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────┐  │   │
│  │  │      GRAFANA       │  │      METABASE      │  │  CARIFLEX UI   │  │   │
│  │  │   (Port 3001)      │  │                    │  │  (Port 5000)   │  │   │
│  │  │                    │  │                    │  │                 │  │   │
│  │  │ • 4 timeseries     │  │ • SQL analytics    │  │ • Asset map    │  │   │
│  │  │ • 1 table (assets) │  │ • Reporting        │  │ • Schedules    │  │   │
│  │  │ • PostgreSQL FM    │  │ • Data exploration │  │ • Forecasts    │  │   │
│  │  └────────────────────┘  └────────────────────┘  └────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 3. Flux de Données

### 3.1 Ingestion
```
Devices → MQTT/OCPP → FM API → PostgreSQL
                    ↓
              FM Worker (RQ Queue)
                    ↓
              Beliefs (timed data)
```

### 3.2 Forecasting
```
Historical Data → TrainPredictPipeline → Forecast Beliefs
     ↓                                         ↓
  PostgreSQL                              PostgreSQL
                                            ↓
                                       Grafana
```

### 3.3 Scheduling
```
Grid Request (OpenADR) → FM API → StorageScheduler → Schedule
                                    ↓
                              Flex Model (soc_min, soc_max, power_capacity)
                                    ↓
                              Device Commands (OCPP)
```

---

## 4. Intégrations à Développer

### 4.1 CitrineOS ↔ FlexMeasures
```
CitrineOS (CSMS) → OCPP 2.0.1 → Charge Points
     ↓
  REST API → FM API (sensor data, transactions)
     ↓
  FM Scheduling → Charge profiles → CitrineOS
```

### 4.2 EVerest ↔ CitrineOS
```
EVerest (Middleware) → OCPP 2.0.1 → CitrineOS
     ↓
  ISO 15118 → EV communication
     ↓
  Smart Charging → Power management
```

### 4.3 Grid Singularity ↔ FlexMeasures
```
Grid Singularity (Market) → gsy-e-sdk → FM API
     ↓
  P2P trading → Price signals
     ↓
  FM Scheduling → Battery/EV schedules
```

### 4.4 OPLEM ↔ FlexMeasures
```
OPLEM (Optimization) → FM sensor data
     ↓
  Local market optimization
     ↓
  FM Scheduling → Device schedules
```

### 4.5 HAMLET ↔ FlexMeasures
```
HAMLET (Simulation) → FM forecasts
     ↓
  Multi-agent simulation
     ↓
  Strategy validation → FM scheduling
```

### 4.6 OpenLEADR ↔ FlexMeasures
```
DSO (OpenADR VTN) → OpenLEADR (VEN) → FM API
     ↓
  Flexibility requests
     ↓
  FM Scheduling → Grid services
```

---

## 5. Configuration Requise

### 5.1 FlexMeasures
```yaml
# Environment variables
FLEXMEASURES_ENV=production
FLEXMEASURES_REDIS_URL=flexmeasures-redis
FLEXMEASURES_REDIS_PORT=6379
FLEXMEASURES_REDIS_DB_NR=0
FLEXMEASURES_REDIS_PASSWORD=***
SQLALCHEMY_DATABASE_URI=postgresql://flexmeasures:***@flexmeasures-db:5432/flexmeasures

# Config file
FLEXMEASURES_MENU_LOGO_PATH=/ui/static/images/cariflex-logo.jpg
FLEXMEASURES_PLATFORM_NAME=Cariflex
```

### 5.2 Grafana Datasource
```json
{
  "name": "PostgreSQL-FlexMeasures",
  "type": "postgres",
  "url": "flexmeasures-db:5432",
  "database": "flexmeasures",
  "user": "flexmeasures"
}
```

### 5.3 MQTT Brokers (TODO)
```yaml
# New brokers needed for Cariflex (format compatible FM)
- cariflex-mqtt: MQTT broker for Cariflex devices
- Topics: cariflex/sensors/{asset_type}/{asset_id}/power
- Format: {"value": float, "unit": "kW|kWh", "timestamp": ISO8601}
```

---

## 6. Prochaines Étapes

1. **Intégrer CitrineOS** : Connecter via OCPP 2.0.1 aux bornes EV
2. **Intégrer EVerest** : Configurer ISO 15118 pour V2G
3. **Intégrer OpenLEADR** : Connecter au DSO pour flexibilité
4. **Créer brokers MQTT Cariflex** : Format compatible FM
5. **Automatiser forecasting/scheduling** : Cron jobs ou scheduler
6. **Intégrer Grid Singularity** : P2P trading
7. **Documentation complète** : API, déploiement, fonctionnement
