etm-powersync-energy-plugin-etm/docs/TEST_TERRAIN.md

TEST_TERRAIN.md — Procédure de test Palier 1 (nymea-dev arm64)

Test terrain du moteur etm-powersync-energy-plugin-etm sur banc : compteur mock forçable (puissance injectée par HTTP) + relais GPIO réels (état vérifié via JSON-RPC nymead ou multimètre NO-COM). 14 tests (T1–T14). Chaque test : inject → log attendu → vérif relais → case ✓/✗.

Convention puissance compteur : currentPower < 0 = export (surplus PV) ; > 0 = import. Le moteur calcule un surplus net SIGNÉ (exportW − importW) qui cascade par priorité.

---

§0 — Pré-vol (à remplir SUR LA BOX)

Élément	Valeur	Source
IP / hostname	192.168.1.75 — hostname hems, user etm (sudo)	briefing terrain
Port JSON-RPC	nymeas://hems:2222 (TCP+TLS) · wss://hems:4444	connu
Auth requise ?	__________	[À LIRE SUR LA BOX] JSONRPC.Hello → champ authenticationRequired
Token (si auth)	__________	Users.Authenticate {username,password,deviceName} → token
ThingClassId compteur mock	2721a051-6e12-471a-baba-21d87c4cebc9	connu (energymocks)
ThingId compteur mock	__________	[À LIRE] après Integrations.AddThing, ou Integrations.GetThings
Port HTTP compteur mock	26655	connu
ThingId R500 (Relay1 C1 BCM5, pin 29)	8538782f-2c8c-4a30-bfce-c8140f791c9b	briefing terrain
ThingId R1000 (Relay2 C2 BCM6, pin 31)	2ebe6bef-829b-4695-9d11-ddb4c16c5448	briefing terrain
ThingId R2000 (Relay3 C3 BCM13, pin 33)	b033b212-1adb-4df0-ba2b-8fa477de52a2	briefing terrain
ThingId K1 (Relay4 C4 BCM16, pin 36)	beaf92e1-aedc-4b84-9ce4-e423648638cc	briefing terrain
ThingId K2 (Relay5 C5 BCM19, pin 35)	bf236e64-5ae7-4bf1-82a6-4ede03de75a6	briefing terrain
gpiochip + BCM offsets	gpiochip0 ; BCM R500=5, R1000=6, R2000=13, K1=16, K2=19	vérifiés — gpioget valide uniquement nymead ARRÊTÉ
Conteneur build cross-arm64	__________	[À LIRE DANS etm-powersync-deploy/DEPLOY.md]

[À LIRE SUR LA BOX] = dépend du déploiement, pas inventé ici. Tout le reste est figé.

---

§1 — Déploiement (option a : build cross-arm64 → scp → dpkg)

a. Build cross-arm64 (depuis le poste dev)

# Dans le conteneur de build cross-arm64 (cf. DEPLOY.md du repo etm-powersync-deploy).
# Produit le .deb arm64 : nymea-energy-plugin-nymea_<ver>_arm64.deb
# (TARGET inchangé = libnymea_energypluginnymea.so, drop-in remplaçant l'amont).

Le nom de paquet/TARGET est inchangé (décision Phase 1) → le .deb ETM remplace le plugin énergie amont. Un seul plugin énergie chargé.

b. Déploiement sur la box

BOX=hems
scp nymea-energy-plugin-nymea_*_arm64.deb etm@$BOX:/tmp/
ssh etm@$BOX 'sudo dpkg -i /tmp/nymea-energy-plugin-nymea_*_arm64.deb && sudo systemctl restart nymead'
ssh etm@$BOX 'sudo journalctl -u nymead -f'    # suivre les logs

.so installé dans /usr/lib/<multiarch>/nymea/energy/libnymea_energypluginnymea.so.

c. Activer le logging [Arbitre] (SINON aucune trace de décision)

La catégorie est exactement NymeaEnergy (NYMEA_LOGGING_CATEGORY(dcNymeaEnergy, "NymeaEnergy")). Méthode robuste — drop-in systemd (Qt logging rules) :

ssh etm@$BOX 'sudo mkdir -p /etc/systemd/system/nymead.service.d && \
  printf "[Service]\nEnvironment=QT_LOGGING_RULES=NymeaEnergy.debug=true\n" | \
  sudo tee /etc/systemd/system/nymead.service.d/etm-logging.conf >/dev/null && \
  sudo systemctl daemon-reload && sudo systemctl restart nymead'

Alternative selon la version : nymead --logging <règles> ou la section logging de /etc/nymea/nymead.conf. [VÉRIFIER nymead --help SUR LA BOX] si le drop-in ne suffit pas. Les lignes attendues commencent par [Arbitre] et [EcsRelayAdapter]/[SgReadyAdapter].

d. Déclarer les adaptateurs de test — LA VRAIE MÉTHODE

⚠️ Il n'existe pas encore de config runtime des adaptateurs (déféré : couche « config priorités »). En production, energypluginnymea.cpp::init() crée l'EnergyArbitrator mais n'enregistre aucun adaptateur ECS/SG-Ready. La déclaration se fait donc par un bloc de code ajouté à energypluginnymea.cpp (juste après la création de chargingManager, ligne ~54), recompilé dans le .deb de test.

Workflow : déployer une 1re fois → Integrations.AddThing le compteur mock + les relais GPIO → relever leurs ThingId (GetThings) → coller le bloc ci-dessous avec ces ThingId → rebuild → redéployer.

// energypluginnymea.cpp, init(), APRÈS la ligne :
//   EnergyArbitrator *chargingManager = new EnergyArbitrator(...);
#ifdef ETM_ARBITRATOR
{
    ThingManager *tm = thingManager();
    // --- ECS 3 relais (8 niveaux binaires) ---
    const QString R500  = "{8538782f-2c8c-4a30-bfce-c8140f791c9b}";  // Relay1 C1 BCM5
    const QString R1000 = "{2ebe6bef-829b-4695-9d11-ddb4c16c5448}";  // Relay2 C2 BCM6
    const QString R2000 = "{b033b212-1adb-4df0-ba2b-8fa477de52a2}";  // Relay3 C3 BCM13
    auto *ecs = new EcsRelayAdapter(
        tm, "ecs-terrain", "ECS banc",
        QList<int>({0, 500, 1000, 1500, 2000, 2500, 3000, 3500}),
        QList<QList<QString>>({ {}, {R500}, {R1000}, {R500,R1000},
                                {R2000}, {R500,R2000}, {R1000,R2000}, {R500,R1000,R2000} }),
        /*minOnS*/ 60, /*minOffS*/ 60, /*priority*/ 1, chargingManager);
    chargingManager->registerEcsAdapter(ecs);

    // --- SG-Ready (2 bits K1/K2) ---
    const QString K1 = "{beaf92e1-aedc-4b84-9ce4-e423648638cc}";  // Relay4 C4 BCM16
    const QString K2 = "{bf236e64-5ae7-4bf1-82a6-4ede03de75a6}";  // Relay5 C5 BCM19
    auto *pac = new SgReadyAdapter(
        tm, "pac-terrain", "PAC banc",
        QHash<int,QList<QString>>({ {1,{K1}}, {2,{}}, {3,{K2}}, {4,{K1,K2}} }),
        QHash<int,double>({ {1,0.0}, {2,0.0}, {3,1500.0}, {4,3000.0} }),
        /*minStateHoldS*/ 300, /*priority*/ 2, chargingManager);
    chargingManager->registerSgReadyAdapter(pac);
}
#endif

Inclure #include "etm/adapters/ecsrelayadapter.h" et etm/adapters/sgreadyadapter.h. Le root meter = le compteur mock : le déclarer via l'expérience énergie nymea (Energy.SetRootMeter / config) avec le ThingId du compteur mock. Pour l'ECS simple (T1/T2), utiliser un seul relais : stages {0,2000}, mapping {{},{R2000}}.

---

Helpers bash (poste dev)

BOX=hems; MPORT=26655
# ThingIds relais (banc hems — pré-vérifiés, cf. §0)
TID_R500="8538782f-2c8c-4a30-bfce-c8140f791c9b"
TID_R1000="2ebe6bef-829b-4695-9d11-ddb4c16c5448"
TID_R2000="b033b212-1adb-4df0-ba2b-8fa477de52a2"
TID_K1="beaf92e1-aedc-4b84-9ce4-e423648638cc"
TID_K2="bf236e64-5ae7-4bf1-82a6-4ede03de75a6"
# Injecter une puissance compteur (W). Négatif = export (surplus PV), positif = import.
inject(){ curl -s "http://$BOX:$MPORT/setstates?connected=true&currentPowerPhaseA=$(($1/3))&currentPowerPhaseB=$(($1/3))&currentPowerPhaseC=$(($1/3))" >/dev/null; echo "compteur = $1 W"; }
# Compteur MUET : on cesse d'injecter (>90 s) → watchdog L2 bascule (QTimer 30 s, seuil 90 s).
mute(){ echo "NE PLUS injecter pendant >90 s…"; sleep 95; }
# Suivre les décisions de l'arbitre.
logs(){ ssh etm@$BOX "sudo journalctl -u nymead -f | grep -E 'Arbitre|EcsRelay|SgReady'"; }

# relay <ThingId> → 1 (ON) | 0 (OFF) via JSON-RPC local nymead.
# Protocole complet : Hello → auth si requise → GetThingClasses (résolution stateTypeId
#   'power') → GetThings. Framing : boucle par id — ignore les notifications push nymea.
# gpioget inutilisable nymead actif (libgpiod v2 busy). Filet : multimètre NO-COM nymead arrêté.
# Variables optionnelles : NYMEA_USER (défaut admin) NYMEA_PASS (défaut vide).
# ACCEPTANCE avant T1 : forcer un relais ON via l'app nymea, vérifier relay $TID_Rxx → 1 ;
#   forcer OFF → 0. Tant que ce test isolé ne passe pas, la colonne "vérif" de T1–T14 est aveugle.
relay(){
  local tid="$1"
  local nu="${NYMEA_USER:-admin}" np="${NYMEA_PASS:-}"
  ssh etm@$BOX "python3 - '$nu' '$np'" << GETSTATE
import ssl, socket, json, sys

user, pw = sys.argv[1], sys.argv[2]

ctx = ssl.create_default_context()
ctx.check_hostname = False; ctx.verify_mode = ssl.CERT_NONE
buf = b''

def call(s, rid, method, params=None, token=None):
    global buf
    req = {'id': rid, 'method': method}
    if params: req['params'] = params
    if token:  req['token']  = token
    s.sendall((json.dumps(req) + '\n').encode())
    while True:
        buf += s.recv(4096)
        lines = buf.split(b'\n'); buf = lines[-1]
        for ln in lines[:-1]:
            ln = ln.strip()
            if not ln: continue
            try:
                m = json.loads(ln)
                if m.get('id') == rid: return m
            except: pass

with socket.create_connection(('localhost', 2222), timeout=10) as raw, \
     ctx.wrap_socket(raw) as s:
    hello = call(s, 1, 'JSONRPC.Hello')
    token = None
    if hello.get('params', {}).get('authenticationRequired', False):
        r = call(s, 2, 'Users.Authenticate',
                 {'username': user, 'password': pw, 'deviceName': 'relay-chk'})
        p = r.get('params', {})
        if not p.get('success', True) or 'token' not in p:
            sys.exit('AUTH_FAILED — définir NYMEA_USER / NYMEA_PASS')
        token = p['token']
    # Résoudre stateTypeId de 'power' pour chaque ThingClass (les states dans GetThings
    # ne portent pas le nom, seulement le stateTypeId — cf. nymea JSON-RPC spec).
    tc = call(s, 3, 'Integrations.GetThingClasses', token=token)
    power_stid = {}
    for c in tc.get('params', {}).get('thingClasses', []):
        for st in c.get('stateTypes', []):
            if st.get('name') == 'power':
                power_stid[c['id']] = st['id']
    resp = call(s, 4, 'Integrations.GetThings', token=token)
    things = resp.get('params', {}).get('things', [])
    t = next((x for x in things if x['id'] == '${tid}'), None)
    if not t: sys.exit('THING_NOT_FOUND: ${tid}')
    stid = power_stid.get(t.get('thingClassId', ''), '')
    state = next((st for st in t.get('states', []) if st.get('stateTypeId') == stid), None)
    print(1 if state and state.get('value') else 0)
GETSTATE
}

Le compteur mock pose currentPower = somme des 3 phases. RootMeter::currentPower() le relit.

---

§2 — ECS simple (1 relais, paliers {0, 2000})

T1 — Montée sur surplus

• inject : inject -2500
• log attendu : [Arbitre] … Surplus PV … ECS palier 1 puis [EcsRelayAdapter] … → stage 1
• vérif : relay $TID_R2000 → 1 (ON)
• ✓ / ✗ : ____

T2 — Délestage (import)

• inject : inject 1000 (import → surplus net négatif)
• log attendu : Surplus insuffisant … ECS éteint ; → stage 0
• vérif : relay $TID_R2000 → 0 (OFF)
• ✓ / ✗ : ____

---

§3 — ECS 3 relais (8 niveaux binaires R500/R1000/R2000)

T3 — Cascade montante

• inject : inject -1700 (budget 1700 → palier 1500)
• log : ECS palier 3 (1500 W)
• vérif : relay $TID_R500→1, relay $TID_R1000→1, relay $TID_R2000→0
• ✓ / ✗ : ____

T4 — Transition NON-CASCADÉE 1500 → 2000 (le test clé)

• contexte : on part de T3 (palier 1500, l'ECS mesure 1500 W).
• inject : inject -700 (budget = 700 + 1500 recrédit = 2200 → palier 2000)
• log : ECS palier 4 (2000 W) ; commutation off-before-on (R500/R1000 coupés avant R2000)
• vérif : relay $TID_R500→0, relay $TID_R1000→0, relay $TID_R2000→1 ← set final R2000 SEUL, pas un état parasite durable
• ✓ / ✗ : ____

T5 — Protection minOn (anti court-cycling)

• contexte : ECS vient de commuter (< minOn 60 s).
• inject : inject 1200 (import → le budget voudrait éteindre)
• log attendu : Verrou minOn — … maintenu palier …
• vérif : relais inchangés (maintien). Attendre > 60 s puis re-inject 1200 → délestage.
• ✓ / ✗ : ____

T6 — Délestage complet

• inject : inject 2000 (import franc, > minOn écoulé)
• vérif : relay $TID_R500→0, relay $TID_R1000→0, relay $TID_R2000→0
• ✓ / ✗ : ____

---

§3.5 — Pré-vol SG-Ready (à cocher avant T7, nymead ARRÊTÉ)

⚠️ La polarité K1/K2 est le seul point non vérifié proprement de toute la chaîne. Le test initial a échoué sur Device or resource busy (nymead tient les lignes GPIO via libgpiod v2). Cette vérification doit se faire nymead arrêté, au multimètre, avant toute mise sous tension côté PAC.

ssh etm@$BOX 'sudo systemctl stop nymead'
ssh etm@$BOX 'gpioget -c gpiochip0 16 19'   # attendu : 0 0 (repos LOW BCM16/BCM19)

• gpioget répond 0 0 — K1 (BCM16) et K2 (BCM19) au repos LOW. ✓
• K1 repos = circuit ouvert : multimètre en continuité NO-COM sur bornes K1 → circuit ouvert = PAC interprète 0:0 = état 2 « normal » (jamais 1:0 = blocage au boot). ✓
• K2 repos = circuit ouvert (idem). ✓
• Fail-safe boot confirmé : nymead démarre K1=K2=0 (repos LOW, NO/NC → circuit ouvert → PAC = normal). ✓
• sudo systemctl start nymead avant T7.

---

§4 — SG-Ready (PAC, 2 bits K1/K2 ; P3=1500, P4=3000)

Seuils code (rulebasedscheduler.cpp, kForceMargin=1.2, P3=1500, P4=3000) :

• État 3 si budgetW ≥ 1500 ; état 4 si budgetW ≥ P4×1,2 = 3600 ; zone morte état 4 si budgetW ≥ 3000.
• budgetW = exportW_brut + allocatedNow ; allocatedNow = 0 (état 2), 1500 (état 3), 3000 (état 4).
• Depuis état 2 (sans recrédit) : min. inject ≤ −3600 pour atteindre état 4 directement.
• Depuis état 3 (recrédit 1500) : min. inject ≤ −2100 pour atteindre état 4.

T7 — Montée d'états 2 → 3 → 4

• inject -1000 → état 2 (budget 1000 < 1500, K1=0,K2=0).
• inject -2000 → état 3 (budget 2000 ≥ 1500, K2=1). Attendre > minStateHold (300 s).
• inject -2500 → état 4 (budget = 2500 + 1500 recrédit = 4000 ≥ 3600, K1=1,K2=1).
• log : … recommandée (état 3 …) puis … forcée (état 4 …)
• vérif : état 3 → relay $TID_K1→0, relay $TID_K2→1 ; état 4 → relay $TID_K1→1, relay $TID_K2→1
• ✓ / ✗ : ____

T8 — Atomicité (transitoire bénin)

• contexte : transition 2→4 (00→11) commute K1 ET K2.
• vérif : set final relay $TID_K1→1, relay $TID_K2→1 (état 4). Le transitoire passe par K2 d'abord (01=reco), jamais 10=blocage — sub-ms, non observable, mais garanti code (transientHarm). Confirmer simplement le set final correct.
• ✓ / ✗ : ____

T9 — Zone morte hystérésis (pas de bascule 4→3 sur fluctuation surplus)

• contexte : PAC en état 4 (K1=K2=1) depuis > minStateHold (300 s). L'opérateur injecte le surplus brut au compteur — le moteur recrédite la puissance allouée (3000 W déclarés) en interne ; ne pas l'ajouter à inject.
• Faire fluctuer le surplus : inject -300 → reste 4 ; inject -500 → reste 4 ; inject -100 → reste 4 ; inject 0 (équilibré) → reste 4 (tout inject ≤ 0 tient l'état).
• Sortie : inject 300 (import net) → état 3.
• vérif : relay $TID_K1→1, relay $TID_K2→1 stable pendant la fluctuation ; relay $TID_K1→0 uniquement après inject 300.
• ✓ / ✗ : ____

---

§5 — Watchdog L2 (compteur muet)

T10 — Compteur muet → mode dégradé

• inject -2500 (ECS/PAC servis), puis mute (>90 s sans injection).
• log attendu : [Arbitre] Compteur muet depuis … mode dégradé L2 ; ECS palier 0 ; PAC état 2.
• vérif : relay $TID_R500→0, relay $TID_R1000→0, relay $TID_R2000→0 ; relay $TID_K1→0, relay $TID_K2→0 (état 2, jamais blocage).
• ✓ / ✗ : ____

T11 — Stabilité (faux surplus piège)

• contexte : toujours muet ; la dernière valeur injectée (-2500) reste « collée » au compteur.
• vérif : sur plusieurs minutes muettes, ECS reste 0 malgré ce surplus stale (planification suspendue — pas de replanif sur cache mort).
• ✓ / ✗ : ____

T12 — Reprise

• inject -2500 (le compteur re-parle).
• log attendu : Compteur de nouveau actif — sortie du mode dégradé ; recalcul normal.
• vérif : ECS resuit le surplus (palier > 0). Pas de restauration d'ancienne consigne.
• ✓ / ✗ : ____

---

§6 — Interaction budget partagé

T13 — Ordre de priorité ECS↔PAC inversable

• contexte : surplus moyen inject -3000, ECS palier 2400 vs PAC P3 1500.
• ECS prio 1 / PAC prio 2 : ECS se sert (palier), PAC voit le reliquat (600) → état 2.
• Inverser les priorités (échanger priority dans le bloc §1.d, rebuild/redeploy) → PAC se sert (état 3), ECS voit le reliquat (1500 < 2400) → palier 0.
• vérif : le service s'inverse selon la priorité (preuve du waterfall unifié).
• ✓ / ✗ : ____

---

§7 — OPTIONNEL EV / V2C (si plugin prêt)

T14 — Ordre étagé EV → ECS (beta : EV servi avant le waterfall)

• contexte : borne EV branchée + surplus moyen.
• attendu : l'EV est servi en premier (proxy amont, décision B), l'ECS voit le reliquat.
• vérif : courant EV puis palier ECS sur le reliquat. (V2C = session dédiée, hors Palier 1.)
• ✓ / ✗ : ____

---

Checklist sécurité (AVANT mise sous tension)

• Disjoncteur L0 du banc accessible et identifié (coupure physique immédiate).
• Banc câblé hors tension ; sections/calibres relais conformes aux puissances (R2000 = 2000 W).
• Polarité SG-Ready vérifiée (§3.5 fait et coché) — seul point non vérifié avant cette session.
• Relais résistifs ECS : pas de charge inductive sur ces voies.
• Mapping BCM↔relais consigné (gpioinfo gpiochip0, nymead arrêté) avant tout test.
• L1 (failsafe bornes/relais) configuré si applicable ; L0 reste le filet ultime.
• Un opérateur à la main sur le disjoncteur pendant T1–T6 (montées de puissance).