@enyo-energy/energy-app-sdk 1.32.0 → 1.33.0

package/README.md

@@ -829,6 +829,9 @@ vehicle?.priceLimitMode;             // how the ceiling is expressed, or none
 vehicle?.priceLimitCtPerKwh;         // ct/kWh ceiling, under 'ct-per-kwh'
 vehicle?.priceLimitSharePercent;     // cheapest n % of the day, under 'cheapest-share'
 vehicle?.immediateReserveKwh;        // full-power reserve before any mode
+vehicle?.minChargingCurrentAmpere;   // lowest current per phase the car accepts
+vehicle?.cannotBePaused;             // true: never pause a started session
+vehicle?.phaseSwitchDisabled;        // true: never switch phases while charging
 vehicle?.departureTimeHHmm;          // daily deadline, wall-clock "07:30"
 vehicle?.departureTimezone;          // IANA zone the time is read in
 
@@ -4327,6 +4330,10 @@ New reason types came with this surface, so a skipped row can say *why* instead
 - `ElectricityPriceBelowThreshold` on a grid charge — the buy and the peak it is for: "Charging at 33.6 ct for the 17:00 peak at 43.7 ct."
 - `ScheduledOptimization` on a price hold (`Discharge 0`) — `sellStartIso` / `sellPricePerKwh`: "Stored energy kept for 17:00 (43.7 ct)." Not `ElectricityPriceBelowThreshold`, which would say power is cheap for a command that stops the battery.
 
+**Not enough power to start.** `BelowMinPower` (category `Contention`) carries `powerW` for the power that was available and `minPowerW` for the minimum the appliance needs to start — e.g. "Only 4.1 kW left — needs at least 4.2 kW to start."
+
+**Left to its own control.** When the energy manager deliberately does not steer an appliance — e.g. a heat pump left alone at night on a static tariff — it states `SelfManaged` (category `Other`). This is the manager's choice not to steer, not the appliance overriding a plan (`ApplianceInitiatedDraw`) or declining power (`AppliancePaused`).
+
 **Installation limits.** Power capped by a limit the owner or installer set — not the grid operator — carries `InstallationLimit` (category `Contention`) with `powerW` set to the ceiling and `context.installationLimit` = `{source, limitW}`, where `source` is `EnyoInstallationLimitSourceEnum.DesiredGridLimit` (`desiredKwLimit`) or `ChargerLimit` (`chargerLimitW`). `limitW` is in **W** even for the desired limit, which is configured in kW. `GridOperatorPowerLimitationActive` stays reserved for limits the grid operator imposed.
 
 **Grid-optimised charging.** A cost-optimised session placed in, or waiting for, a low-load hour because of `gridOptimizedEvCharging` carries `GridLoadOptimized` (category `Schedule`) with `context.placement` (chosen window and deadline) and `context.gridLoad` (`epexPricePerKwh`, `currency`). The EPEX price is a grid-load proxy, not what the customer pays, so the text must not promise a saving — e.g. "Charging from 02:00, when the grid is less busy — ready by 07:00."

package/dist/cjs/types/enyo-charger-appliance.d.cts

@@ -143,6 +143,43 @@ export interface EnyoChargerApplianceMetadata {
      * cannot switch phases.
      */
     phaseSwitchThresholdKw?: number;
+    /**
+     * Lowest charging current, in Amperes per phase, the charger can hold a
+     * session at — typically `6` (the IEC 61851 minimum), higher on chargers
+     * that cannot regulate down that far.
+     *
+     * The EMS must not issue a non-zero current limit below it; a session is
+     * held at the higher of this value and the vehicle's
+     * {@link EnyoVehicle.minChargingCurrentAmpere}. Omit when unknown.
+     */
+    minChargingCurrentAmpere?: number;
+    /**
+     * Whether a charging session on this charger must not be paused once it
+     * has started — e.g. chargers that end the session or need a re-plug
+     * when the current is set to `0`.
+     *
+     * When `true`, the EMS must not pause the session (setpoint `0`) but hold
+     * it at least at its minimum current until it is complete. Applies if
+     * either this or the vehicle's {@link EnyoVehicle.cannotBePaused} is
+     * `true`. Omitted means `false`.
+     *
+     * @default false
+     */
+    cannotBePaused?: boolean;
+    /**
+     * Whether the EMS must not switch phases (1 ↔ 3) on this charger, even
+     * though the hardware supports it (see {@link availablePhases}) — e.g.
+     * because the installer disabled it or switching proved unreliable.
+     *
+     * When `true`, sessions stay in the phase configuration they started in,
+     * and {@link phaseSwitchThresholdKw}, {@link phaseSwitchDelaySeconds} and
+     * {@link phaseSwitchIntervalSeconds} are not used. Applies if either this
+     * or the vehicle's {@link EnyoVehicle.phaseSwitchDisabled} is `true`.
+     * Omitted means `false`.
+     *
+     * @default false
+     */
+    phaseSwitchDisabled?: boolean;
     /**
      * Granularity, in Amperes, at which the charging current limit can be set
      * on this charger. Any current limit the EMS issues should be a multiple of
@@ -166,6 +203,26 @@ export interface EnyoChargerApplianceMetadata {
      *   `ThreeToOnePhaseSwitch` feature)
      */
     availablePhases?: EnyoChargerAppliancePhase[];
+    /**
+     * Time, in seconds, the charger needs to carry out a phase switch after it
+     * has been triggered (e.g. 1 → 3 phases or 3 → 1 phase).
+     *
+     * During this delay the charger is still operating in the previous phase
+     * configuration; the EMS should not expect the new phase count to be in
+     * effect until it has elapsed. Only meaningful on chargers that can switch
+     * phases (see {@link availablePhases}). Omit when unknown.
+     */
+    phaseSwitchDelaySeconds?: number;
+    /**
+     * Minimum time, in seconds, the charger has to stay in a phase
+     * configuration after a phase switch before another phase switch is
+     * possible.
+     *
+     * The EMS must not trigger a new phase switch until this interval has
+     * passed since the last switch. Only meaningful on chargers that can switch
+     * phases (see {@link availablePhases}). Omit when unknown.
+     */
+    phaseSwitchIntervalSeconds?: number;
     /**
      * Whether the energy manager is allowed to actively control (steer) this
      * charger. When `false`, the charger is treated as read-only/monitor-only

package/dist/cjs/types/enyo-data-bus-value.cjs

@@ -213,7 +213,11 @@ var EnyoDataBusCommandReasonTypeEnum;
     /**
      * There is power available, but less than the appliance's minimum operating
      * point — switching it on would not be executable.
-     * {@link EnyoDataBusCommandReason.powerW} is the power that was available.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the power that was
+     * available and {@link EnyoDataBusCommandReason.minPowerW} to the minimum
+     * the appliance needs to start, so the text can say "Only 4.1 kW left —
+     * needs at least 4.2 kW to start."
      */
     EnyoDataBusCommandReasonTypeEnum["BelowMinPower"] = "below-min-power";
     /**
@@ -407,6 +411,19 @@ var EnyoDataBusCommandReasonTypeEnum;
      * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
      */
     EnyoDataBusCommandReasonTypeEnum["InstallationLimit"] = "installation-limit";
+    /**
+     * The appliance runs on its own control: the energy manager deliberately
+     * leaves it alone and issues no setpoint — e.g. a heat pump left to its
+     * own logic at night on a static tariff, where there is no cheaper hour to
+     * shift into and no PV surplus to use.
+     *
+     * A statement that the manager chose not to steer, not that the appliance
+     * overrode a plan: told apart from {@link ApplianceInitiatedDraw} (the
+     * appliance drew outside an allocation) and {@link AppliancePaused} (the
+     * appliance declined power it was given). Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.Other}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["SelfManaged"] = "self-managed";
 })(EnyoDataBusCommandReasonTypeEnum || (exports.EnyoDataBusCommandReasonTypeEnum = EnyoDataBusCommandReasonTypeEnum = {}));
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -229,7 +229,11 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     /**
      * There is power available, but less than the appliance's minimum operating
      * point — switching it on would not be executable.
-     * {@link EnyoDataBusCommandReason.powerW} is the power that was available.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the power that was
+     * available and {@link EnyoDataBusCommandReason.minPowerW} to the minimum
+     * the appliance needs to start, so the text can say "Only 4.1 kW left —
+     * needs at least 4.2 kW to start."
      */
     BelowMinPower = "below-min-power",
     /**
@@ -422,7 +426,20 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link GridOperatorPowerLimitationActive}, which would be untrue here.
      * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
      */
-    InstallationLimit = "installation-limit"
+    InstallationLimit = "installation-limit",
+    /**
+     * The appliance runs on its own control: the energy manager deliberately
+     * leaves it alone and issues no setpoint — e.g. a heat pump left to its
+     * own logic at night on a static tariff, where there is no cheaper hour to
+     * shift into and no PV surplus to use.
+     *
+     * A statement that the manager chose not to steer, not that the appliance
+     * overrode a plan: told apart from {@link ApplianceInitiatedDraw} (the
+     * appliance drew outside an allocation) and {@link AppliancePaused} (the
+     * appliance declined power it was given). Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.Other}.
+     */
+    SelfManaged = "self-managed"
 }
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -483,6 +500,14 @@ export interface EnyoDataBusCommandReason {
     capacityKwh?: number;
     /** Relevant power in Watts */
     powerW?: number;
+    /**
+     * Minimum power, in Watts, the appliance needs to start or keep running.
+     *
+     * Set on {@link EnyoDataBusCommandReasonTypeEnum.BelowMinPower} alongside
+     * {@link powerW} (the power that was available), so the text can contrast
+     * the two: "Only 4.1 kW left — needs at least 4.2 kW to start."
+     */
+    minPowerW?: number;
     /** Relevant energy in Watt hours */
     powerWh?: number;
     /** Relevant temperature in Celsius (e.g. heatpump-driven reasons) */

package/dist/cjs/types/enyo-vehicle.d.cts

@@ -47,6 +47,43 @@ export interface EnyoVehicle {
     maxChargingPowerKw?: number;
     /** How many phases the car charges over — typically `1` or `3`. */
     numberOfPhases?: number;
+    /**
+     * Lowest charging current, in Amperes per phase, the car accepts — e.g.
+     * `6` (the IEC 61851 minimum) or higher for cars that drop out of a
+     * session below a certain current.
+     *
+     * The EMS must not issue a non-zero current limit below it; a session is
+     * held at the higher of this value and the wallbox's
+     * {@link EnyoChargerApplianceMetadata.minChargingCurrentAmpere}. Omit when
+     * the car has no minimum beyond the wallbox's.
+     */
+    minChargingCurrentAmpere?: number;
+    /**
+     * Whether a charging session of this car must not be paused once it has
+     * started — some cars stop responding or end the session when charging
+     * is paused and do not resume on their own.
+     *
+     * When `true`, the EMS must not pause the session (setpoint `0`) but hold
+     * it at least at its minimum current until it is complete. Applies if
+     * either this or the wallbox's
+     * {@link EnyoChargerApplianceMetadata.cannotBePaused} is `true`. Omitted
+     * means `false`.
+     *
+     * @default false
+     */
+    cannotBePaused?: boolean;
+    /**
+     * Whether the EMS must not switch phases (1 ↔ 3) while this car charges —
+     * some cars abort the session or fault on a phase switch.
+     *
+     * When `true`, a session stays in the phase configuration it started in.
+     * Applies if either this or the wallbox's
+     * {@link EnyoChargerApplianceMetadata.phaseSwitchDisabled} is `true`.
+     * Omitted means `false`.
+     *
+     * @default false
+     */
+    phaseSwitchDisabled?: boolean;
     /** Target state of charge for every session, in percent (0-100). */
     defaultChargeLimitPercent?: number;
     /** The mode applied whenever this vehicle is recognised or picked. */

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.32.0';
+exports.SDK_VERSION = '1.33.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.32.0";
+export declare const SDK_VERSION = "1.33.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/types/enyo-charger-appliance.d.ts

@@ -143,6 +143,43 @@ export interface EnyoChargerApplianceMetadata {
      * cannot switch phases.
      */
     phaseSwitchThresholdKw?: number;
+    /**
+     * Lowest charging current, in Amperes per phase, the charger can hold a
+     * session at — typically `6` (the IEC 61851 minimum), higher on chargers
+     * that cannot regulate down that far.
+     *
+     * The EMS must not issue a non-zero current limit below it; a session is
+     * held at the higher of this value and the vehicle's
+     * {@link EnyoVehicle.minChargingCurrentAmpere}. Omit when unknown.
+     */
+    minChargingCurrentAmpere?: number;
+    /**
+     * Whether a charging session on this charger must not be paused once it
+     * has started — e.g. chargers that end the session or need a re-plug
+     * when the current is set to `0`.
+     *
+     * When `true`, the EMS must not pause the session (setpoint `0`) but hold
+     * it at least at its minimum current until it is complete. Applies if
+     * either this or the vehicle's {@link EnyoVehicle.cannotBePaused} is
+     * `true`. Omitted means `false`.
+     *
+     * @default false
+     */
+    cannotBePaused?: boolean;
+    /**
+     * Whether the EMS must not switch phases (1 ↔ 3) on this charger, even
+     * though the hardware supports it (see {@link availablePhases}) — e.g.
+     * because the installer disabled it or switching proved unreliable.
+     *
+     * When `true`, sessions stay in the phase configuration they started in,
+     * and {@link phaseSwitchThresholdKw}, {@link phaseSwitchDelaySeconds} and
+     * {@link phaseSwitchIntervalSeconds} are not used. Applies if either this
+     * or the vehicle's {@link EnyoVehicle.phaseSwitchDisabled} is `true`.
+     * Omitted means `false`.
+     *
+     * @default false
+     */
+    phaseSwitchDisabled?: boolean;
     /**
      * Granularity, in Amperes, at which the charging current limit can be set
      * on this charger. Any current limit the EMS issues should be a multiple of
@@ -166,6 +203,26 @@ export interface EnyoChargerApplianceMetadata {
      *   `ThreeToOnePhaseSwitch` feature)
      */
     availablePhases?: EnyoChargerAppliancePhase[];
+    /**
+     * Time, in seconds, the charger needs to carry out a phase switch after it
+     * has been triggered (e.g. 1 → 3 phases or 3 → 1 phase).
+     *
+     * During this delay the charger is still operating in the previous phase
+     * configuration; the EMS should not expect the new phase count to be in
+     * effect until it has elapsed. Only meaningful on chargers that can switch
+     * phases (see {@link availablePhases}). Omit when unknown.
+     */
+    phaseSwitchDelaySeconds?: number;
+    /**
+     * Minimum time, in seconds, the charger has to stay in a phase
+     * configuration after a phase switch before another phase switch is
+     * possible.
+     *
+     * The EMS must not trigger a new phase switch until this interval has
+     * passed since the last switch. Only meaningful on chargers that can switch
+     * phases (see {@link availablePhases}). Omit when unknown.
+     */
+    phaseSwitchIntervalSeconds?: number;
     /**
      * Whether the energy manager is allowed to actively control (steer) this
      * charger. When `false`, the charger is treated as read-only/monitor-only

package/dist/types/enyo-data-bus-value.d.ts

@@ -229,7 +229,11 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     /**
      * There is power available, but less than the appliance's minimum operating
      * point — switching it on would not be executable.
-     * {@link EnyoDataBusCommandReason.powerW} is the power that was available.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the power that was
+     * available and {@link EnyoDataBusCommandReason.minPowerW} to the minimum
+     * the appliance needs to start, so the text can say "Only 4.1 kW left —
+     * needs at least 4.2 kW to start."
      */
     BelowMinPower = "below-min-power",
     /**
@@ -422,7 +426,20 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link GridOperatorPowerLimitationActive}, which would be untrue here.
      * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
      */
-    InstallationLimit = "installation-limit"
+    InstallationLimit = "installation-limit",
+    /**
+     * The appliance runs on its own control: the energy manager deliberately
+     * leaves it alone and issues no setpoint — e.g. a heat pump left to its
+     * own logic at night on a static tariff, where there is no cheaper hour to
+     * shift into and no PV surplus to use.
+     *
+     * A statement that the manager chose not to steer, not that the appliance
+     * overrode a plan: told apart from {@link ApplianceInitiatedDraw} (the
+     * appliance drew outside an allocation) and {@link AppliancePaused} (the
+     * appliance declined power it was given). Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.Other}.
+     */
+    SelfManaged = "self-managed"
 }
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -483,6 +500,14 @@ export interface EnyoDataBusCommandReason {
     capacityKwh?: number;
     /** Relevant power in Watts */
     powerW?: number;
+    /**
+     * Minimum power, in Watts, the appliance needs to start or keep running.
+     *
+     * Set on {@link EnyoDataBusCommandReasonTypeEnum.BelowMinPower} alongside
+     * {@link powerW} (the power that was available), so the text can contrast
+     * the two: "Only 4.1 kW left — needs at least 4.2 kW to start."
+     */
+    minPowerW?: number;
     /** Relevant energy in Watt hours */
     powerWh?: number;
     /** Relevant temperature in Celsius (e.g. heatpump-driven reasons) */

package/dist/types/enyo-data-bus-value.js

@@ -210,7 +210,11 @@ export var EnyoDataBusCommandReasonTypeEnum;
     /**
      * There is power available, but less than the appliance's minimum operating
      * point — switching it on would not be executable.
-     * {@link EnyoDataBusCommandReason.powerW} is the power that was available.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the power that was
+     * available and {@link EnyoDataBusCommandReason.minPowerW} to the minimum
+     * the appliance needs to start, so the text can say "Only 4.1 kW left —
+     * needs at least 4.2 kW to start."
      */
     EnyoDataBusCommandReasonTypeEnum["BelowMinPower"] = "below-min-power";
     /**
@@ -404,6 +408,19 @@ export var EnyoDataBusCommandReasonTypeEnum;
      * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
      */
     EnyoDataBusCommandReasonTypeEnum["InstallationLimit"] = "installation-limit";
+    /**
+     * The appliance runs on its own control: the energy manager deliberately
+     * leaves it alone and issues no setpoint — e.g. a heat pump left to its
+     * own logic at night on a static tariff, where there is no cheaper hour to
+     * shift into and no PV surplus to use.
+     *
+     * A statement that the manager chose not to steer, not that the appliance
+     * overrode a plan: told apart from {@link ApplianceInitiatedDraw} (the
+     * appliance drew outside an allocation) and {@link AppliancePaused} (the
+     * appliance declined power it was given). Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.Other}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["SelfManaged"] = "self-managed";
 })(EnyoDataBusCommandReasonTypeEnum || (EnyoDataBusCommandReasonTypeEnum = {}));
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.

package/dist/types/enyo-vehicle.d.ts

@@ -47,6 +47,43 @@ export interface EnyoVehicle {
     maxChargingPowerKw?: number;
     /** How many phases the car charges over — typically `1` or `3`. */
     numberOfPhases?: number;
+    /**
+     * Lowest charging current, in Amperes per phase, the car accepts — e.g.
+     * `6` (the IEC 61851 minimum) or higher for cars that drop out of a
+     * session below a certain current.
+     *
+     * The EMS must not issue a non-zero current limit below it; a session is
+     * held at the higher of this value and the wallbox's
+     * {@link EnyoChargerApplianceMetadata.minChargingCurrentAmpere}. Omit when
+     * the car has no minimum beyond the wallbox's.
+     */
+    minChargingCurrentAmpere?: number;
+    /**
+     * Whether a charging session of this car must not be paused once it has
+     * started — some cars stop responding or end the session when charging
+     * is paused and do not resume on their own.
+     *
+     * When `true`, the EMS must not pause the session (setpoint `0`) but hold
+     * it at least at its minimum current until it is complete. Applies if
+     * either this or the wallbox's
+     * {@link EnyoChargerApplianceMetadata.cannotBePaused} is `true`. Omitted
+     * means `false`.
+     *
+     * @default false
+     */
+    cannotBePaused?: boolean;
+    /**
+     * Whether the EMS must not switch phases (1 ↔ 3) while this car charges —
+     * some cars abort the session or fault on a phase switch.
+     *
+     * When `true`, a session stays in the phase configuration it started in.
+     * Applies if either this or the wallbox's
+     * {@link EnyoChargerApplianceMetadata.phaseSwitchDisabled} is `true`.
+     * Omitted means `false`.
+     *
+     * @default false
+     */
+    phaseSwitchDisabled?: boolean;
     /** Target state of charge for every session, in percent (0-100). */
     defaultChargeLimitPercent?: number;
     /** The mode applied whenever this vehicle is recognised or picked. */

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.32.0";
+export declare const SDK_VERSION = "1.33.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '1.32.0';
+export const SDK_VERSION = '1.33.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",