@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.
Files changed (40) hide show
  1. package/README.md +96 -0
  2. package/dist/cjs/energy-app-model-feature.enum.cjs +2 -0
  3. package/dist/cjs/energy-app-model-feature.enum.d.cts +2 -0
  4. package/dist/cjs/implementations/storage/battery-charge-now-validators.cjs +81 -0
  5. package/dist/cjs/implementations/storage/battery-charge-now-validators.d.cts +57 -0
  6. package/dist/cjs/index.cjs +1 -0
  7. package/dist/cjs/index.d.cts +1 -0
  8. package/dist/cjs/integrations/inverter-integration-energy-app.cjs +20 -0
  9. package/dist/cjs/integrations/inverter-integration-energy-app.d.cts +9 -1
  10. package/dist/cjs/types/enyo-charger-appliance.cjs +13 -0
  11. package/dist/cjs/types/enyo-charger-appliance.d.cts +29 -2
  12. package/dist/cjs/types/enyo-data-bus-value.cjs +89 -1
  13. package/dist/cjs/types/enyo-data-bus-value.d.cts +245 -0
  14. package/dist/cjs/types/enyo-energy-manager.cjs +10 -0
  15. package/dist/cjs/types/enyo-energy-manager.d.cts +10 -0
  16. package/dist/cjs/types/enyo-inverter-appliance.cjs +6 -0
  17. package/dist/cjs/types/enyo-inverter-appliance.d.cts +7 -1
  18. package/dist/cjs/types/enyo-settings.d.cts +37 -0
  19. package/dist/cjs/version.cjs +1 -1
  20. package/dist/cjs/version.d.cts +1 -1
  21. package/dist/energy-app-model-feature.enum.d.ts +2 -0
  22. package/dist/energy-app-model-feature.enum.js +2 -0
  23. package/dist/implementations/storage/battery-charge-now-validators.d.ts +57 -0
  24. package/dist/implementations/storage/battery-charge-now-validators.js +76 -0
  25. package/dist/index.d.ts +1 -0
  26. package/dist/index.js +1 -0
  27. package/dist/integrations/inverter-integration-energy-app.d.ts +9 -1
  28. package/dist/integrations/inverter-integration-energy-app.js +20 -0
  29. package/dist/types/enyo-charger-appliance.d.ts +29 -2
  30. package/dist/types/enyo-charger-appliance.js +13 -0
  31. package/dist/types/enyo-data-bus-value.d.ts +245 -0
  32. package/dist/types/enyo-data-bus-value.js +88 -0
  33. package/dist/types/enyo-energy-manager.d.ts +10 -0
  34. package/dist/types/enyo-energy-manager.js +10 -0
  35. package/dist/types/enyo-inverter-appliance.d.ts +7 -1
  36. package/dist/types/enyo-inverter-appliance.js +6 -0
  37. package/dist/types/enyo-settings.d.ts +37 -0
  38. package/dist/version.d.ts +1 -1
  39. package/dist/version.js +1 -1
  40. 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
  }
@@ -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.45.0';
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
@@ -5,7 +5,7 @@
5
5
  /**
6
6
  * Current version of the enyo Energy App SDK.
7
7
  */
8
- export declare const SDK_VERSION = "1.45.0";
8
+ export declare const SDK_VERSION = "1.47.0";
9
9
  /**
10
10
  * Gets the current SDK version.
11
11
  * @returns The semantic version string of the SDK
@@ -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
  }