# Cariflex EMS - Infrastructure Documentation

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              CARIFLEX EMS                                     │
│                    Energy Management System for Martinique                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                    │
│  │   OpenADR    │    │   FlexMeasures│    │   Grafana    │                    │
│  │   VTN/VEN    │───▶│   Server      │───▶│   Dashboard  │                    │
│  │   (S2+OpenADR)│    │   (EMS Core)  │    │   (17 panels)│                    │
│  └──────────────┘    └──────┬───────┘    └──────────────┘                    │
│         │                   │                                                │
│         │                   ▼                                                │
│         │            ┌──────────────┐                                       │
│         │            │  CitrineOS   │                                       │
│         │            │  (OCPP 2.0.1)│                                       │
│         │            └──────┬───────┘                                       │
│         │                   │                                                │
│         ▼                   ▼                                                │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                    │
│  │ PostgreSQL   │    │   RabbitMQ   │    │  Operator UI │                    │
│  │ (time-series)│    │  (AMQP/OCPP) │    │  (Dashboard) │                    │
│  └──────────────┘    └──────────────┘    └──────────────┘                    │
│                                                                               │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## Integration Flow

### OpenADR → FlexMeasures → CitrineOS
```
1. OpenADR VTN creates events (price, load control)
2. OpenADR VEN receives events via poll
3. VEN posts data to FlexMeasures API (sensors 84, 86, 87)
4. FlexMeasures creates charging schedules based on prices
5. Schedules sent to CitrineOS via RabbitMQ (OCPP)
6. CitrineOS sends OCPP profiles to EV charge points
7. Grafana displays real-time data from all sources
```

### Asset Synchronization
- FM EV assets (sensors 61-70) ↔ CitrineOS charge points (CP001-CP010)
- Sync script ensures consistency of: count, power, location
- OCPP 2.0.1 protocol for charge point communication

## Network Architecture

### Networks
| Network | Subnet | Purpose | External |
|---------|--------|---------|----------|
| `traefik-public` | 172.29.0.0/16 | Public services | Yes |
| `config_cariflex-internal` | 172.23.0.0/16 | Internal services | No |
| `openadr-internal` | 192.168.240.0/24 | OpenADR VTN/VEN | No |

### DNS/Hosts
| Service | Domain | Container | Port |
|---------|--------|-----------|------|
| FlexMeasures | cariflex.digitribe.fr | flexmeasures-server | 5000 |
| Grafana | grafana.digitribe.fr | smart-city-grafana | 3000 |
| CitrineOS | citrineos.digitribe.fr | cariflex-citrineos-server | 8080 |
| RabbitMQ Mgmt | amqp.digitribe.fr | cariflex-amqp | 15672 |
| OpenADR VTN | - | openadr-vtn | 8080 |
| OpenADR VEN | - | openadr-ven | - |

## Docker Containers

### Cariflex EMS Stack
| Container | Image | Network | IP | Status |
|-----------|-------|---------|----|--------|
| flexmeasures-server | lfenergy/flexmeasures:latest | traefik-public | 172.29.0.x | ✅ UP |
| flexmeasures-worker | lfenergy/flexmeasures:latest | traefik-public | 172.29.0.x | ✅ UP |
| flexmeasures-db | postgres:17 | traefik-public | 172.29.0.x | ✅ UP |
| flexmeasures-redis | redis:7-alpine | traefik-public | 172.29.0.x | ✅ UP |
| openadr-vtn | flexmeasures-openadr-vtn | openadr-internal | 192.168.240.10 | ✅ UP |
| openadr-ven | flexmeasures-openadr-ven | openadr-internal | 192.168.240.11 | ✅ UP |
| cariflex-citrineos-server | ghcr.io/citrineos/citrineos-server:latest | config_cariflex-internal | 172.23.0.4 | ✅ UP |
| cariflex-citrineos-db | postgis/postgis:16-3.5 | config_cariflex-internal | 172.23.0.x | ✅ UP |
| cariflex-amqp | rabbitmq:3-management | config_cariflex-internal | 172.23.0.3 | ✅ UP |
| smart-city-grafana | grafana/grafana | traefik-public | - | ✅ UP |

## Sensor Mapping

### OpenADR Sensors (from VTN)
| ID | Name | Unit | Source |
|----|------|------|--------|
| 84 | consumption_price | EUR/MWh | OpenADR VTN |
| 86 | load_control_signal | % | OpenADR VTN |
| 87 | demand_response_signal | dimensionless | OpenADR VTN |

### EV Charging Sensors (CitrineOS ↔ FM)
| FM Sensor | CitrineOS CP | Connector | Max Power |
|-----------|--------------|-----------|-----------|
| 61 | CP001 | 1 | 22 kW |
| 62 | CP002 | 1 | 22 kW |
| 63 | CP003 | 1 | 22 kW |
| 64 | CP004 | 1 | 22 kW |
| 65 | CP005 | 1 | 22 kW |
| 66 | CP006 | 1 | 11 kW |
| 67 | CP007 | 1 | 11 kW |
| 68 | CP008 | 1 | 11 kW |
| 69 | CP009 | 1 | 11 kW |
| 70 | CP010 | 1 | 11 kW |

## Grafana Dashboard (17 panels)

| # | Panel | Data Source |
|---|-------|-------------|
| 1 | Production PV (kW) | FM sensors 41-50 |
| 2 | Consommation VE (kW) | FM sensors 61-70 |
| 3 | SOC Batteries (kWh) | FM sensors 51-60 |
| 4 | SOC V2G (kWh) | FM sensors 71-80 |
| 5 | Flexibilite Totale (kWh) | Calculated |
| 6 | Impact Reseau (kW) | Calculated |
| 7 | Irradiance & Temperature | FM sensors 81-82 |
| 8 | Prix DSO (EUR/MWh) | FM sensor 85 |
| 9 | DSR Price Signal (EUR/MWh) | FM sensor 84 (OpenADR) |
| 10 | Load Control Signal (%) | FM sensor 86 (OpenADR) |
| 11 | Impact Flexibilite Reseau (kW) | Calculated |
| 12 | Battery Power (kW) | FM sensors 51-60 (S2) |
| 13 | EV Power (kW) | FM sensors 61-70 (S2) |
| 14 | Flexibility Impact (kW) | Calculated (S2) |
| 15 | EV Charging Power (kW) | FM sensors 61-70 (CitrineOS) |
| 16 | Active Charging Sessions | Calculated |
| 17 | EV Flexibility Potential (kWh) | Calculated |

## Backup Strategy

### Automated Backups
- **Script**: `/home/eric/cariflex/scripts/full_backup.sh`
- **Location**: `/home/eric/backups/cariflex/YYYYMMDD_HHMMSS.tar.gz`
- **Contents**: PostgreSQL, Redis, FM config, OpenADR scripts, Grafana dashboards, container states, network config

## Deployment

### Docker Compose Files
| File | Purpose |
|------|---------|
| `/home/eric/flexmeasures/docker-compose.yml` | FM core stack |
| `/home/eric/flexmeasures/docker-compose.openadr.yml` | OpenADR VTN/VEN |
| `/home/eric/cariflex/config/docker-compose-citrineos.yml` | CitrineOS stack |
| `/home/eric/cariflex/config/docker-compose-citrineos-ui-noproxy.yml` | UI without Traefik (testing) |

### CitrineOS Operator UI
- **URL**: https://citrineos.digitribe.fr
- **Image**: `citrineos-core-main-citrine-ui:latest` (custom build)
- **Build**: `cd /home/eric/cariflex/tools/citrineos-core-main && docker compose -f docker-compose.local.yml build citrine-ui`
- **Tech stack**: Next.js 15.2, React 19, Refine, Leaflet + OpenStreetMap
- **Map**: Replaced Google Maps with Leaflet + OpenStreetMap (no API key needed)
- **Geocoding**: Nominatim OSM (free, no API key)
- **Dependencies**: `leaflet`, `react-leaflet`, `@types/leaflet`

### Deployment Commands
```bash
# FM stack
cd /home/eric/flexmeasures && docker compose up -d

# OpenADR stack
cd /home/eric/flexmeasures && docker compose -f docker-compose.openadr.yml up -d

# CitrineOS stack
cd /home/eric/cariflex/config && docker compose -f docker-compose-citrineos.yml up -d

# Rebuild UI (after code changes)
cd /home/eric/cariflex/tools/citrineos-core-main && docker compose -f docker-compose.local.yml build citrine-ui && docker compose -f docker-compose-citrineos.yml up -d citrineos-operator-ui

# Verify all
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "flexmeasures|openadr|citrine|grafana"
```

## Troubleshooting

### OpenADR Issues
- **VEN not connecting**: Check UFW rules for 192.168.240.0/24
- **No price data**: Check VTN logs: `docker logs openadr-vtn`

### CitrineOS Issues
- **RabbitMQ connection**: Check network aliases on config_cariflex-internal
- **OCPP communication**: Verify charge point network connectivity

### FM Scheduling Issues
- **No schedules created**: Check price sensor data (84)
- **Worker not running**: `docker restart flexmeasures-worker`

## References
- FlexMeasures: https://flexmeasures.readthedocs.io/
- OpenLEADR: https://openleadr.org/
- CitrineOS: https://citrineos.github.io/
- S2 Protocol: https://s2-standard.github.io/
- OCPP 2.0.1: https://www.openchargealliance.org/protocols/ocpp-201/
