etm-powersync-plugins-modbus/specs/fronius-sunspec.md

# Spec — support Fronius du plugin SunSpec

Critères d'acceptation numérotés, dérivés du contrat de conception Fronius
(document interne, non versionné ici) et du brief de lot 0.

Deux natures de critères, à ne jamais mélanger dans un même commit :

| Bloc | Nature | Commits |
|---|---|---|
| **AC-1 … AC-4** | correctifs d'anomalies présentes dans nymea 1.15.2 amont | message en anglais, aucune référence ETM / Fronius / PowerSync — ils ont vocation à être proposés en amont |
| **AC-5 … AC-15** | spécifique ETM (vendor `fronius`) | commits séparés, préfixe libre |

Statut des critères : voir `## Tableau de statut` en fin de document.

---

## Invariants applicables à toute l'implémentation

Ces règles ne sont pas des critères testables un à un ; elles conditionnent
chaque AC ci-dessous.

- **INV-1 — aucune adresse de registre en dur.** Toute lecture et toute écriture
  passent par la découverte dynamique puis par les offsets du modèle. Le nombre
  de blocs répétitifs du modèle 160 décale l'adresse absolue du modèle 124, et
  sans batterie le modèle 124 est absent : une adresse absolue n'est jamais
  valide durablement. Les adresses des documentations constructeur servent à
  valider un dump, jamais à adresser.
- **INV-2 — `libnymea-sunspec` n'est jamais modifiée.** Tout vit dans
  `sunspec/`. Voir `sunspec/VENDORED.md`.
- **INV-3 — une consigne écrite est relue.** Plusieurs onduleurs acceptent une
  écriture puis l'ignorent sans code d'exception Modbus.
- **INV-4 — la régulation se ferme sur la puissance mesurée**, jamais sur la
  consigne émise.
- **INV-5 — les scale factors ne sont pas statiques.** Ils changent avec le
  firmware et en fonctionnement (auto-scale). Relire le SF concerné
  immédiatement avant conversion et avant écriture.

---

## Bloc 0 — correctifs upstream

### AC-1 — plage des consignes de charge/décharge (anomalie A1)

`chargingRate` et `dischargingRate` sont déclarés `minValue: 0, maxValue: 100`
dans `integrationpluginsunspec.json`. La plage réelle des points `InWRte` /
`OutWRte` du modèle 124 est **−100,00 … +100,00** (`int16`, SF −2).

**Critère.** Dans `integrationpluginsunspec.json`, les deux states
`chargingRate` et `dischargingRate` de la thingClass `sunspecStorage` ont
`minValue == -100` et `maxValue == 100`.

**Pourquoi c'est bloquant.** Avec la borne basse à 0, une consigne de charge
forcée (valeur négative, convention de signe du constructeur) est structurellement
inexprimable : nymea rejette le paramètre d'action avant qu'il n'atteigne le
plugin.

---

### AC-2 — cohérence lecture/écriture des consignes (anomalie A2)

`onStorageBlockUpdated()` alimente `chargingRate` depuis `wChaGra()` et
`dischargingRate` depuis `wDisChaGra()`. Ce sont les **gradients**
(`% WChaMax/s`), en lecture seule sur GEN24. Les actions, elles, écrivent dans
`InWRte` / `OutWRte` (`% WChaMax`). Le state relu n'est donc pas la grandeur
écrite : l'utilisateur écrit 50, relit tout autre chose.

**Critère.**
1. `chargingRate` est alimenté depuis `inWRte()`.
2. `dischargingRate` est alimenté depuis `outWRte()`.
3. Les gradients restent exposés, mais sous des noms non ambigus :
   `chargeGradient` ← `wChaGra()`, `dischargeGradient` ← `wDisChaGra()`,
   en lecture seule.

---

### AC-3 — réconciliation de `enableDischarging` (anomalie A3)

`onStorageBlockUpdated()` réconcilie `enableCharging` depuis
`storCtlMod().testFlag(Storctl_modCharge)` mais ne fait rien pour
`enableDischarging`. Le state reste donc figé sur sa dernière valeur écrite, et
diverge silencieusement de l'onduleur dès que celui-ci change d'état seul.

**Critère.** `enableDischarging` est alimenté depuis
`storCtlMod().testFlag(Storctl_modDiScharge)`, symétriquement à
`enableCharging`.

---

### AC-4 — écriture de `InOutWRte_RvrtTms` (anomalie A4)

Le setter `setInOutWRteRvrtTms()` existe dans `libnymea-sunspec` mais n'est
jamais appelé. `RvrtTms` est le délai au bout duquel l'onduleur abandonne la
consigne et reprend son comportement natif. À 0 — le défaut — une consigne reste
active indéfiniment, y compris si le HEMS s'arrête, perd le réseau ou plante.

**Critère.**
1. Une valeur `revertTime` est configurable par thing (paramètre de la
   thingClass `sunspecStorage`), en secondes.
2. Toute séquence de consigne (`InWRte`, `OutWRte`, `StorCtlMod`, `ChaGriSet`)
   se termine par une écriture de `InOutWRte_RvrtTms` à cette valeur.
3. `RvrtTms` est écrit **en dernier** dans la séquence.
4. Défaut du vendor `sunspec` générique : **0** (comportement amont inchangé).
   Défaut du vendor `fronius` : **300** (voir AC-10).

**Plage.** 0 – 28800 s.

---

## Bloc 1 — vendor `fronius`, structure

### AC-5 — filtre fabricant à la découverte

**Critère.** Pour `froniusConnectionThingClassId`, `discoverThings()` ne retient
que les résultats dont au moins un modèle Common porte un nom de fabricant
contenant `Fronius`, insensible à la casse (`hasManufacturer()` fait déjà un
`contains()` insensible à la casse). Les autres résultats sont ignorés, sans
créer de `ThingDescriptor`.

Symétriquement, un GEN24 ne doit pas être proposé deux fois : le vendor
générique `sunspecConnection` continue de le proposer (comportement amont
inchangé) ; c'est l'utilisateur qui choisit la thingClass qu'il appaire.

---

### AC-6 — ordre des octets

**Critère.** Une connexion `fronius` utilise `ByteOrderLittleEndian`, c'est-à-dire
le défaut SunSpec, à la découverte comme à la connexion.

Le `ByteOrderBigEndian` forcé du vendor `solarEdge` est une anomalie propre à
SolarEdge et ne doit pas être étendue.

> **Inférence, pas fait mesuré.** L'ordre des octets du GEN24 n'est documenté
> nulle part dans la documentation constructeur consultée ; on suppose le défaut
> SunSpec. À confirmer au banc (phase 2) puis sur matériel (phase 3).

---

### AC-7 — paramètres de la thingClass `froniusConnection`

**Critère.** La thingClass `froniusConnection` existe, sous un bloc `vendors`
→ `fronius`, et porte exactement :

| Paramètre | Défaut | Contrainte |
|---|---|---|
| `address` | — | comme `sunspecConnection` |
| `hostName` | — | comme `sunspecConnection` |
| `macAddress` | — | comme `sunspecConnection` |
| `port` | 502 | — |
| `slaveId` | **1** | fixe en TCP sur GEN24 : masqué ou en lecture seule |
| `meterSlaveId` | **200** | plage 0 – 247, `advanced`, **0 = pas de compteur sur cette connexion** |

Aucun paramètre `endianness` n'est exposé (cf. AC-6 : la valeur est imposée).

---

### AC-8 — plancher de cadence d'interrogation

Le support constructeur recommande un intervalle d'interrogation supérieur à
**7 secondes** pour les applications tierces. En deçà, la surcharge de
communication peut faire passer l'onduleur hors ligne vis-à-vis du portail
constructeur ; le rétablissement exige une coupure AC+DC d'environ une minute
**sur site**.

**Critère.**
1. Défauts du vendor `fronius` : `updateInterval = 10` s, `timeout = 2000` ms,
   `numberOfRetries = 3`.
2. **Garde-fou dur** : toute valeur d'intervalle strictement inférieure à 7 s
   configurée sur une connexion `fronius` est remontée à 7 s, avec un
   `qCWarning` explicite. Ce n'est pas une valeur par défaut modifiable : c'est
   un plancher dans le code.
3. Le plancher s'applique aussi en debug.
4. Le vendor `sunspec` générique et le vendor `solarEdge` ne sont pas affectés.

---

### AC-9 — registres interdits en écriture

Sur GEN24, ces écritures sont acceptées puis **ignorées sans code d'exception
Modbus** — l'échec est invisible côté HEMS :
`WChaMax`, `WChaGra`, `WDisChaGra`, `InOutWRte_WinTms`, `InOutWRte_RmpTms`,
`VAChaMax` (dont le scale factor n'est de surcroît pas supporté).

**Critère.** Sur une connexion `fronius`, les setters correspondants
(`setWChaMax`, `setWChaGra`, `setWDisChaGra`, `setInOutWRteWinTms`,
`setInOutWRteRmpTms`, `setVAChaMax`) ne sont **jamais** appelés. Une tentative
est refusée avant émission, avec un `qCWarning` nommant le registre.

---

### AC-10 — `revertTime` par défaut à 300 s sur `fronius`

**Critère.** La thingClass `froniusConnection` impose `revertTime = 300` s aux
things `sunspecStorage` créés sous elle, là où le vendor générique laisse 0
(AC-4.4).

> **Hypothèse de travail — décision D4 non validée.** Le contrat recommande
> `RvrtTms = 300 s` à chaque consigne, avec rafraîchissement à chaque cycle
> d'optimisation, plutôt que le choix inverse (ne rien écrire) fait par evcc.
> Le raisonnement retenu : ce qui est acceptable pour un logiciel auto-hébergé
> ne l'est pas pour un produit installé sous la responsabilité d'ETM — une
> consigne persistante après un crash du HEMS immobilise la batterie du client.
> **Prérequis non levé :** la sémantique du timer est décrite dans le chapitre
> général du manuel et illustrée sur le modèle 123, pas sur le 124. Elle doit
> être vérifiée expérimentalement sur le modèle 124 avant d'être figée. Si la
> vérification échoue : replier sur `RvrtTms = 0` + watchdog applicatif côté
> HEMS.

---

## Bloc 2 — chaîne de pilotage batterie

### AC-11 — correspondance intention HEMS → registres

Convention de signe du constructeur : **négatif = charge, positif = décharge**.

**Critère.** Les six modes produisent exactement cette séquence de registres :

| Mode | `ChaGriSet` | `StorCtl_Mod` | `InWRte` | `OutWRte` | `RvrtTms` |
|---|---|---|---|---|---|
| `NORMAL` | — | 0 | — | 100 | 300 |
| `NO_DISCHARGE` | — | 2 | — | 0 | 300 |
| `NO_CHARGE` | — | 1 | 0 | — | 300 |
| `FROZEN` | — | 3 | 0 | 0 | 300 |
| `FORCE_CHARGE(p %)` | 1 | 2 | — | **−p** | 300 |
| `LIMIT(c %, d %)` | — | 3 | c | d | 300 |

`—` = registre non écrit pour ce mode.

**Ordre d'écriture imposé :** `ChaGriSet` → `StorCtl_Mod` → `InWRte` / `OutWRte`
→ `RvrtTms` en dernier.

`StorCtl_Mod` est un bitfield : bit 0 = CHARGE, bit 1 = DISCHARGE.
`ChaGriSet` : 0 = PV, 1 = GRID.

> Les exemples du manuel constructeur affichent des fenêtres de puissance dont
> les signes sont incohérents avec la convention annoncée. Les **valeurs de
> registres** de ces exemples sont correctes, les fenêtres annotées ne le sont
> pas : la table ci-dessus est construite sur les valeurs de registres.

---

### AC-12 — relecture du scale factor avant écriture

**Critère.** `InOutWRte_SF` est relu immédiatement avant chaque écriture de
`InWRte` / `OutWRte`. Une valeur de SF mise en cache lors d'un cycle
d'interrogation antérieur n'est pas réutilisée.

Motif (INV-5) : le constructeur avertit que les SF changent avec le firmware
**et en fonctionnement**. Un SF auto-scalé entre la lecture et l'écriture
produit une consigne d'un facteur 10 à côté.

---

### AC-13 — vérification par relecture et state `controlHealthy`

**Critère.**
1. Après chaque séquence de consigne, `StorCtl_Mod`, `InWRte`, `OutWRte` et
   `ChaGriSet` sont relus et comparés aux valeurs écrites.
2. En cas de divergence : `qCWarning` explicite nommant le registre, la valeur
   écrite et la valeur relue.
3. Un state `controlHealthy` (bool) passe à `false` en cas de divergence, à
   `true` après une séquence vérifiée conforme.

C'est la seule parade aux échecs silencieux du §5 du contrat (pilotage Modbus
non autorisé, charge réseau non autorisée, restriction d'IP, assistant de
tarification qui écrase les consignes).

---

## Bloc 3 — modèle 160 (MPPT et blocs batterie)

### AC-14 — identification des blocs par `IDStr`, jamais par index

Les blocs répétitifs du modèle 160 portent les chaînes `MPPT 1`, `MPPT 2`,
`StCha 3`, `StDisCha 4`. Sur un onduleur à 3 ou 4 MPPT, les blocs batterie ne
sont **pas** en position 3 et 4.

**Critère.**
1. Le classement d'un bloc en « string PV » ou « batterie » se fait sur
   `inputIdSting()`, jamais sur l'index du bloc.
2. Un bloc dont `IDStr` commence par `MPPT` est un string PV.
3. Un bloc dont `IDStr` commence par `StCha` est le bloc batterie en charge ;
   `StDisCha`, le bloc batterie en décharge.
4. Un `IDStr` inconnu n'est pas classé et ne contribue à aucun agrégat ; il est
   signalé par un `qCWarning`.

Le préfixe est comparé de façon insensible à la casse et après suppression des
espaces de bord. **Attention à l'ordre du test** : `StDisCha` contient
`StCha` comme sous-chaîne uniquement si on teste par `contains()` — le test doit
donc porter sur le préfixe, et `StDisCha` doit être testé avant `StCha` si une
implémentation par `startsWith` en cascade est retenue.

---

### AC-15 — agrégats de puissance issus du modèle 160

`DCW` est un `uint16`, donc toujours positif : le signe est porté par le bloc
actif, le bloc inactif étant à zéro.

**Critère.**
1. Puissance PV = Σ `DCW` des blocs classés « string PV ».
2. Puissance batterie = `DCW[StDisCha]` − `DCW[StCha]`, **positif = décharge**.
3. `DCW_SF` est partagé par tous les modules et auto-scalé : il est relu avant
   conversion (INV-5).
4. **Aucun calcul de production PV par différence AC/DC ± batterie.** Le GEN24
   expose la puissance PV réelle string par string ; répliquer le contournement
   du vendor `solarEdge` — qui existe parce que cet onduleur n'expose pas le
   modèle 160 — serait une régression.

---

## Hypothèses de travail — points non tranchés

Chacun de ces points est traité selon l'hypothèse indiquée, faute de
confirmation humaine au moment de l'implémentation.

| # | Point | Statut au contrat | Hypothèse retenue |
|---|---|---|---|
| H-1 | Architecture multi-unit-ID (D1) | ✅ tranché, **implémenté** | **Option A′** : un thing `froniusConnection` portant deux `SunSpecConnection` internes (onduleur `slaveId`, compteur `meterSlaveId`). UX correcte, aucune modification de `libnymea-sunspec`, rebasabilité préservée. La seconde connexion vit dans une table distincte de `m_sunSpecConnections`, ce qui laisse les vendors générique et `solarEdge` inchangés ligne pour ligne. |
| H-2 | Watchdog batterie (D4) | ⬜ à valider | **`RvrtTms = 300 s`** à chaque consigne (AC-10). Prérequis non levé : sémantique du timer à vérifier sur le modèle 124, pas seulement sur le 123. |
| H-3 | Ordre des octets du GEN24 | inférence explicite du brief | Défaut SunSpec, little-endian (AC-6). Non documenté par le constructeur. |
| H-4 | Deux connexions TCP simultanées vers le même onduleur | ✅ **mesuré** sur le GEN24 client | Les deux connexions tiennent simultanément. Reste distincte, et **non mesurée**, la charge de deux *découvertes* simultanées : le plugin ne monte donc la connexion compteur qu'une fois la découverte primaire terminée. La sérialisation des lectures d'interrogation reste un chantier à part. |
| H-5 | Assistant de tarification écrasant les consignes | « à confirmer », absent de la doc constructeur | Constat empirique tiers. Traité en message de diagnostic (AC-13.2), pas en logique de pilotage. |
| H-6 | Ordre des phases du chantier | contrat §8 : la phase 2 ne démarre pas avant que la phase 1 (simulateur) soit verte | **Précondition non vérifiée ici.** Le simulateur `hems-sim` n'a pas été exécuté. Les AC ci-dessous sont validés par tests unitaires hors ligne, ce qui ne remplace pas une validation contre un simulateur reproduisant la sémantique du constructeur. |

---

## Non vérifiable par les tests unitaires de ce dépôt

À porter en phase 2 (banc / simulateur) puis en phase 3 (matériel) :

- l'ordre des octets réel du GEN24 (H-3) ;
- le comportement en double connexion TCP (H-4) ;
- l'expiration effective de `RvrtTms` sur le modèle 124 (H-2) ;
- le refus d'écriture par exception Modbus quand le pilotage n'est pas autorisé
  côté onduleur ;
- l'auto-scale effectif des scale factors en fonctionnement (INV-5) ;
- le fait que les registres de AC-9 soient bien ignorés silencieusement ;
- le comportement des blocs batterie du modèle 160 selon la version de firmware
  (avant/après 1.31, `DCV` et `DCWH` reportés en continu ou zérotés à l'arrêt).

---

## Hors périmètre

- modèles 7xx ;
- Modbus RTU ;
- onduleurs Verto / Tauro (le mapping MPPT diffère — c'est le motif d'AC-14,
  mais ils ne sont pas testés) ;
- toute modification de `libnymea-sunspec` (INV-2) ;
- tout mécanisme de compensation PV à la SolarEdge (AC-15.4) ;
- anomalies A5 (modèle 160 absent du `switch` de `processDiscoveryResult()`),
  A6 (`MinRsvPct` non exposé) et A7 (`.toInt()` sur des paramètres destinés à
  des setters `float`) : réelles et documentées au contrat, mais hors des quatre
  correctifs demandés pour ce lot.

---

## Tableau de statut

Suite : `sunspec/tests/`, **60 tests, 60 verts** — 44 en logique pure, 6 sur
l'aiguillage du plugin, 10 sur le multi unit ID.

Une quatrième suite, `tests/integration`, monte le plugin face à un vrai
appareil. Elle est construite mais **jamais lancée par `make check`** : elle
exige `SUNSPEC_TEST_HOST`.

**Exécutée le 2026-08-02 contre le simulateur `froniusgen24-sunspec` du banc :
8 tests, 8 verts.** Unit 1 = modèles 1/113/120-123/160, unit 200 = 1/213, sans
batterie. Les deux corrections qu'aucune suite hors ligne ne pouvait couvrir y
sont vérifiées, et chacune a été confirmée capable d'échouer en réintroduisant
la forme pré-F3 : le balayage des orphelins non corrigé supprime **les deux**
enfants en deux cycles de découverte, et la propagation de `connected` non
scindée fait passer le parent déconnecté sur la seule chute du compteur.

Reste non exécuté sur **matériel réel** : le GEN24 client est une installation
distante, écartée pour ce lot (une découverte ratée y demanderait une coupure
AC+DC sur site).

Build : `qmake6 NYMEA_SUNSPEC_PATH=<sysroot> sunspec/tests/tests.pro && make check`.
Sans `NYMEA_SUNSPEC_PATH`, `sunspec.pri` résout `libnymea-sunspec` par
`pkg-config`, ce qui suppose `libnymea-sunspec-dev` installé système.

| AC | Objet | Test | Statut |
|---|---|---|---|
| AC-1 | plage −100…+100 | `test_AC_1_*` | vert |
| AC-2 | lecture `inWRte`/`outWRte` | `test_AC_2_*` | vert |
| AC-3 | `enableDischarging` relu | `test_AC_3_*` | vert |
| AC-4 | `RvrtTms` écrit en dernier | `test_AC_4_*` | vert |
| AC-5 | filtre fabricant | `test_AC_5_*` | vert |
| AC-6 | little-endian | `test_AC_6_*` | vert — mais c'est une **inférence** (H-3), pas une mesure |
| AC-7 | paramètres `froniusConnection` | `test_AC_7_*` | vert |
| AC-8 | plancher 7 s | `test_AC_8_*` | vert, avec réserve ci-dessous |
| AC-9 | registres interdits | `test_AC_9_*` | vert |
| AC-10 | `revertTime` 300 s | `test_AC_10_*` | vert |
| AC-11 | table mode → registres | `test_AC_11_*` | vert au niveau du plan ; **aucune action n'expose encore les six modes** |
| AC-12 | relecture du SF | `test_AC_12_*` | vert |
| AC-13 | relecture + `controlHealthy` | `test_AC_13_*` | vert |
| AC-14 | classement par `IDStr` | `test_AC_14_*` | vert ; **non branché** — modèle 160 toujours absent du `switch` (anomalie A5, hors périmètre) |
| AC-15 | agrégats modèle 160 | `test_AC_15_*` | idem AC-14 |

### Réserves à lever

- **AC-8** — le minuteur d'interrogation de nymea est **global au plugin**, pas
  par connexion. Le plancher est donc appliqué à l'échelle du plugin dès qu'une
  connexion `fronius` est configurée : c'est plus strict que l'AC, jamais moins.
  Le paramètre `updateInterval` par thing a été **retiré** de
  `froniusConnection` : l'architecture du plugin ne peut pas l'honorer par
  connexion, et un réglage sans effet serait pire que son absence.
- **AC-11** — la fonction `FroniusRules::planBatteryMode()` produit exactement
  la table du contrat, et le plan est exécutable par
  `IntegrationPluginSunSpec::executeSetpointPlan()`. Il manque l'action nymea
  qui l'appelle : le nommage de cette action et de ses paramètres n'est pas
  tranché par le contrat.
- **AC-14 / AC-15** — les fonctions de classement et d'agrégation sont écrites
  et testées, mais aucun thing du modèle 160 n'est créé tant que l'anomalie A5
  (`ModelIdMppt` absent du `switch` de `processDiscoveryResult()`) n'est pas
  corrigée. A5 est hors du périmètre des quatre correctifs demandés.
- **AC-15.4** — respecté par construction : aucun calcul de production PV par
  différence n'a été ajouté.

### Multi-unit-ID (H-1)

**Non implémenté.** `froniusConnection` porte bien le paramètre `meterSlaveId`
(AC-7, vert), mais le plugin n'instancie encore qu'une seule `SunSpecConnection`
par thing. Le passage à deux connexions internes touche `m_sunSpecConnections`,
`createConnection()`, `setupThing()`, `processDiscoveryResult()`,
`thingRemoved()`, `postSetupThing()` et `onRefreshTimer()`.

Deux raisons de ne pas l'avoir fait dans la foulée : la décision D1 n'est pas
validée, et le brief demande explicitement de traiter ce lot **isolément**,
après que le reste soit fonctionnel sur l'onduleur seul. S'y ajoute H-4 : rien
ne dit que l'onduleur accepte deux connexions TCP simultanées, et le
constructeur recommande des requêtes séquentielles. Ce point se mesure au banc ;
le supposer serait exactement le mode de défaillance que le contrat cherche à
éviter.