@enyo-energy/energy-app-sdk 1.45.0 → 1.47.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -0
- package/dist/cjs/energy-app-model-feature.enum.cjs +2 -0
- package/dist/cjs/energy-app-model-feature.enum.d.cts +2 -0
- package/dist/cjs/implementations/storage/battery-charge-now-validators.cjs +81 -0
- package/dist/cjs/implementations/storage/battery-charge-now-validators.d.cts +57 -0
- package/dist/cjs/index.cjs +1 -0
- package/dist/cjs/index.d.cts +1 -0
- package/dist/cjs/integrations/inverter-integration-energy-app.cjs +20 -0
- package/dist/cjs/integrations/inverter-integration-energy-app.d.cts +9 -1
- package/dist/cjs/types/enyo-charger-appliance.cjs +13 -0
- package/dist/cjs/types/enyo-charger-appliance.d.cts +29 -2
- package/dist/cjs/types/enyo-data-bus-value.cjs +89 -1
- package/dist/cjs/types/enyo-data-bus-value.d.cts +245 -0
- package/dist/cjs/types/enyo-energy-manager.cjs +10 -0
- package/dist/cjs/types/enyo-energy-manager.d.cts +10 -0
- package/dist/cjs/types/enyo-inverter-appliance.cjs +6 -0
- package/dist/cjs/types/enyo-inverter-appliance.d.cts +7 -1
- package/dist/cjs/types/enyo-settings.d.cts +37 -0
- package/dist/cjs/version.cjs +1 -1
- package/dist/cjs/version.d.cts +1 -1
- package/dist/energy-app-model-feature.enum.d.ts +2 -0
- package/dist/energy-app-model-feature.enum.js +2 -0
- package/dist/implementations/storage/battery-charge-now-validators.d.ts +57 -0
- package/dist/implementations/storage/battery-charge-now-validators.js +76 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/integrations/inverter-integration-energy-app.d.ts +9 -1
- package/dist/integrations/inverter-integration-energy-app.js +20 -0
- package/dist/types/enyo-charger-appliance.d.ts +29 -2
- package/dist/types/enyo-charger-appliance.js +13 -0
- package/dist/types/enyo-data-bus-value.d.ts +245 -0
- package/dist/types/enyo-data-bus-value.js +88 -0
- package/dist/types/enyo-energy-manager.d.ts +10 -0
- package/dist/types/enyo-energy-manager.js +10 -0
- package/dist/types/enyo-inverter-appliance.d.ts +7 -1
- package/dist/types/enyo-inverter-appliance.js +6 -0
- package/dist/types/enyo-settings.d.ts +37 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
|
@@ -1288,6 +1288,22 @@ export declare enum EnyoInverterStateEnum {
|
|
|
1288
1288
|
Fault = "fault",
|
|
1289
1289
|
Standby = "standby"
|
|
1290
1290
|
}
|
|
1291
|
+
/**
|
|
1292
|
+
* Whether the public grid is available at the site, as detected by an
|
|
1293
|
+
* appliance declaring
|
|
1294
|
+
* {@link EnyoInverterApplianceAvailableFeaturesEnum.GridOutageDetection}.
|
|
1295
|
+
* Reported on the data bus via {@link EnyoDataBusGridStatusUpdateV1}.
|
|
1296
|
+
*/
|
|
1297
|
+
export declare enum EnyoGridStatusEnum {
|
|
1298
|
+
/** The public grid is available and the site is connected to it */
|
|
1299
|
+
OnGrid = "on-grid",
|
|
1300
|
+
/**
|
|
1301
|
+
* The public grid is not available (grid outage) — the site is
|
|
1302
|
+
* disconnected from it and, where supported, running in backup / island
|
|
1303
|
+
* operation
|
|
1304
|
+
*/
|
|
1305
|
+
OffGrid = "off-grid"
|
|
1306
|
+
}
|
|
1291
1307
|
/**
|
|
1292
1308
|
* Operating state of a heating rod as reported on the data bus via
|
|
1293
1309
|
* {@link EnyoDataBusHeatingRodValuesV1}.
|
|
@@ -1518,6 +1534,8 @@ export declare enum EnyoDataBusMessageEnum {
|
|
|
1518
1534
|
SetStorageChargeLimitV1 = "SetStorageChargeLimitV1",
|
|
1519
1535
|
SetStorageScheduleV1 = "SetStorageScheduleV1",
|
|
1520
1536
|
SetInverterFeedInLimitV1 = "SetInverterFeedInLimitV1",
|
|
1537
|
+
/** An appliance capable of grid outage detection reports whether the site is on grid or off grid (grid outage). */
|
|
1538
|
+
GridStatusUpdateV1 = "GridStatusUpdateV1",
|
|
1521
1539
|
CommandAcknowledgeV1 = "CommandAcknowledgeV1",
|
|
1522
1540
|
TemperatureSensorValuesUpdateV1 = "TemperatureSensorValuesUpdateV1",
|
|
1523
1541
|
HeatpumpTemperaturesUpdateV1 = "HeatpumpTemperaturesUpdateV1",
|
|
@@ -1563,6 +1581,12 @@ export declare enum EnyoDataBusMessageEnum {
|
|
|
1563
1581
|
SetHeatingRodAvailablePowerV2 = "SetHeatingRodAvailablePowerV2",
|
|
1564
1582
|
/** V2 control command: prescribe a single-setpoint control (mode + direction + power) to a battery/storage appliance. */
|
|
1565
1583
|
SetStorageControlV2 = "SetStorageControlV2",
|
|
1584
|
+
/** One-time user request: charge a battery appliance to full (or a target SoC) now. Handled by the energy manager. */
|
|
1585
|
+
RequestBatteryChargeNowV1 = "RequestBatteryChargeNowV1",
|
|
1586
|
+
/** Cancel a running {@link EnyoDataBusMessageEnum.RequestBatteryChargeNowV1} request on a battery appliance. */
|
|
1587
|
+
CancelBatteryChargeNowV1 = "CancelBatteryChargeNowV1",
|
|
1588
|
+
/** The energy manager reports how a {@link EnyoDataBusMessageEnum.RequestBatteryChargeNowV1} request progresses. */
|
|
1589
|
+
BatteryChargeNowStatusV1 = "BatteryChargeNowStatusV1",
|
|
1566
1590
|
/** Live values of a smart plug: relay state, power draw and energy meter reading. */
|
|
1567
1591
|
SmartPlugValuesUpdateV1 = "SmartPlugValuesUpdateV1",
|
|
1568
1592
|
/** Control command: switch a smart plug / relay channel on or off. */
|
|
@@ -1816,6 +1840,41 @@ export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
|
|
|
1816
1840
|
gridOperatorLimit?: EnyoGridOperatorLimit;
|
|
1817
1841
|
};
|
|
1818
1842
|
}
|
|
1843
|
+
/**
|
|
1844
|
+
* Grid status of the site — on grid or off grid (grid outage) — as detected
|
|
1845
|
+
* by an appliance, typically an inverter declaring
|
|
1846
|
+
* {@link EnyoInverterApplianceAvailableFeaturesEnum.GridOutageDetection}.
|
|
1847
|
+
*
|
|
1848
|
+
* Publish this immediately whenever the detected status changes, and
|
|
1849
|
+
* additionally once on startup so consumers learn the current status without
|
|
1850
|
+
* having to wait for the next transition. Consumers such as an energy manager
|
|
1851
|
+
* can use it to suspend grid-dependent strategies (grid charging, feed-in
|
|
1852
|
+
* optimization, dynamic tariffs) while the site is
|
|
1853
|
+
* {@link EnyoGridStatusEnum.OffGrid}.
|
|
1854
|
+
*/
|
|
1855
|
+
export interface EnyoDataBusGridStatusUpdateV1 extends EnyoDataBusMessage {
|
|
1856
|
+
type: 'message';
|
|
1857
|
+
message: EnyoDataBusMessageEnum.GridStatusUpdateV1;
|
|
1858
|
+
/** ID of the appliance that detected the grid status */
|
|
1859
|
+
applianceId: string;
|
|
1860
|
+
data: {
|
|
1861
|
+
/** Detected grid status */
|
|
1862
|
+
gridStatus: EnyoGridStatusEnum;
|
|
1863
|
+
/**
|
|
1864
|
+
* ISO 8601 timestamp of when the appliance detected the transition into
|
|
1865
|
+
* the current {@link gridStatus}. Omit when the integration cannot tell
|
|
1866
|
+
* (e.g. the status was only read after startup).
|
|
1867
|
+
*/
|
|
1868
|
+
sinceIso?: string;
|
|
1869
|
+
/**
|
|
1870
|
+
* Whether the appliance is currently supplying the site's loads in
|
|
1871
|
+
* backup / island operation. Only meaningful while
|
|
1872
|
+
* {@link EnyoGridStatusEnum.OffGrid}; omit when unknown or not
|
|
1873
|
+
* supported by the device.
|
|
1874
|
+
*/
|
|
1875
|
+
backupPowerActive?: boolean;
|
|
1876
|
+
};
|
|
1877
|
+
}
|
|
1819
1878
|
/**
|
|
1820
1879
|
* An appliance announces how much energy it can shift, and until when.
|
|
1821
1880
|
*
|
|
@@ -3659,6 +3718,192 @@ export interface EnyoDataBusSetStorageControlV2 extends EnyoDataBusMessage {
|
|
|
3659
3718
|
reason?: EnyoDataBusCommandReason;
|
|
3660
3719
|
};
|
|
3661
3720
|
}
|
|
3721
|
+
/**
|
|
3722
|
+
* One-time user request to charge a battery appliance to full — or to
|
|
3723
|
+
* {@link data.targetSocPercent} — right now ("Batterie jetzt voll laden").
|
|
3724
|
+
*
|
|
3725
|
+
* **Addressed to the battery appliance, handled by the energy manager.** The
|
|
3726
|
+
* battery integration does not act on this message itself: an energy manager
|
|
3727
|
+
* declaring {@link EnergyManagerFeatureEnum.BatteryChargeNow} picks it up and
|
|
3728
|
+
* charges the battery through its regular storage commands (typically
|
|
3729
|
+
* {@link EnyoDataBusSetStorageControlV2} with direction `Charge` at the
|
|
3730
|
+
* battery's maximum charging power and reason
|
|
3731
|
+
* {@link EnyoDataBusCommandReasonTypeEnum.UserRequest}). Routing it through the
|
|
3732
|
+
* energy manager is what keeps the next optimization cycle from overriding the
|
|
3733
|
+
* user's request.
|
|
3734
|
+
*
|
|
3735
|
+
* Energy manager contract:
|
|
3736
|
+
* - The request ranks above the regular optimization (price arbitrage, PV
|
|
3737
|
+
* priority, EV discharge rules), but below a grid operator limitation
|
|
3738
|
+
* (§14a EnWG) and device protection — while one of those caps the battery,
|
|
3739
|
+
* the request keeps {@link EnyoBatteryChargeNowStateEnum.Running} and
|
|
3740
|
+
* resumes once the cap lifts.
|
|
3741
|
+
* - It ends on its own when the battery reaches the target SoC (or its
|
|
3742
|
+
* `maxSoC`, or reports full), when {@link data.maxDurationMinutes} has
|
|
3743
|
+
* elapsed, or when a {@link EnyoDataBusCancelBatteryChargeNowV1} arrives.
|
|
3744
|
+
* Afterwards the energy manager returns to its regular planning — it does not
|
|
3745
|
+
* release the battery to `Auto` unless that is what its planning does anyway.
|
|
3746
|
+
* - At most one request per battery: a new request replaces a running one, and
|
|
3747
|
+
* the replaced one ends with {@link EnyoBatteryChargeNowStopReasonEnum.Superseded}.
|
|
3748
|
+
* - Every state change is reported with {@link EnyoDataBusBatteryChargeNowStatusV1}
|
|
3749
|
+
* referencing this message's `id`.
|
|
3750
|
+
*/
|
|
3751
|
+
export interface EnyoDataBusRequestBatteryChargeNowV1 extends EnyoDataBusMessage {
|
|
3752
|
+
type: 'message';
|
|
3753
|
+
message: EnyoDataBusMessageEnum.RequestBatteryChargeNowV1;
|
|
3754
|
+
/** ID of the battery/storage appliance to charge. */
|
|
3755
|
+
applianceId: string;
|
|
3756
|
+
data: {
|
|
3757
|
+
/**
|
|
3758
|
+
* State of charge in percent (1–100) to charge to. Defaults to `100`.
|
|
3759
|
+
* The energy manager stops earlier when the battery's `maxSoC` is
|
|
3760
|
+
* lower.
|
|
3761
|
+
*/
|
|
3762
|
+
targetSocPercent?: number;
|
|
3763
|
+
/**
|
|
3764
|
+
* Whether the battery may be charged from the grid to fulfil the
|
|
3765
|
+
* request.
|
|
3766
|
+
*
|
|
3767
|
+
* Omitted or `true`: grid charging is allowed — the explicit request
|
|
3768
|
+
* overrides the energy manager's general `BatteryChargeFromGrid`
|
|
3769
|
+
* setting, since "charge full now" is rarely possible from PV alone.
|
|
3770
|
+
* It still needs a battery declaring {@link EnyoBatteryFeature.GridCharging}.
|
|
3771
|
+
* `false`: charge from PV surplus only, at the highest priority.
|
|
3772
|
+
*/
|
|
3773
|
+
allowGridCharging?: boolean;
|
|
3774
|
+
/**
|
|
3775
|
+
* Safety stop: the request ends with
|
|
3776
|
+
* {@link EnyoBatteryChargeNowStopReasonEnum.MaxDurationReached} after
|
|
3777
|
+
* this many minutes even if the target was not reached. When omitted
|
|
3778
|
+
* the energy manager applies its own limit.
|
|
3779
|
+
*/
|
|
3780
|
+
maxDurationMinutes?: number;
|
|
3781
|
+
/** Optional reason why this request was issued, usually {@link EnyoDataBusCommandReasonTypeEnum.UserRequest}. */
|
|
3782
|
+
reason?: EnyoDataBusCommandReason;
|
|
3783
|
+
};
|
|
3784
|
+
}
|
|
3785
|
+
/**
|
|
3786
|
+
* Cancels a running {@link EnyoDataBusRequestBatteryChargeNowV1} request on a
|
|
3787
|
+
* battery appliance. Handled by the energy manager, which ends the request with
|
|
3788
|
+
* {@link EnyoBatteryChargeNowStateEnum.Cancelled} and returns to its regular
|
|
3789
|
+
* planning.
|
|
3790
|
+
*
|
|
3791
|
+
* Idempotent: cancelling when no request is running, or a request that already
|
|
3792
|
+
* ended, is not an error.
|
|
3793
|
+
*/
|
|
3794
|
+
export interface EnyoDataBusCancelBatteryChargeNowV1 extends EnyoDataBusMessage {
|
|
3795
|
+
type: 'message';
|
|
3796
|
+
message: EnyoDataBusMessageEnum.CancelBatteryChargeNowV1;
|
|
3797
|
+
/** ID of the battery/storage appliance whose request is cancelled. */
|
|
3798
|
+
applianceId: string;
|
|
3799
|
+
data: {
|
|
3800
|
+
/**
|
|
3801
|
+
* `id` of the {@link EnyoDataBusRequestBatteryChargeNowV1} message to
|
|
3802
|
+
* cancel. When given, only that request is cancelled, so a newer one
|
|
3803
|
+
* that replaced it is left alone. When omitted, whatever request is
|
|
3804
|
+
* running on the appliance is cancelled.
|
|
3805
|
+
*/
|
|
3806
|
+
requestMessageId?: string;
|
|
3807
|
+
/** Optional reason why the request is cancelled. */
|
|
3808
|
+
reason?: EnyoDataBusCommandReason;
|
|
3809
|
+
};
|
|
3810
|
+
}
|
|
3811
|
+
/**
|
|
3812
|
+
* Where a {@link EnyoDataBusRequestBatteryChargeNowV1} request stands.
|
|
3813
|
+
*
|
|
3814
|
+
* `Accepted` and `Running` are intermediate; `Completed`, `Cancelled`,
|
|
3815
|
+
* `Aborted` and `Rejected` are final — no further status follows for that
|
|
3816
|
+
* request.
|
|
3817
|
+
*/
|
|
3818
|
+
export declare enum EnyoBatteryChargeNowStateEnum {
|
|
3819
|
+
/** The energy manager took the request on but is not charging yet. */
|
|
3820
|
+
Accepted = "accepted",
|
|
3821
|
+
/**
|
|
3822
|
+
* The battery is being charged for the request — or would be, but a grid
|
|
3823
|
+
* operator limitation or device protection is capping it right now.
|
|
3824
|
+
*/
|
|
3825
|
+
Running = "running",
|
|
3826
|
+
/** The battery reached the target SoC (or its `maxSoC`, or reported full). Final. */
|
|
3827
|
+
Completed = "completed",
|
|
3828
|
+
/** The request was cancelled via {@link EnyoDataBusCancelBatteryChargeNowV1}. Final. */
|
|
3829
|
+
Cancelled = "cancelled",
|
|
3830
|
+
/** The request started but ended before reaching the target. See the stop reason. Final. */
|
|
3831
|
+
Aborted = "aborted",
|
|
3832
|
+
/** The request was refused and never started. See the stop reason. Final. */
|
|
3833
|
+
Rejected = "rejected"
|
|
3834
|
+
}
|
|
3835
|
+
/**
|
|
3836
|
+
* Why a {@link EnyoDataBusRequestBatteryChargeNowV1} request was
|
|
3837
|
+
* {@link EnyoBatteryChargeNowStateEnum.Rejected} or
|
|
3838
|
+
* {@link EnyoBatteryChargeNowStateEnum.Aborted}.
|
|
3839
|
+
*/
|
|
3840
|
+
export declare enum EnyoBatteryChargeNowStopReasonEnum {
|
|
3841
|
+
/** The request itself is malformed — e.g. `targetSocPercent` outside 1–100 or a non-positive `maxDurationMinutes`. */
|
|
3842
|
+
InvalidRequest = "invalid-request",
|
|
3843
|
+
/** No battery appliance with the given `applianceId` exists. */
|
|
3844
|
+
ApplianceNotFound = "appliance-not-found",
|
|
3845
|
+
/** The battery is offline / unreachable. */
|
|
3846
|
+
ApplianceOffline = "appliance-offline",
|
|
3847
|
+
/**
|
|
3848
|
+
* The battery integration does not permit control (`controlAllowed` is
|
|
3849
|
+
* `false`) or does not declare {@link EnyoBatteryFeature.ManualCharge}.
|
|
3850
|
+
*/
|
|
3851
|
+
ControlNotAllowed = "control-not-allowed",
|
|
3852
|
+
/**
|
|
3853
|
+
* The user switched battery control off in the energy manager settings
|
|
3854
|
+
* (`BatteryControl`). Actionable: point the user at the setting.
|
|
3855
|
+
*/
|
|
3856
|
+
ControlDisabledByUser = "control-disabled-by-user",
|
|
3857
|
+
/**
|
|
3858
|
+
* Grid charging was allowed for the request but the battery does not
|
|
3859
|
+
* declare {@link EnyoBatteryFeature.GridCharging}, and there is no PV
|
|
3860
|
+
* surplus to charge from.
|
|
3861
|
+
*/
|
|
3862
|
+
GridChargingNotSupported = "grid-charging-not-supported",
|
|
3863
|
+
/** The battery already is at or above the target SoC (or its `maxSoC`). */
|
|
3864
|
+
AlreadyAtTarget = "already-at-target",
|
|
3865
|
+
/** {@link EnyoDataBusRequestBatteryChargeNowV1.data.maxDurationMinutes} (or the energy manager's own limit) elapsed. */
|
|
3866
|
+
MaxDurationReached = "max-duration-reached",
|
|
3867
|
+
/** A newer request for the same battery replaced this one. */
|
|
3868
|
+
Superseded = "superseded",
|
|
3869
|
+
/** The battery stopped accepting charge below the target (e.g. a device-side limit or fault). */
|
|
3870
|
+
BatteryStoppedCharging = "battery-stopped-charging"
|
|
3871
|
+
}
|
|
3872
|
+
/**
|
|
3873
|
+
* Status of a {@link EnyoDataBusRequestBatteryChargeNowV1} request, published
|
|
3874
|
+
* by the energy manager on every state change — and, while
|
|
3875
|
+
* {@link EnyoBatteryChargeNowStateEnum.Running}, whenever the estimate changes
|
|
3876
|
+
* noticeably — so the app can show progress and the outcome.
|
|
3877
|
+
*/
|
|
3878
|
+
export interface EnyoDataBusBatteryChargeNowStatusV1 extends EnyoDataBusMessage {
|
|
3879
|
+
type: 'message';
|
|
3880
|
+
message: EnyoDataBusMessageEnum.BatteryChargeNowStatusV1;
|
|
3881
|
+
/** ID of the battery/storage appliance the request is for. */
|
|
3882
|
+
applianceId: string;
|
|
3883
|
+
data: {
|
|
3884
|
+
/** `id` of the {@link EnyoDataBusRequestBatteryChargeNowV1} message this status refers to. */
|
|
3885
|
+
requestMessageId: string;
|
|
3886
|
+
/** Where the request stands. */
|
|
3887
|
+
state: EnyoBatteryChargeNowStateEnum;
|
|
3888
|
+
/**
|
|
3889
|
+
* Why the request ended early. Set exactly when {@link state} is
|
|
3890
|
+
* {@link EnyoBatteryChargeNowStateEnum.Rejected} or
|
|
3891
|
+
* {@link EnyoBatteryChargeNowStateEnum.Aborted}.
|
|
3892
|
+
*/
|
|
3893
|
+
stopReason?: EnyoBatteryChargeNowStopReasonEnum;
|
|
3894
|
+
/**
|
|
3895
|
+
* The target SoC in percent the energy manager actually charges to —
|
|
3896
|
+
* the requested target, lowered to the battery's `maxSoC` if needed.
|
|
3897
|
+
*/
|
|
3898
|
+
effectiveTargetSocPercent?: number;
|
|
3899
|
+
/** The battery's current state of charge in percent, when known. */
|
|
3900
|
+
currentSocPercent?: number;
|
|
3901
|
+
/** Charging power in Watt currently applied for the request, when known. */
|
|
3902
|
+
chargingPowerW?: number;
|
|
3903
|
+
/** Estimated time the target SoC is reached, in ISO 8601 format. Only while running. */
|
|
3904
|
+
estimatedCompletionIso?: string;
|
|
3905
|
+
};
|
|
3906
|
+
}
|
|
3662
3907
|
/**
|
|
3663
3908
|
* Command message to set or reset the inverter's grid feed-in power limit.
|
|
3664
3909
|
* When a limit is set, the inverter will not feed more than the specified power into the grid.
|
|
@@ -21,6 +21,16 @@ var EnergyManagerFeatureEnum;
|
|
|
21
21
|
EnergyManagerFeatureEnum["BatteryPeakShaving"] = "battery-peak-shaving";
|
|
22
22
|
/** Reserve battery capacity for power outages */
|
|
23
23
|
EnergyManagerFeatureEnum["BatteryBackupPower"] = "battery-backup-power";
|
|
24
|
+
/**
|
|
25
|
+
* The energy manager handles one-time user requests to charge a battery
|
|
26
|
+
* now (`RequestBatteryChargeNowV1` / `CancelBatteryChargeNowV1`) and
|
|
27
|
+
* reports their progress with `BatteryChargeNowStatusV1`.
|
|
28
|
+
*
|
|
29
|
+
* The app only offers the "charge battery full now" button when the active
|
|
30
|
+
* energy manager declares this feature — without it nobody would act on
|
|
31
|
+
* the request.
|
|
32
|
+
*/
|
|
33
|
+
EnergyManagerFeatureEnum["BatteryChargeNow"] = "battery-charge-now";
|
|
24
34
|
// Wallbox / EV Charging
|
|
25
35
|
/** Charge EV from solar surplus */
|
|
26
36
|
EnergyManagerFeatureEnum["WallboxPvSurplusCharging"] = "wallbox-pv-surplus-charging";
|
|
@@ -15,6 +15,16 @@ export declare enum EnergyManagerFeatureEnum {
|
|
|
15
15
|
BatteryPeakShaving = "battery-peak-shaving",
|
|
16
16
|
/** Reserve battery capacity for power outages */
|
|
17
17
|
BatteryBackupPower = "battery-backup-power",
|
|
18
|
+
/**
|
|
19
|
+
* The energy manager handles one-time user requests to charge a battery
|
|
20
|
+
* now (`RequestBatteryChargeNowV1` / `CancelBatteryChargeNowV1`) and
|
|
21
|
+
* reports their progress with `BatteryChargeNowStatusV1`.
|
|
22
|
+
*
|
|
23
|
+
* The app only offers the "charge battery full now" button when the active
|
|
24
|
+
* energy manager declares this feature — without it nobody would act on
|
|
25
|
+
* the request.
|
|
26
|
+
*/
|
|
27
|
+
BatteryChargeNow = "battery-charge-now",
|
|
18
28
|
/** Charge EV from solar surplus */
|
|
19
29
|
WallboxPvSurplusCharging = "wallbox-pv-surplus-charging",
|
|
20
30
|
/** Adjust EV charging based on total home load */
|
|
@@ -21,6 +21,12 @@ var EnyoInverterApplianceAvailableFeaturesEnum;
|
|
|
21
21
|
EnyoInverterApplianceAvailableFeaturesEnum["ReactivePowerControl"] = "ReactivePowerControl";
|
|
22
22
|
/** The inverter reports its own AC energy meter reading. */
|
|
23
23
|
EnyoInverterApplianceAvailableFeaturesEnum["EnergyMeterReadout"] = "EnergyMeterReadout";
|
|
24
|
+
/**
|
|
25
|
+
* The inverter detects grid outages and reports whether the site is on
|
|
26
|
+
* grid or off grid via `GridStatusUpdateV1` data bus messages (see
|
|
27
|
+
* `EnyoDataBusGridStatusUpdateV1`).
|
|
28
|
+
*/
|
|
29
|
+
EnyoInverterApplianceAvailableFeaturesEnum["GridOutageDetection"] = "GridOutageDetection";
|
|
24
30
|
})(EnyoInverterApplianceAvailableFeaturesEnum || (exports.EnyoInverterApplianceAvailableFeaturesEnum = EnyoInverterApplianceAvailableFeaturesEnum = {}));
|
|
25
31
|
/**
|
|
26
32
|
* How much trust to place in an {@link EnyoInverterIrradianceResponse}.
|
|
@@ -16,7 +16,13 @@ export declare enum EnyoInverterApplianceAvailableFeaturesEnum {
|
|
|
16
16
|
/** Reactive power can be controlled. */
|
|
17
17
|
ReactivePowerControl = "ReactivePowerControl",
|
|
18
18
|
/** The inverter reports its own AC energy meter reading. */
|
|
19
|
-
EnergyMeterReadout = "EnergyMeterReadout"
|
|
19
|
+
EnergyMeterReadout = "EnergyMeterReadout",
|
|
20
|
+
/**
|
|
21
|
+
* The inverter detects grid outages and reports whether the site is on
|
|
22
|
+
* grid or off grid via `GridStatusUpdateV1` data bus messages (see
|
|
23
|
+
* `EnyoDataBusGridStatusUpdateV1`).
|
|
24
|
+
*/
|
|
25
|
+
GridOutageDetection = "GridOutageDetection"
|
|
20
26
|
}
|
|
21
27
|
export interface EnyoInverterDcString {
|
|
22
28
|
index: number;
|
|
@@ -132,6 +132,27 @@ export interface EnyoPackageConfigurationSetting {
|
|
|
132
132
|
priorityOptions?: EnyoPackageConfigurationSettingPriorityOption[];
|
|
133
133
|
/** Configuration for action-type settings (a button). Required when `type` is `'action'`. */
|
|
134
134
|
actionOptions?: EnyoPackageConfigurationSettingActionOptions;
|
|
135
|
+
/**
|
|
136
|
+
* Marks the setting as an expert setting. The host hides expert settings
|
|
137
|
+
* from the default view and shows them only in an expert / advanced
|
|
138
|
+
* section, e.g. for installers.
|
|
139
|
+
*
|
|
140
|
+
* When omitted, the setting inherits
|
|
141
|
+
* {@link EnyoPackageConfigurationSettingGroup.expertSetting} of its group,
|
|
142
|
+
* and is a normal setting outside a group. An explicit value overrides
|
|
143
|
+
* the group's.
|
|
144
|
+
*/
|
|
145
|
+
expertSetting?: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* Shows the setting during onboarding, so the user can set it while
|
|
148
|
+
* setting up the app instead of looking for it in the settings later.
|
|
149
|
+
*
|
|
150
|
+
* When omitted, the setting inherits
|
|
151
|
+
* {@link EnyoPackageConfigurationSettingGroup.showInOnboarding} of its
|
|
152
|
+
* group, and is not shown in onboarding outside a group. An explicit value
|
|
153
|
+
* overrides the group's.
|
|
154
|
+
*/
|
|
155
|
+
showInOnboarding?: boolean;
|
|
135
156
|
}
|
|
136
157
|
/**
|
|
137
158
|
* Represents a change event when a setting value is modified.
|
|
@@ -175,6 +196,18 @@ export interface EnyoPackageConfigurationSettingGroup {
|
|
|
175
196
|
caption?: EnyoPackageConfigurationTranslatedValue[];
|
|
176
197
|
/** The settings belonging to this group (1 or more) */
|
|
177
198
|
settings: EnyoPackageConfigurationSetting[];
|
|
199
|
+
/**
|
|
200
|
+
* Marks every setting of the group as an expert setting (see
|
|
201
|
+
* {@link EnyoPackageConfigurationSetting.expertSetting}). A setting can
|
|
202
|
+
* override it with its own value. Defaults to `false`.
|
|
203
|
+
*/
|
|
204
|
+
expertSetting?: boolean;
|
|
205
|
+
/**
|
|
206
|
+
* Shows every setting of the group during onboarding (see
|
|
207
|
+
* {@link EnyoPackageConfigurationSetting.showInOnboarding}). A setting can
|
|
208
|
+
* override it with its own value. Defaults to `false`.
|
|
209
|
+
*/
|
|
210
|
+
showInOnboarding?: boolean;
|
|
178
211
|
}
|
|
179
212
|
/**
|
|
180
213
|
* Represents a setting group with resolved setting values.
|
|
@@ -187,4 +220,8 @@ export interface EnyoSettingGroupWithValues {
|
|
|
187
220
|
caption?: EnyoPackageConfigurationTranslatedValue[];
|
|
188
221
|
/** The settings belonging to this group, including IDs and current values */
|
|
189
222
|
settings: EnyoSettingConfigWithValue[];
|
|
223
|
+
/** Whether the group is an expert group, see {@link EnyoPackageConfigurationSettingGroup.expertSetting}. */
|
|
224
|
+
expertSetting?: boolean;
|
|
225
|
+
/** Whether the group is shown during onboarding, see {@link EnyoPackageConfigurationSettingGroup.showInOnboarding}. */
|
|
226
|
+
showInOnboarding?: boolean;
|
|
190
227
|
}
|
package/dist/cjs/version.cjs
CHANGED
|
@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
|
|
|
9
9
|
/**
|
|
10
10
|
* Current version of the enyo Energy App SDK.
|
|
11
11
|
*/
|
|
12
|
-
exports.SDK_VERSION = '1.
|
|
12
|
+
exports.SDK_VERSION = '1.47.0';
|
|
13
13
|
/**
|
|
14
14
|
* Gets the current SDK version.
|
|
15
15
|
* @returns The semantic version string of the SDK
|
package/dist/cjs/version.d.cts
CHANGED
|
@@ -17,6 +17,8 @@ export declare enum EnergyAppModelFeatureEnum {
|
|
|
17
17
|
PvFeedInLimitation = "pv-feed-in-limitation",
|
|
18
18
|
/** The inverter active power output can be limited */
|
|
19
19
|
InverterPowerLimitation = "inverter-power-limitation",
|
|
20
|
+
/** The inverter detects grid outages and reports on grid / off grid status */
|
|
21
|
+
InverterGridOutageDetection = "inverter-grid-outage-detection",
|
|
20
22
|
/** Charging can be started and stopped remotely */
|
|
21
23
|
ChargingStartStop = "charging-start-stop",
|
|
22
24
|
/** The charging power (in Ampere or Watt) can be limited */
|
|
@@ -20,6 +20,8 @@ export var EnergyAppModelFeatureEnum;
|
|
|
20
20
|
EnergyAppModelFeatureEnum["PvFeedInLimitation"] = "pv-feed-in-limitation";
|
|
21
21
|
/** The inverter active power output can be limited */
|
|
22
22
|
EnergyAppModelFeatureEnum["InverterPowerLimitation"] = "inverter-power-limitation";
|
|
23
|
+
/** The inverter detects grid outages and reports on grid / off grid status */
|
|
24
|
+
EnergyAppModelFeatureEnum["InverterGridOutageDetection"] = "inverter-grid-outage-detection";
|
|
23
25
|
// Wallbox / Charging
|
|
24
26
|
/** Charging can be started and stopped remotely */
|
|
25
27
|
EnergyAppModelFeatureEnum["ChargingStartStop"] = "charging-start-stop";
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { EnyoBatteryChargeNowStateEnum, EnyoBatteryChargeNowStopReasonEnum, EnyoDataBusRequestBatteryChargeNowV1 } from '../../types/enyo-data-bus-value.js';
|
|
2
|
+
import { EnyoBatteryApplianceMetadata } from '../../types/enyo-battery-appliance.js';
|
|
3
|
+
/** Target SoC in percent a `RequestBatteryChargeNowV1` charges to when it names none. */
|
|
4
|
+
export declare const DEFAULT_BATTERY_CHARGE_NOW_TARGET_SOC_PERCENT = 100;
|
|
5
|
+
/**
|
|
6
|
+
* Outcome of {@link validateBatteryChargeNowRequest}: whether an energy manager
|
|
7
|
+
* should take a `RequestBatteryChargeNowV1` on, and the target it charges to.
|
|
8
|
+
*/
|
|
9
|
+
export interface BatteryChargeNowValidationResult {
|
|
10
|
+
/** {@link EnyoBatteryChargeNowStateEnum.Accepted} or {@link EnyoBatteryChargeNowStateEnum.Rejected}. */
|
|
11
|
+
state: EnyoBatteryChargeNowStateEnum.Accepted | EnyoBatteryChargeNowStateEnum.Rejected;
|
|
12
|
+
/** Why the request is rejected. Set exactly when {@link state} is `Rejected`. */
|
|
13
|
+
stopReason?: EnyoBatteryChargeNowStopReasonEnum;
|
|
14
|
+
/**
|
|
15
|
+
* The SoC in percent to charge to: the requested target (default
|
|
16
|
+
* {@link DEFAULT_BATTERY_CHARGE_NOW_TARGET_SOC_PERCENT}), lowered to the
|
|
17
|
+
* battery's `maxSoC` when that is lower. Absent when the request is
|
|
18
|
+
* malformed.
|
|
19
|
+
*/
|
|
20
|
+
effectiveTargetSocPercent?: number;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Validates a `RequestBatteryChargeNowV1` against the battery's metadata and
|
|
24
|
+
* current state of charge, and returns whether an energy manager should accept
|
|
25
|
+
* it — the answer to publish as the first `BatteryChargeNowStatusV1`.
|
|
26
|
+
*
|
|
27
|
+
* Rules, in order — the first that fails decides:
|
|
28
|
+
* 1. `targetSocPercent`, when given, is a finite number from 1 to 100, and
|
|
29
|
+
* `maxDurationMinutes`, when given, is a finite positive number
|
|
30
|
+
* (**InvalidRequest**).
|
|
31
|
+
* 2. The battery's metadata sets `controlAllowed: false`, or lists `features`
|
|
32
|
+
* without {@link EnyoBatteryFeature.ManualCharge} (**ControlNotAllowed**).
|
|
33
|
+
* A battery without a `features` list is not rejected, since the list is
|
|
34
|
+
* optional.
|
|
35
|
+
* 3. The current SoC is at or above the effective target (**AlreadyAtTarget**).
|
|
36
|
+
*
|
|
37
|
+
* Without metadata only rule 1 and, given the SoC, rule 3 are checked. Runtime
|
|
38
|
+
* conditions the metadata cannot tell — the battery being offline, battery
|
|
39
|
+
* control switched off in the energy manager settings, no PV surplus for a
|
|
40
|
+
* battery without grid charging — are left to the energy manager.
|
|
41
|
+
*
|
|
42
|
+
* @param message - The request to validate.
|
|
43
|
+
* @param metadata - The battery's metadata, if known.
|
|
44
|
+
* @param currentSocPercent - The battery's current state of charge in percent, if known.
|
|
45
|
+
* @returns `Accepted` with the effective target when every rule holds, otherwise `Rejected` with the reason.
|
|
46
|
+
*/
|
|
47
|
+
export declare function validateBatteryChargeNowRequest(message: EnyoDataBusRequestBatteryChargeNowV1, metadata?: EnyoBatteryApplianceMetadata, currentSocPercent?: number): BatteryChargeNowValidationResult;
|
|
48
|
+
/**
|
|
49
|
+
* The SoC in percent a `RequestBatteryChargeNowV1` actually charges to: the
|
|
50
|
+
* requested target (default {@link DEFAULT_BATTERY_CHARGE_NOW_TARGET_SOC_PERCENT}),
|
|
51
|
+
* lowered to the battery's `maxSoC` when that is lower.
|
|
52
|
+
*
|
|
53
|
+
* @param targetSocPercent - The request's `targetSocPercent`, if given.
|
|
54
|
+
* @param metadata - The battery's metadata, if known.
|
|
55
|
+
* @returns The effective target SoC in percent.
|
|
56
|
+
*/
|
|
57
|
+
export declare function resolveBatteryChargeNowTargetSoc(targetSocPercent: number | undefined, metadata?: EnyoBatteryApplianceMetadata): number;
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { EnyoBatteryChargeNowStateEnum, EnyoBatteryChargeNowStopReasonEnum, } from '../../types/enyo-data-bus-value.js';
|
|
2
|
+
import { EnyoBatteryFeature } from '../../types/enyo-battery-appliance.js';
|
|
3
|
+
/** Target SoC in percent a `RequestBatteryChargeNowV1` charges to when it names none. */
|
|
4
|
+
export const DEFAULT_BATTERY_CHARGE_NOW_TARGET_SOC_PERCENT = 100;
|
|
5
|
+
/**
|
|
6
|
+
* Validates a `RequestBatteryChargeNowV1` against the battery's metadata and
|
|
7
|
+
* current state of charge, and returns whether an energy manager should accept
|
|
8
|
+
* it — the answer to publish as the first `BatteryChargeNowStatusV1`.
|
|
9
|
+
*
|
|
10
|
+
* Rules, in order — the first that fails decides:
|
|
11
|
+
* 1. `targetSocPercent`, when given, is a finite number from 1 to 100, and
|
|
12
|
+
* `maxDurationMinutes`, when given, is a finite positive number
|
|
13
|
+
* (**InvalidRequest**).
|
|
14
|
+
* 2. The battery's metadata sets `controlAllowed: false`, or lists `features`
|
|
15
|
+
* without {@link EnyoBatteryFeature.ManualCharge} (**ControlNotAllowed**).
|
|
16
|
+
* A battery without a `features` list is not rejected, since the list is
|
|
17
|
+
* optional.
|
|
18
|
+
* 3. The current SoC is at or above the effective target (**AlreadyAtTarget**).
|
|
19
|
+
*
|
|
20
|
+
* Without metadata only rule 1 and, given the SoC, rule 3 are checked. Runtime
|
|
21
|
+
* conditions the metadata cannot tell — the battery being offline, battery
|
|
22
|
+
* control switched off in the energy manager settings, no PV surplus for a
|
|
23
|
+
* battery without grid charging — are left to the energy manager.
|
|
24
|
+
*
|
|
25
|
+
* @param message - The request to validate.
|
|
26
|
+
* @param metadata - The battery's metadata, if known.
|
|
27
|
+
* @param currentSocPercent - The battery's current state of charge in percent, if known.
|
|
28
|
+
* @returns `Accepted` with the effective target when every rule holds, otherwise `Rejected` with the reason.
|
|
29
|
+
*/
|
|
30
|
+
export function validateBatteryChargeNowRequest(message, metadata, currentSocPercent) {
|
|
31
|
+
const { targetSocPercent, maxDurationMinutes } = message.data;
|
|
32
|
+
const targetValid = targetSocPercent === undefined
|
|
33
|
+
|| (Number.isFinite(targetSocPercent) && targetSocPercent >= 1 && targetSocPercent <= 100);
|
|
34
|
+
const durationValid = maxDurationMinutes === undefined
|
|
35
|
+
|| (Number.isFinite(maxDurationMinutes) && maxDurationMinutes > 0);
|
|
36
|
+
if (!targetValid || !durationValid) {
|
|
37
|
+
return reject(EnyoBatteryChargeNowStopReasonEnum.InvalidRequest);
|
|
38
|
+
}
|
|
39
|
+
const effectiveTargetSocPercent = resolveBatteryChargeNowTargetSoc(targetSocPercent, metadata);
|
|
40
|
+
if (metadata) {
|
|
41
|
+
const lacksManualCharge = metadata.features !== undefined
|
|
42
|
+
&& !metadata.features.includes(EnyoBatteryFeature.ManualCharge);
|
|
43
|
+
if (metadata.controlAllowed === false || lacksManualCharge) {
|
|
44
|
+
return reject(EnyoBatteryChargeNowStopReasonEnum.ControlNotAllowed, effectiveTargetSocPercent);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
if (currentSocPercent !== undefined && Number.isFinite(currentSocPercent)
|
|
48
|
+
&& currentSocPercent >= effectiveTargetSocPercent) {
|
|
49
|
+
return reject(EnyoBatteryChargeNowStopReasonEnum.AlreadyAtTarget, effectiveTargetSocPercent);
|
|
50
|
+
}
|
|
51
|
+
return { state: EnyoBatteryChargeNowStateEnum.Accepted, effectiveTargetSocPercent };
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The SoC in percent a `RequestBatteryChargeNowV1` actually charges to: the
|
|
55
|
+
* requested target (default {@link DEFAULT_BATTERY_CHARGE_NOW_TARGET_SOC_PERCENT}),
|
|
56
|
+
* lowered to the battery's `maxSoC` when that is lower.
|
|
57
|
+
*
|
|
58
|
+
* @param targetSocPercent - The request's `targetSocPercent`, if given.
|
|
59
|
+
* @param metadata - The battery's metadata, if known.
|
|
60
|
+
* @returns The effective target SoC in percent.
|
|
61
|
+
*/
|
|
62
|
+
export function resolveBatteryChargeNowTargetSoc(targetSocPercent, metadata) {
|
|
63
|
+
const requested = targetSocPercent ?? DEFAULT_BATTERY_CHARGE_NOW_TARGET_SOC_PERCENT;
|
|
64
|
+
const maxSoC = metadata?.maxSoC;
|
|
65
|
+
return maxSoC !== undefined && Number.isFinite(maxSoC) ? Math.min(requested, maxSoC) : requested;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Builds a rejected {@link BatteryChargeNowValidationResult}.
|
|
69
|
+
*
|
|
70
|
+
* @param stopReason - Why the request is rejected.
|
|
71
|
+
* @param effectiveTargetSocPercent - The effective target, when it could be resolved.
|
|
72
|
+
* @returns The rejected result.
|
|
73
|
+
*/
|
|
74
|
+
function reject(stopReason, effectiveTargetSocPercent) {
|
|
75
|
+
return { state: EnyoBatteryChargeNowStateEnum.Rejected, stopReason, effectiveTargetSocPercent };
|
|
76
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -20,6 +20,7 @@ export * from './implementations/appliances/identifier-strategies.js';
|
|
|
20
20
|
export * from './implementations/network-devices/network-access-guard.js';
|
|
21
21
|
export * from './implementations/network-devices/network-device-manager.js';
|
|
22
22
|
export * from './implementations/storage/storage-schedule-handler.js';
|
|
23
|
+
export * from './implementations/storage/battery-charge-now-validators.js';
|
|
23
24
|
export * from './enyo-package-channel.js';
|
|
24
25
|
export * from './enyo-energy-app-environment.js';
|
|
25
26
|
export * from './types/enyo-timeseries.js';
|
package/dist/index.js
CHANGED
|
@@ -20,6 +20,7 @@ export * from './implementations/appliances/identifier-strategies.js';
|
|
|
20
20
|
export * from './implementations/network-devices/network-access-guard.js';
|
|
21
21
|
export * from './implementations/network-devices/network-device-manager.js';
|
|
22
22
|
export * from './implementations/storage/storage-schedule-handler.js';
|
|
23
|
+
export * from './implementations/storage/battery-charge-now-validators.js';
|
|
23
24
|
export * from './enyo-package-channel.js';
|
|
24
25
|
export * from './enyo-energy-app-environment.js';
|
|
25
26
|
export * from './types/enyo-timeseries.js';
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { IntegrationEnergyApp } from "./integration-energy-app.js";
|
|
2
2
|
import { IntegrationCommandResponse, IntegrationEnergyAppOptions } from "./integration-types.js";
|
|
3
3
|
import { EnyoApplianceTypeEnum } from "../types/enyo-appliance.js";
|
|
4
|
-
import { EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusInverterValuesV1, EnyoDataBusSetInverterFeedInLimitV1 } from "../types/enyo-data-bus-value.js";
|
|
4
|
+
import { EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusGridStatusUpdateV1, EnyoDataBusInverterValuesV1, EnyoDataBusSetInverterFeedInLimitV1 } from "../types/enyo-data-bus-value.js";
|
|
5
5
|
/**
|
|
6
6
|
* Abstract base class for PV inverter integrations.
|
|
7
7
|
*
|
|
@@ -31,4 +31,12 @@ export declare abstract class InverterIntegrationEnergyApp extends IntegrationEn
|
|
|
31
31
|
* current state, PV power, voltages, and string values.
|
|
32
32
|
*/
|
|
33
33
|
publishInverterValuesUpdate(applianceId: string, data: EnyoDataBusInverterValuesV1['data']): void;
|
|
34
|
+
/**
|
|
35
|
+
* Publishes a `GridStatusUpdateV1` message reporting whether the site is
|
|
36
|
+
* on grid or off grid (grid outage), as detected by the inverter.
|
|
37
|
+
*
|
|
38
|
+
* Only for inverters declaring the `GridOutageDetection` feature. Call it
|
|
39
|
+
* whenever the detected grid status changes, and once on startup.
|
|
40
|
+
*/
|
|
41
|
+
publishGridStatusUpdate(applianceId: string, data: EnyoDataBusGridStatusUpdateV1['data']): void;
|
|
34
42
|
}
|
|
@@ -37,4 +37,24 @@ export class InverterIntegrationEnergyApp extends IntegrationEnergyApp {
|
|
|
37
37
|
};
|
|
38
38
|
this.useDataBus().sendMessage([msg]);
|
|
39
39
|
}
|
|
40
|
+
/**
|
|
41
|
+
* Publishes a `GridStatusUpdateV1` message reporting whether the site is
|
|
42
|
+
* on grid or off grid (grid outage), as detected by the inverter.
|
|
43
|
+
*
|
|
44
|
+
* Only for inverters declaring the `GridOutageDetection` feature. Call it
|
|
45
|
+
* whenever the detected grid status changes, and once on startup.
|
|
46
|
+
*/
|
|
47
|
+
publishGridStatusUpdate(applianceId, data) {
|
|
48
|
+
const msg = {
|
|
49
|
+
id: this.generateMessageId(),
|
|
50
|
+
type: 'message',
|
|
51
|
+
message: EnyoDataBusMessageEnum.GridStatusUpdateV1,
|
|
52
|
+
source: this.source,
|
|
53
|
+
applianceId,
|
|
54
|
+
timestampIso: new Date().toISOString(),
|
|
55
|
+
resolution: 'dynamic',
|
|
56
|
+
data
|
|
57
|
+
};
|
|
58
|
+
this.useDataBus().sendMessage([msg]);
|
|
59
|
+
}
|
|
40
60
|
}
|