nymea-energy-plugin-nymea est un Energy Plugin pour la plateforme nymea. Il ne crée pas lui-même des appareils (Things) — il orchestre les appareils existants (chargeurs VE, compteurs d'énergie, véhicules électriques, stockages) pour offrir des fonctionnalités avancées de gestion d'énergie :
Fonctionnalité
Description
Smart Charging
Optimisation de la charge VE selon le surplus solaire, le tarif spot, ou une heure cible
Spot Market Charging
Planification aux heures les moins chères (aWATTar API — Autriche & Allemagne)
Overload Protection
Limitation automatique du courant pour ne pas dépasser la limite de puissance par phase
API JSON-RPC
Namespace NymeaEnergy (v0–8) pour le contrôle à distance par les applications
Protocoles utilisés
Protocole
Direction
Usage
JSON-RPC 2.0 sur WebSocket
Bidirectionnel
API principale : apps clients ↔ nymea
HTTP REST
Sortant
Récupération des prix spot aWATTar (toutes les 60 s)
IntegrationPlugin EnergyPlugin (ce plugin)
│ │
▼ ▼
setupThing() init() uniquement
thingRemoved() Écoute ThingManager
executeAction() Orchestre les Things
→ Crée des Things → Utilise des Things
créées ailleurs
Rappel architectural : ce plugin Energy ne définit pas ses propres ThingClasses.
Il interagit avec des Things créées par des plugins d'intégration qui implémentent les
interfaces nymea : evcharger, energymeter, electricvehicle, energystorage.
Le plugin mock de test (a45e07fc-6ccc-40af-b7ad-bac4a003e775) simule ces appareils.
Identifiants du plugin mock de test
Champ
Valeur
Plugin ID
a45e07fc-6ccc-40af-b7ad-bac4a003e775
Vendor ID
2062d64d-3232-433c-88bc-0d33c0ba2ba6
Vendor Name
nymea
ThingClass : Meter (Compteur d'énergie)
Champ
Valeur
ID
2721a051-6e12-471a-baba-21d87c4cebc9
Interfaces
energymeter, connectable
Param de configuration
Nom
UUID
Type
Défaut
port
7abcc8a1-08b1-45bc-9116-10f9848359f9
uint
6655
States
Nom
UUID
Type
Unité
Writable
Défaut
connected
3b393e45-594d-436a-bbd3-1f9b18ad9cfe
bool
—
—
false
voltagePhaseA
db018146-0441-4dc0-9834-6d43ebaf8311
double
Volt
—
230
voltagePhaseB
f0bae0af-2cde-4615-a36b-c81d7b233ebe
double
Volt
—
230
voltagePhaseC
fb76f2a8-0ace-4655-b368-1508843a15c6
double
Volt
—
230
currentPhaseA
00668c48-8b12-449a-907b-6744d65b021e
double
Ampere
—
0
currentPhaseB
6cd08b22-3a54-43a8-b828-b6ebb49678bb
double
Ampere
—
0
currentPhaseC
c9e196ec-0b59-43df-9ca6-4e318a63bf0f
double
Ampere
—
0
currentPower
f0490dd9-79ac-41ff-a952-083ed683687d
double
Watt
—
0
currentPowerPhaseA
ae450e65-2bbd-4054-84d6-b8f766b3d7cf
double
Watt
—
0
currentPowerPhaseB
dde0c5cf-9ce7-4e0d-979c-56d52d31eb25
double
Watt
—
0
currentPowerPhaseC
cfdc65bf-8e5a-40dd-acf3-79f3b86fd808
double
Watt
—
0
totalEnergyConsumed
8945c576-1e13-4611-adc8-4123b18d3a70
double
kWh
—
0
totalEnergyProduced
0420b758-e77f-4cf5-a30b-a6e1235b1efd
double
kWh
—
0
originalPower(sim)
e9776745-6f43-408d-9a4c-e5d74c711800
double
Watt
oui
0
ThingClass : Charger (Chargeur VE)
Champ
Valeur
ID
5a3ae99f-c7da-46df-9104-f477be4606b7
Interfaces
evcharger, smartmeterconsumer, connectable
Params de configuration
Nom
UUID
Type
Valeurs possibles
Défaut
port
652624a2-8f9a-4bc3-b34f-5e3492af4d30
uint
—
6656
phases
facd5c76-d15e-4e29-9929-5e1764ae05dc
QString
A / B / C / AB / BC / AC / ABC
"A"
maxChargingCurrentUpperLimit
234c6676-1ec0-4eff-bed0-ecee7ce82074
double
Ampere
32
States
Nom
UUID
Type
Unité
Writable
Min
Max
Défaut
connected
6c18e134-0420-41b3-974c-869b5e7125e4
bool
—
—
—
—
false
power
13672543-9344-4d55-afd6-6393ae052f18
bool
—
oui
—
—
true
maxChargingCurrent
e7566b5b-8258-486e-b0ed-42a1bee332d9
uint
A
oui
6
32
6
pluggedIn
13f8f008-aa70-4772-9fb8-81a9674dd6ad
bool
—
—
—
—
false
charging
63879844-6342-45ed-8e97-276e0f3092e5
bool
—
—
—
—
false
phaseCount
728aa4b2-0c90-40da-9a46-6f07ab6a1497
uint
—
—
1
3
1
usedPhases
cc3abc60-42e1-421d-b32e-37c2c9a113a3
QString
A…ABC
—
—
—
"A"
currentPower
89d5bab8-3fad-41e4-a3cb-55cd673bbb6c
double
W
—
—
—
0
totalEnergyConsumed
aadf7384-5953-48b3-aedc-5c3835a61639
double
kWh
—
—
—
0
voltagePhaseA/B/C
9eb201d2… / 06be3d4e… / e327de62…
double
V
—
—
—
230
currentPhaseA/B/C
025298dc… / ed7ee826… / 7ab9b93a…
double
A
—
—
—
0
currentPowerPhaseA/B/C
09e9a514… / 4f27a8f1… / 859d3a00…
double
W
—
—
—
0
Actions
Nom
UUID
Description
update
924174ed-e2ed-4d28-b2de-750cf01e41e3
Mise à jour manuelle des états (test)
ThingClass : ChargerPhaseSwitching (Chargeur avec commutation de phases)
Champ
Valeur
ID
9208d9f0-280c-469d-a145-106f3277470c
Interfaces
evcharger, smartmeterconsumer, connectable
Identique à Charger, avec un state supplémentaire :
State
UUID
Type
Valeurs
Writable
desiredPhaseCount
b3c4618a-223f-4c97-80e8-04a2fb490083
uint
1, 3
oui
ThingClass : SimpleCharger (Chargeur sans mesure)
Champ
Valeur
ID
29bcf255-b654-4764-be92-399bc26fe7c3
Interfaces
evcharger, connectable
States
connected (bool), power (bool, writable), maxChargingCurrent (uint 6–32 A, writable)
// Côté app : abonnement (fait une seule fois après auth)
{"id":5,"method":"JSONRPC.SetNotificationStatus","params":{"namespaces":["NymeaEnergy","Integrations"]}}// Réception asynchrone depuis nymea (aucun id de requête) :
{"notification":"NymeaEnergy.ChargingInfoChanged","params":{"chargingInfo":{"evChargerId":"f1e2d3c4-...","chargingMode":"ChargingModeEcoWithTargetTime","chargingState":"ChargingStateSpotMarketCharging","targetPercentage":80}}}// Autre exemple — nouveaux prix spot reçus :
{"notification":"NymeaEnergy.SpotMarketScoreEntriesChanged","params":{"spotMarketScoreEntries":[{"startDateTime":"2026-02-24T02:00:00","endDateTime":"2026-02-24T03:00:00","value":48.5,"weighting":0.92}]}}
8.4 Exemples Dart/Flutter (etm_powersync_app)
Les fichiers complets se trouvent dans integration_app_examples/ :
Fichier
Contenu
nymea_client.dart
Classe NymeaClient : connexion WS, auth, toutes les méthodes NymeaEnergy.*, streams de notifications
voidEnergyPluginNymea::init(){EnergyManagerConfiguration*configuration=newEnergyManagerConfiguration(this);QNetworkAccessManager*networkManager=newQNetworkAccessManager(this);SpotMarketManager*spotMarketManager=newSpotMarketManager(networkManager,this);SmartChargingManager*chargingManager=newSmartChargingManager(energyManager(),thingManager(),spotMarketManager,configuration,this);// [NOUVEAU]
HeatPumpManager*heatPumpManager=newHeatPumpManager(energyManager(),thingManager(),this);EnergyPriorityManager*priorityManager=newEnergyPriorityManager(energyManager(),thingManager(),this);// Handler étendu — version 9
jsonRpcServer()->registerExperienceHandler(newNymeaEnergyJsonHandler(spotMarketManager,chargingManager,heatPumpManager,priorityManager,this),0,9);}
9.8 Exemples d'utilisation depuis l'app (extension)
Contrôler une pompe à chaleur
// Passer en mode chauffage à 22°C
{"id":20,"method":"NymeaEnergy.SetHeatPumpMode","params":{"thingId":"<uuid-pac>","mode":"heating"},"token":"..."}{"id":21,"method":"NymeaEnergy.SetHeatPumpTargetTemperature","params":{"thingId":"<uuid-pac>","targetTemperature":22.0},"token":"..."}
// Définir la puissance totale disponible (3 x 16A x 230V ≈ 11 kW)
{"id":23,"method":"NymeaEnergy.SetTotalAvailablePower","params":{"totalAvailablePower":11040},"token":"..."}// Mettre le chargeur VE en priorité basse
{"id":24,"method":"NymeaEnergy.SetLoadPriority","params":{"thingId":"<uuid-chargeur>","priority":"LoadPriorityLow"},"token":"..."}// Mettre la PAC en priorité critique (ne jamais couper)
{"id":25,"method":"NymeaEnergy.SetLoadPriority","params":{"thingId":"<uuid-pac>","priority":"LoadPriorityCritical"},"token":"..."}
Documentation mise à jour le 2026-02-23 — Branche : nymea-energy-plugin-etmSections générées : analyse du code source, intégration app, plan d'extension ETM
ManualStrategy (strategyId = "manual") est la stratégie de niveau Community.
Elle donne à l'utilisateur un contrôle total : chaque créneau horaire est piloté
par une ManualSlotConfig explicitement définie. Aucune optimisation automatique.
Cas d'usage typique : utilisateur technique qui sait exactement quand et à quelle
puissance charger son VE, sans déléguer la décision à un algorithme.
11.2 Comportement par cas
Situation
Résultat
decisionRules
Slot dans une config active
Allocations appliquées exactement
["ManualSlot"]
Slot sans config
Charges inflexibles/critiques uniquement
["ManualDefault"] ou ["CriticalHeating"]
Config existante mais expirée
Charges critiques uniquement
["ExpiredSlot"]
Slot en override manuel
Préservé tel quel
["ManualOverride"]
Invariant : decisionReason n'est jamais vide (contrat ISchedulingStrategy).
11.3 Type ManualSlotConfig
structManualSlotConfig{QDateTimestart;QDateTimeend;QMap<LoadSource,double>powerAllocations;// "ev"→2000W, "battery"→1000W, ...
QStringlabel;// affiché dans l'UI, ex. "Recharge VE nuit"
boolrepeating;// si true : récurrence hebdomadaire (même jour/heure)
QDateTimeexpiresAt;// optionnel — ignoré après cette date
};
Pour les slots répétables (repeating=true) : la récurrence est calculée en
minutes-de-semaine (jour_semaine × 1440 + heure × 60 + minute), ce qui gère
correctement les slots overnight (ex. Lun 22:00 → Mar 06:00).
11.4 JSON-RPC — NymeaEnergy v11
GetManualSlots
→{}←{"slots":[{ManualSlotConfig},...]}
SetManualSlot
→{"start":"2026-02-24T22:00:00.000Z","end":"2026-02-25T06:00:00.000Z","label":"Recharge VE nuit","repeating":false,"expiresAt":"2026-03-01T00:00:00.000Z","allocations":{"ev":2000,"battery":1000,"heatpump":0,"dhw":0}}←{"energyError":"EnergyErrorNoError"}
{"slot":{/*ManualSlotConfig*/},"appliedAllocations":{"ev":2000,"battery":1000,"heatpump":0,"dhw":0,"feedin":0},"reason":"Créneau manuel 'Recharge VE nuit' activé"}
Chargement : au démarrage, dans SchedulerManager::registerStrategy() lorsque
ManualStrategy est enregistrée. Les slots expirés sont ignorés à la lecture.
Sauvegarde : à chaque SetManualSlot / RemoveManualSlot / ClearManualSlots.
11.6 Guide d'intégration — créneau EV hebdomadaire
L'Installer Setup permet à un installateur de mapper des rôles énergétiques
(EVCharger, DHW, HeatPump, Battery, SolarMeter, GridMeter) à des Things nymea concrètes.
Le LoadAdapterRegistry crée ensuite l'adaptateur approprié (relay, SG-Ready, evcharger, battery)
et transmet les consignes du Scheduler au matériel réel.
Flux en 3 étapes :
Activer le rôle → SetRoleEnabled(role, true)
Choisir la Thing → AssignThingToRole(role, thingId)
Tester la connexion → TestRoleConnection(role) → notification ConnectionTestResult
12.2 Tableau de compatibilité (rôle → interfaces requises)
{"method":"NymeaEnergy.TestRoleConnection","params":{"role":"DHW"}}// Notification:
{"notification":"NymeaEnergy.ConnectionTestResult","params":{"role":"DHW","success":true,"message":"Connection test OK"}}
12.5 Notifications push
Notification
Payload
Déclencheur
SetupStatusChanged
{ setupStatus }
Assignment, enable, reachability
ConnectionTestResult
{ role, success, message }
Fin de TestRoleConnection
ThingBecameCompatible
{ role, thing }
Nouvelle Thing ajoutée dans nymea
12.6 Gestion des erreurs — Thing disparue
Si une Thing assignée disparaît au redémarrage du daemon :
L'entrée dans adapters.conf est conservée
RoleStatus.reachable = false, lastError = "Thing not found: <uuid>"
SetupStatus.allEnabledRolesOk = false
Notification SetupStatusChanged émise avec l'erreur
Dès que la Thing réapparaît (ThingManager::thingAdded), notification ThingBecameCompatible
12.7 Exemple complet — EV charger hebdomadaire via Installer Setup
// 1. Activer le rôle
{"method":"NymeaEnergy.SetRoleEnabled","params":{"role":"EVCharger","enabled":true}}// 2. Lister les Things compatibles
{"method":"NymeaEnergy.GetCompatibleThings","params":{"role":"EVCharger"}}// 3. Assigner la Thing choisie
{"method":"NymeaEnergy.AssignThingToRole","params":{"role":"EVCharger","thingId":"…uuid…","params":{"phases":1}}}// 4. Tester
{"method":"NymeaEnergy.TestRoleConnection","params":{"role":"EVCharger"}}// → ConnectionTestResult { "success": true, "message": "EV charger connected" }
// 5. Configurer un créneau manuel EV
{"method":"NymeaEnergy.SetManualSlot","params":{"start":"2026-02-23T22:00:00.000Z","end":"2026-02-24T06:00:00.000Z","label":"Recharge hebdo VE","repeating":true,"allocations":{"ev":2000}}}
12.8 Persistance
Les assignements sont sauvegardés dans :
NymeaSettings::settingsPath() + "/adapters.conf"
Format INI, identique à scheduler.conf. Chargés automatiquement au démarrage du daemon.
Section 12 ajoutée le 2026-02-24 — Installer Setup LoadAdapterRegistry v12