@enyo-energy/energy-app-sdk 1.32.0 → 1.34.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
 
@@ -3150,11 +3153,12 @@ Drives a heatpump. Manages building / DHW overheating commands and grid-power-av
 
 > **Preferred: control heatpumps with the V3 messages.** `HeatpumpControlV3` (power, power sources, which zones to heat now, until when), `HeatpumpControlCancelV3` (cancel a session) and `HeatpumpControlStatusV3` (progress) are the preferred way to control a heatpump — for energy managers sending commands and for integrations receiving them. Use them for all new work. `HeatpumpOverheatingV1`, `SetHeatpumpAvailablePowerV2` and `HeatpumpAvailablePowerAnnouncementV1` are deprecated and only remain for heatpumps that do not declare `ControlV3`. See [HeatpumpControlV3](#heatpumpcontrolv3). Likewise, a heatpump offers its flexibility with `HeatpumpFlexibilityAnnouncementV3` rather than the generic `ApplianceFlexibilityAnnouncementV1` / `V2` — see [HeatpumpFlexibilityAnnouncementV3](#heatpumpflexibilityannouncementv3).
 
-- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
 - **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleSetHeatpumpAvailablePower`, `handleGridOperatorPowerLimitation`
 - **Optional overrides:**
   - `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
   - `handleHeatpumpControl` — support `HeatpumpControlV3` (see below). Answers `NotSupported` by default; override it and declare `ControlV3`.
+  - `handleHeatpumpProgramSwitch(request)` — switch a zone to comfort or eco, or back to its time program (see [HeatpumpProgramSwitchV3](#heatpumpprogramswitchv3)). Answers `NotSupported` by default; override it and declare `ProgramSwitch`.
   - `handleHeatpumpControlCancel` — withdraw a cancelled session on the device. By default `Accepted` for heatpumps declaring `ControlV3`, `NotSupported` otherwise.
   - `onHeatpumpControlEnded(applianceId, cause)` — return the heatpump to its own behaviour when a session ends; `cause` is `HeatpumpControlEndCauseEnum.Expired`, `Ended` or `Cancelled`. Does nothing by default.
   - `resolveHeatpumpMetadata(applianceId)` — the metadata actions are validated against. Defaults to the stored appliance's `heatpump` metadata.
@@ -3194,6 +3198,26 @@ One message per control session says **how much** power (`availablePowerW`), **f
   - DHW must stay within `domesticHotWater[].maxTemperatureC`: setpoint + `deltaK` above it is rejected.
   - When the session names an `offerId`, each action must fit the heatpump's current offer.
 
+#### HeatpumpProgramSwitchV3
+
+Switches one heating circuit or DHW zone to its **comfort** or **eco** setpoint regardless of the time program, or back to the **program** — e.g. eco while electricity is expensive, comfort while there is PV surplus. The temperatures are the user's own; the energy manager chooses only which of them applies. It comes with a reason (`EnyoDataBusCommandReason`), e.g. `ElectricityPriceAboveThreshold` or `PvSurplusAvailable`.
+
+```typescript
+{
+    target: EnyoHeatpumpControlTargetEnum.Room,       // Room or Dhw
+    index: 0,
+    mode: EnyoHeatpumpProgramModeEnum.Eco,             // Program | Comfort | Eco
+    untilIso: '2026-10-18T17:30:00.000Z',              // required for Comfort / Eco, at most 30 min ahead
+    reason: { type: EnyoDataBusCommandReasonTypeEnum.ElectricityPriceAboveThreshold },
+}
+```
+
+- **Only to heatpumps declaring `ProgramSwitch`**, and only with a mode the zone lists in `heatingCircuits[].supportedProgramModes` / `domesticHotWater[].supportedProgramModes`. `programModeTemperaturesC` (`{comfort: 22, eco: 20}`) tells the energy manager what eco means at this house, and `activeProgramMode` what the zone runs in right now — so it notices a manual change.
+- **One zone per message**, answered with a plain `CommandAcknowledgeV1`.
+- **Ending and safety net.** `mode: Program` ends a switch (idempotent). A switch to comfort or eco holds until `untilIso` (at most `HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES` = 30 min ahead); the energy manager re-sends about every 15 min while it should hold. When `untilIso` passes without a newer message, the base class calls `handleHeatpumpProgramSwitch` with `mode: Program` and `cause: HeatpumpProgramSwitchCauseEnum.Expired` — so after a restart of either side a zone is back on its program within 30 min, and the app stores nothing.
+- **Alongside `HeatpumpControlV3`.** The two run side by side: the mode sets the base, an action raises above it (eco 20 °C + room action +1 K = 21 °C).
+- **Validation** (run by the base class before the handler, or `validateHeatpumpProgramSwitch(data, metadata)` directly): target `Room` / `Dhw`, a known mode, a valid `untilIso` for comfort / eco (`Rejected`); `ProgramSwitch` declared and the mode listed for the zone (`NotSupported`); a known zone index (`Rejected`).
+
 #### HeatpumpFlexibilityAnnouncementV3
 
 The heatpump's offer, in the vocabulary of `HeatpumpControlV3`: per zone (`target` + `index`), how far it can be raised right now (`maxDeltaK` above `setpointC`, room in Kelvin of room temperature) and the smallest raise that actually starts it (`minDeltaK`, e.g. the remaining hysteresis), with which heat source at what power (`heatSources`: compressor and heating rod as separate entries, each with a `power` band and an optional `estimatedElectricalKwh` for the full raise), and when (`earliestStartIso` / `latestStartIso`, `minDurationMinutes`). An optional `required: {deltaK, byIso}` turns a "may" into a "must, by then" — e.g. hot water dropping below comfort at 18:00. Declare `FlexibilityAnnouncementV3` on the heatpump; for such heatpumps it supersedes the generic `ApplianceFlexibilityAnnouncementV1` / `V2`.
@@ -3226,6 +3250,7 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 |---|---|
 | `HeatingCurve` | `heatingCircuits[].heatingCurve` — outdoor → flow temperature `points` (vendor-neutral, linearly interpolated), plus raw `slope` / `parallelShiftK`, min / max flow and an optional cooling curve |
 | `TimeProgram` | `heatingCircuits[].timeProgram` and `domesticHotWater[].timeProgram` — weekly periods (`daysOfWeek` 0 = Sunday, local `HH:mm` times, may wrap past midnight) switching between `Comfort` / `Reduced` / `Off` / `Boost` |
+| `ProgramSwitch` | `heatingCircuits[].supportedProgramModes` / `programModeTemperaturesC` / `activeProgramMode` and the same on `domesticHotWater[]` — which zones can be switched to comfort / eco with `HeatpumpProgramSwitchV3`, at which setpoints, and the mode they run in now |
 | `RoomTemperature` | `heatingCircuits[].roomTemperatureC` in `HeatpumpTemperaturesUpdateV1`; where it is measured goes in `heatingCircuits[].roomTemperatureSource` (`None` / `Internal` / `External`) and, for an enyo sensor, `roomTemperatureSensor` |
 | `RoomTemperatureInput` | The heatpump accepts measured room temperatures via `SetHeatpumpRoomTemperatureV1` |
 | `PvSurplusSignal` | The heatpump takes `availablePowerW` of `HeatpumpControlV3` as a PV surplus signal (e.g. Lambda register 102). Supersedes the deprecated `AvailablePowerAnnouncement` |
@@ -4317,7 +4342,7 @@ Each event carries the **complete** picture of the slot — render it as it arri
 
 New reason types came with this surface, so a skipped row can say *why* instead of falling back to a generic "scheduled optimization": `SessionComplete`, `AppliancePaused`, `NothingConnected`, `DeadlinePassed`, `WaitingForCheaperSlot`, `AboveOwnPriceLimit`, `BelowMinPower`, `OtherApplianceTurn`, `SupplyExhausted`, `OutsideSchedule` — grouped by the new `SessionState` and `Contention` reason categories. `ApplianceInitiatedDraw` and `PowerOffered` came with the waterfall states above.
 
-**Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`), `socLimitPercent`, `allowanceWh` and `remainingWh`. The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history. The car's side of the same decision is stated on the charger's command with `EvChargingFromHomeBattery` (also category `BatteryState`): `powerW` is the battery's share of the charging setpoint (never the whole setpoint), `socPercent` the battery fleet's SoC, `context.batteryToEv` the owner's mode and the session's `socLimitPercent` / `allowanceWh` / `remainingWh` (never `trigger` or `probe`), and, under `Intelligent` only, `electricityPricePerKwh` is what the stored energy costs.
+**Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`, `NightReserve`), `socLimitPercent`, `allowanceWh`, `nightReserveWh` and `remainingWh`. Under `Intelligent`, `NightReserve` says the battery is held because only the night reserve is left — the house's load from dusk until PV covers it again — with `nightReserveWh` the energy kept, e.g. "The rest of the home battery (8.3 kWh) is kept for the house tonight, until the sun is back." The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history. The car's side of the same decision is stated on the charger's command with `EvChargingFromHomeBattery` (also category `BatteryState`): `powerW` is the battery's share of the charging setpoint (never the whole setpoint), `socPercent` the battery fleet's SoC, `context.batteryToEv` the owner's mode and the session's `socLimitPercent` / `allowanceWh` / `remainingWh` (never `trigger` or `probe`), and, under `Intelligent` only, `electricityPricePerKwh` is what the stored energy costs.
 
 **Battery first on PV surplus.** When a surplus consumer (EV on PV, heating rod, heat pump boost, surplus automation) is held back or reduced because the battery is charged first up to the owner's `batteryPvPriorityTargetSocPercent`, the energy manager states `BatteryPvPriority` (category `PvSurplus`) on that consumer: `context.batteryPvPriority.targetSocPercent` for the target, `socPercent` for the pack's current SoC and `powerW` for the surplus the battery is taking — e.g. "The battery charges to 40 % first (now 28 %)."
 
@@ -4327,6 +4352,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."
@@ -4337,6 +4366,8 @@ New reason types came with this surface, so a skipped row can say *why* instead
 
 A hold that keeps an appliance **off** after a stop has its own type, `RestartDelay` (category `DeviceProtection`): set `context.switching` with `hold: KeptOff`, `minOffSeconds` and `untilIso` (when it may restart), and `powerW` to the power waiting for it — e.g. "Short pause after switching off — charging resumes at 13:15 so the car isn't switched on and off too often."
 
+A session kept running because it **must not be paused** at all — the charger's or the car's `cannotBePaused` is `true` — has its own type, `CannotBePaused` (category `DeviceProtection`), with `powerW` set to the minimum it is held at and no `context.switching` — e.g. "Kept charging at the minimum of 1.4 kW — this car cannot pause charging." Do not send it as `DeviceProtection` / `KeptOn`: that reads "Kept running for its minimum run time", which is untrue for a hold that lasts until the session is complete.
+
 **Fluctuating PV surplus.** When the surplus jumps around (clouds passing) and the energy manager holds an appliance's power steady instead of following every dip, state `PvSurplusFluctuating` (category `PvSurplus`) with `powerW` set to the power being held — e.g. "Charging power held steady while clouds pass." / "Ladeleistung wird gehalten, solange Wolken durchziehen." It is a smoothing decision, told apart from `PvSurplusAvailable` / `PvSurplusUnavailable`.
 
 ## Dynamic Grid Fees & Tariff Bonuses

package/dist/cjs/implementations/heatpump/heatpump-control-validators.cjs

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HEATPUMP_CONTROL_TARGET_FEATURE = void 0;
+exports.HEATPUMP_PROGRAM_SWITCH_CLOCK_TOLERANCE_SECONDS = exports.HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES = exports.HEATPUMP_CONTROL_TARGET_FEATURE = void 0;
 exports.isPvOnlyPowerSources = isPvOnlyPowerSources;
 exports.validateHeatpumpControlAction = validateHeatpumpControlAction;
 exports.computeHeatpumpSetpointRaise = computeHeatpumpSetpointRaise;
+exports.validateHeatpumpProgramSwitch = validateHeatpumpProgramSwitch;
 const enyo_data_bus_value_js_1 = require("../../types/enyo-data-bus-value.cjs");
 const enyo_heatpump_appliance_js_1 = require("../../types/enyo-heatpump-appliance.cjs");
 /**
@@ -196,3 +197,90 @@ function computeHeatpumpSetpointRaise(input) {
     }
     return { ok: true, targetTemperatureC: target, appliedDeltaK: target - setpointC };
 }
+/**
+ * How far ahead `untilIso` of a `HeatpumpProgramSwitchV3` to `Comfort` or
+ * `Eco` may lie, in minutes. Bounds how long a zone stays switched when the
+ * energy manager stops re-sending (e.g. after a restart).
+ */
+exports.HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES = 30;
+/**
+ * Clock-skew tolerance on top of {@link HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES},
+ * in seconds, so an `untilIso` sent exactly 30 min ahead is not rejected
+ * because the two clocks differ slightly.
+ */
+exports.HEATPUMP_PROGRAM_SWITCH_CLOCK_TOLERANCE_SECONDS = 60;
+/**
+ * Validates a `HeatpumpProgramSwitchV3` against the heatpump's metadata and
+ * returns the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleHeatpumpProgramSwitch`; an integration handling the message itself
+ * can call it too.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. `target` is `Room` or `Dhw`, and `mode` is an
+ *    {@link EnyoHeatpumpProgramModeEnum} member (**Rejected**).
+ * 2. For `Comfort` / `Eco`: `untilIso` is an ISO 8601 timestamp in the future
+ *    and at most {@link HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES} minutes ahead
+ *    (plus {@link HEATPUMP_PROGRAM_SWITCH_CLOCK_TOLERANCE_SECONDS})
+ *    (**Rejected**).
+ * 3. The heatpump does not declare `ProgramSwitch` (**NotSupported**).
+ * 4. The metadata lists zones for the target but none with the message's
+ *    `index` (**Rejected**).
+ * 5. For `Comfort` / `Eco`: the zone does not list the mode in
+ *    `supportedProgramModes` (**NotSupported**).
+ *
+ * Without metadata only rules 1 and 2 can be checked.
+ *
+ * @param data - The message's data.
+ * @param metadata - The heatpump's metadata, if known.
+ * @param nowMs - The current time in epoch milliseconds; injectable for tests.
+ * @returns The answer: `Accepted` when every rule holds.
+ *
+ * @example
+ * ```typescript
+ * const result = validateHeatpumpProgramSwitch(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+function validateHeatpumpProgramSwitch(data, metadata, nowMs = Date.now()) {
+    const rejected = (rejectionReason) => ({ answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, rejectionReason });
+    const notSupported = (rejectionReason) => ({ answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported, rejectionReason });
+    if (data.target !== enyo_data_bus_value_js_1.EnyoHeatpumpControlTargetEnum.Room && data.target !== enyo_data_bus_value_js_1.EnyoHeatpumpControlTargetEnum.Dhw) {
+        return rejected(`Only room and dhw zones can be switched; got "${data.target}".`);
+    }
+    if (!Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum).includes(data.mode)) {
+        return rejected(`Unknown program mode "${data.mode}".`);
+    }
+    const isOverride = data.mode !== enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Program;
+    if (isOverride) {
+        const untilMs = data.untilIso !== undefined ? Date.parse(data.untilIso) : Number.NaN;
+        if (!Number.isFinite(untilMs)) {
+            return rejected(`A switch to ${data.mode} needs untilIso as an ISO 8601 timestamp; got ${data.untilIso}.`);
+        }
+        if (untilMs <= nowMs) {
+            return rejected(`untilIso ${data.untilIso} has already passed.`);
+        }
+        const maxMs = nowMs + exports.HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES * 60_000 + exports.HEATPUMP_PROGRAM_SWITCH_CLOCK_TOLERANCE_SECONDS * 1000;
+        if (untilMs > maxMs) {
+            return rejected(`untilIso ${data.untilIso} is more than ${exports.HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES} min ahead; ` +
+                're-send the switch instead of sending a far-off untilIso.');
+        }
+    }
+    if (!metadata)
+        return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+    if (!(metadata.availableFeatures ?? []).includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.ProgramSwitch)) {
+        return notSupported('The heatpump does not support program switches (no ProgramSwitch).');
+    }
+    const zones = data.target === enyo_data_bus_value_js_1.EnyoHeatpumpControlTargetEnum.Dhw ? metadata.domesticHotWater : metadata.heatingCircuits;
+    const zone = zones && zones.length > 0
+        ? (data.index === undefined ? zones[0] : zones.find((z) => z.index === data.index))
+        : undefined;
+    if (zones && zones.length > 0 && !zone) {
+        return rejected(`No ${data.target} zone with index ${data.index}.`);
+    }
+    if (isOverride && !(zone?.supportedProgramModes ?? []).includes(data.mode)) {
+        return notSupported(`The ${data.target} zone ${zone?.index ?? data.index ?? 0} cannot be switched to ${data.mode}.`);
+    }
+    return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+}

package/dist/cjs/implementations/heatpump/heatpump-control-validators.d.cts

@@ -1,4 +1,4 @@
-import { EnyoCommandAcknowledgeActionResult, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoHeatpumpControlAction, EnyoHeatpumpControlTargetEnum, EnyoPowerSourceShare } from '../../types/enyo-data-bus-value.cjs';
+import { EnyoCommandAcknowledgeActionResult, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoDataBusHeatpumpProgramSwitchV3, EnyoHeatpumpControlAction, EnyoHeatpumpControlTargetEnum, EnyoPowerSourceShare } from '../../types/enyo-data-bus-value.cjs';
 import { EnyoHeatpumpApplianceAvailableFeaturesEnum, EnyoHeatpumpApplianceMetadata } from '../../types/enyo-heatpump-appliance.cjs';
 /**
  * The overheating feature each `HeatpumpControlV3` target needs — and that a
@@ -121,3 +121,57 @@ export type HeatpumpSetpointRaiseResult = {
  * ```
  */
 export declare function computeHeatpumpSetpointRaise(input: HeatpumpSetpointRaiseInput): HeatpumpSetpointRaiseResult;
+/**
+ * How far ahead `untilIso` of a `HeatpumpProgramSwitchV3` to `Comfort` or
+ * `Eco` may lie, in minutes. Bounds how long a zone stays switched when the
+ * energy manager stops re-sending (e.g. after a restart).
+ */
+export declare const HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES = 30;
+/**
+ * Clock-skew tolerance on top of {@link HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES},
+ * in seconds, so an `untilIso` sent exactly 30 min ahead is not rejected
+ * because the two clocks differ slightly.
+ */
+export declare const HEATPUMP_PROGRAM_SWITCH_CLOCK_TOLERANCE_SECONDS = 60;
+/** The answer {@link validateHeatpumpProgramSwitch} gives a `HeatpumpProgramSwitchV3`. */
+export interface HeatpumpProgramSwitchValidationResult {
+    /** `Accepted` when every rule holds. */
+    answer: EnyoCommandAcknowledgeAnswerEnum;
+    /** Why the switch was rejected or is not supported. */
+    rejectionReason?: string;
+}
+/**
+ * Validates a `HeatpumpProgramSwitchV3` against the heatpump's metadata and
+ * returns the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleHeatpumpProgramSwitch`; an integration handling the message itself
+ * can call it too.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. `target` is `Room` or `Dhw`, and `mode` is an
+ *    {@link EnyoHeatpumpProgramModeEnum} member (**Rejected**).
+ * 2. For `Comfort` / `Eco`: `untilIso` is an ISO 8601 timestamp in the future
+ *    and at most {@link HEATPUMP_PROGRAM_SWITCH_MAX_MINUTES} minutes ahead
+ *    (plus {@link HEATPUMP_PROGRAM_SWITCH_CLOCK_TOLERANCE_SECONDS})
+ *    (**Rejected**).
+ * 3. The heatpump does not declare `ProgramSwitch` (**NotSupported**).
+ * 4. The metadata lists zones for the target but none with the message's
+ *    `index` (**Rejected**).
+ * 5. For `Comfort` / `Eco`: the zone does not list the mode in
+ *    `supportedProgramModes` (**NotSupported**).
+ *
+ * Without metadata only rules 1 and 2 can be checked.
+ *
+ * @param data - The message's data.
+ * @param metadata - The heatpump's metadata, if known.
+ * @param nowMs - The current time in epoch milliseconds; injectable for tests.
+ * @returns The answer: `Accepted` when every rule holds.
+ *
+ * @example
+ * ```typescript
+ * const result = validateHeatpumpProgramSwitch(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+export declare function validateHeatpumpProgramSwitch(data: EnyoDataBusHeatpumpProgramSwitchV3['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined, nowMs?: number): HeatpumpProgramSwitchValidationResult;

package/dist/cjs/implementations/heatpump/heatpump-metadata-validators.cjs

@@ -2,8 +2,8 @@
 /**
  * Client-side validation for the advanced heatpump metadata an integration
  * publishes: heating curves ({@link EnyoHeatpumpApplianceHeatingCurve}), time
- * programs ({@link EnyoHeatpumpTimeProgram}) and the room-temperature wiring of
- * heating circuits.
+ * programs ({@link EnyoHeatpumpTimeProgram}), the room-temperature wiring of
+ * heating circuits and the program-switch modes of circuits and DHW zones.
  *
  * None of these shapes can be checked at the type level — a curve with one
  * point, an unsorted curve, `'25:00'` as a switching time or a period on day
@@ -45,6 +45,41 @@ const MINUTES_PER_DAY = 24 * 60;
 const MINUTES_PER_WEEK = 7 * MINUTES_PER_DAY;
 const TIME_OF_DAY = /^([01]\d|2[0-3]):([0-5]\d)$/;
 const LEVELS = new Set(Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpTimeProgramLevelEnum));
+const PROGRAM_MODES = new Set(Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum));
+const OVERRIDE_PROGRAM_MODES = new Set([enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Comfort, enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Eco]);
+/**
+ * Validates the program-switch fields of one heating circuit or DHW zone
+ * (`supportedProgramModes`, `programModeTemperaturesC`, `activeProgramMode`)
+ * and appends the problems to `errors` / `warnings`.
+ *
+ * @param zone - The heating circuit or DHW zone.
+ * @param prefix - Path prefix for the messages, e.g. `heatingCircuits[index=0]`.
+ * @param errors - Receives blocking problems.
+ * @param warnings - Receives advisory problems.
+ */
+function checkProgramModes(zone, prefix, errors, warnings) {
+    for (const mode of zone.supportedProgramModes ?? []) {
+        if (!OVERRIDE_PROGRAM_MODES.has(mode)) {
+            errors.push(`${prefix}: supportedProgramModes may only list comfort and eco; got "${mode}"`);
+        }
+    }
+    const temperatures = zone.programModeTemperaturesC ?? {};
+    for (const [mode, temperatureC] of Object.entries(temperatures)) {
+        if (!OVERRIDE_PROGRAM_MODES.has(mode)) {
+            errors.push(`${prefix}: programModeTemperaturesC may only have comfort and eco; got "${mode}"`);
+        }
+        else if (!isFiniteNumber(temperatureC)) {
+            errors.push(`${prefix}: programModeTemperaturesC.${mode} must be a finite number`);
+        }
+    }
+    const { comfort, eco } = temperatures;
+    if (isFiniteNumber(comfort) && isFiniteNumber(eco) && eco > comfort) {
+        warnings.push(`${prefix}: programModeTemperaturesC.eco ${eco} °C is above comfort ${comfort} °C`);
+    }
+    if (zone.activeProgramMode !== undefined && !PROGRAM_MODES.has(zone.activeProgramMode)) {
+        errors.push(`${prefix}: activeProgramMode "${zone.activeProgramMode}" is not a valid value`);
+    }
+}
 /**
  * Parses an `HH:mm` time of day into minutes since midnight.
  *
@@ -289,6 +324,12 @@ function assertValidHeatpumpTimeProgram(program) {
  *    disagree, so pre-heating may be planned where the heatpump does nothing.
  *  - Error: a circuit's `heatingControlReference` is not an
  *    `EnyoHeatpumpHeatingControlReferenceEnum` member.
+ *  - Error: a circuit's or DHW zone's `supportedProgramModes` or
+ *    `programModeTemperaturesC` name a mode other than comfort and eco, a
+ *    temperature is not finite, or `activeProgramMode` is not an
+ *    `EnyoHeatpumpProgramModeEnum` member. Warning: eco is above comfort.
+ *  - Warning: `ProgramSwitch` is declared but no zone lists
+ *    `supportedProgramModes`, or a zone lists them without `ProgramSwitch`.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.
@@ -325,6 +366,20 @@ function validateHeatpumpAdvancedMetadata(metadata) {
             warnings.push(`${v3} is declared without any overheating feature — no action could ever be taken`);
         }
     }
+    const switchableZones = [
+        ...circuits.map((c) => ({ zone: c, prefix: `heatingCircuits[index=${c.index}]` })),
+        ...dhwZones.map((z) => ({ zone: z, prefix: `domesticHotWater[index=${z.index}]` })),
+    ];
+    const declaresProgramSwitch = features.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.ProgramSwitch);
+    for (const { zone, prefix } of switchableZones) {
+        checkProgramModes(zone, prefix, errors, warnings);
+        if (!declaresProgramSwitch && (zone.supportedProgramModes ?? []).length > 0) {
+            warnings.push(`${prefix}: supportedProgramModes are listed but the heatpump does not declare ProgramSwitch`);
+        }
+    }
+    if (declaresProgramSwitch && !switchableZones.some(({ zone }) => (zone.supportedProgramModes ?? []).length > 0)) {
+        warnings.push('ProgramSwitch is declared but no zone lists supportedProgramModes — no switch could ever be accepted');
+    }
     for (const circuit of circuits) {
         const prefix = `heatingCircuits[index=${circuit.index}]`;
         if (circuit.heatingCurve)

package/dist/cjs/implementations/heatpump/heatpump-metadata-validators.d.cts

@@ -1,8 +1,8 @@
 /**
  * Client-side validation for the advanced heatpump metadata an integration
  * publishes: heating curves ({@link EnyoHeatpumpApplianceHeatingCurve}), time
- * programs ({@link EnyoHeatpumpTimeProgram}) and the room-temperature wiring of
- * heating circuits.
+ * programs ({@link EnyoHeatpumpTimeProgram}), the room-temperature wiring of
+ * heating circuits and the program-switch modes of circuits and DHW zones.
  *
  * None of these shapes can be checked at the type level — a curve with one
  * point, an unsorted curve, `'25:00'` as a switching time or a period on day
@@ -107,6 +107,12 @@ export declare function assertValidHeatpumpTimeProgram(program: EnyoHeatpumpTime
  *    disagree, so pre-heating may be planned where the heatpump does nothing.
  *  - Error: a circuit's `heatingControlReference` is not an
  *    `EnyoHeatpumpHeatingControlReferenceEnum` member.
+ *  - Error: a circuit's or DHW zone's `supportedProgramModes` or
+ *    `programModeTemperaturesC` name a mode other than comfort and eco, a
+ *    temperature is not finite, or `activeProgramMode` is not an
+ *    `EnyoHeatpumpProgramModeEnum` member. Warning: eco is above comfort.
+ *  - Warning: `ProgramSwitch` is declared but no zone lists
+ *    `supportedProgramModes`, or a zone lists them without `ProgramSwitch`.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.

package/dist/cjs/integrations/heatpump-integration-energy-app.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HeatpumpIntegrationEnergyApp = exports.HEATPUMP_FLEXIBILITY_DEFAULT_REPEAT_EVERY_SECONDS = exports.HEATPUMP_FLEXIBILITY_DEFAULT_VALID_FOR_SECONDS = void 0;
+exports.HeatpumpIntegrationEnergyApp = exports.HeatpumpProgramSwitchCauseEnum = exports.HEATPUMP_FLEXIBILITY_DEFAULT_REPEAT_EVERY_SECONDS = exports.HEATPUMP_FLEXIBILITY_DEFAULT_VALID_FOR_SECONDS = void 0;
 exports.combineHeatpumpControlAnswers = combineHeatpumpControlAnswers;
 const integration_energy_app_js_1 = require("./integration-energy-app.cjs");
 const enyo_appliance_js_1 = require("../types/enyo-appliance.cjs");
@@ -13,6 +13,20 @@ const heatpump_control_session_js_1 = require("../implementations/heatpump/heatp
 exports.HEATPUMP_FLEXIBILITY_DEFAULT_VALID_FOR_SECONDS = 900;
 /** Default interval at which a published heatpump flexibility offer is repeated, in seconds. */
 exports.HEATPUMP_FLEXIBILITY_DEFAULT_REPEAT_EVERY_SECONDS = 300;
+/**
+ * Why {@link HeatpumpIntegrationEnergyApp.handleHeatpumpProgramSwitch} is called.
+ */
+var HeatpumpProgramSwitchCauseEnum;
+(function (HeatpumpProgramSwitchCauseEnum) {
+    /** The energy manager sent a `HeatpumpProgramSwitchV3`. */
+    HeatpumpProgramSwitchCauseEnum["Command"] = "command";
+    /**
+     * A switch to comfort or eco reached its `untilIso` without a newer
+     * message; the base class switches the zone back to
+     * {@link EnyoHeatpumpProgramModeEnum.Program}.
+     */
+    HeatpumpProgramSwitchCauseEnum["Expired"] = "expired";
+})(HeatpumpProgramSwitchCauseEnum || (exports.HeatpumpProgramSwitchCauseEnum = HeatpumpProgramSwitchCauseEnum = {}));
 /**
  * Combines the answers of a `HeatpumpControlV3` session — the power and each
  * action — into the session's top-level answer: `Accepted` as soon as one part
@@ -43,6 +57,12 @@ function combineHeatpumpControlAnswers(answers) {
  *    and calls {@link onHeatpumpControlEnded} when it ends.
  *  - `HeatpumpControlCancelV3` — cancel one `HeatpumpControlV3` session right
  *    away (optional: override {@link handleHeatpumpControlCancel}).
+ *  - `HeatpumpProgramSwitchV3` — switch a heating circuit or DHW zone to its
+ *    comfort or eco setpoint, or back to its time program (optional: override
+ *    {@link handleHeatpumpProgramSwitch} and declare
+ *    {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.ProgramSwitch}). The
+ *    base class validates it and switches the zone back when `untilIso`
+ *    passes.
  *  - `HeatpumpOverheatingV1` — overheating commands (room / buffer tank / DHW).
  *    Deprecated in favour of `HeatpumpControlV3`.
  *  - `HeatpumpAvailablePowerAnnouncementV1` — available power announcements.
@@ -92,6 +112,8 @@ function combineHeatpumpControlAnswers(answers) {
 class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.IntegrationEnergyApp {
     heatpumpFlexibilityOffers = new Map();
     heatpumpControlSessions = new heatpump_control_session_js_1.HeatpumpControlSessionTracker((applianceId) => void this.notifyHeatpumpControlEnded(applianceId, heatpump_control_session_js_1.HeatpumpControlEndCauseEnum.Expired));
+    /** Expiry timers of the zones currently switched to comfort or eco, by {@link heatpumpProgramSwitchKey}. */
+    heatpumpProgramSwitchTimers = new Map();
     /**
      * @param options - Standard integration options (see {@link IntegrationEnergyAppOptions}).
      */
@@ -108,15 +130,21 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetHeatpumpRoomTemperatureV1, (msg) => this.handleSetHeatpumpRoomTemperature(msg));
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpControlV3, (msg) => this.dispatchHeatpumpControl(msg));
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpControlCancelV3, (msg) => this.dispatchHeatpumpControlCancel(msg));
+        this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpProgramSwitchV3, (msg) => this.dispatchHeatpumpProgramSwitch(msg));
     }
     /**
      * Stops the integration, drops every running `HeatpumpControlV3` session
-     * and its expiry timer, and stops repeating published flexibility offers.
-     * The offers already sent lapse at their `validUntilIso`.
+     * and its expiry timer, drops the expiry timers of program switches, and
+     * stops repeating published flexibility offers. The offers already sent
+     * lapse at their `validUntilIso`. Zones switched to comfort or eco are not
+     * switched back on stop.
      */
     stop() {
         super.stop();
         this.heatpumpControlSessions.dispose();
+        for (const timer of this.heatpumpProgramSwitchTimers.values())
+            clearTimeout(timer);
+        this.heatpumpProgramSwitchTimers.clear();
         for (const offer of this.heatpumpFlexibilityOffers.values()) {
             if (offer.timer !== undefined)
                 clearInterval(offer.timer);
@@ -280,6 +308,43 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
         }
         return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
     }
+    /**
+     * Switches one zone of the heatpump to a mode — for a
+     * `HeatpumpProgramSwitchV3` from the energy manager
+     * ({@link HeatpumpProgramSwitchCauseEnum.Command}), and back to
+     * {@link EnyoHeatpumpProgramModeEnum.Program} when such a switch reached
+     * its `untilIso` without a newer message
+     * ({@link HeatpumpProgramSwitchCauseEnum.Expired}). Answers `NotSupported`
+     * by default. Override it, declare
+     * {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.ProgramSwitch}, and
+     * list the zone's `supportedProgramModes` to support program switches.
+     *
+     * What an implementation must do:
+     * - `Comfort` / `Eco`: run the zone at the user's comfort or eco setpoint,
+     *   regardless of the time program — never a temperature of its own.
+     * - `Program`: return the zone to its time program and undo whatever the
+     *   switch wrote. Must be idempotent: it is also called when nothing is
+     *   switched.
+     * - The same mode arrives again about every 15 min as the energy manager
+     *   renews the switch; skip the device write when nothing changed.
+     *
+     * The base class has already validated the request with
+     * {@link validateHeatpumpProgramSwitch} and keeps the expiry timer: it is
+     * armed when a switch to `Comfort` / `Eco` is answered `Accepted`, renewed
+     * by every further accepted switch, and cleared by an accepted `Program`.
+     * On expiry the answer is only logged.
+     *
+     * @param _request - The zone, the mode, and why.
+     * @returns `Accepted` once the mode is written, `Rejected` (with
+     *   `rejectionReason`) when the zone cannot be switched right now,
+     *   `NotSupported` when the integration cannot switch modes.
+     */
+    async handleHeatpumpProgramSwitch(_request) {
+        return {
+            answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported,
+            rejectionReason: 'Heatpump integration does not support HeatpumpProgramSwitchV3',
+        };
+    }
     /**
      * Called when a `HeatpumpControlV3` session ends, with why:
      * {@link HeatpumpControlEndCauseEnum.Expired} (no repeat by
@@ -508,6 +573,58 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
         }
         return response;
     }
+    async dispatchHeatpumpProgramSwitch(message) {
+        const { applianceId, data } = message;
+        const metadata = await this.resolveHeatpumpMetadata(applianceId);
+        const validation = (0, heatpump_control_validators_js_1.validateHeatpumpProgramSwitch)(data, metadata);
+        if (validation.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted) {
+            return validation;
+        }
+        const isOverride = data.mode !== enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Program;
+        const response = await this.handleHeatpumpProgramSwitch({
+            applianceId,
+            target: data.target,
+            ...(data.index !== undefined ? { index: data.index } : {}),
+            mode: data.mode,
+            ...(isOverride && data.untilIso !== undefined ? { untilIso: data.untilIso } : {}),
+            ...(data.reason !== undefined ? { reason: data.reason } : {}),
+            cause: HeatpumpProgramSwitchCauseEnum.Command,
+        });
+        if (response.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted) {
+            return response;
+        }
+        const key = heatpumpProgramSwitchKey(applianceId, data.target, data.index);
+        const previous = this.heatpumpProgramSwitchTimers.get(key);
+        if (previous !== undefined)
+            clearTimeout(previous);
+        this.heatpumpProgramSwitchTimers.delete(key);
+        if (isOverride) {
+            const delayMs = Math.max(0, Date.parse(data.untilIso) - Date.now());
+            this.heatpumpProgramSwitchTimers.set(key, setTimeout(() => {
+                this.heatpumpProgramSwitchTimers.delete(key);
+                void this.expireHeatpumpProgramSwitch(applianceId, data.target, data.index);
+            }, delayMs));
+        }
+        return response;
+    }
+    async expireHeatpumpProgramSwitch(applianceId, target, index) {
+        try {
+            const response = await this.handleHeatpumpProgramSwitch({
+                applianceId,
+                target,
+                ...(index !== undefined ? { index } : {}),
+                mode: enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Program,
+                cause: HeatpumpProgramSwitchCauseEnum.Expired,
+            });
+            if (response.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted) {
+                console.warn(`HeatpumpIntegrationEnergyApp: switching ${target} ${index ?? 0} of ${applianceId} back to its program ` +
+                    `after expiry was answered ${response.answer}: ${response.rejectionReason ?? ''}`);
+            }
+        }
+        catch (error) {
+            console.error(`HeatpumpIntegrationEnergyApp: switching ${target} ${index ?? 0} of ${applianceId} back to its program failed`, error);
+        }
+    }
     async dispatchHeatpumpControlCancel(message) {
         const response = await this.handleHeatpumpControlCancel(message);
         if (response.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported
@@ -518,3 +635,14 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
     }
 }
 exports.HeatpumpIntegrationEnergyApp = HeatpumpIntegrationEnergyApp;
+/**
+ * Key of one zone's program-switch timer.
+ *
+ * @param applianceId - The heatpump appliance.
+ * @param target - Room or DHW.
+ * @param index - The zone index; omitted counts as `0`.
+ * @returns E.g. `heatpump-1|room:0`.
+ */
+function heatpumpProgramSwitchKey(applianceId, target, index) {
+    return `${applianceId}|${target}:${index ?? 0}`;
+}