# Brief agent — plugin V2C Trydan

> Repo : `etm-powersync-plugins-modbus` · Dossier : `v2c/` · Branche : `feature/v2c-trydan`
> Borne : V2C Trydan / Trydan Pro (monophasée·triphasée, ES).
> Comm locale : **Modbus TCP (port 502)** [Étape 1] + **Modbus RTU / RS485** [Étape 2] + **HTTP REST** (discovery/diag).
> Statut cible : **Partiel** (comme Keba) — PAS dans la matrice beta validée. Ne pas promettre tant que non testé sur borne réelle.
> Borne de test : IP 192.168.1.127 (Modbus TCP / LAN).
>
> **Livraison en 2 étapes** :
> - **Étape 1 — Modbus TCP** : implémentation complète + testable maintenant sur la borne réelle. C'est le périmètre de la beta.
> - **Étape 2 — Modbus RTU (RS485)** : ajout d'un second transport réutilisant le cœur. Hors beta, non bloquant pour le lab field test.
>
> **Sources de vérité croisées (juin 2026)** :
> - Lib officielle V2C : `github.com/V2Charge/Trydan_Modbus_TCP`, fichier `src/v2ctrydan/modbus.py` (carte registres + décodage float + params série RTU).
> - Carte officielle RS485 (Google Sheet) : intitulée « V2C - Datamanager Modbus **TCP & RTU** » → **une seule carte de registres pour les deux transports**.
> - Implémentation de référence evcc : `charger/trydan.go` (sémantique ChargeState, conflit Dynamic, endpoints HTTP).

---

## RÔLE

Créer le plugin nymea `v2c` dans `etm-powersync-plugins-modbus`, sur le modèle des plugins
existants du repo (`abbterra` pour la structure evcharger Modbus TCP, `eastron` pour le pattern
registres). ThingClass `trydan` implémentant l'interface **`evcharger`** — c'est elle que le
moteur energy-etm consomme (states `chargingEnabled`, `maxChargingCurrent`, `pluggedIn`,
`charging`, `currentPower` ; actions `setChargingEnabled`, `setMaxChargingCurrent`).

## ARCHITECTURE TRANSPORT — séparation cœur / transport (règle d'or)

Le point central de ce plugin : **la carte de registres, le décodage des valeurs et la
gestion du conflit Dynamic sont STRICTEMENT IDENTIQUES en TCP et en RTU** (confirmé par la
feuille officielle « TCP & RTU » : mêmes adresses, même format). Seule la couche transport change.

→ **Le code doit isoler la logique métier du transport.** Lectures/écritures de registres,
décodage float, logique evcharger, gestion conflit : tout doit passer par une abstraction de
transport (master Modbus) sans savoir si dessous c'est du TCP ou du RTU.

- **Étape 1** : une seule implémentation concrète de transport = **Modbus TCP** (master
  libnymea-modbus TCP). Tout le reste du plugin est écrit dessus mais sans le coupler en dur.
- **Étape 2** : ajouter une implémentation **Modbus RTU** (master libnymea-modbus RTU) qui se
  branche sur la même abstraction. AUCUN registre, AUCUN décodage, AUCUNE logique conflit à
  réécrire — sinon c'est que l'étape 1 a mal découpé.

🔴 **Interdiction étape 1** : ne PAS écrire de logique métier qui appelle directement le client
TCP. Si l'agent se retrouve à devoir réécrire le décodage pour l'étape 2, l'étape 1 est ratée.

## TRANSPORT — détails par couche

### HTTP (commun aux deux étapes — discovery + diag)
1. **Découverte** : la Trydan TCP est en WiFi/LAN, pas de discovery Modbus natif.
   `GET /RealTimeData` (JSON) sert de probe d'identification pendant le setup
   (NetworkDeviceDiscovery + test HTTP). ⚠️ Le JSON expose le champ **`Paused`** (pas `PauseState`).
2. **Fallback diagnostic** : compléter un champ manquant par HTTP est permis, mais le chemin de
   contrôle (pause, intensité) reste Modbus.

### Étape 1 — Modbus TCP
- Port **502**, unit id **1**. Master libnymea-modbus TCP. Setup par IP manuelle + discovery réseau.

### Étape 2 — Modbus RTU (RS485)
- Couche physique RS485 série. Params confirmés par la lib officielle (`modbus.py`) :
  **19200 baud, 8N1 (parité N), unit id 1**.
- Pas de discovery réseau : setup = sélection du port série + unit id (modèle des plugins RTU
  existants si le repo en a, sinon paramRegisters série classiques nymea).
- Réutilise intégralement le cœur de l'étape 1. Le HTTP discovery n'a PAS de sens en RTU pur
  (pas d'IP) → le setup RTU est manuel.

Ne PAS implémenter plusieurs ThingClasses pour les transports — **une seule ThingClass `trydan`**,
le transport est un paramètre/variante interne.

## ⚠️ DÉCODAGE LECTURE — chaque valeur = UNE transaction (NE PAS regrouper) [commun TCP+RTU]

Source confirmée (`modbus.py`, `_read_register` + `regenera_float`) :
- Lecture : `read_holding_registers(addr, count=2, unit=1)` → **2 registres par valeur**.
- Décodage : **float 32 bits, `byteorder=Endian.Big`, `wordorder=Endian.Big`** (Big/Big).
- Les valeurs entières (ChargeState, Intensity, Dynamic…) sont encodées en float32 puis
  arrondies : décoder en float, puis caster int. NE PAS supposer du uint16 brut.

🔴 **PIÈGE FIRMWARE** : valeurs à adresses **consécutives** (0x0BC2, 0x0BC3…) alors que chacune
occupe 2 registres → fenêtres **qui se chevauchent**. Bizarrerie assumée du firmware V2C (la lib
officielle lit valeur par valeur). **INTERDICTION de regrouper en block read** dans le JSON ou
le code. libnymea-modbus regroupe volontiers les registres contigus — ici ça corrompt tout.
Chaque valeur = une transaction Modbus individuelle de 2 registres. Vrai en TCP comme en RTU.

## CARTE REGISTRES (source : `modbus.py`, vérifiée juin 2026 — identique TCP/RTU)

### Lecture — holding registers (READ, base 0x0BC2)
| Reg | Nom | Type/Note |
|---|---|---|
| 0x0BC2 | ChargeState | **0=A déconnecté, 1=B connecté sans charge, 2=C en charge** ✅ confirmé (evcc `Status()`) |
| 0x0BC3 | ChargePower | W → `currentPower` |
| 0x0BC4 | ChargeEnergy | kWh session — **NE PAS exposer en `sessionEnergy`** (voir ChargeRater ci-dessous) |
| 0x0BC5 | SlaveError | code erreur → state diag |
| 0x0BC6 | ChargeTime | s |
| 0x0BC7 | ValuePWM | duty CP |
| 0x0BC8 | HousePower | W — pince CT maison (si installée) → state diag |
| 0x0BC9 | PowerFV | W — production PV vue par la borne (si configurée) → state diag |
| 0x0BCA | PauseState | 0=actif, 1=pausé |
| 0x0BCB | Lock | 0=déverrouillé, 1=verrouillé |
| 0x0BCC | Program (Promgram) | timer interne |
| 0x0BCD | Intensity | A courante |
| 0x0BCE | Dynamic | **mode dynamique V2C on/off — pivot du conflit, lire à CHAQUE poll** |
| 0x0BCF | Payment | hors scope |
| 0x0BD0 | OCPP | hors scope |
| 0x0BD1 | MinIntensity | A |
| 0x0BD2 | MaxIntensity | A |
| 0x0BD3 | PauseDynamic | **levier de neutralisation propre — voir CONFLIT** |
| 0x0BD4 | DynamicPowerMode | |
| 0x0BD5 | ContractedPower | W |

### Écriture — write single register FC6, uint16 (WRITE, base 0x177A)
| Reg | Nom | Usage HEMS |
|---|---|---|
| 0x177A | PauseState | **setChargingEnabled** (1=pause → désactivé, 0=actif) |
| 0x177B | Lock | **à écrire en miroir de PauseState** (voir logique enable) |
| 0x177C | Program | timer interne — **ne pas utiliser** (conflit moteur) |
| 0x177D | Intensity | **setMaxChargingCurrent** (A) |
| 0x177E | Dynamic | **NE JAMAIS écrire 0** (voir CONFLIT — casse la télémétrie) |
| 0x177F | Payment | hors scope |
| 0x1780 | OCPP | hors scope |
| 0x1781 | MinIntensity | borne basse (6 A) |
| 0x1782 | MaxIntensity | borne haute (bug historique V2C corrigé upstream — vérifier firmware) |
| 0x1783 | PauseDynamic | **levier de neutralisation : 1=suspend PID interne, 0=relâche** |
| 0x1784 | DynamicPowerMode | ne pas toucher sans raison |
| 0x1785 | ContractedPower | protection abonnement interne borne — ne pas toucher |

Écriture confirmée : `write_register(addr, value, unit=1)` — FC6 simple, valeur uint16
(`modbus.py`, `_write_register`). Pas de write float en écriture, contrairement aux lectures.

## 🔴 CONFLIT D'OPTIMISEURS — le piège central (commun TCP+RTU)

La Trydan embarque SON PROPRE pilotage solaire (« Dynamic » : pince CT + lecture onduleur,
PID interne). Deux cerveaux ne doivent pas piloter la même borne — MAIS la neutralisation
naïve (écrire Dynamic=0) est **un bug** :

> **Leçon evcc (commentaire explicite dans `trydan.go`)** : si on désactive `Dynamic`,
> **la borne arrête de remonter les lectures de puissance**. On perd `currentPower`.
> Donc on NE touche JAMAIS au registre Dynamic (0x177E).

**Stratégie correcte — suspendre via PauseDynamic, pas désactiver Dynamic** :

1. À chaque poll, LIRE `Dynamic` (0x0BCE). État que l'app V2C du client peut changer à tout
   moment → re-lecture systématique, pas seulement à l'init.
2. Si `Dynamic == 1` (optimiseur interne présent) :
   - HEMS **prend** le contrôle (charge activée) → écrire `PauseDynamic = 1` (0x1783).
     Suspend le PID interne SANS couper la télémétrie.
   - HEMS **relâche** (charge désactivée) → écrire `PauseDynamic = 0`.
   - N'écrire `PauseDynamic` **que si `Dynamic == 1`** a été lu (sinon sans objet).
3. Si `Dynamic == 0` : pas de PID interne, rien à suspendre. Pilotage HEMS direct.
4. Exposer un state `conflictDetected` / `internalOptimizerActive` reflétant `Dynamic == 1`,
   et logger un avertissement clair. NE PAS modifier silencieusement le mode du client.
5. Setting de Thing `suspendInternalOptimizer` (défaut: oui, demander à la première détection) :
   contrôle si le plugin a le droit d'écrire PauseDynamic. Si refus, avertir que l'arbitrage
   sera combattu par le PID (oscillations).
6. `decisionReason` côté moteur doit pouvoir refléter « borne en autopilotage V2C — pilotage
   HEMS suspendu » si Dynamic==1 et suspension refusée/échouée.

**Logique `chargingEnabled` (state + action) — Lock inclus** (source evcc `Enabled()`/`Enable()`) :
- `chargingEnabled = (PauseState == 0) ET (Lock == 0)`.
- `setChargingEnabled(false)` → écrire `PauseState=1` ET `Lock=1`.
- `setChargingEnabled(true)`  → écrire `PauseState=0` ET `Lock=0`, puis gérer PauseDynamic
  selon Dynamic comme ci-dessus.

Même problème que la PV-Edition Keba : borne « intelligente » à neutraliser proprement — mais
ici via PauseDynamic, pas une coupure brutale.

## ⚠️ SESSION ENERGY — ne pas l'exposer (pour l'instant)

evcc a **retiré** son interface ChargeRater pour la Trydan (cf. `github.com/evcc-io/evcc/issues/28047`)
— remontée d'énergie session jugée peu fiable côté firmware. Donc `ChargeEnergy` (0x0BC4) reste
un **state diag uniquement**, ne PAS le câbler sur `sessionEnergy` tant que non validé sur borne
réelle avec compteur de référence.

## SÉCURITÉ / ROBUSTESSE [commun]

- Anti-flapping : respecter les verrous du moteur (`chargingEnabledLockDuration` etc.) — le
  plugin n'introduit PAS sa propre cadence d'écriture.
- Connexion perdue (TCP timeout OU RTU pas de réponse) → state `connected=false`, backoff,
  pas de retry agressif.
- Écritures idempotentes : ne réécrire Intensity / PauseDynamic que sur transition réelle
  (la borne journalise chaque write ; éviter usure flash et spam).
- Min 6 A (IEC 61851). Clamper toute consigne < 6 A à pause (PauseState=1).
- Float decode : 2 registres, Big/Big, transactions individuelles. NE PAS regrouper.

## INTERDIT [commun]

- Écrire le registre `Dynamic` (0x177E) — casse la télémétrie. Utiliser PauseDynamic.
- Regrouper les lectures en block read (chevauchement firmware).
- **Coupler la logique métier au transport TCP** (casse l'étape 2).
- Toucher aux plugins publiés du repo (`eastron`, `abbb2x`, `abbterra`, `waveshare-relay-d8`).
- Promettre la borne dans la doc/matrice beta (statut Partiel, non testé matériel).
- Dépendance à un service privé ETM — plugin 100% GPL, parle à la borne en direct.
- Implémenter OCPP/Payment/RFID — hors scope HEMS.
- Exposer `sessionEnergy` depuis ChargeEnergy sans validation matérielle.

## DEFINITION OF DONE

### Étape 1 — Modbus TCP (périmètre beta)
1. Plugin compile (amd64 + cross arm64) et s'intègre au `.pro` du repo.
2. **Cœur métier découplé du transport** : registres/décodage/conflit passent par une
   abstraction de master Modbus, implémentation concrète = TCP uniquement.
3. ThingClass `trydan` expose l'interface `evcharger` complète + states diag
   (HousePower, PowerFV, SlaveError, Dynamic/conflit). PAS de sessionEnergy.
4. Discovery réseau (probe HTTP `/RealTimeData`) + setup par IP manuelle fonctionnels.
5. Gestion du conflit Dynamic **via PauseDynamic** (lecture Dynamic à chaque poll, state
   `conflictDetected`, setting `suspendInternalOptimizer`). JAMAIS d'écriture Dynamic=0.
6. Logique `chargingEnabled` = PauseState==0 ET Lock==0 ; écritures en miroir.
7. Lectures en transactions individuelles de 2 registres (float Big/Big), pas de block read.
8. Testé contre simulateur Modbus TCP (registres mockés). Test sur borne réelle (192.168.1.127)
   = jalon séparé, AVANT tout passage en « Supporté ».
9. Entrée `PORTING_STATUS_modbus.md` : statut Partiel, sources notées, firmware à documenter.

### Étape 2 — Modbus RTU (RS485, hors beta)
1. Ajout d'une implémentation de transport **RTU** sur la même abstraction — **zéro** réécriture
   du cœur (registres, décodage, conflit, logique evcharger).
2. Setup RTU : sélection port série + unit id ; params **19200 8N1, unit 1** (confirmés lib V2C).
3. Pas de discovery HTTP en RTU (setup manuel).
4. Testé contre simulateur Modbus RTU (mocké). Test sur borne réelle via RS485 = jalon séparé.
5. `PORTING_STATUS_modbus.md` mis à jour : RTU ajouté, statut Partiel, params série notés.

## RÉFÉRENCES

- Lib officielle : `github.com/V2Charge/Trydan_Modbus_TCP` → `src/v2ctrydan/modbus.py`
  (carte registres + décodage float Big/Big + FC6 écriture + params série RTU 19200 8N1).
- Carte officielle RS485/TCP (Google Sheet) : gid=0 (Modbus, « TCP & RTU ») et gid=1147522182 (HTTP).
- Implémentation evcc de référence : `charger/trydan.go` (ChargeState 0/1/2 = A/B/C,
  conflit Dynamic via PauseDynamic, Lock en miroir, ChargeRater retiré issue #28047).
- API HTTP : endpoints `/RealTimeData` (lecture JSON, champ `Paused`) et `/write/<Param>=<val>`
  (réponse texte `"OK"`) — confirmés via evcc.
- Dans le repo : `abbterra` (structure evcharger Modbus TCP), `PORTING_STATUS_modbus.md`,
  + tout plugin RTU existant comme modèle de couche série pour l'étape 2.
- Firmware : updates V2C mentionnent des fixes Modbus (Max/MinIntensity) — documenter la
  version firmware minimale constatée lors du test réel sur 192.168.1.127.