NymeaEnergy¶
Methods¶
NymeaEnergy.ClearLoadDerogation¶
CONTROL
Cancel a derogation before its term and restore the memorised charging mode. Returns EnergyErrorInvalidParameter if no derogation was running on that load.
Parameters:
| Field | Type | Notes |
|---|---|---|
loadId |
String |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.ClearLoadFault¶
CONTROL
Clear the fault latch of a controllable load (ECS-410). Deliberate operator action: the fault never clears by itself.
Parameters:
| Field | Type | Notes |
|---|---|---|
loadId |
String |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.GetAcquisitionTolerance¶
AUTH
Get the acquisition tolerance. This value will control how much solar surplus is required to start the charging.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
acquisitionTolerance |
Double |
NymeaEnergy.GetAvailableSpotMarketProviders¶
AUTH
Get the list of available spot market data providers.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
providers |
SpotMarketProviderInfo[] |
NymeaEnergy.GetBatteryLevelConsideration¶
AUTH
Get the battery level consideration. This value will control how much the energy storage is taking in account
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
batteryLevelConsideration |
Double |
NymeaEnergy.GetChargingInfos¶
AUTH
Get the charging info for all EV chargers, or for a single one when evChargerId is given. An unknown id yields an EMPTY list, never an error: every configured charger has an entry, so an empty list means 'no such charger' and nothing else.
Parameters:
| Field | Type | Notes |
|---|---|---|
evChargerId |
Uuid |
optional |
Returns:
| Field | Type | Notes |
|---|---|---|
chargingInfos |
ChargingInfo[] |
NymeaEnergy.GetChargingSchedules¶
AUTH
Get the planed charging schedules, and whether the L2 degraded mode is currently active (meter silent > 90s, planning suspended).
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
chargingSchedules |
ChargingSchedule[] | |
degradedMode |
Bool |
NymeaEnergy.GetEnergyRatios¶
AUTH
Get the current energy ratios (self-consumption / autonomy) in percent, derived from the energy manager's cumulative counters over the current local day. A rate field is omitted (never null) when not available (denominator <= 0).
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
measuredSince |
Uint |
|
autonomyRate |
Double |
optional |
selfConsumptionRate |
Double |
optional |
periodStartedAt |
Uint |
|
timeZone |
String |
NymeaEnergy.GetForecastSite¶
AUTH
Read which site's PV forecast is kept, and which sites COULD be. 'forecastSiteThingId' is omitted when none is designated - a NORMAL state, not a fault. 'candidateSiteThingIds' lists every site with at least one plane publishing a curve; it is what a configuration screen offers. When exactly one candidate exists and nothing has ever been chosen, the engine designates it by itself - designating is not CHOOSING when there is nothing to choose. NOTHING is ever designated automatically: the choice is persisted, and the day a second site appears it would look deliberate when nobody made it. 'fault' carries MISSING_FORECAST_SITE when planes publish but no site is designated - it is ABSENT when no site exists at all, since announcing a missing designation to an installation that has nothing to designate would be an unsatisfiable warning.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
candidateSiteThingIds |
Uuid[] |
|
acLimitW |
Uint |
optional |
fault |
String |
optional |
forecastSiteThingId |
Uuid |
optional |
NymeaEnergy.GetForecastSnapshot¶
AUTH
The CURRENT PV forecast, read straight from the channel - never from the stored table. GetPvForecast serves the TABLE (history, revisions, reproducible reads); this one serves the DECISION. An arbiter reading the table would read its own trace instead of its input: it would no longer measure, it would re-read itself. 'capturedAt' is when this reply was built. 'contentChangedAt' is when the current content FIRST APPEARED - and it is the one that matters: without it, a FROZEN provider reads as a stable forecast, which is the costliest form of 'silence that looks like a result' since whoever reads it decides to BUY. It is omitted when the store has never seen this content, rather than guessed. 'forecastPoints' is ABSENT when nothing is readable - never a curve of zeros; a missing forecast and a forecast of zero are different statements. 'fault' carries MISSING_FORECAST_SITE (nobody designated a site, and one exists) or FORECAST_PAYLOAD_REFUSED with its cause (the channel publishes something we cannot read). Two faults, two gestures: configure, or look at the provider. With a curve come 'corrections' (physical corrections applied, canonical order: 'temperature' by the provider, 'ac-limit' when the site has an AC limit; empty = raw GTI x kWp x PR; when planes disagree, only the corrections ALL of them received), 'perField' (one entry per summed plane: its thing 'id' and the 'corrections' it declared - where a divergence between planes is read), 'conversion' ('physics' - this engine has no other) and 'acLimitW' when an AC limit is configured: the curve is the sum of the planes CLIPPED to it. ALWAYS (ETM build), whatever the PV outcome: the GRID 'start' (instant), 'resolutionS' and 'steps' - the PV grid when a curve exists (first slot to last, holes included), otherwise hourly from local midnight today to local midnight after tomorrow - and on it, index by index: 'baseload' {model: profile|none, p50W: [W or null], quality} - consumption WITHOUT the controlled loads, median per local slot and day type over 28 days, 'none' with nulls under 7 covered days - and 'price' (null when no tariff is set) {currency, importCtkWh, exportCtkWh, includes, source: fixed|tou, knownUntil}. A slot straddling two tariff zones gets the time-weighted mean. NOTHING here is read by any decision.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
capturedAt |
String |
|
acLimitW |
Uint |
optional |
baseload |
{'model': 'String', 'o:quality': 'Object', 'p50W': ['Variant']} |
optional |
contentChangedAt |
String |
optional |
conversion |
String |
optional |
corrections |
String[] |
optional |
fault |
String |
optional |
faultParams |
Variant |
optional |
forecastPoints |
{'forecastWh': 'Double', 'targetAt': 'String'}[] |
optional |
issuedAt |
String |
optional |
model |
String |
optional |
perField |
{'corrections': ['String'], 'id': 'Uuid'}[] |
optional |
price |
Variant |
optional |
resolutionS |
Uint |
optional |
start |
String |
optional |
steps |
Uint |
optional |
NymeaEnergy.GetLoadConfig¶
AUTH
Get the configured controllable loads (etmvariableload).
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
loadConfigs |
LoadConfig[] |
NymeaEnergy.GetLoadTelemetry¶
AUTH
Get a snapshot of the arbitration runtime state: surplus budget, per-load allocation, availability, fault code, active lock (seconds remaining), mechanism payload and decision reason. Reason and fault are CODES with numeric params - never human-readable sentences: the client renders them in the user's language. Identical payload to the LoadTelemetryChanged notification. 'timestamp' is the end of the last arbitration cycle and is omitted while no cycle has run yet.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
degradedMode |
Bool |
|
loads |
{'allocatedW': 'Double', 'available': 'Bool', 'decision': {'code': 'String', 'o:level': 'String', 'params': 'Variant'}, 'levels': [{'counts': 'Variant', 'funding': 'String', 'level': 'String', 'targetW': 'Double'}], 'loadId': 'String', 'o:faultCode': 'String', 'o:lock': {'kind': 'String', 'remainingS': 'Int'}, 'o:measurement': {'o:powerW': 'Double', 'source': 'String'}, 'o:mechanism': {'kind': 'String', 'o:chargingEnabled': 'Bool', 'o:currentA': 'Double', 'o:estimatedPowerW': 'Double', 'o:maxPowerW': 'Double', 'o:maxStageW': 'Double', 'o:minPowerW': 'Double', 'o:percent': 'Double', 'o:phaseCount': 'Uint', 'o:pluggedIn': 'Bool', 'o:setpointW': 'Double', 'o:stageW': 'Double', 'o:stagesW': ['Double'], 'o:state': 'Int'}, 'o:temperatureC': 'Double'}[] |
|
budget |
{'allocatedW': 'Double', 'evReservedW': 'Double', 'recreditedW': 'Double', 'remainingW': 'Double', 'surplusW': 'Double'} |
optional |
derogationEnded |
{'cause': 'String', 'loadId': 'String', 'o:restoredMode': 'Int'}[] |
optional |
draw |
{'committedW': 'Double'} |
optional |
timestamp |
String |
optional |
NymeaEnergy.GetLockOnUnplug¶
AUTH
Get the lock on unplug setting.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
lockOnUnplug |
Bool |
NymeaEnergy.GetOptimizerProtocol¶
AUTH
The OpenRPC 1.3 document of the engine <-> optimizer protocol spoken by THIS engine (docs/etm-powersync-optimizer-protocol.openrpc.json, embedded at build time). protocolVersion: the version sent at handshake. schema: the document (methods Handshake, GetPlan, UpdateLearned; components.schemas; x-etm-* extensions for transport, fallback machine and semantic rules). No secret. Static for a given binary: no notification.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
protocolVersion |
String |
|
schema |
Object |
NymeaEnergy.GetOptimizerStatus¶
AUTH
State of the external-optimizer fallback machine (OPTIMIZER_PROTOCOL 7). optimizerExpected: an endpoint is configured. optimizerAlive: the optimizer answered with a valid plan and has not failed two consecutive requests nor lost its connection since. activeStrategy: optimizer | rules | none (none = degraded mode L2, planning suspended). The other fields are for the installer view; an unknown value is OMITTED, never 0. The token is never returned: tokenConfigured only says whether one is set. Same payload as OptimizerStatusChanged.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
activeStrategy |
String |
|
capabilities |
{'o:kinds': ['String'], 'o:maxHorizonH': 'Double', 'o:reasonCodes': 'Bool', 'o:resolutionS': 'Double', 'o:usesForecast': ['String']} |
optional |
consecutiveFailures |
Int |
optional |
lastErrorCode |
String |
optional |
lastPlanAt |
String |
optional |
name |
String |
optional |
protocolVersion |
String |
optional |
optimizerAlive |
Bool |
|
optimizerExpected |
Bool |
|
tokenConfigured |
Bool |
NymeaEnergy.GetOptimizerTrace¶
ADMIN
Decision traces (OPTIMIZER_PROTOCOL annex D): one NDJSON line per cycle, in a daily file (local time) etm-powersync-optimizer-trace-YYYY-MM-DD.ndjson under directory. They contain site measurements and stay on the box: export is manual only. enabled (default false), retentionDays (default 14, today included), maxBytesPerDay (cap of one daily file; beyond it nothing more is written until the next day).
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
directory |
String |
|
enabled |
Bool |
|
maxBytesPerDay |
Int |
|
retentionDays |
Int |
NymeaEnergy.GetPhasePowerLimit¶
AUTH
Get the phase power consumption limit. 0 if unset. This needs to be set in order for the smart charging to do anything.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
phasePowerLimit |
Uint |
NymeaEnergy.GetPlan¶
AUTH
The plan IN FORCE at the last planned cycle. Under an optimizer: the current slot with the power APPLIED by the adapters, then the following slots with the power REQUESTED (informative). Under the rule-based: one slot, strategy rules, and fallbackCode when an optimizer is configured but did not command this cycle. Reasons are codes and params only, never text. inForce is false, and nothing else is returned, before the first cycle and in degraded mode L2 (no plan in force). No notification: read it again on LoadTelemetryChanged or OptimizerStatusChanged.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
inForce |
Bool |
|
computedAt |
String |
optional |
diagnostics |
Variant |
optional |
fallbackCode |
String |
optional |
slots |
{'actions': [{'kind': 'String', 'loadId': 'String', 'o:reasonParams': 'Variant', 'o:state': 'Int', 'powerW': 'Double', 'reasonCode': 'String'}], 'from': 'String', 'o:expected': 'Variant', 'to': 'String'}[] |
optional |
strategy |
String |
optional |
validUntil |
String |
optional |
NymeaEnergy.GetPvForecast¶
AUTH
Read the stored PV production FORECAST for a window. This is a forecast, NEVER a measurement: the conversion ignores shading, soiling, module temperature and inverter clipping - all optimistic - so the curve is a CEILING, systematically above what will be produced. Hours with no forecast are ABSENT, never zero: a zero would read as 'we expect night'. 'knownAt' makes the read reproducible - it returns the curve as it was known at that instant. A revision exists only when the FORECAST CHANGED; the provider's run id does NOT identify the content (it comes from a domain that supplies none of the curve's values), so revisions are keyed on the content itself. 'firstSeenAt' is when this content first appeared - it ORDERS revisions; 'lastSeenAt' is the last time it was republished unchanged - FRESHNESS. Neither is an emission time, and no horizon may be computed from them. The provider blends two model domains, so the FIRST HOURS ARE FRESHER THAN THE REST - a single age cannot date the whole curve, which is why none is published per slot. And beware what a near horizon buys: it reduces the METEOROLOGICAL error, never the CONVERSION bias - shading, soiling, module temperature and inverter clipping are as wrong at three hours as at thirty-six, and all in the optimistic direction. 'Nearer forecast is more reliable' must NOT be shown as 'nearer figure is more accurate'. An UNREADABLE date ('from', 'to' or 'knownAt') is an ERROR, never a window: 'energyError' is EnergyErrorInvalidParameter, 'fault' is FORECAST_DATE_UNREADABLE with 'faultParams.fields' naming the parameters, and 'forecastPoints' is empty and MEANS NOTHING - read 'energyError' first. 'energyError' is EnergyErrorNoError on every successful read.
Parameters:
| Field | Type | Notes |
|---|---|---|
from |
String |
|
knownAt |
String |
optional |
to |
String |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError | |
forecastPoints |
{'firstSeenAt': 'String', 'forecastWh': 'Double', 'lastSeenAt': 'String', 'targetAt': 'String'}[] |
|
fault |
String |
optional |
faultParams |
Variant |
optional |
NymeaEnergy.GetSpotMarketConfiguration¶
AUTH
Get the current spotmarket configuration.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
available |
Bool |
|
enabled |
Bool |
|
providerId |
Uuid |
optional |
NymeaEnergy.GetSpotMarketScoreEntries¶
AUTH
Get the current score entries from the current spot market. If spot market is not enabled or not available, the list will be empty. The weighting of the available score entries goes from 0 (worst) to 1.0 (best).
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
spotMarketScoreEntries |
ScoreEntry[] |
NymeaEnergy.GetTariff¶
AUTH
The tariff entered by the installer. 'zones', 'exportCtkWh' and 'source' (fixed = one zone over 24 h, tou = several) are OMITTED when no tariff is set - never an empty tariff at 0. Ranges are LOCAL wall-clock times of the box, in 'timeZone' (IANA id, always returned): the phone may live in another zone. Prices are FULL prices paid, in c€/kWh incl. taxes ('includes'). Read by no decision.
Parameters:
No parameters.
Returns:
| Field | Type | Notes |
|---|---|---|
currency |
String |
|
includes |
String[] |
|
exportCtkWh |
Double |
optional |
source |
String |
optional |
zones |
{'label': 'String', 'priceCtkWh': 'Double', 'ranges': [{'from': 'String', 'to': 'String'}]}[] |
optional |
timeZone |
String |
NymeaEnergy.SetAcquisitionTolerance¶
CONFIGURE
Set the acquisition tolerance for the charging.
Parameters:
| Field | Type | Notes |
|---|---|---|
acquisitionTolerance |
Double |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetBatteryLevelConsideration¶
ADMIN
Set the battery level consideration for the charging.
Parameters:
| Field | Type | Notes |
|---|---|---|
batteryLevelConsideration |
Double |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetChargingInfo¶
CONTROL
Set the charging info for an EV charger. The given object REPLACES the stored one as a whole: a writable property omitted from the call is reset to its default (assignedCarId: none, chargingMode: ChargingModeNormal, endDateTime: none, repeatDays: none, targetPercentage: 80, spotMarketChargingEnabled: false, dailySpotMarketPercentage: 0); omitting a property does NOT keep its current value. Read the object with GetChargingInfos, change what you need, and send it back complete. Read-only properties (chargingState) are ignored.
Parameters:
| Field | Type | Notes |
|---|---|---|
chargingInfo |
ChargingInfo |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetForecastSite¶
CONFIGURE
Designate the site whose PV forecast is kept. ALL the PV planes under that site are SUMMED - not chosen between: a site's production is physically the sum of its planes, and the curve is superimposed on the MEASURED total. Keeping one plane would put the forecast systematically below the measurement, which reads as an under-performing installation. Planes from DIFFERENT runs are never summed: a partly refreshed roof published as the whole would be a chimera, so the engine waits for the next pass. Pass an empty id to keep no forecast at all. 'acLimitW' is the site's inverter AC limit in W, applied AFTER the sum of the planes. It is the ONE field that is not replaced: OMITTED = UNCHANGED (an older client that ignores it must not clear it each time it saves the site), null = CLEAR the limit, an integer = set it. Declared Variant because nymea refuses null on a Uint; anything but null or an integer is refused. Refused (EnergyErrorInvalidParameter, nothing changed) outside [100, 1000000] W or without a site. Designating no site clears the limit too: a limit has no object without a site.
Parameters:
| Field | Type | Notes |
|---|---|---|
acLimitW |
Variant |
optional |
forecastSiteThingId |
Uuid |
optional |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetLoadConfig¶
CONFIGURE
Replace the full set of controllable load configs. Rejected as a whole (energyError) if any entry is invalid; persisted and applied atomically.
Parameters:
| Field | Type | Notes |
|---|---|---|
loadConfigs |
{'adapter': 'String', 'enabled': 'Bool', 'id': 'String', 'label': 'String', 'mode': 'String', 'o:domain': 'String', 'o:maxPowerW': 'Uint', 'o:meterThingId': 'Uuid', 'o:minOffS': 'Uint', 'o:minOnS': 'Uint', 'o:minPowerW': 'Uint', 'o:needs': {'o:dailyDeadline': 'String', 'o:minEnergyWhPerDay': 'Uint'}, 'o:powerLevels': ['Uint'], 'o:progressUnmeasurableCause': 'String', 'o:rankOrigin': 'String', 'o:relays': [{'powerW': 'Uint', 'thingId': 'String'}], 'o:sensorThingId': 'Uuid', 'o:sgReady': {'o:minStateHoldS': 'Uint', 'o:states': [{'estimatedPowerW': 'Double', 'relays': ['String'], 'state': 'Uint'}]}, 'priority': 'Uint', 'r:progressMeasurable': 'Bool'}[] |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetLoadDerogation¶
CONTROL
Grant a DEROGATION on a load: it is served at its maximum, funded from the grid, ahead of every other eco need regardless of rank. It is NOT a mode - it overlays the current one and clears itself. 'durationS' is MANDATORY and bounded [60, 21600]: it is the safety net, and it stays armed even when a target is given, because a target relies on an instrument and an instrument can fall silent. 'targetWh' is optional energy delivered SINCE the grant - energy, never SoC. Draw authorisation and overload shedding still bound it. The previous charging mode is memorised and restored when it ends.
Parameters:
| Field | Type | Notes |
|---|---|---|
durationS |
Int |
|
loadId |
String |
|
targetWh |
Double |
optional |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetLockOnUnplug¶
CONTROL
Set the lock on unplug setting.
Parameters:
| Field | Type | Notes |
|---|---|---|
lockOnUnplug |
Bool |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetOptimizerEndpoint¶
ADMIN
Set the external-optimizer endpoint, persisted and applied immediately: unix:///path or tcp://host:port (IPv6 in brackets). An EMPTY string removes it (rule-based only). On refusal: EnergyErrorInvalidParameter, fault invalid-endpoint, and nothing is changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
endpoint |
String |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError | |
fault |
String |
optional |
NymeaEnergy.SetOptimizerToken¶
ADMIN
Set the shared secret sent to the optimizer at handshake. WRITE-ONLY: no method returns it (GetOptimizerStatus has tokenConfigured). Stored in its own file, mode 0600, never in energy.conf; used from the next (re)connection. An EMPTY string removes it. A string of printable bytes, no whitespace, at most 4096 bytes; on refusal: EnergyErrorInvalidParameter, fault token-refused, nothing is changed. Send ONLY the 'token' key: nymea logs, as a warning, the params of a call whose keys it rejects.
Parameters:
| Field | Type | Notes |
|---|---|---|
token |
String |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError | |
fault |
String |
optional |
NymeaEnergy.SetOptimizerTrace¶
ADMIN
Change the decision-trace setting, persisted and applied immediately. Each key is optional; an absent key is unchanged. enabled: bool. retentionDays: integer 1-365. maxBytesPerDay: integer 1048576-1073741824. On refusal: EnergyErrorInvalidParameter, fault invalid-trace-setting, and nothing is changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
enabled |
Bool |
optional |
maxBytesPerDay |
Int |
optional |
retentionDays |
Int |
optional |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError | |
fault |
String |
optional |
NymeaEnergy.SetPhasePowerLimit¶
ADMIN
Set the phase power consumption limit. This is the maximum allowed Ampere per phase. A value of 0 means unset. All smart charging will be disabled.
Parameters:
| Field | Type | Notes |
|---|---|---|
phasePowerLimit |
Uint |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError |
NymeaEnergy.SetSpotMarketConfiguration¶
CONFIGURE
Set the current spotmarket configuration. If enabled, the provideId must be valid. You can get the available providers using GetAvailableSpotMarketProviders. [ETM] The shipped build compiles NO spot market provider (no outbound network flow): enabling is then refused with EnergyErrorInvalidParameter and 'fault' SPOT_MARKET_NOT_IN_BUILD - a code, never a sentence. Disabling is always accepted.
Parameters:
| Field | Type | Notes |
|---|---|---|
enabled |
Bool |
|
providerId |
Uuid |
optional |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError | |
fault |
String |
optional |
NymeaEnergy.SetTariff¶
CONFIGURE
Replace the tariff, effective immediately and persisted. One zone covering 00:00-24:00 is a single tariff; several zones are a time-of-use tariff, each with one or more LOCAL ranges [from, to) - a range may cross midnight (22:00-06:00). The ranges must cover the 24 h with NO gap and NO overlap. 'priceCtkWh' >= 0, in c€/kWh incl. taxes (NOT €/kWh). 'exportCtkWh' is the resale price, 0 when omitted. An EMPTY 'zones' clears the tariff. On refusal: EnergyErrorInvalidParameter, 'fault' TARIFF_REFUSED and 'faultParams' {cause, zone?, range?, at?, zones?} - codes and indexes, never a sentence - and NOTHING is changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
exportCtkWh |
Double |
optional |
zones |
{'label': 'String', 'priceCtkWh': 'Double', 'ranges': [{'from': 'String', 'to': 'String'}]}[] |
Returns:
| Field | Type | Notes |
|---|---|---|
energyError |
EnergyError | |
fault |
String |
optional |
faultParams |
Variant |
optional |
Notifications¶
NymeaEnergy.AcquisitionToleranceChanged¶
Emitted whenever the acquisition tolerance changes.
Parameters:
| Field | Type | Notes |
|---|---|---|
acquisitionTolerance |
Double |
NymeaEnergy.BatteryLevelConsiderationChanged¶
Emitted whenever the battery level consideration changes.
Parameters:
| Field | Type | Notes |
|---|---|---|
batteryLevelConsideration |
Double |
NymeaEnergy.ChargingInfoAdded¶
Emitted whenever a charging info is added.
Parameters:
| Field | Type | Notes |
|---|---|---|
chargingInfo |
ChargingInfo |
NymeaEnergy.ChargingInfoChanged¶
Emitted whenever a charging info changes.
Parameters:
| Field | Type | Notes |
|---|---|---|
chargingInfo |
ChargingInfo |
NymeaEnergy.ChargingInfoRemoved¶
Emitted whenever a charging info is removed.
Parameters:
| Field | Type | Notes |
|---|---|---|
evChargerThingId |
Uuid |
NymeaEnergy.ChargingSchedulesChanged¶
Emitted whenever the planed charging schedules have changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
chargingSchedules |
ChargingSchedule[] | |
degradedMode |
Bool |
optional |
NymeaEnergy.EnergyRatiosChanged¶
Emitted whenever the energy ratios (self-consumption / autonomy) change. A rate field is omitted (never null) when not available.
Parameters:
| Field | Type | Notes |
|---|---|---|
measuredSince |
Uint |
|
autonomyRate |
Double |
optional |
selfConsumptionRate |
Double |
optional |
periodStartedAt |
Uint |
|
timeZone |
String |
NymeaEnergy.LoadConfigChanged¶
Emitted whenever the controllable load configuration changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
loadConfigs |
LoadConfig[] |
NymeaEnergy.LoadTelemetryChanged¶
Emitted whenever the arbitration runtime state changed significantly, and periodically (heartbeat) even when unchanged, so that a frozen arbitrator is detectable by a timestamp that stops advancing. Same payload as GetLoadTelemetry.
Parameters:
| Field | Type | Notes |
|---|---|---|
degradedMode |
Bool |
|
loads |
{'allocatedW': 'Double', 'available': 'Bool', 'decision': {'code': 'String', 'o:level': 'String', 'params': 'Variant'}, 'levels': [{'counts': 'Variant', 'funding': 'String', 'level': 'String', 'targetW': 'Double'}], 'loadId': 'String', 'o:faultCode': 'String', 'o:lock': {'kind': 'String', 'remainingS': 'Int'}, 'o:measurement': {'o:powerW': 'Double', 'source': 'String'}, 'o:mechanism': {'kind': 'String', 'o:chargingEnabled': 'Bool', 'o:currentA': 'Double', 'o:estimatedPowerW': 'Double', 'o:maxPowerW': 'Double', 'o:maxStageW': 'Double', 'o:minPowerW': 'Double', 'o:percent': 'Double', 'o:phaseCount': 'Uint', 'o:pluggedIn': 'Bool', 'o:setpointW': 'Double', 'o:stageW': 'Double', 'o:stagesW': ['Double'], 'o:state': 'Int'}, 'o:temperatureC': 'Double'}[] |
|
budget |
{'allocatedW': 'Double', 'evReservedW': 'Double', 'recreditedW': 'Double', 'remainingW': 'Double', 'surplusW': 'Double'} |
optional |
derogationEnded |
{'cause': 'String', 'loadId': 'String', 'o:restoredMode': 'Int'}[] |
optional |
draw |
{'committedW': 'Double'} |
optional |
timestamp |
String |
optional |
NymeaEnergy.LockOnUnplugChanged¶
Emitted whenever the lock on unplug setting changes.
Parameters:
| Field | Type | Notes |
|---|---|---|
lockOnUnplug |
Bool |
NymeaEnergy.OptimizerStatusChanged¶
Emitted at each transition of the optimizer fallback machine: optimizerExpected, optimizerAlive or activeStrategy changed. Not emitted every cycle. Same payload as GetOptimizerStatus.
Parameters:
| Field | Type | Notes |
|---|---|---|
activeStrategy |
String |
|
capabilities |
{'o:kinds': ['String'], 'o:maxHorizonH': 'Double', 'o:reasonCodes': 'Bool', 'o:resolutionS': 'Double', 'o:usesForecast': ['String']} |
optional |
consecutiveFailures |
Int |
optional |
lastErrorCode |
String |
optional |
lastPlanAt |
String |
optional |
name |
String |
optional |
protocolVersion |
String |
optional |
optimizerAlive |
Bool |
|
optimizerExpected |
Bool |
|
tokenConfigured |
Bool |
NymeaEnergy.PhasePowerLimitChanged¶
Emitted whenever the phase power limit configuration changes.
Parameters:
| Field | Type | Notes |
|---|---|---|
phasePowerLimit |
Uint |
NymeaEnergy.SpotMarketConfigurationChanged¶
Emitted whenever a spot market configuration has changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
available |
Bool |
|
enabled |
Bool |
|
providerId |
Uuid |
optional |
NymeaEnergy.SpotMarketScoreEntriesChanged¶
Emitted whenever the score entries of the current spot market provider changed. The weighting of the available score entries goes from 0 (worst) to 1.0 (best).
Parameters:
| Field | Type | Notes |
|---|---|---|
spotMarketScoreEntries |
ScoreEntry[] |
NymeaEnergy.SpotMarketStatusChanged¶
Emitted whenever the spot market manager status changed.
Parameters:
| Field | Type | Notes |
|---|---|---|
available |
Bool |
|
enabled |
Bool |
Since 1.15.2+etm80 and 1.15.2+etm81 — not yet in the introspection above¶
Written from the engine contract, not generated
The reference above is generated from a box introspection (JSONRPC.Introspect) taken on
an older engine. The methods and notifications below were added in 1.15.2+etm80 and
1.15.2+etm81; they are written here from the engine's interface contract (INTERFACE.md),
with the same permissions and JSON shapes. This section goes away when the reference is
regenerated from a box running 1.15.2+etm81 or later.
NymeaEnergy.GetEvSolarCoverage¶
AUTH · since 1.15.2+etm80
Get the minimum solar coverage of EV chargers in Auto mode (ChargingModeEco), in percent.
One setting for all chargers. It is the same quantity as acquisitionTolerance, in percent:
evSolarCoveragePercent = acquisitionTolerance × 100. Outside off-peak hours: 100 = surplus
only (the charger starts when the surplus covers its minimum); 0 = the minimum is always taken
from the grid (ECO_FLOOR_GRID), surplus added on top; in between = the charger starts when the
surplus covers that share of its minimum and draws the rest from the grid (EV_GRID_START),
holds while the share is covered and stops below it; within 30 min after a stop, restarting
requires 10 points more. During off-peak hours: no effect, a charger in Auto charges at full power
(EV_OFF_PEAK_FULL_POWER).
Parameters: No parameters.
Returns:
NymeaEnergy.SetEvSolarCoverage¶
CONFIGURE · since 1.15.2+etm80
Set the minimum solar coverage of EV chargers in Auto mode. Same permission as
SetAcquisitionTolerance.
Parameters:
| Field | Notes |
|---|---|
evSolarCoveragePercent |
Integer from 0 to 100 inclusive. Above, or negative: EnergyErrorInvalidParameter, and nothing changes. |
Returns:
Persisted under both evSolarCoveragePercent and acquisitionTolerance. Notified by
EvSolarCoverageChanged and AcquisitionToleranceChanged: writing either setting notifies
both.
Value on the first start of 1.15.2+etm80 (written once, the rule does not replay):
| Before etm80 | Coverage kept |
|---|---|
| empty energy configuration (new box) | 100 |
other keys, no acquisitionTolerance |
50 (the former default, 0.5) |
acquisitionTolerance = t > 0 |
t × 100 (at least 1) |
acquisitionTolerance = 0 |
100 (a zero tolerance never started a charger from the grid: it already meant surplus only) |
evSolarCoveragePercent present (0–100) |
that value |
NymeaEnergy.GetEvManualCharging¶
AUTH · since 1.15.2+etm81
Get the Manual switch of each EV charger.
Parameters: No parameters.
Returns:
A charger whose switch has never been set is absent from the list: its
ChargingModeNormal keeps the former behaviour (stored manual settings) until it is first
unplugged.
NymeaEnergy.SetEvManualCharging¶
CONTROL · since 1.15.2+etm81
Set the Manual switch of an EV charger, and put it in ChargingModeNormal ("Manuel") if it is
not already; a running derogation then ends (modeChanged).
Parameters:
| Field | Notes |
|---|---|
evChargerId |
Uuid of the charger |
enabled |
Bool. true: full power at any time (current maximum, phase limit and its margin, draw cap; as many phases as the charger and the installation allow; overload protection has the last word), published in loads[] with decision EV_MANUAL_FULL_POWER. false: the charger is stopped at once (a user action: the on/off lock does not hold it) and leaves the arbitration (absent from loads[]). |
Returns:
Persisted across restarts. On unplugging, a charger in ChargingModeNormal returns by
itself to ChargingModeEco ("Auto") and its switch to false, unless lockOnUnplug is set. A
charger found unplugged in ChargingModeNormal when nymead starts is treated as unplugged (the
car left while it was stopped); ChargingInfoChanged and EvManualChargingChanged are
notified. A time-limited forcing remains SetLoadDerogation.
New notifications¶
NymeaEnergy.EvSolarCoverageChanged¶
Since 1.15.2+etm80. Emitted when the minimum solar coverage changes (also when
acquisitionTolerance is written).
NymeaEnergy.EvManualChargingChanged¶
Since 1.15.2+etm81. Emitted when the Manual switch of a charger changes, including the return
to Auto on unplugging. Same entry as in GetEvManualCharging.
Related changes in the telemetry¶
ChargingMode: see the note at the top of the types page.- Decision codes
EV_MANUAL_FULL_POWER(gridW,maxW,phases,o:boundBy;1.15.2+etm81) andEV_NOT_DRAWING(commandedW,since,plannedCode;1.15.2+etm80): the charger is commanded on and the car has drawn nothing for 120 s, seen by all sources; the command is unchanged.EV_OFF_PEAK_FULL_POWERis also emitted in Auto mode since1.15.2+etm80. mechanismof anevchargerload:chargingEnabled= charging allowed (since1.15.2+etm81; before: "the car is charging"),charging= the car is charging (1.15.2+etm81).