@enyo-energy/energy-app-sdk 1.42.0 → 1.43.0

package/README.md

@@ -3666,12 +3666,13 @@ 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`, `HeatpumpProgramSwitchV3`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `SetHeatpumpHeatingCurveOffsetV1`, `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`.
+  - `handleHeatpumpHeatingCurveOffset(message)` — shift a heating circuit's curve permanently, relative to its initial curve (see [SetHeatpumpHeatingCurveOffsetV1](#setheatpumpheatingcurveoffsetv1)). Answers `NotSupported` by default; override it and declare `HeatingCurveOffset`.
   - `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.
@@ -3732,6 +3733,44 @@ Switches one heating circuit or DHW zone to its **comfort** or **eco** setpoint
 - **Owner's consent for price-driven eco.** An energy manager switches zones to eco for price reasons only while the general setting `heatpumpEcoModeInExpensiveTimes` (and `heatpumpControl`) is `true` — see [General settings](#general-settings).
 - **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`).
 
+#### SetHeatpumpHeatingCurveOffsetV1
+
+Shifts the heating curve of one heating circuit in parallel — **permanently**, until the next message. The energy manager uses it to lower the curve as far as the measured room temperature allows (less flow temperature, roughly 2.5 % less heating electricity per K).
+
+```typescript
+{
+    heatingCircuitIndex: 0,
+    offsetK: -1.5,   // K of flow temperature, relative to the initial curve; 0 restores it
+}
+```
+
+- **Relative to the initial curve, never to the current one.** Before the first offset other than `0`, the integration stores the curve set on the device as `heatingCircuits[].initialHeatingCurve` (`ApplianceManager.rememberHeatpumpInitialHeatingCurve` keeps an already stored one). The same message may therefore arrive twice.
+- **`offsetK: 0` restores** the initial curve exactly, including vendor parameters, then clears it (`ApplianceManager.clearHeatpumpInitialHeatingCurve`, which also sets `activeHeatingCurveOffsetK` to `0`).
+- **No expiry.** If the hub is offline nobody could reset it anyway; the stored initial curve is the safety net.
+- **Vendor units.** Convert to whatever the device shifts in (K of room temperature, steps, …) and report the effective shift in K of flow temperature as `heatingCircuits[].activeHeatingCurveOffsetK`, read back from the device. The energy manager waits for it before the next change.
+- **Changed by hand.** If the curve read from the device differs from `initialHeatingCurve` shifted by `activeHeatingCurveOffsetK` by more than 0.5 K at any point (`isHeatingCurveManuallyChanged(initial, offsetK, read)`), store the read curve as the new `initialHeatingCurve`, set `activeHeatingCurveOffsetK` to `0` and log it in a plain sentence.
+- **Alongside `HeatpumpControlV3` and `HeatpumpProgramSwitchV3`.** Boost and eco act on top; the offset is the new base.
+- **Validation** (run by the base class before the handler via `checkHeatingCurveOffset`, or `validateHeatpumpHeatingCurveOffset(data, metadata)` directly): a valid index and finite `offsetK` (`Rejected`); `HeatingCurveOffset` declared (`NotSupported`); a known circuit and — unless `offsetK` is `0` — within `heatingCurveOffsetRangeK` (`Rejected`).
+- **Customer settings.** Whether to optimise at all, and which rooms of the home the circuit heats (`roomIds`, whether or not a room has a sensor), live in `heatingCircuits[].curveOptimization`. The host resolves them into `rooms`: per room its target temperature (set in the enyo app, `HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C` = 21 °C until then) and the temperature sensors assigned to it. Rooms without a sensor are left out; the room furthest below its target counts, and the curve is lowered by at most `HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K` (3 K). Integrations only read them.
+
+```typescript
+protected async handleHeatpumpHeatingCurveOffset(message: EnyoDataBusSetHeatpumpHeatingCurveOffsetV1) {
+    const {heatingCircuitIndex: index, offsetK} = message.data;
+    if (offsetK !== 0) {
+        await this.appliances.rememberHeatpumpInitialHeatingCurve(message.applianceId, index, await this.readCurve(index));
+    }
+    await this.device.writeCurveShift(index, offsetK);
+    if (offsetK === 0) {
+        await this.appliances.clearHeatpumpInitialHeatingCurve(message.applianceId, index);
+    } else {
+        await this.appliances.updateHeatpumpHeatingCircuit(message.applianceId, index, {
+            activeHeatingCurveOffsetK: await this.readEffectiveShiftK(index),
+        });
+    }
+    return {answer: EnyoCommandAcknowledgeAnswerEnum.Accepted};
+}
+```
+
 #### 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`.
@@ -3767,6 +3806,9 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 | `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` |
+| `HeatingCurveOffset` | The heatpump's app shifts a circuit's curve via `SetHeatpumpHeatingCurveOffsetV1`. `heatingCircuits[].heatingCurveOffsetRangeK` (allowed range, must contain 0), `activeHeatingCurveOffsetK` (effective shift read back) and `initialHeatingCurve` (the curve before the first shift) |
+| — | `heatingCircuits[].curveOptimization` — the customer's choice for the room-temperature based curve optimisation: `enabled` (off by default), `roomIds` (the rooms the circuit heats) and, resolved by the host, `rooms` — per room `roomId`, `name`, its `targetRoomTemperatureC` (16–26 °C) and the `sensors` assigned to it. Customer-owned; integrations only read it |
+| — | `building.recommendedHeatingCurve` — the curve the building actually needs, learned from the days the room held its target |
 | `PvSurplusSignal` | The heatpump takes `availablePowerW` of `HeatpumpControlV3` as a PV surplus signal (e.g. Lambda register 102). Supersedes the deprecated `AvailablePowerAnnouncement` |
 | `ControlV3` | The heatpump's app handles `HeatpumpControlV3` / `HeatpumpControlCancelV3` and reports `HeatpumpControlStatusV3`. The energy manager sends V3 only to heatpumps declaring it. Needs at least one overheating feature to be actionable |
 | `FlexibilityAnnouncementV3` | The heatpump publishes `HeatpumpFlexibilityAnnouncementV3` offers; the energy manager plans from them instead of deriving the headroom from metadata. Needs at least one overheating feature to be actionable |

package/dist/cjs/implementations/appliances/appliance-manager.cjs

@@ -618,6 +618,62 @@ class ApplianceManager {
         await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { domesticHotWater: zones } }), applianceId);
         await this.primeCacheFromSdk(applianceId);
     }
+    /**
+     * Remembers the heating curve a circuit had before the first
+     * `SetHeatpumpHeatingCurveOffsetV1` changed it, as the circuit's
+     * `initialHeatingCurve` — the curve `offsetK: 0` restores. Call it before
+     * writing the first offset other than `0`.
+     *
+     * Keeps an already stored initial curve: every later offset is relative to
+     * the curve before the *first* change, so it must not be overwritten with
+     * an already shifted one. Works like {@link updateHeatpumpHeatingCircuit}
+     * otherwise.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @param curve The curve currently set on the device
+     * @returns `true` when the curve was stored, `false` when an initial curve
+     *   was already stored or the appliance does not exist
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async rememberHeatpumpInitialHeatingCurve(applianceId, index, curve) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return false;
+        const circuit = appliance.heatpump?.heatingCircuits?.find(c => c.index === index);
+        if (circuit?.initialHeatingCurve)
+            return false;
+        await this.updateHeatpumpHeatingCircuit(applianceId, index, { initialHeatingCurve: curve });
+        return true;
+    }
+    /**
+     * Forgets a circuit's `initialHeatingCurve` after the integration restored
+     * it on the device (`offsetK: 0`), and sets `activeHeatingCurveOffsetK` to
+     * `0`. Other circuits and fields are left untouched.
+     *
+     * Does nothing when the appliance or the circuit does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async clearHeatpumpInitialHeatingCurve(applianceId, index) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return;
+        const circuits = [...(appliance.heatpump?.heatingCircuits ?? [])];
+        const position = circuits.findIndex(c => c.index === index);
+        if (position < 0)
+            return;
+        const { initialHeatingCurve: _removed, ...rest } = circuits[position];
+        circuits[position] = { ...rest, activeHeatingCurveOffsetK: 0 };
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { heatingCircuits: circuits } }), applianceId);
+        await this.primeCacheFromSdk(applianceId);
+    }
     /**
      * Refetches an appliance from the SDK and reflects the result in the
      * cache. Used by mutating methods to keep cache reads consistent with

package/dist/cjs/implementations/appliances/appliance-manager.d.cts

@@ -3,7 +3,7 @@ import type { EnyoNetworkDevice } from "../../types/enyo-network-device.cjs";
 import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceGroup, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
 import type { EnyoApplianceCreatedFilter } from "../../packages/energy-app-appliance.cjs";
 import type { EnyoChargerApplianceMetadata } from "../../types/enyo-charger-appliance.cjs";
-import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
+import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceHeatingCurve, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
 import type { EnyoBatteryApplianceMetadata } from "../../types/enyo-battery-appliance.cjs";
 import type { EnyoInverterApplianceMetadata } from "../../types/enyo-inverter-appliance.cjs";
 import type { EnyoMeterAppliance } from "../../types/enyo-meter-appliance.cjs";
@@ -401,6 +401,39 @@ export declare class ApplianceManager {
      * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
      */
     updateHeatpumpDomesticHotWater(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceDomesticHotWater, 'index'>>): Promise<void>;
+    /**
+     * Remembers the heating curve a circuit had before the first
+     * `SetHeatpumpHeatingCurveOffsetV1` changed it, as the circuit's
+     * `initialHeatingCurve` — the curve `offsetK: 0` restores. Call it before
+     * writing the first offset other than `0`.
+     *
+     * Keeps an already stored initial curve: every later offset is relative to
+     * the curve before the *first* change, so it must not be overwritten with
+     * an already shifted one. Works like {@link updateHeatpumpHeatingCircuit}
+     * otherwise.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @param curve The curve currently set on the device
+     * @returns `true` when the curve was stored, `false` when an initial curve
+     *   was already stored or the appliance does not exist
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    rememberHeatpumpInitialHeatingCurve(applianceId: string, index: number, curve: EnyoHeatpumpApplianceHeatingCurve): Promise<boolean>;
+    /**
+     * Forgets a circuit's `initialHeatingCurve` after the integration restored
+     * it on the device (`offsetK: 0`), and sets `activeHeatingCurveOffsetK` to
+     * `0`. Other circuits and fields are left untouched.
+     *
+     * Does nothing when the appliance or the circuit does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    clearHeatpumpInitialHeatingCurve(applianceId: string, index: number): Promise<void>;
     /**
      * Refetches an appliance from the SDK and reflects the result in the
      * cache. Used by mutating methods to keep cache reads consistent with

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

@@ -5,6 +5,7 @@ exports.isPvOnlyPowerSources = isPvOnlyPowerSources;
 exports.validateHeatpumpControlAction = validateHeatpumpControlAction;
 exports.computeHeatpumpSetpointRaise = computeHeatpumpSetpointRaise;
 exports.validateHeatpumpProgramSwitch = validateHeatpumpProgramSwitch;
+exports.validateHeatpumpHeatingCurveOffset = validateHeatpumpHeatingCurveOffset;
 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");
 /**
@@ -284,3 +285,63 @@ function validateHeatpumpProgramSwitch(data, metadata, nowMs = Date.now()) {
     }
     return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
 }
+/**
+ * Validates a `SetHeatpumpHeatingCurveOffsetV1` against the heatpump's
+ * metadata and returns the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleHeatpumpHeatingCurveOffset`; an integration handling the message
+ * itself can call it too.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. `heatingCircuitIndex` is an integer ≥ 0 and `offsetK` a finite number
+ *    (**Rejected**).
+ * 2. The heatpump does not declare `HeatingCurveOffset` (**NotSupported**).
+ * 3. No heating circuit has the message's index (**Rejected**).
+ * 4. `offsetK` is not `0` and the circuit has no `heatingCurveOffsetRangeK`
+ *    or `offsetK` lies outside it (**Rejected**). `0` — restoring the initial
+ *    curve — is always allowed.
+ *
+ * Without metadata only rule 1 can be checked.
+ *
+ * @param data - The message's data.
+ * @param metadata - The heatpump's metadata, if known.
+ * @returns The answer: `Accepted` when every rule holds.
+ *
+ * @example
+ * ```typescript
+ * const result = validateHeatpumpHeatingCurveOffset(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+function validateHeatpumpHeatingCurveOffset(data, metadata) {
+    const rejected = (rejectionReason) => ({ answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, rejectionReason });
+    if (!Number.isInteger(data.heatingCircuitIndex) || data.heatingCircuitIndex < 0) {
+        return rejected(`heatingCircuitIndex must be an integer ≥ 0; got ${data.heatingCircuitIndex}.`);
+    }
+    if (typeof data.offsetK !== 'number' || !Number.isFinite(data.offsetK)) {
+        return rejected(`offsetK must be a finite number; got ${data.offsetK}.`);
+    }
+    if (!metadata)
+        return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+    if (!(metadata.availableFeatures ?? []).includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingCurveOffset)) {
+        return {
+            answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported,
+            rejectionReason: 'The heatpump does not support heating curve offsets (no HeatingCurveOffset).',
+        };
+    }
+    const circuit = (metadata.heatingCircuits ?? []).find((c) => c.index === data.heatingCircuitIndex);
+    if (!circuit) {
+        return rejected(`No heating circuit with index ${data.heatingCircuitIndex}.`);
+    }
+    if (data.offsetK === 0)
+        return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+    const range = circuit.heatingCurveOffsetRangeK;
+    if (!range) {
+        return rejected(`Heating circuit ${circuit.index} declares no heatingCurveOffsetRangeK; only offsetK 0 is accepted.`);
+    }
+    if (data.offsetK < range.minK || data.offsetK > range.maxK) {
+        return rejected(`offsetK ${data.offsetK} K is outside the range ${range.minK}…${range.maxK} K of heating circuit ${circuit.index}.`);
+    }
+    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, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoDataBusHeatpumpProgramSwitchV3, EnyoHeatpumpControlAction, EnyoHeatpumpControlTargetEnum, EnyoPowerSourceShare } from '../../types/enyo-data-bus-value.cjs';
+import { EnyoCommandAcknowledgeActionResult, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoDataBusHeatpumpProgramSwitchV3, EnyoDataBusSetHeatpumpHeatingCurveOffsetV1, 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
@@ -175,3 +175,40 @@ export interface HeatpumpProgramSwitchValidationResult {
  * ```
  */
 export declare function validateHeatpumpProgramSwitch(data: EnyoDataBusHeatpumpProgramSwitchV3['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined, nowMs?: number): HeatpumpProgramSwitchValidationResult;
+/** The answer {@link validateHeatpumpHeatingCurveOffset} gives a `SetHeatpumpHeatingCurveOffsetV1`. */
+export interface HeatpumpHeatingCurveOffsetValidationResult {
+    /** `Accepted` when every rule holds. */
+    answer: EnyoCommandAcknowledgeAnswerEnum;
+    /** Why the offset was rejected or is not supported. */
+    rejectionReason?: string;
+}
+/**
+ * Validates a `SetHeatpumpHeatingCurveOffsetV1` against the heatpump's
+ * metadata and returns the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleHeatpumpHeatingCurveOffset`; an integration handling the message
+ * itself can call it too.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. `heatingCircuitIndex` is an integer ≥ 0 and `offsetK` a finite number
+ *    (**Rejected**).
+ * 2. The heatpump does not declare `HeatingCurveOffset` (**NotSupported**).
+ * 3. No heating circuit has the message's index (**Rejected**).
+ * 4. `offsetK` is not `0` and the circuit has no `heatingCurveOffsetRangeK`
+ *    or `offsetK` lies outside it (**Rejected**). `0` — restoring the initial
+ *    curve — is always allowed.
+ *
+ * Without metadata only rule 1 can be checked.
+ *
+ * @param data - The message's data.
+ * @param metadata - The heatpump's metadata, if known.
+ * @returns The answer: `Accepted` when every rule holds.
+ *
+ * @example
+ * ```typescript
+ * const result = validateHeatpumpHeatingCurveOffset(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+export declare function validateHeatpumpHeatingCurveOffset(data: EnyoDataBusSetHeatpumpHeatingCurveOffsetV1['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined): HeatpumpHeatingCurveOffsetValidationResult;

package/dist/cjs/implementations/heatpump/heatpump-heating-curve-offset.cjs

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Pure helpers for `SetHeatpumpHeatingCurveOffsetV1`: shifting a heating curve
+ * by an offset, reading a flow temperature off a curve, and telling whether
+ * someone changed the curve on the device by hand.
+ *
+ * No I/O — persisting the initial curve is done with
+ * `ApplianceManager.rememberHeatpumpInitialHeatingCurve` /
+ * `ApplianceManager.clearHeatpumpInitialHeatingCurve`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEATPUMP_HEATING_CURVE_MANUAL_CHANGE_TOLERANCE_K = void 0;
+exports.interpolateHeatingCurve = interpolateHeatingCurve;
+exports.shiftHeatingCurve = shiftHeatingCurve;
+exports.isHeatingCurveManuallyChanged = isHeatingCurveManuallyChanged;
+/**
+ * How far, in Kelvin of flow temperature, the curve read from the device may
+ * differ from `initialHeatingCurve + activeHeatingCurveOffsetK` at any point
+ * before it counts as changed by hand.
+ */
+exports.HEATPUMP_HEATING_CURVE_MANUAL_CHANGE_TOLERANCE_K = 0.5;
+/**
+ * Reads the target flow temperature off a curve at an outdoor temperature:
+ * linear interpolation between neighbouring points, clamped to the first /
+ * last point outside the covered range — the way every consumer of
+ * {@link EnyoHeatpumpApplianceHeatingCurve.points} reads it.
+ *
+ * @param points - The curve points, sorted by increasing outdoor temperature.
+ * @param outdoorTemperatureC - The outdoor temperature in °C.
+ * @returns The flow temperature in °C, or `undefined` for an empty curve.
+ *
+ * @example
+ * ```ts
+ * interpolateHeatingCurve(curve.points, 7.5); // 30.0 between (5 → 31.4) and (10 → 28.5)
+ * ```
+ */
+function interpolateHeatingCurve(points, outdoorTemperatureC) {
+    if (points.length === 0)
+        return undefined;
+    const first = points[0];
+    const last = points[points.length - 1];
+    if (outdoorTemperatureC <= first.outdoorTemperatureC)
+        return first.flowTemperatureC;
+    if (outdoorTemperatureC >= last.outdoorTemperatureC)
+        return last.flowTemperatureC;
+    for (let i = 1; i < points.length; i++) {
+        const right = points[i];
+        if (outdoorTemperatureC <= right.outdoorTemperatureC) {
+            const left = points[i - 1];
+            const share = (outdoorTemperatureC - left.outdoorTemperatureC)
+                / (right.outdoorTemperatureC - left.outdoorTemperatureC);
+            return left.flowTemperatureC + share * (right.flowTemperatureC - left.flowTemperatureC);
+        }
+    }
+    return last.flowTemperatureC;
+}
+/**
+ * Shifts a heating curve in parallel: every point's flow temperature (and
+ * every cooling point's) moves by `offsetK`. The vendor parameters and the
+ * flow temperature bounds are kept as they are — the device still clamps to
+ * them.
+ *
+ * @param curve - The curve to shift, typically the circuit's `initialHeatingCurve`.
+ * @param offsetK - The shift in Kelvin of flow temperature; negative lowers.
+ * @returns A new curve; `curve` is not modified.
+ *
+ * @example
+ * ```ts
+ * const expected = shiftHeatingCurve(circuit.initialHeatingCurve, -1.5);
+ * ```
+ */
+function shiftHeatingCurve(curve, offsetK) {
+    const shift = (points) => points.map((p) => ({ ...p, flowTemperatureC: p.flowTemperatureC + offsetK }));
+    return {
+        ...curve,
+        points: shift(curve.points),
+        ...(curve.coolingPoints ? { coolingPoints: shift(curve.coolingPoints) } : {}),
+    };
+}
+/**
+ * Whether the heating curve read from the device was changed by hand — i.e.
+ * it differs from `initialCurve` shifted by `activeOffsetK` by more than
+ * `toleranceK` at any point of either curve.
+ *
+ * When it returns `true`, the integration stores `readCurve` as the new
+ * `initialHeatingCurve`, sets `activeHeatingCurveOffsetK` to `0` and logs it
+ * in a plain sentence; the energy manager sees the jump to `0` and restarts
+ * its controller.
+ *
+ * @param initialCurve - The circuit's stored `initialHeatingCurve`.
+ * @param activeOffsetK - The offset in K the integration believes is in effect.
+ * @param readCurve - The curve just read from the device.
+ * @param toleranceK - Allowed difference per point, in K. Defaults to
+ *   {@link HEATPUMP_HEATING_CURVE_MANUAL_CHANGE_TOLERANCE_K}.
+ * @returns `true` when the curve was changed by hand.
+ *
+ * @example
+ * ```ts
+ * if (circuit.initialHeatingCurve
+ *     && isHeatingCurveManuallyChanged(circuit.initialHeatingCurve, circuit.activeHeatingCurveOffsetK ?? 0, read)) {
+ *     console.info('The heating curve was changed on the device; it is the new starting point.');
+ *     await applianceManager.updateHeatpumpHeatingCircuit(id, 0, {
+ *         heatingCurve: read, initialHeatingCurve: read, activeHeatingCurveOffsetK: 0,
+ *     });
+ * }
+ * ```
+ */
+function isHeatingCurveManuallyChanged(initialCurve, activeOffsetK, readCurve, toleranceK = exports.HEATPUMP_HEATING_CURVE_MANUAL_CHANGE_TOLERANCE_K) {
+    const expected = shiftHeatingCurve(initialCurve, activeOffsetK).points;
+    const read = readCurve.points;
+    if (expected.length === 0 || read.length === 0)
+        return expected.length !== read.length;
+    const outdoorTemperatures = [...expected, ...read].map((p) => p.outdoorTemperatureC);
+    return outdoorTemperatures.some((outdoorC) => {
+        const a = interpolateHeatingCurve(expected, outdoorC);
+        const b = interpolateHeatingCurve(read, outdoorC);
+        return Math.abs(a - b) > toleranceK;
+    });
+}

package/dist/cjs/implementations/heatpump/heatpump-heating-curve-offset.d.cts

@@ -0,0 +1,77 @@
+/**
+ * Pure helpers for `SetHeatpumpHeatingCurveOffsetV1`: shifting a heating curve
+ * by an offset, reading a flow temperature off a curve, and telling whether
+ * someone changed the curve on the device by hand.
+ *
+ * No I/O — persisting the initial curve is done with
+ * `ApplianceManager.rememberHeatpumpInitialHeatingCurve` /
+ * `ApplianceManager.clearHeatpumpInitialHeatingCurve`.
+ */
+import type { EnyoHeatpumpApplianceHeatingCurve, EnyoHeatpumpApplianceHeatingCurvePoint } from '../../types/enyo-heatpump-appliance.cjs';
+/**
+ * How far, in Kelvin of flow temperature, the curve read from the device may
+ * differ from `initialHeatingCurve + activeHeatingCurveOffsetK` at any point
+ * before it counts as changed by hand.
+ */
+export declare const HEATPUMP_HEATING_CURVE_MANUAL_CHANGE_TOLERANCE_K = 0.5;
+/**
+ * Reads the target flow temperature off a curve at an outdoor temperature:
+ * linear interpolation between neighbouring points, clamped to the first /
+ * last point outside the covered range — the way every consumer of
+ * {@link EnyoHeatpumpApplianceHeatingCurve.points} reads it.
+ *
+ * @param points - The curve points, sorted by increasing outdoor temperature.
+ * @param outdoorTemperatureC - The outdoor temperature in °C.
+ * @returns The flow temperature in °C, or `undefined` for an empty curve.
+ *
+ * @example
+ * ```ts
+ * interpolateHeatingCurve(curve.points, 7.5); // 30.0 between (5 → 31.4) and (10 → 28.5)
+ * ```
+ */
+export declare function interpolateHeatingCurve(points: EnyoHeatpumpApplianceHeatingCurvePoint[], outdoorTemperatureC: number): number | undefined;
+/**
+ * Shifts a heating curve in parallel: every point's flow temperature (and
+ * every cooling point's) moves by `offsetK`. The vendor parameters and the
+ * flow temperature bounds are kept as they are — the device still clamps to
+ * them.
+ *
+ * @param curve - The curve to shift, typically the circuit's `initialHeatingCurve`.
+ * @param offsetK - The shift in Kelvin of flow temperature; negative lowers.
+ * @returns A new curve; `curve` is not modified.
+ *
+ * @example
+ * ```ts
+ * const expected = shiftHeatingCurve(circuit.initialHeatingCurve, -1.5);
+ * ```
+ */
+export declare function shiftHeatingCurve(curve: EnyoHeatpumpApplianceHeatingCurve, offsetK: number): EnyoHeatpumpApplianceHeatingCurve;
+/**
+ * Whether the heating curve read from the device was changed by hand — i.e.
+ * it differs from `initialCurve` shifted by `activeOffsetK` by more than
+ * `toleranceK` at any point of either curve.
+ *
+ * When it returns `true`, the integration stores `readCurve` as the new
+ * `initialHeatingCurve`, sets `activeHeatingCurveOffsetK` to `0` and logs it
+ * in a plain sentence; the energy manager sees the jump to `0` and restarts
+ * its controller.
+ *
+ * @param initialCurve - The circuit's stored `initialHeatingCurve`.
+ * @param activeOffsetK - The offset in K the integration believes is in effect.
+ * @param readCurve - The curve just read from the device.
+ * @param toleranceK - Allowed difference per point, in K. Defaults to
+ *   {@link HEATPUMP_HEATING_CURVE_MANUAL_CHANGE_TOLERANCE_K}.
+ * @returns `true` when the curve was changed by hand.
+ *
+ * @example
+ * ```ts
+ * if (circuit.initialHeatingCurve
+ *     && isHeatingCurveManuallyChanged(circuit.initialHeatingCurve, circuit.activeHeatingCurveOffsetK ?? 0, read)) {
+ *     console.info('The heating curve was changed on the device; it is the new starting point.');
+ *     await applianceManager.updateHeatpumpHeatingCircuit(id, 0, {
+ *         heatingCurve: read, initialHeatingCurve: read, activeHeatingCurveOffsetK: 0,
+ *     });
+ * }
+ * ```
+ */
+export declare function isHeatingCurveManuallyChanged(initialCurve: EnyoHeatpumpApplianceHeatingCurve, activeOffsetK: number, readCurve: EnyoHeatpumpApplianceHeatingCurve, toleranceK?: number): boolean;

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

@@ -80,6 +80,67 @@ function checkProgramModes(zone, prefix, errors, warnings) {
         errors.push(`${prefix}: activeProgramMode "${zone.activeProgramMode}" is not a valid value`);
     }
 }
+/** Range the customer may choose for a room's `targetRoomTemperatureC`, in °C. */
+const CURVE_OPTIMIZATION_TARGET_RANGE_C = { min: 16, max: 26 };
+/**
+ * Validates the heating-curve-offset fields of one heating circuit
+ * (`heatingCurveOffsetRangeK`, `activeHeatingCurveOffsetK`,
+ * `curveOptimization`) and appends the problems to `errors`.
+ *
+ * Errors: the range is not finite or does not contain `0`; the active offset
+ * is not finite or lies outside the range; a room id is empty; a resolved room
+ * lacks its `roomId`, a sensor lacks its `applianceId` / `sensorId`, or its
+ * target lies outside 16…26 °C.
+ *
+ * @param circuit - The heating circuit.
+ * @param prefix - Path prefix for the messages, e.g. `heatingCircuits[index=0]`.
+ * @param errors - Receives blocking problems.
+ */
+function checkHeatingCurveOffset(circuit, prefix, errors) {
+    const range = circuit.heatingCurveOffsetRangeK;
+    const rangeValid = range !== undefined && isFiniteNumber(range.minK) && isFiniteNumber(range.maxK);
+    if (range !== undefined) {
+        if (!rangeValid) {
+            errors.push(`${prefix}: heatingCurveOffsetRangeK.minK and maxK must be finite numbers`);
+        }
+        else if (!(range.minK <= 0 && range.maxK >= 0)) {
+            errors.push(`${prefix}: heatingCurveOffsetRangeK ${range.minK}…${range.maxK} K must contain 0`);
+        }
+    }
+    const active = circuit.activeHeatingCurveOffsetK;
+    if (active !== undefined) {
+        if (!isFiniteNumber(active)) {
+            errors.push(`${prefix}: activeHeatingCurveOffsetK must be a finite number`);
+        }
+        else if (rangeValid && (active < range.minK || active > range.maxK)) {
+            errors.push(`${prefix}: activeHeatingCurveOffsetK ${active} K is outside heatingCurveOffsetRangeK ${range.minK}…${range.maxK} K`);
+        }
+    }
+    const settings = circuit.curveOptimization;
+    if (!settings)
+        return;
+    (settings.roomIds ?? []).forEach((roomId, i) => {
+        if (typeof roomId !== 'string' || roomId.length === 0) {
+            errors.push(`${prefix}: curveOptimization.roomIds[${i}] must be a non-empty string`);
+        }
+    });
+    (settings.rooms ?? []).forEach((room, i) => {
+        if (!room?.roomId) {
+            errors.push(`${prefix}: curveOptimization.rooms[${i}] needs a roomId`);
+        }
+        (room?.sensors ?? []).forEach((sensor, j) => {
+            if (!sensor?.applianceId || !sensor?.sensorId) {
+                errors.push(`${prefix}: curveOptimization.rooms[${i}].sensors[${j}] needs applianceId and sensorId`);
+            }
+        });
+        const target = room?.targetRoomTemperatureC;
+        if (!(isFiniteNumber(target)
+            && target >= CURVE_OPTIMIZATION_TARGET_RANGE_C.min && target <= CURVE_OPTIMIZATION_TARGET_RANGE_C.max)) {
+            errors.push(`${prefix}: curveOptimization.rooms[${i}].targetRoomTemperatureC must lie within ` +
+                `${CURVE_OPTIMIZATION_TARGET_RANGE_C.min}…${CURVE_OPTIMIZATION_TARGET_RANGE_C.max} °C; got ${target}`);
+        }
+    });
+}
 /**
  * Parses an `HH:mm` time of day into minutes since midnight.
  *
@@ -330,6 +391,9 @@ function assertValidHeatpumpTimeProgram(program) {
  *    `EnyoHeatpumpProgramModeEnum` member. Warning: eco is above comfort.
  *  - Warning: `ProgramSwitch` is declared but no zone lists
  *    `supportedProgramModes`, or a zone lists them without `ProgramSwitch`.
+ *  - Heating curve offset: errors from {@link checkHeatingCurveOffset}.
+ *    Warning: `HeatingCurveOffset` is declared but no circuit has a
+ *    `heatingCurveOffsetRangeK` — no offset other than `0` could be accepted.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.
@@ -380,10 +444,18 @@ function validateHeatpumpAdvancedMetadata(metadata) {
     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');
     }
+    if (features.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingCurveOffset)
+        && !circuits.some((c) => c.heatingCurveOffsetRangeK)) {
+        warnings.push('HeatingCurveOffset is declared but no heating circuit has a heatingCurveOffsetRangeK — only offset 0 could be accepted');
+    }
     for (const circuit of circuits) {
         const prefix = `heatingCircuits[index=${circuit.index}]`;
         if (circuit.heatingCurve)
             merge(`${prefix}.heatingCurve`, validateHeatpumpHeatingCurve(circuit.heatingCurve));
+        checkHeatingCurveOffset(circuit, prefix, errors);
+        if (circuit.initialHeatingCurve) {
+            merge(`${prefix}.initialHeatingCurve`, validateHeatpumpHeatingCurve(circuit.initialHeatingCurve));
+        }
         if (circuit.timeProgram)
             merge(`${prefix}.timeProgram`, validateHeatpumpTimeProgram(circuit.timeProgram));
         const isExternal = circuit.roomTemperatureSource === enyo_heatpump_appliance_js_1.EnyoHeatpumpRoomTemperatureSourceEnum.External;

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

@@ -113,6 +113,9 @@ export declare function assertValidHeatpumpTimeProgram(program: EnyoHeatpumpTime
  *    `EnyoHeatpumpProgramModeEnum` member. Warning: eco is above comfort.
  *  - Warning: `ProgramSwitch` is declared but no zone lists
  *    `supportedProgramModes`, or a zone lists them without `ProgramSwitch`.
+ *  - Heating curve offset: errors from {@link checkHeatingCurveOffset}.
+ *    Warning: `HeatingCurveOffset` is declared but no circuit has a
+ *    `heatingCurveOffsetRangeK` — no offset other than `0` could be accepted.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.

package/dist/cjs/index.cjs

@@ -109,6 +109,7 @@ __exportStar(require("./implementations/heatpump/heatpump-metadata-validators.cj
 __exportStar(require("./implementations/heatpump/heatpump-control-validators.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-control-session.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-flexibility-validators.cjs"), exports);
+__exportStar(require("./implementations/heatpump/heatpump-heating-curve-offset.cjs"), exports);
 __exportStar(require("./types/enyo-inverter-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding.cjs"), exports);
 __exportStar(require("./packages/energy-app-onboarding.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -93,6 +93,7 @@ export * from './implementations/heatpump/heatpump-metadata-validators.cjs';
 export * from './implementations/heatpump/heatpump-control-validators.cjs';
 export * from './implementations/heatpump/heatpump-control-session.cjs';
 export * from './implementations/heatpump/heatpump-flexibility-validators.cjs';
+export * from './implementations/heatpump/heatpump-heating-curve-offset.cjs';
 export * from './types/enyo-inverter-appliance.cjs';
 export * from './types/enyo-onboarding.cjs';
 export * from './packages/energy-app-onboarding.cjs';