Skip to content

Protocol

The protocol links the box's energy engine to an optimizer, over a dedicated channel. It is not the app's API: the app goes through the JSON-RPC API.

What is authoritative

  • The shape of messages (fields, types, allowed values, what the engine rejects) is set by the machine-readable contract. The tables on this page are generated from it on every publication: framing in English, descriptions taken as-is from the contract, in French. They are identical in all three languages.
  • The meaning is described in detail, in French, in OPTIMIZER_PROTOCOL.md, in the engine repository. This page gives the essentials; where they differ, the engine's documents prevail.

Transport and roles

  • The optimizer is the server, the engine is the client: the engine connects and asks the questions. The box opens no port.
  • Two transports, same messages: unix:// (local socket, default) and tcp:// (machine on the local network).
  • JSON-RPC 2.0, one message per line (NDJSON), UTF-8.
  • If the connection drops, the engine reconnects with a growing delay and drives the loads by its rules in the meantime.
Property Value (contract)
Protocol version 1.8
Application protocol JSON-RPC 2.0
Framing ndjson (one message per line)
Encoding utf-8
Endpoint schemes unix:// · tcp://
Default endpoint unix:///run/powersync/optimizer.sock
Client engine
Server optimizer
Max line size 1048576 bytes
Handshake timeout 5 s
Request timeout 10 s
Reconnect backoff 1 s → 60 s, ×2
Requests in flight 1
Request ids entiers croissants sur toute la vie du client, à travers les reconnexions
Line errors ligne non JSON, sans id, id jamais émis, ligne > maxLineBytes : comptée, connexion CONSERVÉE (côté moteur ; côté optimiseur : x-etm-message-errors)
Token masking toute occurrence du token dans un message reçu est remplacée par « [token masqué] » dès l'analyse

Servers

Name URL Summary (contract) Example values
unix unix:///run/powersync/optimizer.sock Défaut : optimiseur local, socket possédé par root:powersync, mode 0660. Le répertoire /run/powersync appartient au paquet de l'optimiseur (x-etm-transport.runtimeDirectory).
tcp tcp://{host}:{port} Optimiseur sur le LAN. Token recommandé ; il circule en clair sans TLS (E16). host = 192.0.2.10, port = 7400

Methods

Method Direction Kind Timeout Summary (contract)
Handshake engine→optimizer request 5 s Ouverture de session, à chaque (re)connexion (§3).
GetPlan engine→optimizer request 10 s Demande d'un plan pour le contexte courant (§4-§6).
UpdateLearned optimizer→engine notification (no id) — Estimations apprises de l'optimiseur (§8) — notification, sans id.

Handshake

On every connection, the engine sends Handshake with its protocol version and, if configured, the shared secret. The optimizer answers with its version and, if it wishes, its name and capabilities. A different major version, a refused secret or an unreadable answer: the connection is refused, and the engine drives by its rules. If the optimizer announces the action kinds (kinds) it emits, the engine then rejects any action of another kind.

Handshake — params

Ouverture de session, à chaque (re)connexion (§3).

Envoyé par le moteur (client) dès la connexion. Délai : 5 s depuis le DÉBUT de la tentative ; au-delà, repli et nouvelle tentative au backoff. Le message porte le secret : il n'est jamais journalisé. Refus (1.2) : token absent ou différent → -32001 ; majeure incompatible → -32602 ; les deux fautes dans le même handshake → -32001, le token est jugé AVANT la majeure (1.3) ; l'optimiseur ferme après avoir envoyé l'erreur, le moteur à sa réception. Un token envoyé alors que l'optimiseur n'en exige pas est accepté, sans erreur.

Field Type Required Values Description (contract, French)
protocolVersion ProtocolVersion yes Version du moteur ; seule la majeure est comparée, des deux côtés (une autre majeure : l'optimiseur répond -32602 et ferme — -32001 si le token est faux aussi, 1.3).
engine string yes pattern ^etm-powersync-energy-plugin-etm/ Moteur et sa version.
token HandshakeToken no

result (handshake): HandshakeResult

Errors

Code Message Note (contract)
-32001 token refusé Token configuré côté optimiseur, et absent ou différent dans le Handshake — jugé AVANT la majeure (1.3) : token faux et autre majeure dans le même Handshake → -32001. Un token envoyé alors que l'optimiseur n'en exige pas est ACCEPTÉ.
-32602 majeure incompatible Majeure de params.protocolVersion différente de celle de l'optimiseur (1.2), le token étant accepté ou non exigé (1.3 : le token est jugé d'abord).

HandshakeToken

Secret partagé (§3, E-T2-8) : 16 caractères au moins, 4 096 octets au plus (borne en octets non exprimable ici : contrôlée par le moteur), imprimable, sans blanc ni caractère de contrôle, UTF-8 admis. Envoyé seulement s'il est configuré ; jamais journalisé.

Type: string — ≥ 16 char. ; pattern ^[^\s\x00-\x1f\x7f]+$

HandshakeResult

Field Type Required Values Description (contract, French)
protocolVersion string yes ≥ 1 char. ; pattern ^[0-9]+(\.[0-9]+)*$ Version semver de l'optimiseur ; même MAJEURE que le moteur exigée (règle major-mismatch).
name string no Nom affiché (mode installateur), non contrôlé par le moteur (E-T7-3).
planning boolean no Vrai si l'optimiseur produit des plans multi-créneaux. Informatif.
capabilities Capabilities no

Undeclared fields: ignored (optimizer-emitted form, open).

Capabilities

Capacités annoncées (§3, 1.1, optionnel). Affichées en mode installateur, réduites aux clés et valeurs connues (capacitesPubliees) ; un champ inconnu est ignoré (§9).

Field Type Required Values Description (contract, French)
maxHorizonH number no ≥ 0 Horizon maximal planifié, en heures.
resolutionS number no ≥ 0 Pas des créneaux, en secondes.
kinds [ActionKind] no PRÉSENT, il restreint les kinds acceptés (règle kind-not-announced).
usesForecast [string] no pv · baseload · price · temperature
reasonCodes boolean no L'optimiseur émet des reasonCode du catalogue.

Undeclared fields: ignored (optimizer-emitted form, open).

The context: GetPlan

On every cycle, and on events (vehicle plugged in, new forecast, configuration change…), the engine sends GetPlan with a context: state of the site and of the grid meter, production, battery, the arbitrated loads with their bounds, locks and needs, and forecasts on a single time grid.

A few reading rules that change decisions:

  • the meter is sent as a raw measurement, never as the balance after control;
  • an unknown value is null, never 0;
  • an unavailable load (available: false) must receive no setpoint, but it consumes: it is still counted;
  • current locks (lockMinPowerW, lockMaxPowerW) say what the load can do now; the engine enforces them regardless;
  • what a load measures is read from measurement.source, never from its mechanism (adapter); a declared power is never a measurement.

The shape sent by the engine is closed: it emits no field outside the contract.

GetPlan — params

Demande d'un plan pour le contexte courant (§4-§6).

À chaque cycle (~1/min) et sur événement (trigger). Une requête en vol au plus : une plus récente remplace l'attente de la précédente (sa réponse est ignorée par id, ce n'est pas un échec). Délai : 10 s par requête. La réponse à la requête N sert au cycle N+1 (modèle cache). Le JSON Schema dit la FORME ; x-etm-semantic-rules dit ce que le validateur refuse en plus.

Field Type Required Values Description (contract, French)
timestamp string yes instant with offset Instant du cycle — le « maintenant » du validateur.
trigger Trigger yes
site Site yes
meter Meter yes
pv Pv yes
battery Battery yes
loads [Load] yes Charges arbitrées, ⊆ GetLoadConfig.
forecast Forecast | null yes null sans instantané de prévision.
tariff Tariff | null yes

Errors

Code Message Note (contract)
-32600 handshake requis GetPlan reçu avant un Handshake réussi sur cette connexion (1.2). Le moteur n'en envoie jamais : il attend d'être prêt.
-32602 contexte invalide Contexte GetPlan non conforme au contrat (1.2). error.data liste les problèmes : pour chacun, le chemin du champ fautif et la nature du problème, JAMAIS la valeur reçue. Forme normée en 1.3 : InvalidContextData. Une erreur et non une abstention : un contexte invalide est un défaut du moteur, une abstention le cacherait.
-32603 erreur interne Code JSON-RPC 2.0 standard pour toute autre panne de l'optimiseur.

Site

Field Type Required Values Description (contract, French)
contractedPowerW number | null yes Puissance souscrite (W) ; null si inconnue (E1), jamais 0.
gridCapW null yes RÉSERVÉ (signaux réseau type §14a EnWG) : toujours null en 1.1.
phaseLimitA [number] | null yes SEUIL par phase (A) que le moteur fait respecter au COMPTEUR RACINE — le courant total de la phase, maison comprise, pas la part des charges pilotées : la limite du branchement moins la marge de sécurité (phaseSafetyMarginPercent), pas la limite elle-même ; un plan bâti sur la limite serait écrêté à chaque cycle. Ce qu'une charge peut encore prendre = seuil − courant mesuré de la phase (meter.perPhaseA) + ce qu'elle tire déjà. null sans limite réglée.
timeZone string no ≥ 1 char. 1.8 — fuseau IANA de la box (« Europe/Paris ») : celui des heures murales du contexte (needs.dailyDeadline, départ quotidien d'une voiture, heures du tarif). Absent pour un optimiseur 1.7 ou antérieur, et si la box n'en connaît pas.

Undeclared fields: rejected (engine-emitted form, closed).

Meter

Field Type Required Values Description (contract, French)
source string | null yes ThingId du compteur racine désigné ; null si inconnu.
importW number yes ≥ 0 Puissance importée (W).
exportW number yes ≥ 0 Exported power (W), RAW measurement (rule 8 of the project's coding rules) — never the net after control.
perPhaseA [number] yes Courant par phase (A).

Undeclared fields: rejected (engine-emitted form, closed).

Pv

Field Type Required Values Description (contract, French)
currentW number | null yes ≥ 0 Production instantanée (W), positive ; null sans producteur (jamais 0).

Undeclared fields: rejected (engine-emitted form, closed).

Battery

One of: BatteryAbsent · BatteryPresent.

Load

Une charge arbitrée (§5.3) — la forme dépend du mécanisme (adapter).

One of: LoadWatts · LoadEvCharger · LoadSgReady.

Forecast

Prévisions sur UNE grille (§5.2) ; tableaux alignés index par index.

Field Type Required Values Description (contract, French)
start string yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
resolutionS integer yes ≥ 1 Pas de la grille (s) — fait foi, jamais supposé.
steps integer yes ≥ 0 Nombre de cases ; toutes les séries ont cette longueur.
pv PvForecast | null yes null sans courbe (site non désigné, charge utile refusée, canal muet).
baseload Baseload yes
weather null yes Aucune source de température en 1.1 : toujours null.
price Price | null yes null sans tarif (ni saisi, ni lu sur un appareil fournisseur).

Undeclared fields: rejected (engine-emitted form, closed).

Tariff

Le tarif EN VIGUEUR, rempli depuis 1.4 : le tarif SAISI (NymeaEnergy.SetTariff), ou celui d'un appareil fournisseur de tarif choisi par NymeaEnergy.SetTariffSource (ses créneaux connus) — null sans tarif. current : la zone en vigueur à timestamp ; next : chaque changement de zone après timestamp, dans l'ordre, jusqu'à la fin du lendemain dans le fuseau de la box (l'horizon de forecast). offPeak sur chaque entrée : le jugement « heures creuses » du moteur. Le prix sur la grille de la prévision se lit dans forecast.price (1.1), du même tarif. 1.6 : chaque entrée porte nominal (0-100, null si le prix n'est pas confirmé) et expensive (le prix fort du moteur). Rien n'est émis au-delà du connu : la fin du connu est forecast.price.knownUntil.

Field Type Required Values Description (contract, French)
provider string | null yes null : un tarif saisi n'a pas de fournisseur. Tarif lu sur un appareil fournisseur : le nom de son plugin (« edf »).
current TariffEntry yes
next [TariffNextEntry] yes

Undeclared fields: rejected (engine-emitted form, closed).

BatteryAbsent

Aucun stockage déclaré : rien d'autre n'est émis.

Field Type Required Values Description (contract, French)
present boolean yes false

Undeclared fields: rejected (engine-emitted form, closed).

BatteryPresent

Field Type Required Values Description (contract, French)
present boolean yes true
socPercent number yes
powerW number yes Positif = charge, négatif = décharge.
capacityWh number | null yes null si inconnue.
maxChargeW number | null yes null si inconnue.
maxDischargeW number | null yes null si inconnue.
reserveSocPercent integer | null yes Réserve de secours (%) ; null si inconnue.

Undeclared fields: rejected (engine-emitted form, closed).

LoadWatts

Charge pilotée en watts : combinaison de relais (relay-router) ou consigne continue (etmvariableload).

Field Type Required Values Description (contract, French)
id string yes ≥ 1 char. Identifiant de la charge — clé des actions.
label string yes Nom lisible.
priority integer yes Rang effectif (1 = premier servi).
domain Domain no
learned LoadLearned no
needs LoadNeeds no
progress LoadProgress no
readback LoadReadback no
adapter string yes relay-router · etmvariableload
declared object yes
declared.minPowerW number yes 0 = aucun plancher.
declared.maxPowerW number yes
declared.phase enum no L1 · L2 · L3 1.7 — phase du réseau sur laquelle la charge MONOPHASÉE est câblée, saisie par l'installateur. Absente = inconnue : garder le pire cas (toutes les monophasées sur la même phase).
declared.powerRanges [PowerRange] no 1.8 — les puissances atteignables (PowerRange). Absent si rien n'est déclaré (borne sans appareil). Toujours une liste de niveaux pour un relay-router et une PAC, deux plages (mono, tri) qui peuvent se chevaucher pour une borne commutable.
telemetry object yes
telemetry.currentPowerW number yes Puissance courante (W) telle que l'adaptateur la publie.
telemetry.available boolean yes Gouverne l'ALLOCATION, pas la COMPTABILITÉ (§5.3).
telemetry.measurement Measurement no
telemetry.lockMinPowerW number yes Plancher imposé MAINTENANT par un verrou.
telemetry.lockMaxPowerW number yes Plafond imposé maintenant ; négatif = aucun plafond.
telemetry.tank object no 1.8 — le BALLON servi par ce chauffe-eau (LoadConfig.tank) : volume (L), température visée (°C) et mesurée par sa sonde (absente si la sonde ne mesure pas ce cycle). Avec la température, le besoin est la température visée avant needs.dailyDeadline : energyTargets en porte l'énergie (volume × 1,163 Wh/(L·K) × écart, source installer) à la place des kWh par jour. Absent sans ballon déclaré.
telemetry.tank.volumeL number yes > 0
telemetry.tank.targetC number yes
telemetry.tank.tempC number no
limits object yes
limits.minOnS integer yes
limits.minOffS integer yes

Undeclared fields: rejected (engine-emitted form, closed).

LoadEvCharger

Borne. Une borne CONFIGURÉE dont l'appareil manque n'a ni declared, ni limits, ni pluggedIn/charging : ses zéros diraient « inconnu ».

Field Type Required Values Description (contract, French)
id string yes ≥ 1 char. Identifiant de la charge — clé des actions.
label string yes Nom lisible.
priority integer yes Rang effectif (1 = premier servi).
domain Domain no
learned LoadLearned no
needs LoadNeeds no
progress LoadProgress no
readback LoadReadback no
adapter string yes "evcharger"
declared object no
declared.minA number yes
declared.maxA number yes
declared.phases integer yes Phases que le moteur VISE ce cycle (règle de bascule, voiture), pas la plaque — sens gardé pour un optimiseur 1.0 à 1.6. La plaque : wiredPhases (1.7).
declared.wiredPhases enum no 1 · 3 1.7 — phases CÂBLÉES de la borne (plaque, installation), indépendamment de la voiture et de la règle. Absent si inconnu.
declared.phaseSwitch object no 1.7 — le matériel bascule 1 ↔ 3 (absent sinon). Ce que la séquence impose : arrêt de la charge tenu stopHoldS avant d'écrire les phases, puis settleS sans nouvelle bascule. Ce que ce cycle permet : telemetry.allowedPhases.
declared.phaseSwitch.phases [enum] yes 1 · 3 Phases que le matériel accepte.
declared.phaseSwitch.stopHoldS integer yes ≥ 0 Arrêt vu par toutes les sources, tenu ce temps avant d'écrire les phases (s).
declared.phaseSwitch.settleS integer yes ≥ 0 Après une bascule : aucune autre bascule, la commande n'est pas jugée (s).
declared.phase enum no L1 · L2 · L3 1.7 — phase du réseau d'une borne câblée en MONOPHASÉ (wiredPhases 1), saisie par l'installateur. Absente = inconnue (pire cas), et toujours absente d'une borne triphasée.
declared.powerRanges [PowerRange] no 1.8 — les puissances atteignables (PowerRange). Absent si rien n'est déclaré (borne sans appareil). Toujours une liste de niveaux pour un relay-router et une PAC, deux plages (mono, tri) qui peuvent se chevaucher pour une borne commutable.
telemetry object yes
telemetry.currentPowerW number yes Puissance courante (W) telle que l'adaptateur la publie.
telemetry.available boolean yes Gouverne l'ALLOCATION, pas la COMPTABILITÉ (§5.3).
telemetry.measurement Measurement no
telemetry.pluggedIn boolean no
telemetry.charging boolean no
telemetry.heldPhases enum no 1 · 3 1.7 — phases que la borne tient maintenant (relues pour une borne à bascule, comptées par le moteur sinon).
telemetry.allowedPhases [enum] no 1 · 3 ; ≥ 1 items 1.7 — les valeurs de phases qu'une action peut porter CE cycle : [1, 3] pour une borne qui bascule avec cette voiture hors séquence, fenêtre qui suit une bascule et espacement (sans 3 si la règle interdit le triphasé : délestage, limite de phase) ; sinon [heldPhases]. Une autre valeur est servie sur heldPhases (readback.boundBy : adapter).
telemetry.carPhases enum no 1 · 3 1.7 — phases de la voiture, connues (publiées par la voiture assignée, ou mesurées par la borne) ; absent si inconnues.
telemetry.sessionWh number no Absent si la borne ne compte pas sa session (LM-1009 C1).
telemetry.vehicle Vehicle no
limits object no
limits.chargingEnabledLockS integer yes
limits.currentChangeLockS integer yes

Undeclared fields: rejected (engine-emitted form, closed).

LoadSgReady

PAC SG-Ready : 4 états normés, kind state.

Field Type Required Values Description (contract, French)
id string yes ≥ 1 char. Identifiant de la charge — clé des actions.
label string yes Nom lisible.
priority integer yes Rang effectif (1 = premier servi).
domain Domain no
learned LoadLearned no
needs LoadNeeds no
progress LoadProgress no
readback LoadReadback no
adapter string yes "sg-ready"
declared object yes
declared.states [integer] yes ≥ 1 ; ≤ 4
declared.estimatedPowerW map of number yes
declared.powerRanges [PowerRange] no 1.8 — les puissances atteignables (PowerRange). Absent si rien n'est déclaré (borne sans appareil). Toujours une liste de niveaux pour un relay-router et une PAC, deux plages (mono, tri) qui peuvent se chevaucher pour une borne commutable.
declared.modes [object] no 1.8 — la puissance de chaque état (mode) : apprise au compteur de la PAC (source learned, moyenne mesurée dans ce mode hors transitoire), sinon saisie (source declared). Jamais exacte : un mode est commandé, sa puissance en est l'effet. Classer les modes par powerW, jamais par leur numéro.
declared.compressorBlock boolean no true 1.8 — vrai : l'état 1 (bloquée) est servi par le contact du COMPRESSEUR seul (régulation et circulateur tournent), les contacts SG restant sur l'état 2. Absent : l'état 1 est l'état SG 1 (toute la PAC).
telemetry object yes
telemetry.currentPowerW number yes Puissance courante (W) telle que l'adaptateur la publie.
telemetry.available boolean yes Gouverne l'ALLOCATION, pas la COMPTABILITÉ (§5.3).
telemetry.measurement Measurement no
telemetry.state integer yes ≥ 0 ; ≤ 4 État commandé (1-4) ; 0 = non applicable.
telemetry.minState integer yes Fenêtre d'états autorisée MAINTENANT par minStateHold.
telemetry.maxState integer yes
telemetry.blockedS integer no ≥ 0 1.8 — durée déjà bloquée dans la période en cours (s) ; absente si la PAC n'a pas été bloquée.
limits object yes
limits.minStateHoldS integer yes
limits.maxBlockS integer no ≥ 0 1.8 — durée MAXIMALE de blocage (état 1) par période chère (s) : au-delà, le moteur rend la main (état 2, HEAT_PUMP_BLOCK_LIMIT, readback.boundBy : blockLimit), même si le plan redemande le blocage. Hors prix fort, le compte repart après autant de temps libre.
limits.blockAtExpensivePrice boolean no 1.8 — l'interrupteur « bloquer au prix fort » de la PAC (défaut vrai). Vrai : le moteur seul bloque la PAC au prix fort (HEAT_PUMP_PEAK_BLOCK), au plus maxBlockS ; un plan peut le faire aussi. Faux : un état 1 demandé AU PRIX FORT est refusé par la garde du moteur (état 2, HEAT_PUMP_PEAK_BLOCK_REFUSED, readback.boundBy : peakBlockOff) ; hors prix fort, rien ne change.

Undeclared fields: rejected (engine-emitted form, closed).

PvForecast

Field Type Required Values Description (contract, French)
p50W [number | null] yes Puissance AC moyenne sur [t, t+pas), sommée sur les plans puis plafonnée à acLimitW ; null = case inconnue. Un plafond, pas une espérance (§5.2).
conversion string yes physics Seule valeur émise par le moteur GPL ; un consommateur ignore une valeur inconnue.
corrections [Correction] yes [] = conversion brute.
weatherModel string | null yes Modèle qui a RÉPONDU ; null si inconnu.
issuedAt string | null yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
contentChangedAt string | null yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
acLimitW integer no Plafond AC du site (W), s'il est configuré.
perField [PvField] no

Undeclared fields: rejected (engine-emitted form, closed).

Baseload

Field Type Required Values Description (contract, French)
model string yes profile · none Le moteur GPL émet profile ou none (learned n'est pas émis).
p50W [number | null] yes
quality BaseloadQuality no

Undeclared fields: rejected (engine-emitted form, closed).

Price

Field Type Required Values Description (contract, French)
currency string yes "EUR"
importCtkWh [number | null] yes
exportCtkWh [number | null] yes
includes [PriceInclude] yes
source string yes fixed · tou Une zone (fixed) ou des zones horaires (tou). Créneaux d'un appareil fournisseur : tou dès que leurs prix diffèrent, fixed sinon ; une case de la grille non couverte par les créneaux connus vaut null, et knownUntil est la fin du connu. tempo et day-ahead ne sont pas émis en 1.1.
knownUntil string yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.

Undeclared fields: rejected (engine-emitted form, closed).

TariffEntry

Zone tarifaire en vigueur à timestamp (1.4).

Field Type Required Values Description (contract, French)
label string yes Libellé saisi par l'installateur, ou code de période publié par un appareil fournisseur de tarif (donnée, jamais une phrase du moteur).
priceCtkWh number yes Prix complet payé de la zone, c€/kWh.
offPeak boolean yes La zone est CREUSE au jugement du moteur (1.4) : au prix le plus bas d'un tarif dont les zones n'ont pas toutes le même prix — plusieurs zones à ce prix sont toutes creuses ; le libellé n'y entre pas. Tarif unique ou prix tous égaux : false. Tarif lu sur un appareil fournisseur : le créneau au NOMINAL (0-100) le plus bas parmi les créneaux connus, même règle (TariffConfig::niveauxCreux()). Même lecture que les décisions du rule-based.
nominal integer | null yes ≥ 0 ; ≤ 100 1.6 — prix NORMALISÉ du créneau, 0-100 : 0 = la période la moins chère du CONTRAT, 100 = la plus chère, les autres au prorata de leur prix, arrondi à l'entier ; contrat à prix unique (base, prix tous égaux) : 0. Tarif lu sur un appareil fournisseur : le nominal qu'il publie ; tarif saisi : calculé de même sur les zones saisies. Relatif au contrat, jamais à la journée. null : le prix du créneau n'est pas confirmé (publié présumé — priceKnown faux chez le fournisseur, couleur Tempo pas encore annoncée). C'est la grandeur que l'optimiseur place ; il ne lit pas le contrat.
expensive boolean yes 1.6 — le créneau est au PRIX FORT au jugement du moteur : prix ≥ facteur (2 par défaut, réglable de 1,5 à 4) × le prix le plus bas du contrat (pointe EJP, rouge Tempo HP ; jamais HC/HP, base, Tempo bleu ou blanc). Le moteur n'y prend rien du réseau sans l'accord de l'usager, quel que soit le plan (§1). Même règle que ses décisions ; appliquée au prix publié, confirmé ou non.

Undeclared fields: rejected (engine-emitted form, closed).

TariffNextEntry

Un changement de zone (1.4) : la zone qui commence à from et court jusqu'au from suivant.

Field Type Required Values Description (contract, French)
label string yes
priceCtkWh number yes
from string | null yes instant with offset Début de la zone : instant ISO 8601 AVEC son décalage (Z ou ±hh:mm), tiré de la plage murale minute par minute absolue — une heure murale nue est refusée. Jamais null en 1.4.
offPeak boolean yes La zone est CREUSE au jugement du moteur (1.4) : au prix le plus bas d'un tarif dont les zones n'ont pas toutes le même prix — plusieurs zones à ce prix sont toutes creuses ; le libellé n'y entre pas. Tarif unique ou prix tous égaux : false. Tarif lu sur un appareil fournisseur : le créneau au NOMINAL (0-100) le plus bas parmi les créneaux connus, même règle (TariffConfig::niveauxCreux()). Même lecture que les décisions du rule-based.
nominal integer | null yes ≥ 0 ; ≤ 100 1.6 — prix NORMALISÉ du créneau, 0-100 : 0 = la période la moins chère du CONTRAT, 100 = la plus chère, les autres au prorata de leur prix, arrondi à l'entier ; contrat à prix unique (base, prix tous égaux) : 0. Tarif lu sur un appareil fournisseur : le nominal qu'il publie ; tarif saisi : calculé de même sur les zones saisies. Relatif au contrat, jamais à la journée. null : le prix du créneau n'est pas confirmé (publié présumé — priceKnown faux chez le fournisseur, couleur Tempo pas encore annoncée). C'est la grandeur que l'optimiseur place ; il ne lit pas le contrat.
expensive boolean yes 1.6 — le créneau est au PRIX FORT au jugement du moteur : prix ≥ facteur (2 par défaut, réglable de 1,5 à 4) × le prix le plus bas du contrat (pointe EJP, rouge Tempo HP ; jamais HC/HP, base, Tempo bleu ou blanc). Le moteur n'y prend rien du réseau sans l'accord de l'usager, quel que soit le plan (§1). Même règle que ses décisions ; appliquée au prix publié, confirmé ou non.

Undeclared fields: rejected (engine-emitted form, closed).

LoadLearned

Absent tant qu'aucun profil n'a été reçu (E12).

Field Type Required Values Description (contract, French)
dailyEnergyWh number yes
confidence number yes ≥ 0 ; ≤ 1

Undeclared fields: rejected (engine-emitted form, closed).

LoadNeeds

Besoins (§5.3). Champs 1.0 émis tels quels quand ils sont déclarés ; un optimiseur 1.1 préfère energyTargets.

Field Type Required Values Description (contract, French)
dailyDeadline string no pattern ^[0-9]{2}:[0-9]{2}$ Heure murale locale HH:MM (1.0).
minEnergyWhPerDay integer no > 0
targetSocPercent integer no > 0 ; ≤ 100 SoC visé (%). 1.5 — pour une borne : le SoC VISÉ de la voiture assignée, réglé par l'usager (NymeaEnergy.SetCarChargingSettings) ; le moteur ne le planifie pas.
deadline string no instant with offset Échéance absolue. 1.5 — pour une borne : le PROCHAIN départ de la voiture assignée (le départ ponctuel tant qu'il est à venir, sinon la prochaine heure quotidienne). Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
energyTargets [EnergyTarget] no ≥ 1 items
offPeakShift boolean no true 1.4 — true, ou absent : le besoin RÉSEAU de cette charge se reporte en heures creuses (borne en « Éco avec minimum » ou à échéance). Le rule-based la sert à pleine puissance dans les zones offPeak de tariff, au surplus seulement en dehors ; sans heure creuse, sans effet.
minSocPercent integer no > 0 ; ≤ 90 1.5 — SoC MINIMUM de la voiture assignée (%), une sécurité : le moteur le sert lui-même, à pleine puissance permise, et impose son action comme PLANCHER sur le plan (progress.minSocStatus: below). À planifier autour, jamais à retirer. ABSENT, comme minSocStatus, quand la voiture est sous son minimum pendant la période chère du tarif sans confirmation de l'usager : le moteur ne le sert pas alors, et n'impose aucun plancher.

Undeclared fields: rejected (engine-emitted form, closed).

LoadProgress

1.5 — AVANCEMENT des obligations de la charge, forme plate ; chaque champ est présent seulement s'il a un objet. Pour qu'un optimiseur planifie la journée entière sans rien laisser au rule-based.

Field Type Required Values Description (contract, French)
chargingMode string no normal · eco · ecoWithMinCurrent · ecoWithTargetTime · ecoMinWithTargetTime Borne : le mode choisi par l'usager (normal = Manuel, eco = Auto).
manualEnabled boolean no Borne en mode normal dont l'interrupteur Manuel a été posé : activé (pleine puissance) ou désactivé (arrêt).
energyTargetWh integer no > 0 Obligation quotidienne en énergie (Wh) — needs.minEnergyWhPerDay.
energyDeliveredWh integer no ≥ 0 Énergie livrée sur la période d'obligation en cours (Wh) ; ABSENTE si elle ne se mesure pas (energyRegime: unmeasurable), jamais 0.
energyRegime string no measured · estimated · unmeasurable D'où vient energyDeliveredWh.
energyBy string no instant with offset Échéance de l'obligation quotidienne en cours. Instant ISO 8601 AVEC son décalage.
derogationEndsAt string no instant with offset Fin du filet de la dérogation qui court. Instant ISO 8601 AVEC son décalage.
derogationTargetWh integer no > 0 Cible en énergie de la dérogation (Wh), depuis sa pose.
derogationDeliveredWh integer no ≥ 0 Énergie livrée depuis la pose de la dérogation (Wh).
minSocStatus string no below · met · unknown · stale SoC minimum de la voiture assignée : below — sous le minimum, le moteur le sert CE cycle et impose son action comme plancher (l'action de l'optimiseur pour cette borne est ignorée) ; met — atteint ; unknown / stale — non servi, SoC inconnu ou trop ancien. Absent sans minimum réglé, et quand la voiture est sous son minimum pendant la période chère du tarif sans confirmation de l'usager (non servi, aucun plancher).

Undeclared fields: rejected (engine-emitted form, closed).

LoadReadback

1.5 — RELECTURE du cycle PRÉCÉDENT : ce que le moteur a fait de la consigne de cette charge, qu'elle vienne du plan ou du rule-based (abstention, repli). Absente si la charge n'était pas au plan de ce cycle, ou si aucun cycle n'a été planifié (premier cycle, mode dégradé).

Field Type Required Values Description (contract, French)
cycleAt string yes instant with offset Instant du cycle relu. Instant ISO 8601 AVEC son décalage.
origin string yes optimizer · rules Qui a décidé : optimizer (la charge était nommée par le plan) ou rules (rule-based : sans plan, abstention, repli, charge indisponible).
planId string no planId du plan appliqué, si origin = optimizer et qu'il en avait un.
decidedW number yes ≥ 0 Puissance DÉCIDÉE (W) : celle que demandait le plan, ou que le rule-based avait allouée — avant toute garde.
decidedState integer no ≥ 1 ; ≤ 4 État SG-Ready décidé.
appliedW number yes ≥ 0 Puissance APPLIQUÉE (W) : ce que l'adaptateur a posé, ou ce que la protection a laissé.
appliedState integer no ≥ 0 ; ≤ 4 État SG-Ready appliqué.
appliedA number no ≥ 0 Borne : courant appliqué (A), 0 à l'arrêt.
appliedPhases integer no ≥ 1 ; ≤ 3 Borne : phases appliquées.
bounded boolean yes Vrai si une garde du moteur a modifié la consigne décidée.
boundBy string no overload · minSoc · drawCap · phaseLimit · lock · loadCeiling · adapter · blockLimit · peakBlockOff Quelle garde : overload (protection de surcharge), minSoc (plancher du SoC minimum, à la place de la demande du plan), drawCap (autorisation de soutirage), phaseLimit (limite de phase du branchement), lock (verrou de la charge), loadCeiling (plafond de cycle de la charge), adapter (arrondi ou bornes du mécanisme), blockLimit (durée maximale de blocage d'une PAC atteinte : rendue à l'état 2), peakBlockOff (blocage au prix fort refusé : l'interrupteur de la PAC est décoché, rendue à l'état 2). Absent si bounded est faux.
reasonCode string no Motif FINAL publié pour la charge (catalogue du moteur) — le code, jamais une phrase.
measurementSource string yes meter · device · none Source de la mesure publiée (§5.3) ; none = rien ne mesure.
measuredW number no Puissance MESURÉE (W) ; absente sous none.
divergent boolean no Le moteur juge que la mesure ne suit pas la commande (au-delà de sa tolérance et de la latence du mécanisme). Absent quand rien n'est commandé.

Undeclared fields: rejected (engine-emitted form, closed).

PowerRange

1.8 — une plage de puissances ATTEIGNABLES, déduite par le moteur de la configuration (relais et combinaisons, paliers, plancher et plafond, courants publiés et phases de la borne, puissance d'un mode de PAC) : une liste de niveaux OU un continu. 0 W (arrêt) est toujours permis en plus, sauf verrou du moment (telemetry). Les verrous du cycle, la limite de phase et les phases permises ce cycle (allowedPhases) n'y sont PAS appliqués. Une consigne hors plage est servie au niveau atteignable INFÉRIEUR, jamais au-dessus (readback.boundBy : adapter).

variant 1 — Paliers : relais (combinaisons ou un seul à la fois), etmvariableload fixed, modes d'une PAC.

Field Type Required Values Description (contract, French)
kind string yes setpoint · cap setpoint : la charge tire la valeur demandée ; cap : elle tire AU PLUS la valeur (réservé : entrée 0-10 V d'une PAC) — jamais comptée comme une consommation sûre.
exact boolean yes Vrai pour un relais ou une borne ; faux pour une puissance estimée ou apprise (mode de PAC).
phases enum no 1 · 3 Phases tirées : 1 ou 3. Absent si inconnu (charge en watts sans phase saisie). La phase d'une charge monophasée : declared.phase.
levelsW [number] yes ≥ 1 items Niveaux atteignables (W), croissants, sans 0.

Undeclared fields: rejected (engine-emitted form, closed).

variant 2 — Continu : gradateur (etmvariableload dynamic), borne (au pas d'un ampère).

Field Type Required Values Description (contract, French)
kind string yes setpoint · cap setpoint : la charge tire la valeur demandée ; cap : elle tire AU PLUS la valeur (réservé : entrée 0-10 V d'une PAC) — jamais comptée comme une consommation sûre.
exact boolean yes Vrai pour un relais ou une borne ; faux pour une puissance estimée ou apprise (mode de PAC).
phases enum no 1 · 3 Phases tirées : 1 ou 3. Absent si inconnu (charge en watts sans phase saisie). La phase d'une charge monophasée : declared.phase.
minW number yes ≥ 0 Plus petite puissance non nulle (W) ; 0 = aucun plancher.
maxW number yes > 0 Plus grande puissance (W).
stepW number no > 0 Pas (W) — 230 W (mono) ou 690 W (tri) pour une borne, un ampère par phase. Absent : au watt près.

Undeclared fields: rejected (engine-emitted form, closed).

Measurement

Mesure par charge (§5.3, LM-1105/1106) : décider sur source, jamais sur adapter.

variant 1 — Rien ne mesure : état positif, pas une erreur.

Field Type Required Values Description (contract, French)
source string yes "none"

Undeclared fields: rejected (engine-emitted form, closed).

variant 2

Field Type Required Values Description (contract, French)
source string yes meter · device
powerW number yes

Undeclared fields: rejected (engine-emitted form, closed).

Vehicle

1.5 — la voiture ASSIGNÉE à la borne, lue sur ses états génériques (jamais une marque). Absente sans voiture assignée.

Field Type Required Values Description (contract, French)
carId string yes ≥ 1 char. Identifiant de la voiture (ThingId) — stable d'une borne à l'autre.
source string yes vehicle · estimate vehicle : SoC lu sur la voiture (état en lecture seule) ; estimate : SoC saisi par l'usager et avancé par l'estimation du moteur.
known boolean yes Un SoC est lu. Faux : socPercent absent (jamais 0).
socPercent integer no ≥ 0 ; ≤ 100 SoC lu (%). Présent si known.
socAt string no instant with offset Instant du SoC, quand la voiture l'horodate ; absent sinon (son âge est alors inconnu). Le moteur juge un SoC de plus de 12 h trop ancien pour servir le minimum. Instant ISO 8601 AVEC son décalage.
capacityWh number no > 0 Capacité de la batterie (Wh) ; absente si inconnue.
sessionMinEnergyWh integer no > 0 1.8 — kWh minimum PAR BRANCHEMENT réglés pour cette voiture (Wh), avant son départ (needs.deadline). Servis par le moteur quand le SoC n'est pas utilisable (inconnu, périmé, ou aucun visé) : energyTargets en porte alors le reste (source user-intent) et progress l'avancement, compté sur l'énergie de CETTE borne depuis le branchement, remis à zéro au débranchement. Une borne qui ne mesure ni l'énergie de sa séance ni sa puissance (progress.energyRegime estimated, estimé sur la puissance commandée) : le reste compte en plus 10 % de ces kWh (supplément exigé avant de les dire livrés, energyTargetWh reste la valeur réglée). Absent si non réglé.
departureMarginS integer no ≥ 0 ; ≤ 7200 1.8 — marge de départ de la voiture (s, 0 à 7 200, défaut 1 800), présente dès qu'un départ est connu (needs.deadline). Les kWh (energyTargets, source user-intent) et le SoC visé sont à livrer AVANT deadline − marge — et avant le début d'un prix fort connu plus tôt ; de deadline − marge à deadline, la borne reste ouverte au plancher (6 A sur les phases tenues) pour que la voiture prenne son préconditionnement sur le secteur, jamais au prix fort sans accord de l'usager. 0 = finir à l'heure du départ, sans fenêtre de préconditionnement. Le moteur seul (rule-based) applique cette règle aux kWh par branchement.

Undeclared fields: rejected (engine-emitted form, closed).

PvField

Field Type Required Values Description (contract, French)
id string yes ThingId du plan.
corrections [Correction] yes

Undeclared fields: rejected (engine-emitted form, closed).

BaseloadQuality

Field Type Required Values Description (contract, French)
windowDays integer yes
minDays integer yes
resolutionS integer yes
daysCovered object yes
daysCovered.workday integer yes
daysCovered.weekend integer yes
minutes integer yes
commandedMinutes integer yes
negativeMinutes integer yes
incompleteMinutes integer yes
computedAt string no instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
loads [BaseloadLoadQuality] yes

Undeclared fields: rejected (engine-emitted form, closed).

EnergyTarget

Field Type Required Values Description (contract, French)
by string yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
minWh number yes > 0 Énergie minimale à avoir délivrée à l'échéance.
source string yes installer · user-intent installer : obligation quotidienne (1.1). user-intent : dérogation à cible d'énergie (1.1), ou SoC visé d'une voiture converti en Wh — énergie qui RESTE à charger d'ici le départ, batterie seule (1.5). learned n'est pas émis.

Undeclared fields: rejected (engine-emitted form, closed).

BaseloadLoadQuality

Field Type Required Values Description (contract, French)
loadId string yes
source string yes meter · device · none
minutesBySource map of integer yes keys meter · device · none
constantMeasurement boolean no

Undeclared fields: rejected (engine-emitted form, closed).

The answer: a plan or an abstention

The optimizer answers quickly — with its last cached plan if it computes for long — and recomputes in the background. It answers either:

  • a plan in time slots: each slot carries one action per available load (setpoint in watts or amps, or SG-Ready state), each with its reason; only the current slot is executed, and validUntil bounds the plan's lifetime;
  • an abstention (abstain: true): "no plan right now". The engine drives by its rules for that cycle, without treating the optimizer as failed.

An action's reason has two forms: a free text in French, mandatory, for the traces; and, optionally, a code from the catalogue (reasonCode) with its parameters. Only the code is passed on to the app, which translates it. An unknown code goes out as OPTIMIZER_DECISION.

The shape received by the engine is open: an unknown field is ignored.

GetPlan — result

plan: GetPlanResult

Errors

Code Message Note (contract)
-32600 handshake requis GetPlan reçu avant un Handshake réussi sur cette connexion (1.2). Le moteur n'en envoie jamais : il attend d'être prêt.
-32602 contexte invalide Contexte GetPlan non conforme au contrat (1.2). error.data liste les problèmes : pour chacun, le chemin du champ fautif et la nature du problème, JAMAIS la valeur reçue. Forme normée en 1.3 : InvalidContextData. Une erreur et non une abstention : un contexte invalide est un défaut du moteur, une abstention le cacherait.
-32603 erreur interne Code JSON-RPC 2.0 standard pour toute autre panne de l'optimiseur.

GetPlanResult

One of: Abstention · Plan.

InvalidContextData

error.data de la réponse -32602 à GetPlan (§7, 1.3). Exigé d'un optimiseur qui s'annonce 1.3 ou plus ; un optimiseur 1.2 peut répondre un autre data, le moteur ne le lit pas. Aucune valeur reçue n'y figure, dans aucun champ : la forme est fermée, le chemin suit un motif, la nature est un code d'une liste fermée.

Field Type Required Values Description (contract, French)
problems [ContextProblem] yes ≥ 1 items Les problèmes trouvés, de 1 à 50 ; s'il y en a davantage, les 50 premiers, et truncated.
truncated boolean no true Présent, et vrai, seulement si des problèmes ont été omis (problems en compte alors 50) ; absent sinon.

Undeclared fields: rejected (engine-emitted form, closed).

Abstention

« Pas de plan maintenant » (§7) : repli pour ce cycle, pas un échec.

Field Type Required Values Description (contract, French)
abstain boolean yes true
reason string no

Undeclared fields: ignored (optimizer-emitted form, open).

Plan

Plan par créneaux (§6).

Field Type Required Values Description (contract, French)
abstain boolean no false
planId string no
strategy string no Chaîne libre, informative.
computedAt string no instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
validUntil string | null no instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
slots [Slot] yes [] = abstention (empty-plan). Seul le créneau couvrant maintenant est exécuté.
diagnostics Diagnostics no

Undeclared fields: ignored (optimizer-emitted form, open).

ContextProblem

Un problème du contexte GetPlan (1.3) : où, et de quelle nature — jamais la valeur reçue.

Field Type Required Values Description (contract, French)
path string yes pattern ^params(\.[A-Za-z0-9_]+\|\[[0-9]+\])*$ Chemin du champ fautif depuis params : noms séparés par des points, indices de liste entre crochets (params.forecast.pv[3].from). Champ absent : son chemin attendu.
problem ContextProblemCode yes

Undeclared fields: rejected (engine-emitted form, closed).

Slot

Field Type Required Values Description (contract, French)
from string yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
to string yes instant with offset Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.
actions [Action] | null no Absent ou null = aucune action.
expected Expected no

Undeclared fields: ignored (optimizer-emitted form, open).

Diagnostics

Informatif : mode installateur et traces.

Field Type Required Values Description (contract, French)
solver string no
status string no optimal · feasible · best-so-far · infeasible-relaxed
gapPercent number no
computeMs number no ≥ 0
inputsUsed object no
inputsUsed.pv string no physics · hybrid · none

Undeclared fields: ignored (optimizer-emitted form, open).

Action

One of: SetpointAction · StateAction · ConstraintAction.

Expected

Trajectoire prévue : affichage et mesure d'écart, JAMAIS pour commander.

Field Type Required Values Description (contract, French)
gridImportW number no
gridExportW number no
batterySocPercent any no RÉSERVÉ (annexe F) : ignoré.

Undeclared fields: ignored (optimizer-emitted form, open).

SetpointAction

Field Type Required Values Description (contract, French)
loadId string yes ≥ 1 char. Charge visée : connue du contexte (règle unknown-load), une fois par créneau (duplicate-load).
reason string yes ≥ 1 char. ; pattern \S Texte français, OBLIGATOIRE et non vide (règle missing-reason). Traces et journal seulement, jamais vers l'app.
reasonCode ReasonCode no
reasonParams ReasonParams no
force any no INTERDIT sur le fil (§6) : ignoré, signalé une fois.
kind string yes "setpoint"
powerW number no ≥ 0 Consigne en watts (relay-router, etmvariableload ; ou borne).
currentA number no ≥ 0 Borne : courant (0 = suspendre).
phases enum no 1 · 3 Borne : phases visées ; absent = inchangé.

Undeclared fields: ignored (optimizer-emitted form, open).

At least one of: powerW, currentA.

StateAction

Field Type Required Values Description (contract, French)
loadId string yes ≥ 1 char. Charge visée : connue du contexte (règle unknown-load), une fois par créneau (duplicate-load).
reason string yes ≥ 1 char. ; pattern \S Texte français, OBLIGATOIRE et non vide (règle missing-reason). Traces et journal seulement, jamais vers l'app.
reasonCode ReasonCode no
reasonParams ReasonParams no
force any no INTERDIT sur le fil (§6) : ignoré, signalé une fois.
kind string yes "state"
state integer yes ≥ 1 ; ≤ 4 1 = verrouillage, 2 = normal, 3 = recommandation, 4 = forcé.

Undeclared fields: ignored (optimizer-emitted form, open).

ConstraintAction

RÉSERVÉ (annexe F) : forme décrite, toujours refusée (kind-mismatch).

Field Type Required Values Description (contract, French)
loadId string yes ≥ 1 char. Charge visée : connue du contexte (règle unknown-load), une fois par créneau (duplicate-load).
reason string yes ≥ 1 char. ; pattern \S Texte français, OBLIGATOIRE et non vide (règle missing-reason). Traces et journal seulement, jamais vers l'app.
reasonCode ReasonCode no
reasonParams ReasonParams no
force any no INTERDIT sur le fil (§6) : ignoré, signalé une fois.
kind string yes "constraint"
charge enum no allow · forbid
discharge enum no allow · forbid

Undeclared fields: ignored (optimizer-emitted form, open).

ReasonParams

Paramètres du motif : valeurs nombre, booléen ou code [A-Za-z]+ ; clés admises par code : x-etm-reason-params. Toute autre clé est SUPPRIMÉE avant l'app (filtrée, pas refusée). gridW (ECO_FLOOR_GRID, PRICE_SLOT, EV_DEADLINE — 1.7 pour les deux derniers) : la part RÉSEAU de l'action (W), telle que l'optimiseur la planifie ; le moteur la valide (nombre, 0 ≤ gridW ≤ puissance de l'action) et la republie, il ne la calcule jamais — hors bornes, elle est supprimée.

Type: map of number | boolean | string | null

Emittable reason codes

reasonCode Accepted reasonParams keys
SURPLUS_SETPOINT budgetW, setpointW, stepped
SURPLUS_INSUFFICIENT budgetW
BELOW_MIN_POWER budgetW, minPowerW, state
EV_DEADLINE gridW
SG_FORCED budgetW, estimatedW
SG_RECOMMENDED budgetW, estimatedW
SG_NORMAL budgetW
ECO_FLOOR_GRID gridW, atMaximum, remainingWh, targetWh, remainingS, regime, minAlwaysW, boundBy
PRICE_SLOT priceCtkWh, setpointW, gridW
OPTIMIZER_DECISION —
TARGET_NOT_MET missingWh, socAtDeparturePercent

UpdateLearned

Notification sent by the optimizer to the engine, with no answer, to pass on what it has learned about the loads. The engine receives and logs it, but does not use it yet: nothing is kept or sent back in the following contexts.

UpdateLearned — params

Estimations apprises de l'optimiseur (§8) — notification, sans id.

Envoyée par l'OPTIMISEUR, et seulement par lui (1.2) : sens inverse des deux autres, sans id, sans réponse. Reçue PAR UN OPTIMISEUR : notification ignorée ; requête avec id → -32601 (x-etm-message-errors). État du moteur : reçue, journalisée une fois, IGNORÉE — rien n'est persisté, le contenu n'est pas lu. Forme NON NORMÉE (1.2 à 1.4) : elle sera fixée avec la première stratégie qui apprend.

Field Type Required Values Description (contract, French)
loads [object] no Non normé (1.2 à 1.4) : intention §8 (learned + confidence par charge).

Fallback state machine

There is no separate heartbeat: a valid answer to GetPlan means the optimizer is alive. Failures are counted per request; after several consecutive failures, the optimizer is declared absent and the engine drives by its rules until the next valid plan. The app sees this state continuously (optimizerAlive, activeStrategy).

Machine de repli §7 (OptimizerStatus) : heartbeat implicite — une réponse valide à GetPlan = optimiseur vivant. Les échecs se comptent PAR REQUÊTE.

Consecutive failed requests before optimizerAlive = false: 2.

Situation (contract) optimizerAlive activeStrategy
réponse plan valide true optimizer
abstain, plan vide, aucun créneau courant inchangé rules (ce cycle)
plan expiré (validUntil dépassé) inchangé rules jusqu'au prochain plan valide
timeout / erreur / plan invalide sur deux requêtes consécutives false rules
socket absent / fermé / handshake refusé false rules
aucun endpoint configuré false rules
mode dégradé L2 (compteur muet > 90 s) inchangé none

Validation rules

The contract's JSON Schema states the shape. The engine then judges each answer against the context of its request, rule by rule, in the order below; the first that fails gives its code (fallbackCode, visible in the app).

Ce que le moteur refuse EN PLUS de la forme, dans l'ordre de ses contrôles (OptimizerPlan::valider, OptimizerClient::handleHandshakeReply). name = code du verdict. issue : abstention (repli ce cycle, pas un échec), expired, invalid (plan refusé en entier, compté comme échec), connection-refused (handshake). needs : ce qu'il faut connaître en plus de la réponse (la requête, le handshake).

# Rule Method Outcome fallbackCode lastErrorCode Counts as failure Also needs Schema catches it too What is rejected (contract)
1 abstain GetPlan abstention abstain — no — no result.abstain vaut true.
2 malformed-plan GetPlan invalid malformed-plan malformed-plan yes — yes slots absent ou non liste ; un créneau qui n'est pas un objet ; actions non liste.
3 empty-plan GetPlan abstention empty-plan — no — no slots est une liste vide.
4 bad-time GetPlan invalid bad-time bad-time yes — yes from/to illisibles ou sans décalage, ou from ≥ to ; validUntil illisible ou sans décalage.
5 slots-unordered GetPlan invalid slots-unordered slots-unordered yes — no un créneau commence avant la fin du précédent.
6 malformed-action GetPlan invalid malformed-action malformed-action yes — yes action qui n'est pas un objet, ou sans loadId (chaîne non vide).
7 unknown-load GetPlan invalid unknown-load unknown-load yes request no loadId absent des loads[] de la requête.
8 unknown-kind GetPlan invalid unknown-kind unknown-kind yes — yes kind hors ActionKind.
9 kind-mismatch GetPlan invalid kind-mismatch kind-mismatch yes request no kind différent de celui du mécanisme de la charge (setpoint : evcharger, relay-router, etmvariableload ; state : sg-ready ; constraint : aucun).
10 kind-not-announced GetPlan invalid kind-not-announced kind-not-announced yes handshake no capabilities.kinds annoncé au handshake et kind absent de la liste.
11 missing-reason GetPlan invalid missing-reason missing-reason yes — yes reason absent, non textuel, ou vide une fois les caractères de contrôle retirés.
12 bad-value GetPlan invalid bad-value bad-value yes request yes state absent ou hors 1-4 ; borne : currentA/powerW absents ou négatifs, phases hors {1, 3} ; charge en watts : powerW absent ou négatif.
13 duplicate-load GetPlan invalid duplicate-load duplicate-load yes — no deux actions pour la même charge dans un créneau.
14 expired GetPlan expired expired — no request no validUntil ≤ timestamp de la requête.
15 no-current-slot GetPlan abstention no-current-slot — no request no aucun créneau ne couvre le timestamp de la requête.
16 incomplete-slot GetPlan invalid incomplete-slot incomplete-slot yes request no une charge available de la requête n'a pas d'action dans le créneau courant (décision Q1).
17 handshake-refused Handshake connection-refused no-plan handshake-refused no — no réponse error, quel que soit son code (token refusé : -32001, jugé d'abord ; majeure incompatible : -32602, Handshake.errors) → le moteur ferme, nouvelle tentative au backoff.
18 invalid-handshake Handshake connection-refused no-plan invalid-handshake no — yes result non objet, protocolVersion absent ou vide, capabilities présent et non objet.
19 major-mismatch Handshake connection-refused no-plan major-mismatch no — no MAJEURE de protocolVersion (ce qui précède le premier point) différente de celle du moteur.

Tolerances

What the engine accepts beyond the contract. A conformant optimizer does not rely on it.

Ce que le moteur ACCEPTE au-delà du schéma — un optimiseur conforme ne s'en sert pas.

  • reasonCode absent ou hors ReasonCode : action acceptée, motif transmis sous OPTIMIZER_DECISION sans paramètres.
  • reasonParams : clé non admise pour le code (x-etm-reason-params) ou valeur refusée : clé supprimée, action acceptée.
  • planId, strategy : lus comme chaînes quel que soit leur type ; computedAt illisible : ignoré.
  • diagnostics, expected : non objets ignorés ; valeurs inconnues filtrées avant l'app.
  • abstain : toute valeur « vraie » au sens de QVariant::toBool (true, chaîne non vide autre que « false »/« 0 », nombre non nul).
  • champs inconnus (params et result) : ignorés (§9) ; force et champs réservés (annexe F) : ignorés et signalés une fois.
  • state : 3.0 accepté comme 3 (entier au sens JSON Schema).
  • error.data d'une réponse error (1.3) : jamais lu — un code problem inconnu, un data d'une autre forme (optimiseur 1.2) ou absent ne changent rien : l'erreur reste un échec rpc-error.
  • error.message (1.4) : jamais lu ni journalisé par le moteur (le code seul) — un message qui recopierait une valeur reçue ne change rien côté moteur ; c'est un écart de l'optimiseur, jugé par le validateur et la conformité.

Closed lists

Allowed values, regenerated from the engine's code.

ProtocolVersion

Version du protocole parlée par le moteur (GEN : OptimizerProtocol::ProtocolVersion).

1.8

Regenerated from the engine code: OptimizerProtocol::ProtocolVersion.

Trigger

Cause de la requête (§5.1). GEN : SocketScheduler::knownTriggers() — du moins au plus significatif.

cycle · forecast · config · load-change · intent

Regenerated from the engine code: SocketScheduler::knownTriggers().

Domain

Intention déclarée par l'installateur, jamais déduite du mécanisme, non lue par l'arbitre (§5.3). GEN : LoadConfig::knownDomains().

ecs · ev · heating · hvac · battery

Regenerated from the engine code: LoadConfig::knownDomains().

ActionKind

Type d'action (§6). GEN : OptimizerPlan::kinds(). constraint est RÉSERVÉ (annexe F) : reconnu par le validateur, toujours refusé (règle kind-mismatch) faute de mécanisme porteur.

setpoint · state · constraint

Regenerated from the engine code: OptimizerPlan::kinds().

ReasonCode

Codes de motif qu'un optimiseur peut émettre (§6, liste blanche). GEN : DecisionCode::optimizerEmittableCodes(). Clés de paramètres admises par code : x-etm-reason-params.

SURPLUS_SETPOINT · SURPLUS_INSUFFICIENT · BELOW_MIN_POWER · EV_DEADLINE · SG_FORCED · SG_RECOMMENDED · SG_NORMAL · ECO_FLOOR_GRID · PRICE_SLOT · OPTIMIZER_DECISION · TARGET_NOT_MET

Regenerated from the engine code: DecisionCode::optimizerEmittableCodes().

PriceInclude

Composante incluse dans le prix (§5.2). GEN : TariffConfig::includes().

energy · grid · taxes

Regenerated from the engine code: TariffConfig::includes().

FallbackCode

Côté app (NymeaEnergy.GetPlan.fallbackCode) : pourquoi l'optimiseur n'a pas commandé le cycle. Hors fil. GEN : SocketScheduler::knownFallbackCodes().

no-plan · abstain · empty-plan · no-current-slot · expired · malformed-plan · bad-time · slots-unordered · malformed-action · unknown-load · unknown-kind · kind-mismatch · kind-not-announced · missing-reason · bad-value · duplicate-load · incomplete-slot · no-shadow-slot

Regenerated from the engine code: SocketScheduler::knownFallbackCodes().

LastErrorCode

Côté app (NymeaEnergy.GetOptimizerStatus.lastErrorCode) : dernier code d'erreur vu (connexion, requête, plan). Hors fil. GEN : SocketScheduler::knownLastErrorCodes().

invalid-endpoint · token-too-short · connect-failed · closed-during-handshake · connection-lost · handshake-timeout · handshake-refused · invalid-handshake · major-mismatch · line-too-long · invalid-json · missing-id · unknown-id · timeout · rpc-error · invalid-response · disconnected · request-too-long · malformed-plan · bad-time · slots-unordered · malformed-action · unknown-load · unknown-kind · kind-mismatch · kind-not-announced · missing-reason · bad-value · duplicate-load · incomplete-slot

Regenerated from the engine code: SocketScheduler::knownLastErrorCodes().

Correction

temperature · ac-limit

ContextProblemCode

Nature d'un problème du contexte (1.3), liste fermée : missing (obligatoire absent), type (type faux), range (hors bornes), format (chaîne mal formée : instant, durée…), enum (valeur hors liste), constraint (règle entre champs, ordre des créneaux…). Un code inconnu est ignoré par le moteur (§9).

missing · type · range · format · enum · constraint