etm-powersync-plugins-modbus/sunspec/DIVERGENCES.md

Divergences — vendor Fronius du plugin SunSpec

Écarts assumés entre ce que demandent specs/fronius-sunspec.md et le contrat d'une part, et ce que le code fait d'autre part. Chaque entrée dit pourquoi et comment la lever.

Deux étiquettes :

• MESURÉ — l'écart repose sur une observation faite sur du matériel ou sur le code de la plateforme, reproductible.
• INFÉRÉ — l'écart repose sur un raisonnement, faute de donnée. À reprendre dès qu'une mesure existe.

---

D-1 — meterSlaveId n'est pas marqué advanced (MESURÉ)

Ce que demande AC-7. Le paramètre meterSlaveId de la thingClass froniusConnection doit être advanced.

Ce que fait le code. Rien : le paramètre n'a pas ce drapeau.

Pourquoi. advanced n'est pas une propriété de paramType dans nymea 1.15.2. ParamType::typeProperties() énumère exactement id, name, displayName, type, defaultValue, inputType, unit, minValue, maxValue, stepSize, allowedValues, readOnly. Le vérificateur de métadonnée refuse tout champ inconnu :

Param type "meterSlaveId" has unknown fields: "advanced"

et PluginMetadata::isValid() passe à false. Ce n'est pas un paramètre mal affiché : le plugin ne se charge plus du tout, et les erreurs suivantes en cascade (le paramType est abandonné, donc froniusConnection ne satisfait plus l'interface networkdevice) rendent le diagnostic trompeur.

Vérifié en chargeant le JSON, avec et sans le drapeau, dans un PluginMetadata lié à la libnymea installée — pas seulement lu dans une source amont qui pourrait diverger du paquet.

Comment lever. Rien à faire côté plugin. Il faut soit que nymea ajoute la propriété, soit que AC-7 soit corrigé. Un test de garde (test_F3_meter_slave_id_is_not_marked_advanced) empêche qu'on ajoute le drapeau sans refaire la mesure.

---

D-2 — délai de garde du balayage des enfants orphelins (INFÉRÉ)

Contexte. processDiscoveryResult() fait disparaître les things enfants dont le modèle n'est plus annoncé. Avec deux connexions sous le même parent, chacune ne voit que la moitié du tableau : balayer sur cette moitié ferait disparaître les enfants de l'autre à chaque découverte. Le balayage attend donc que toutes les connexions du parent aient réussi une découverte, puis confronte les enfants à l'union de leurs modèles.

L'écart. Une connexion dont la découverte n'aboutit jamais bloquerait le balayage pour toujours. Un délai de garde le débloque : OrphanSweepGraceSeconds = 600 (10 minutes).

Pourquoi cette valeur, et pourquoi elle est INFÉRÉE. Aucune donnée ne la fixe. Le choix est asymétrique et volontairement paresseux : un balayage trop tardif laisse traîner un thing périmé affiché déconnecté, un balayage trop précoce supprime un thing de l'utilisateur. À conséquences inégales, réglage prudent. 10 minutes est très au-delà de tout cycle de découverte observé, sans être infini.

Comment lever. Mesurer, sur le banc puis sur matériel, le temps que met une découverte SunSpec à échouer définitivement sur un unit ID qui ne répond pas (timeout × retries × nombre de registres de base balayés). Le délai de garde doit valoir quelques fois cette durée, pas dix minutes arbitraires. La valeur est un seul const dans integrationpluginsunspec.cpp ; la changer n'a d'effet sur rien d'autre.

---

D-3 — la configuration du plugin écrase les défauts de cadence Fronius (MESURÉ, préexistant)

Contexte. createConnection() impose timeout et numberOfRetries du vendor Fronius (AC-8) à la création. Mais onPluginConfigurationChanged() réapplique ensuite les valeurs globales du plugin à toutes les connexions, Fronius comprise.

L'écart. Il est antérieur à F3 et affecte déjà la connexion onduleur seule. F3 ne le corrige pas ; il l'étend symétriquement à la connexion compteur, pour que les deux connexions d'un même thing se comportent identiquement. Le plancher d'intervalle d'interrogation d'AC-8, lui, reste appliqué : il vit dans effectiveUpdateInterval(), pas ici.

Comment lever. Hors périmètre de F3 : cela demande de décider si les réglages globaux du plugin doivent pouvoir passer outre un défaut vendor, ce que ni le contrat ni la spec ne tranchent.

---

D-4 — connexion détruite par ThingSetupInfo::aborted et laissée dans la table (MESURÉ, préexistant, amont)

Contexte. setupThing() relie ThingSetupInfo::aborted à SunSpecConnection::deleteLater(), alors que createConnection() a déjà inséré la connexion dans m_sunSpecConnections. Un setup avorté laisse donc un pointeur pendant dans la table ; le setup suivant du même thing prend la branche « reconfiguration » et appelle deleteLater() sur un objet déjà détruit.

L'écart. F3 ne corrige pas ce chemin pour la connexion primaire : il est commun aux trois vendors, y compris solarEdge dont aucun test ne couvre le comportement, et le périmètre du lot est explicitement « generic et solarEdgeConnection ne changent pas de comportement ». La connexion compteur ajoutée par F3, elle, se retire proprement de sa table à la destruction.

Comment lever. Relier QObject::destroyed au retrait de la table pour les deux connexions, dans un lot qui assume de toucher le chemin commun, avec une couverture de test pour solarEdge.

---

D-5 — le signe du compteur est corrigé côté Fronius seulement (MESURÉ)

Contexte. onMeterBlockUpdated() négociait le signe de façon générique : tous les modèles compteur (201, 202, 203, 204, 211…214) faisaient -meter->watts(). Il n'existait aucun mapping spécifique à un fabricant.

L'écart. Sur Fronius cette négation est fausse : le Smart Meter émet déjà dans la convention nymea (négatif = injection). Le correctif n'annule la négation que lorsque le compteur est enfant d'une froniusConnection ; les vendors generic et solarEdge gardent la négation historique, verrouillée par test_AC_16_generic_meter_keeps_the_historical_negation.

Preuve. Relevé du 02/08/2026 sur un Primo GEN24 3.0, onduleur monophasé (modèle 101) et Smart Meter TS 65A-3 (modèle 203, pas 213). L'onduleur n'injecte que sur la phase A ; le plugin rapportait phase A = +1003 W (soutirage) et phases B et C à −33 W et −262 W, soit une injection sur deux phases ne portant aucune source. En inversant, le bilan se referme : production 1190 W = charge phase A 187 W + export 1003 W ; import B+C 294 W ; consommation 481 W ; export réseau 709 W contre 708 W mesuré. Corroboration indépendante : sur la même fenêtre, le compteur d'énergie import de l'appareil reste à 0 pendant que l'export s'incrémente. Conséquence observée : [Arbitre] "chauffe-eau" → "Surplus insuffisant (-842 W)" alors que le site exportait ~842 W.

Non touché. Les compteurs d'énergie (totalEnergyConsumed / totalEnergyProduced) sont corrects et ne sont pas permutés : ce sont eux qui servent de témoin à charge ci-dessus.

Comment lever. Déterminer si la négation générique est fausse pour tous les fabricants ou seulement pour Fronius demanderait un compteur d'un autre vendor sur banc. Tant que ce n'est pas tranché, le générique ne bouge pas.

---

D-6 — présence batterie : le côté « batterie présente » n'est pas validé (INFÉRÉ)

Contexte. Un GEN24 hybride publie le modèle 124 même sans batterie câblée. Le plugin créait donc un enfant storage systématiquement, d'où batterie fantôme et batteryCritical permanent.

L'écart. FroniusRules::hasBattery() exige désormais InBatV > 0 ou StorAval > 0 pour créer l'enfant, et seulement sous une froniusConnection. Le SoC est écarté (0 % ne se distingue pas d'une batterie vide) ainsi que les registres de consigne (WChaMax… gardent leurs défauts sans batterie).

Ce qui est établi. Le côté « absente » est confirmé sur matériel : le GEN24 des beaux-parents, sans batterie, exposait le modèle 124 avec ChaSt = Off et un SoC de 0, et nymea journalisait « There is no energy storage available to consider » pendant que l'enfant restait visible.

Ce qui ne l'est pas. InBatV et StorAval n'étant pas exposés en states nymea, leurs valeurs sur ce GEN24 sans batterie n'ont pas pu être relevées, et aucun GEN24 avec batterie n'était joignable. L'hypothèse « une batterie installée porte une tension au repos » est donc INFÉRÉE des deux côtés.

Comment lever. Relever en lecture seule le bloc 124 d'un GEN24 équipé d'une batterie et vérifier InBatV/StorAval non nuls. À faire avant tout déploiement : un discriminateur trop strict ferait disparaître une vraie batterie chez un client.

---

D-7 — la présence batterie ne peut pas être vérifiée par la suite logique (MESURÉ)

Contexte. La première version du garde de D-6 demandait isFroniusChild(thing->id()), qui résout le parent par myThings().findById().

L'écart. Pendant le setup initial, la connexion parente n'est pas encore enregistrée dans myThings() : la recherche répond faux, le garde Fronius est contourné, et l'enfant storage est créé malgré InBatV = StorAval = 0. Trace nymead correspondante : ThingManager: Invalid parent thing id … Not adding thing to the system.

Le garde interroge désormais directement le thing de connexion que la fonction tient déjà (thing->thingClassId() == froniusConnectionThingClassId), sans aucune recherche. Même traitement pour le signe compteur, qui utilise le parentThing déjà résolu et non nul.

Ce que cela apprend. La suite tests/logic ne peut pas attraper ce défaut : elle couvre la décision pure (FroniusRules), pas le câblage du plugin, c'est à dire quel prédicat est interrogé et à quel moment du cycle de vie. Seul un essai en boucle fermée contre un simulateur le révèle. Toute modification du garde de présence doit donc être rejouée sur banc, pas seulement en unitaire.

Comment lever. Étendre tests/plugin, qui instancie réellement le plugin, à un scénario de setup initial avec un modèle 124 à zéro. Hors périmètre ici.

---

D-8 — ordre des mots des float32 : le défaut de la bibliothèque n'est pas celui de la spec (MESURÉ)

Contexte. FroniusRules::byteOrder() renvoyait ByteOrderLittleEndian, avec pour justification « non documenté par le constructeur, on suppose le défaut SunSpec ».

L'écart. La supposition confondait deux « défauts ». Un float32 SunSpec occupe deux registres, mot de poids fort d'abord. Or SunSpecDataPoint::convertToUInt32 lit registers.at(0) puis .at(1) en ByteOrderBigEndian, et l'inverse en ByteOrderLittleEndian — qui est le défaut de libnymea-sunspec. Garder ce défaut revient à lire tous les float32 de la personnalité Fronius avec leurs deux mots permutés.

Mesure. Relevé du 2026-08-07 sur un Fronius Symo réel, en lecture seule (sunspec/tools/read-float-order.py) :

point	registres bruts	big endian	mots inversés
compteur 213 u200 Hz	4248 0000	50,0000	2,3777e−41
compteur 213 u200 PhVphA	436a 8000	234,5000	−2,4184e−41
onduleur 113 u1 Hz	4247 fc48	49,9964	−4,1592e+36

Ce que cela coûtait. Pas un décalage : une absurdité. Reproduit sur banc avec le simulateur émettant l'ordre du matériel — un compteur important 2,7 kW a été rapporté comme exportant 107 MW, Current load on root meter: -1.07621e+08W, et l'arbitre a enclenché toutes les charges sur un « Surplus PV 107622496 W ». Un tel appareil se présente connected = true, sans aucune erreur Modbus.

Ordre des correctifs. meterPowerSign() (D-5) reste juste, mais n'est observable qu'une fois l'ordre des mots corrigé : corriger le signe d'un dénormal ne produit rien.

Non touché. Le vendor solarEdge force déjà big endian sur son propre chemin ; le vendor générique conserve son paramètre endianness réglable par l'utilisateur. Aucun des deux n'est modifié.

Verrou. test_AC_6 affirme désormais ByteOrderBigEndian, et test_AC_18_swapped_words_yield_denormals fige le raisonnement : les registres réels lus à l'envers donnent un dénormal, jamais une mesure plausible.

---

D-9 — sunspecStorage déclare energystorage mais tous ses porteurs ne savent pas mesurer (MESURÉ)

Ce que demande le brief. BRIEF_sunspec_energystorage.md : le Thing déclarait battery + connectable, donc les trois consommateurs qui filtrent par filterByInterface("energystorage") ne le trouvaient pas — le bilan de puissance que le client lit, la réserve de recharge VE, la réserve du waterfall. Sur .75, currentPowerStorage valait 0 pendant que la batterie affichait 50 % et « Holding » : elle n'était pas à zéro, elle était invisible.

Ce que fait le code. sunspecStorage déclare désormais ["battery", "energystorage", "connectable"] et porte currentPower (W) et capacity (kWh), câblés sur des registres.

D'où vient currentPower

Le modèle 124 ne porte aucune puissance. Il décrit ce que la batterie est — SoC, statut, consignes — pas ce qu'elle fait en watts. WChaMax est une puissance maximale, StorAval est en ampères-heures. Vérifié registre par registre sur le banc.

La puissance instantanée vit dans le modèle 160, réparti sur deux blocs distincts que Fronius nomme StCha (charge) et StDisCha (décharge). DCW est un uint16 : chaque bloc est toujours positif, et le bloc inactif est à zéro. D'où

currentPower = DCW[StCha] − DCW[StDisCha]

Le signe est mesuré, pas déduit. Relevé du 2026-08-26, banc .211 unité 1, modèle 160 à 40265, consigne batterie imposée par MQTT (banc/cmd/manual) et registres relus en lecture seule :

consigne banc	banc/etat/batterie	StCha	StDisCha	ChaSt (124)	StCha − StDisCha
+2000 W (charge)	+2000,0 W	2000,0 W	0,0 W	Charging	+2000,0 W
−1500 W (décharge)	−1500,0 W	0,0 W	1500,0 W	Discharging	−1500,0 W
0 W	0,0 W	0,0 W	0,0 W	Holding	0,0 W

libnymea/interfaces/energystorage.json : « positive is 'consumed' ». Une batterie qui charge consomme, donc charge = positif. C'est l'inverse de la convention constructeur du contrat §4 et de FroniusRules::batteryPower(). Les deux fonctions coexistent, et batteryPower() est écrite comme la négation de storageCurrentPower() pour qu'aucune des deux ne puisse dériver seule.

Ce que le relevé a montré en plus. DCW_SF est passé de −2 à −1 entre la lecture au repos et la lecture en charge, sans hystérésis (I5 du contrat). Un plugin qui mettrait ce facteur en cache à la découverte lirait des puissances fausses d'un facteur 10. libnymea-sunspec ne le met pas en cache : les 90 registres du modèle 160 sont lus en une seule transaction Modbus, et processBlockData() relit les facteurs d'échelle du bloc fixe avant de traiter les blocs répétés. La propriété est donc tenue, mais elle tient à cet ordre — la casser en amont casserait cette lecture sans aucun signe extérieur.

D'où vient capacity

WHRtg du modèle 120 (plaque signalétique), Wh → kWh. SunSpecStorageLogic::nameplateCapacityKwh() rend une valeur négative quand le nameplate n'en porte pas, et le plugin laisse alors l'état tranquille plutôt que de publier un zéro qui se lirait comme une mesure.

Non vérifiable au banc. Le simulateur sert les modèles 120 à 123 en coquilles vides (choix assumé du lot 1) : les 26 registres du 120 sont à zéro, WHRtg compris. capacity reste donc à 0 sur .75, et le chemin de lecture n'est éprouvé que par les tests unitaires. Comment lever : peupler WHRtg dans la vue sunspec-fronius du banc, ou relever le modèle 120 d'un GEN24 réel équipé d'une batterie. Aucun des trois consommateurs cités par le brief ne lit capacity — la conséquence d'un 0 est bornée à l'affichage.

L'écart assumé

sunspecStorage est partagé entre les vendors sunspec générique et Fronius, et les interfaces se déclarent par thingClass, pas par thing. Un appareil SunSpec générique qui publie le modèle 124 sans modèle 160 — c'est le cas du simulateur générique .210 — porte désormais l'interface energystorage avec un currentPower qui ne bougera jamais de zéro. C'est exactement le défaut que le brief décrit : un zéro se lit « ni charge ni décharge » là où l'absence se lisait « je ne sais pas ».

Pourquoi l'accepter quand même. Les trois alternatives sont pires :

• créer une thingClass Fronius distincte (à la solarEdgeBattery) contredit le contrat §A′ ligne 44, et détruit le Thing existant de .75 avec son historique, puisque le balayage des orphelins ferait disparaître l'ancien ;
• ne pas déclarer l'interface laisse les trois consommateurs aveugles, ce qui est le défaut d'origine ;
• refuser de créer l'enfant storage quand la puissance n'est pas mesurable ferait disparaître des appareils génériques qui fonctionnent aujourd'hui.

Ce qui rend l'écart audible. Le plugin avertit une fois par thing quand il ne trouve pas de source de puissance, en distinguant les deux cas : pas de modèle 160 du tout sur la connexion, ou modèle 160 sans bloc StCha/StDisCha (un GEN24 sans batterie publie N=2). L'avertissement ne remplace pas la mesure, mais il retire le silence — qui était le vrai coût du défaut d'origine.

Comment lever. Que nymea permette de déclarer une interface par thing et non par thingClass, ou que le vendor générique reçoive sa propre thingClass storage au moment où un appareil générique avec batterie entre réellement au parc.

Verrous. test_D9_* dans tests/logic : la déclaration d'interface, les deux états et leurs unités, le signe dans les deux sens, l'opposition stricte avec batteryPower(), l'exclusion des strings PV, et la distinction entre « batterie à l'arrêt » et « pas de bloc batterie ». La cohérence des unités avec l'interface est en outre vérifiée à la compilation par nymea-plugininfocompiler : essayer KiloWattHour sur currentPower fait échouer le build avec « claims to implement interface "energystorage" but state "currentPower" has not matching unit ».

---

D-10 — la géométrie des modèles est figée à la découverte (MESURÉ)

Contexte. Le plugin lie chaque thing à un SunSpecModel au moment de la découverte : identifiant de modèle, registre de départ, longueur. Les modèles compagnons du storage (160, 120) sont liés de la même façon, par bindStorageCompanionModels().

L'écart. Rien ne redécouvre la chaîne tant que la connexion ne tombe pas. Si l'appareil change la FORME de sa chaîne sans rompre le TCP, le plugin continue de lire l'ancienne géométrie.

Mesure du 2026-08-26. Le simulateur .211 a été redémarré sans batterie, puis de nouveau avec. Trois états successifs, connexion Modbus jamais rompue :

moment	chaîne	ce que fait le plugin
avant	160 L=88 (4 blocs) · 124 présent	currentPower suit la batterie
sans batterie	160 L=48 (2 blocs) · 124 absent	Read data block response error: ProtocolError toutes les 7 s sur "storage" — il lit toujours 40355
batterie revenue	160 L=88 · 124 présent	les erreurs cessent, mais currentPower reste figé à sa dernière valeur

thingPower du storage : 0.0 à 16:09, 16:10, 16:11 pendant que les registres portaient StCha = 2000 W et ChaSt = Charging. Un systemctl restart nymead force la redécouverte, et la valeur repart immédiatement — 2000.0 à 16:13.

Ce que cela apprend. Le défaut n'est ni dans le signe ni dans le mapping de D-9 : ceux-là sont justes, et le prouvent dès que la découverte est refaite. Il est dans le fait qu'une liaison thing↔modèle est établie une fois et jamais reconsidérée. Le storage y est plus exposé que les autres things parce qu'il dépend de trois modèles au lieu d'un.

Portée réelle. Au banc, c'est fréquent : tout redémarrage du simulateur avec d'autres options change la chaîne. Sur du matériel, c'est rare mais pas théorique — une mise à jour de firmware, ou une batterie ajoutée à un hybride déjà appairé, produisent exactement cette transition.

Contournement aujourd'hui. Redémarrer nymead, ou retirer et rajouter la connexion. La perte de la connexion TCP suffit aussi, puisqu'elle déclenche une redécouverte.

Comment lever. Redécouvrir périodiquement, ou sur erreur Modbus répétée à une adresse jusque-là valide — le ProtocolError toutes les 7 s du tableau ci-dessus est précisément le signal que la chaîne a bougé, et il est actuellement journalisé sans conséquence. Hors périmètre de D-9, qui ne touche pas au cycle de découverte.