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.