# Cariflex - Architecture d'Intégration EMS v2

> Documentation de l'architecture Cariflex - Plateforme d'Energy Management System
> **Mise à jour :** Intégration OCPI et GIREVE

---

## 1. Vue d'Ensemble

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

### Composants Principaux
| Composant | Rôle | Protocole | Statut |
|-----------|------|-----------|--------|
| **FlexMeasures** | Moteur central EMS | REST API | ✅ Installé |
| **CitrineOS** | CSMS (Charge Station Management) | OCPP 2.0.1 | ✅ Extrait |
| **EVerest** | Middleware EV charging | OCPP/ISO 15118 | ✅ Extrait |
| **OpenLEADR** | Communication DSO | OpenADR 2.0b | ✅ Installé |
| **Grid Singularity** | Marché P2P | gsy-e-sdk | ✅ Extrait |
| **OPLEM** | Marché local | Python | ✅ Installé |
| **HAMLET** | Simulation LEM | Agent-based | ✅ Extrait |
| **OCPI** | Interopérabilité EV | OCPI 2.2 | 📋 À intégrer |
| **GIREVE** | Plateforme interop GIREVE | eMSP API | 📋 À intégrer |

### Glossaire
- **OCPI** : Open Charge Point Interface - Protocole d'échange entre opérateurs de bornes
- **GIREVE** : Plateforme d'interopérabilité pour la mobilité électrique
- **eMSP** : E-Mobility Service Provider
- **CPO** : Charge Point Operator
- **CSMS** : Charge Station Management System
- **OCPP** : Open Charge Point Protocol

---

## 2. Architecture Fonctionnelle Complète

```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                    CARIFLEX EMS - ARCHITECTURE v2                            │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                               │
│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
│  │                                    EXTERNAL LAYER                                         │ │
│  │                                                                                           │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │ │
│  │  │  EPEX SPOT   │  │   ENTSO-E    │  │  Weather API │  │  DSO/TSO     │               │ │
│  │  │  (Day-ahead) │  │  (Prices,    │  │  (Solcast,   │  │  (OpenADR/   │               │ │
│  │  │  Localflex)  │  │   CO2)       │  │   Météo)     │  │   S2)        │               │ │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │ │
│  │         │                 │                 │                 │                       │ │
│  │         └─────────────────┴─────────────────┴─────────────────┘                       │ │
│  │                                                         │                               │ │
│  │  ┌──────────────────────────────────────────────────────┼───────────────────────────┐ │ │
│  │  │                    INTEROPERABILITY LAYER            │                           │ │ │
│  │  │                                                      ▼                           │ │ │
│  │  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                          │ │ │
│  │  │  │    OCPI      │  │    GIREVE    │  │   OpenLEADR  │                          │ │ │
│  │  │  │  (eMSP/CPO)  │  │  (Platform)  │  │   (VEN)      │                          │ │ │
│  │  │  │              │  │              │  │              │                          │ │ │
│  │  │  │ • Tarifs     │  │ • Session    │  │ • Flex       │                          │ │ │
│  │  │  │ • Sessions   │  │   data       │  │   requests   │                          │ │ │
│  │  │  │ • CDRs       │  │ • Roaming    │  │ • Events     │                          │ │ │
│  │  │  │ • Roaming    │  │ • Billing    │  │ • Reports    │                          │ │ │
│  │  │  │ • Commands   │  │ • CDRs       │  │              │                          │ │ │
│  │  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘                          │ │ │
│  │  │         │                 │                 │                                    │ │ │
│  │  └─────────┼─────────────────┼─────────────────┼────────────────────────────────────┘ │ │
│  │            │                 │                 │                                      │ │
│  │            ▼                 ▼                 ▼                                      │ │
│  │  ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │
│  │  │                              FLEXMEASURES EMS                                     │ │ │
│  │  │                                                                                   │ │ │
│  │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │ │ │
│  │  │  │  INGESTION  │  │  FORECAST   │  │  SCHEDULING │  │  REPORTING  │            │ │ │
│  │  │  │             │  │             │  │             │  │             │            │ │ │
│  │  │  │ • Sensors   │  │ • PV        │  │ • Batteries │  │ • Assets    │            │ │ │
│  │  │  │ • Assets    │  │ • Load      │  │ • EVs       │  │ • Schedules │            │ │ │
│  │  │  │ • Beliefs   │  │ • Prices    │  │ • Grid      │  │ • Forecasts │            │ │ │
│  │  │  │ • OCPI CDRs │  │ • CO2       │  │   services  │  │ • OCPI CDRs │            │ │ │
│  │  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │ │ │
│  │  │                                                                                   │ │ │
│  │  │  ┌─────────────────────────────────────────────────────────────────────────┐    │ │ │
│  │  │  │                           DATA MODEL                                     │    │ │ │
│  │  │  │  Accounts ──► Assets ──► Sensors ──► Beliefs (timed data)               │    │ │ │
│  │  │  └─────────────────────────────────────────────────────────────────────────┘    │ │ │
│  │  └──────────────────────────────────────────────────────────────────────────────────┘ │ │
│  │                                                                                       │ │
│  │  ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │
│  │  │                                DEVICE LAYER                                        │ │ │
│  │  │                                                                                   │ │ │
│  │  │  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐         │ │ │
│  │  │  │     CITRINEOS      │  │      EVEREST       │  │   _grid SINGULARITY │         │ │ │
│  │  │  │     (CSMS)         │  │    (Middleware)    │  │    (Market)         │         │ │ │
│  │  │  │                    │  │                    │  │                    │         │ │ │
│  │  │  │ • OCPP 2.0.1       │  │ • ISO 15118-2     │  │ • P2P trading      │         │ │ │
│  │  │  │ • Charge Points    │  │ • OCPP proxy      │  │ • Market clearing  │         │ │ │
│  │  │  │ • Transactions     │  │ • Smart Charging  │  │ • Price discovery  │         │ │ │
│  │  │  │ • Remote control   │  │ • V2G             │  │                    │         │ │ │
│  │  │  │                    │  │                    │  │                    │         │ │ │
│  │  │  │ ← OCPP             │  │ ← ISO 15118       │  │ ← gsy-e-sdk        │         │ │ │
│  │  │  │ → 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                                  │   │ │ │
│  │  │  │  10 EVs (75kWh V2G)     │  ISO 15118                                   │   │ │ │
│  │  │  └─────────────────────────────────────────────────────────────────────────┘   │ │ │
│  │  └──────────────────────────────────────────────────────────────────────────────────┘ │ │
│  │                                                                                       │ │
│  │  ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │
│  │  │                           MARKET LAYER (R&D)                                     │ │ │
│  │  │                                                                                   │ │ │
│  │  │  ┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐   │ │ │
│  │  │  │       OPLEM          │  │       HAMLET         │  │    EPEX LOCALFLEX    │   │ │ │
│  │  │  │  (Local Market)      │  │  (Agent-based LEM)   │  │  (Flexibility)       │   │ │ │
│  │  │  │                      │  │                      │  │                      │   │ │ │
│  │  │  │ • Prosumer optim.    │  │ • Multi-agent sim    │  │ • Local flex market  │   │ │ │
│  │  │  │ • Battery agents     │  │ • Battery agents     │  │ • Price signals      │   │ │ │
│  │  │  │ • EV agents          │  │ • EV agents          │  │ • Flex bidding       │   │ │ │
│  │  │  └──────────────────────┘  └──────────────────────┘  └──────────────────────┘   │ │ │
│  │  └──────────────────────────────────────────────────────────────────────────────────┘ │ │
│  │                                                                                       │ │
│  │  ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │
│  │  │                           VISUALIZATION LAYER                                     │ │ │
│  │  │                                                                                   │ │ │
│  │  │  ┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐   │ │ │
│  │  │  │      GRAFANA         │  │      METABASE        │  │    CARIFLEX UI       │   │ │ │
│  │  │  │   (Port 3001)        │  │   (Analytics)        │  │    (Port 5000)       │   │ │ │
│  │  │  │                      │  │                      │  │                      │   │ │ │
│  │  │  │ • Timeseries         │  │ • SQL queries        │  │ • Asset map          │   │ │ │
│  │  │  │ • Asset table        │  │ • Reporting          │  │ • Schedules          │   │ │ │
│  │  │  │ • OCPI CDRs          │  │ • Data exploration   │  │ • Forecasts          │   │ │ │
│  │  │  │ • Flexibility KPIs   │  │ • Billing            │  │ • OCPI sessions      │   │ │ │
│  │  │  └──────────────────────┘  └──────────────────────┘  └──────────────────────┘   │ │ │
│  │  └──────────────────────────────────────────────────────────────────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 3. Intégration OCPI

### 3.1 Qu'est-ce qu'OCPI ?

**OCPI (Open Charge Point Interface)** est un protocole standard pour l'interopérabilité entre opérateurs de bornes de recharge EV. Il permet :

- **Tarification** : Échange des tarifs entre opérateurs
- **Sessions** : Suivi des sessions de recharge en temps réel
- **CDRs** (Call Detail Records) : Facturation inter-opérateurs
- **Roaming** : Accès aux bornes d'autres opérateurs
- **Commands** : Démarrage/arrêt à distance

### 3.2 Architecture OCPI dans Cariflex

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              OCPI INTEGRATION                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐         ┌──────────────┐         ┌──────────────┐        │
│  │   OTHER      │◄───────►│   CARIFLEX   │◄───────►│   CITRINEOS  │        │
│  │   CPOs       │  OCPI   │   OCPI       │  OCPP   │   (CSMS)     │        │
│  │              │  2.2     │   GATEWAY    │  2.0.1  │              │        │
│  └──────────────┘         └──────┬───────┘         └──────────────┘        │
│                                  │                                          │
│                                  ▼                                          │
│                         ┌──────────────┐                                   │
│                         │ FLEXMEASURES │                                   │
│                         │     EMS      │                                   │
│                         │              │                                   │
│                         │ • CDRs       │                                   │
│                         │ • Sessions   │                                   │
│                         │ • Tariffs    │                                   │
│                         │ • Roaming    │                                   │
│                         └──────────────┘                                   │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 3.3 Flux de Données OCPI

```mermaid
sequenceDiagram
    participant EV as EV Driver
    participant OtherCPO as Other CPO
    participant OCPI as Cariflex OCPI Gateway
    participant FM as FlexMeasures
    participant CitrineOS as CitrineOS CSMS
    participant CP as Cariflex Charge Point

    %% Roaming in (EV driver from other CPO)
    EV->>CP: Plug in (RFID/App)
    CP->>CitrineOS: StartTransaction
    CitrineOS->>FM: POST /sensors/{id}/data (power)
    
    FM->>OCPI: Check roaming rights
    OCPI->>OtherCPO: POST /cdrs (session start)
    OtherCPO-->>OCPI: 200 OK
    OCPI-->>FM: Authorized
    
    %% Charging loop
    loop Every 30s
        CitrineOS->>FM: Power readings
        FM->>OCPI: Update session
        OCPI->>OtherCPO: PATCH /sessions/{id}
    end
    
    %% Session end
    EV->>CP: Unplug
    CP->>CitrineOS: StopTransaction
    CitrineOS->>FM: Final readings
    FM->>OCPI: Generate CDR
    OCPI->>OtherCPO: POST /cdrs
    OtherCPO-->>OCPI: CDR accepted
```

### 3.4 Modules OCPI à Développer

| Module | Endpoint | Description |
|--------|----------|-------------|
| `ocpi_versions` | `GET /ocpi/2.2` | Version negotiation |
| `ocpi_credentials` | `POST /ocpi/2.2/credentials` | Auth tokens |
| `ocpi_locations` | `GET /ocpi/2.2/locations` | Bornes Cariflex |
| `ocpi_sessions` | `GET/POST /ocpi/2.2/sessions` | Sessions de recharge |
| `ocpi_cdrs` | `POST /ocpi/2.2/cdrs` | Facturation |
| `ocpi_tariffs` | `GET /ocpi/2.2/tariffs` | Tarifs Cariflex |
| `ocpi_commands` | `POST /ocpi/2.2/commands` | Remote control |

---

## 4. Intégration GIREVE

### 4.1 Qu'est-ce que GIREVE ?

**GIREVE** (Gestion des Itinéraires de Recharge des Véhicules Electriques) est une plateforme d'interopérabilité française pour la mobilité électrique :

- **Agrégation** : Centralise les données de multiples CPOs et eMSPs
- **Roaming** : Facilite l'itinérance de recharge
- **Données** : Session data, CDRs, tarifs, disponibilité
- **Billing** : Facturation inter-opérateurs
- **PNIRE** : Point d'Intersection au Réseau d'Information

### 4.2 Architecture GIREVE dans Cariflex

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                             GIREVE INTEGRATION                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐         ┌──────────────┐         ┌──────────────┐        │
│  │   GIREVE     │◄───────►│   CARIFLEX   │◄───────►│  FLEXMEASURES│        │
│  │   PLATFORM   │  eMSP   │   GIREVE     │  REST   │     EMS      │        │
│  │              │  API    │   CONNECTOR  │  API    │              │        │
│  │              │         │              │         │ • CDRs       │        │
│  │ • Sessions   │         │ • Tarifs     │         │ • Sessions   │        │
│  │ • CDRs       │         │ • Sessions   │         │ • Billing    │        │
│  │ • Tarifs     │         │ • CDRs       │         │ • Reporting  │        │
│  │ • Roaming    │         │ • Billing    │         │              │        │
│  └──────────────┘         └──────────────┘         └──────────────┘        │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                           GIREVE SERVICES                             │   │
│  │                                                                        │   │
│  │  • PNIRE (Point d'Intersection au Réseau d'Information)              │   │
│  │  • Roaming hub (inter-CPO)                                           │   │
│  │  • Data aggregation (sessions, CDRs)                                 │   │
│  │  • Billing reconciliation                                            │   │
│  │  • Availability dissemination                                        │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 4.3 Flux de Données GIREVE

```mermaid
sequenceDiagram
    participant EV as EV Driver
    participant CP as Charge Point
    participant CitrineOS as CitrineOS CSMS
    participant FM as FlexMeasures
    participant GIREVE as GIREVE Platform
    participant OtherCPO as Other CPO

    %% Session start
    EV->>CP: Start charging
    CP->>CitrineOS: StartTransaction
    CitrineOS->>FM: POST /sensors/{id}/data
    FM->>GIREVE: POST /session (session start)
    GIREVE-->>FM: Session acknowledged
    
    %% Charging loop
    loop Every 30s
        CitrineOS->>FM: Power readings
        FM->>GIREVE: PATCH /session/{id} (consumption)
    end
    
    %% Session end
    EV->>CP: Stop charging
    CP->>CitrineOS: StopTransaction
    CitrineOS->>FM: Final readings
    FM->>GIREVE: POST /cdr (final CDR)
    GIREVE-->>FM: CDR accepted
    
    %% Roaming
    OtherCPO->>GIREVE: GET /tariffs (Cariflex tariffs)
    GIREVE-->>OtherCPO: Tariff data
    OtherCPO->>GIREVE: POST /session (roaming session)
    GIREVE->>FM: Validate roaming
    FM-->>GIREVE: Authorized
```

### 4.4 Services GIREVE à Développer

| Service | Endpoint | Description |
|---------|----------|-------------|
| `gireve_tariffs` | `GET /tariffs` | Diffusion des tarifs Cariflex |
| `gireve_sessions` | `POST /sessions` | Envoi des sessions |
| `gireve_cdrs` | `POST /cdrs` | Envoi des CDRs |
| `gireve_locations` | `GET /locations` | Disponibilité des bornes |
| `gireve_roaming` | `POST /validate` | Validation roaming entrant |
| `gireve_billing` | `GET /reports` | Rapports de facturation |

---

## 5. Intégrations à Développer (Mise à Jour)

| Intégration | Priorité | Complexité | Statut | Description |
|-------------|----------|------------|--------|-------------|
| **OCPI Gateway** | Haute | Élevée | 📋 À faire | Protocole OCPI 2.2 pour roaming |
| **GIREVE Connector** | Haute | Moyenne | 📋 À faire | Connexion plateforme GIREVE |
| **CitrineOS ↔ FM** | Haute | Moyenne | ⏳ À faire | OCPP 2.0.1 → FM API |
| **EVerest ↔ CitrineOS** | Haute | Moyenne | ⏳ À faire | ISO 15118 → OCPP proxy |
| **OpenLEADR ↔ FM** | Haute | Faible | ⏳ À faire | OpenADR 2.0b → FM scheduling |
| **Grid Singularity ↔ FM** | Moyenne | Élevée | ⏳ À faire | P2P trading → FM schedules |
| **OPLEM ↔ FM** | Moyenne | Moyenne | ⏳ À faire | Local market optimization |
| **HAMLET ↔ FM** | Basse | Élevée | ⏳ À faire | Multi-agent simulation |
| **MQTT Brokers Cariflex** | Haute | Moyenne | ⏳ À faire | Format compatible FM |

---

## 6. Configuration Requise

### 6.1 FlexMeasures (mise à jour)
```yaml
# Environment variables
FLEXMEASURES_ENV=production
FLEXMEASURES_PLATFORM_NAME=Cariflex
FLEXMEASURES_MENU_LOGO_PATH=/ui/static/images/cariflex-logo.jpg
FLEXMEASURES_REDIS_URL=flexmeasures-redis
FLEXMEASURES_REDIS_PORT=6379
FLEXMEASURES_REDIS_DB_NR=0
FLEXMEASURES_REDIS_PASSWORD=***
S...n

# New: OCPI settings
OCPI_ENABLED=true
OCPI_VERSION=2.2
OCPI_BASE_URL=https://cariflex.digitribe.fr/ocpi
OCPI_CPO_IDENTIFIER=FR*CAR

# New: GIREVE settings
GIREVE_ENABLED=true
GIREVE_BASE_URL=https://platform.gireve.com
GIREVE_CPO_ID=FR_CARIFLEX
GIREVE_API_KEY=***
```

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

### 6.3 Nouvaires Services Docker à Ajouter
```yaml
# OCPI Gateway
cariflex-ocpi:
  image: cariflex/ocpi-gateway:latest
  environment:
    OCPI_VERSION: "2.2"
    FM_API_URL: "http://flexmeasures-server:5000"
    CPO_IDENTIFIER: "FR*CAR"
  ports:
    - "8081:8080"
  networks:
    - cariflex-internal

# GIREVE Connector
cariflex-gireve:
  image: cariflex/gireve-connector:latest
  environment:
    GIREVE_API_URL: "https://platform.gireve.com"
    FM_API_URL: "http://flexmeasures-server:5000"
    CPO_ID: "FR_CARIFLEX"
  networks:
    - cariflex-internal
```

---

## 7. Prochaines Étapes

1. **Développer OCPI Gateway** : Implémenter les endpoints OCPI 2.2
2. **Développer GIREVE Connector** : Connexion à la plateforme GIREVE
3. **Intégrer CitrineOS** : Connecter via OCPP 2.0.1 aux bornes EV
4. **Intégrer EVerest** : Configurer ISO 15118 pour V2G
5. **Intégrer OpenLEADR** : Connecter au DSO pour flexibilité
6. **Créer brokers MQTT Cariflex** : Format compatible FM
7. **Automatiser forecasting/scheduling** : Cron jobs ou scheduler
8. **Intégrer Grid Singularity** : P2P trading
9. **Documentation complète** : API, déploiement, fonctionnement
