etm-powersync-app/docs/BRIEF_depuis_plugin.md

Brief — du moteur vers l'app

Ce que l'agent plugin (etm-powersync-energy-plugin-etm) constate et qui change quelque chose côté app. Une section datée par lot. Le plus récent en haut.

---

2026-08-26 — passage machine 3g-1 sur le banc .75

Contexte : powersync-energy-plugin-nymea 1.15.2+etm22 déployé sur .75. Relevé complet dans le dépôt du plugin, docs/RELEVE_3g1.md.

---

1. SetChargingInfo substitue targetPercentage = 80 à un champ absent — en silence

Envoyer un chargingInfo sans targetPercentage ne laisse pas la valeur en place : elle est remplacée par 80. Constaté en restaurant le banc — le champ valait 0, j'ai réécrit l'objet sans lui, il valait 80 à la relecture.

Cause : ChargingInfo est reconstruit intégralement à chaque écriture (unpack<ChargingInfo>), et son membre C++ porte m_targetPercentage = 80 comme valeur par défaut. Un champ absent du JSON n'est donc pas « inchangé » : il retombe sur le défaut. Cela vaut pour tout l'objet, targetPercentage n'est que le cas où le défaut n'est pas neutre.

Et la substitution est muette. Vérifié sur machine, journal du banc à 17:35:56 :

• la réponse RPC est EnergyErrorNoError — aucune erreur, aucun avertissement ;
• le seul avertissement du chemin d'écriture ne se déclenche que pour targetPercentage > 100 ;
• la seule trace au journal est une ligne de debug qui imprime Target percentage: 80, c'est-à-dire le résultat — jamais le fait qu'un champ était absent ;
• la notification ChargingInfoChanged qui suit porte 80, comme si l'utilisateur l'avait choisi.

Ce que l'app doit en faire. Toujours envoyer targetPercentage, même inchangé — donc lire l'objet, patcher le champ voulu, réécrire l'objet complet (le même chemin que pour priority dans LoadConfig). Et ne jamais afficher targetPercentage comme une cible choisie par l'utilisateur tant que l'écran n'a pas lui-même écrit cette valeur : 80 peut être une valeur héritée d'une écriture qui ne parlait pas de cible du tout.

Le risque concret : un écran qui change le seul mode de charge repose une cible de 80 % à l'insu de l'utilisateur, sans que rien ne le signale.

---

2. GetPowerBalanceLogs en SampleRate15Mins — RIEN À SIGNALER, l'alerte était fausse

J'avais signalé que ce taux rendait des échantillons tous à zéro. C'était mon erreur de lecture, pas un défaut de la box. Je la consigne quand même pour qu'elle ne circule pas.

Ce qui s'est passé : ma sonde lisait les clés currentPowerProduction / currentPowerConsumption alors que les entrées de log portent production, consumption, acquisition, storage — sans le préfixe currentPower, contrairement à GetPowerBalance. Tout tombait donc sur le défaut 0.

Vérifié après coup, dans les deux sens :

• par RPC, mêmes bornes de temps, avec les bonnes clés : 51 échantillons, 51 non nuls ;
• dans la base du banc (/var/lib/nymea/energylogs.sqlite), la table powerBalance porte 7 908 lignes à sampleRate = 15, du 2026-06-05 à aujourd'hui 16:30, valeurs réelles. Les autres taux (1, 60, 180, 1440, 10080, 43200) sont peuplés aussi.

Conséquence pour l'app : l'historique 90 jours n'est bloqué par rien de ce côté. Le seul piège est le nom des champs — les entrées de log ne portent pas le préfixe currentPower, à la différence de GetPowerBalance. Un modèle qui réutilise les mêmes clés pour les deux appels lira des zéros sans la moindre erreur. C'est exactement ce qui m'est arrivé.

---

3. Contrat neuf — loads[].funding, et les bornes entrent enfin dans loads[]

3.1 Les bornes franchissent la frontière RPC (+etm22)

Jusqu'ici buildTelemetry() sautait les bornes : elles étaient arbitrées, leurs décisions apparaissaient au journal du plugin, mais GetLoadTelemetry n'en publiait aucune. L'écran ne pouvait donc pas les voir. C'est corrigé.

loads[] contient désormais les bornes de recharge, avec leur decision, leur mechanism (kind: "evcharger", chargingEnabled, currentA, phaseCount, pluggedIn) et leur faultCode le cas échéant.

Les motifs EV EV_SURPLUS, EV_ECO_MIN, EV_IDLE ne sont plus émis : une borne reçoit maintenant les motifs communs à tous les mécanismes — SURPLUS_SETPOINT, BELOW_MIN_POWER, SURPLUS_INSUFFICIENT, LOAD_UNAVAILABLE. Les trois codes restent rendus côté plugin pour qu'un journal ancien reste lisible, mais plus rien ne les produit. EV_SPOT_MARKET et EV_DEADLINE subsistent.

3.2 Le champ funding — "surplus" ou "grid"

Nouveau, optionnel (o:), présent dès qu'il y a un plan. Il devient nécessaire du seul fait que les bornes sont dans loads[], car deux d'entre elles peuvent y être pour des raisons différentes :

funding	d'où vient l'allocation	où elle est comptée
"surplus"	la cascade (waterfall PV)	dans budget.allocatedW
"grid"	le proxy — échéance de départ, tarif dynamique — qui soutire au réseau	dans budget.evReservedW

Sommer loads[].allocatedW sans filtrer sur funding == "surplus" donne un écart avec budget.allocatedW que rien ne permet d'interpréter : défaut du moteur, ou borne servie au réseau ? L'identité à vérifier est donc : somme des allocatedW des charges financées au surplus == budget.allocatedW.

Omis en mode dégradé : sans plan, il n'y a pas de financement. Règle maison habituelle — omis, jamais nul.

3.3 ⚠️ Mise en garde — pour une borne, l'allocation publiée est une INTENTION, pas un ordre

adjustEvChargers() re-décide le surplus après le waterfall et passe outre le refus de l'arbitre. Observé sur le banc, deux lignes consécutives du même cycle (17:34:00) :

[Arbitre] "{09e520fd…}" → "Budget 1096 W sous le premier palier … — 0 W"
---------------- Adjusting chargers ----------------
Executing action Simulated wallbox to power: ON, Charging current: 6A, Issuer: Surplus

L'arbitre refuse et publie BELOW_MIN_POWER ; le chemin d'exécution du proxy commande ON à 6 A une milliseconde plus tard. Tant que ce n'est pas traité (lot 3g-2, côté plugin), ce que la télémétrie publie pour une borne n'est pas ce qui est commandé.

Ce que l'app doit en faire. Pour les bornes — et seulement pour elles —, ne pas présenter allocatedW et son motif comme l'état de la borne. Ce sont la décision de l'arbitre, ce qui n'est pas la même chose que ce que la borne fait. L'état réel se lit dans mechanism.chargingEnabled / mechanism.currentA, qui viennent du Thing.

Concrètement : ne pas écrire « la borne ne charge pas parce que le budget est sous le plancher » à partir du seul motif. Les deux peuvent se contredire aujourd'hui, et c'est l'écran qui aurait l'air faux.

Cette réserve ne vaut pas pour l'ECS, la PAC et les autres charges pilotées : là, l'allocation publiée est la commande.

---

4. Rappel — clés ARB à prévoir côté app

Deux motifs sont émis par le banc et n'ont pas encore de rendu français dans telemetry_text.dart :

• BELOW_MIN_POWER — params budgetW, minPowerW, et state pour les mécanismes à états (SG-Ready). Déjà traité dans telemetry_text.dart, à vérifier côté ARB.
• BATTERY_RESERVE — params socPercent, reservePercent, withheldW. Le kCodesReserveBatterie de telemetry_text.dart est encore vide, et les clés qu'il cherche (batteryLevel/soc, threshold/batteryLevelConsideration) ne sont pas celles publiées. À aligner sur les trois noms ci-dessus.

Et un réglage à exposer dans l'écran installateur : batteryLevelConsideration — son défaut d'usine est passé de 0,9 à 0,2 (à 0,9 avec une batterie à 50 %, le HEMS ne pilote plus rien, sans erreur ni panne). En revanche minimalChargingCurrent ne doit jamais être présenté comme configurable : il n'existe pas comme réglage, il se déduit de la borne et de la voiture.