@enyo-energy/energy-app-sdk 1.25.0 → 1.27.0

package/README.md

@@ -191,6 +191,7 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Read EPEX SPOT wholesale prices (incl. negative-price windows) | [`useEpexSpotPrices()`](#useepexspotprices-energyappepexspotprice) |
 | Manage electricity tariffs (default tariff, price per kWh) | [`useElectricityTariff()`](#useelectricitytariff-energyappelectricitytariff) |
 | Publish or resolve time-variable grid fees (§14a HT/NT) | [`useGridFee()`](#usegridfee-energyappgridfee) |
+| Price appliances behind a cascade meter (own tariff, prices and grid fee) | [`useCascade()`](#usecascade-energyappcascade) |
 | Register a PV system (kWp, DC strings, orientation) | [`usePvSystem()`](#usepvsystem-energyapppvsystem) |
 | Discover capabilities of the active energy manager | [`useEnergyManager()`](#useenergymanager-energyappenergymanager) |
 | Serve your v2 onboarding guides when the host asks for them | [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2) |
@@ -249,6 +250,7 @@ Every Energy App must be defined using `defineEnergyAppPackage()`:
 import {
     defineEnergyAppPackage,
     EnergyAppPackageCategory,
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum,
     EnergyAppPermissionTypeEnum
 } from '@enyo-energy/energy-app-sdk';
 
@@ -291,11 +293,22 @@ const packageDef = defineEnergyAppPackage({
         },
         deviceDetection: {
             modbus: [{
+                // Optional, only on the first entry: how the entries and their matching
+                // values combine. Default: RegistersOr_MatchingValuesOr.
+                mode: EnergyAppPackageOptionsDeviceDetectionModbusModeEnum.RegistersAnd_MatchingValuesOr,
                 unitIds: [1],
                 registerAddress: 40001,
                 registerSize: 2,
                 type: 'string',
                 matchingValues: ['SolarMax', 'SMA']
+            }, {
+                unitIds: [1],
+                // `registerType` defaults to 'holding'; use 'input' for function code 4.
+                registerType: 'input',
+                registerAddress: 30053,
+                registerSize: 2,
+                type: 'UInt32BE',
+                matchingValues: ['9401', '9402']
             }],
             mdns: [{
                 // The Envoy advertises under a vendor-specific service type; without
@@ -1703,6 +1716,18 @@ const prices = await tariffs.getPrices(EnyoTariffDirectionEnum.Consumption, { fr
 const needsGridFee = !prices?.includes.includes(EnyoPriceComponentEnum.GridFee);
 ```
 
+To price one device, ask for the prices that actually bill it. This works for every appliance: the
+site's consumption prices, or — for an appliance behind an active [meter cascade](#usecascade-energyappcascade)
+— the cascade's, filled per 15-minute slot. The prices are effective prices (grid fee and taxes
+included, see `includes`), so never add a grid fee on top:
+
+```typescript
+const billed = await tariffs.getPricesForAppliance('heatpump-1', { fromIso, untilIso });
+// billed.billingMeter: 'primary' | 'cascade'
+// entry.fallback: cascade had no price for this slot, the site's was used
+// billed.inheritedFromSite: cascade has no tariff of its own yet
+```
+
 The app that integrates a provider owns the other side. It answers when the user picks it, sets the
 tariff once it is actually usable, and pushes prices as they arrive:
 
@@ -1773,6 +1798,115 @@ const fees = await gridFee.getGridFeeValues({ fromIso, untilIso });
 
 Publishers need `GridFeeRegister`; consumers need `GridFeeUse`.
 
+#### `useCascade(): EnergyAppCascade`
+
+A **meter cascade** (Kaskadenschaltung) is a second billing meter (Z2) installed *behind* the primary
+meter (Z1) — typically for a heatpump or wallbox on a dedicated tariff with a reduced (§14a EnWG) grid
+fee. Appliances behind an **active** Z2 are billed on the cascade's tariff and grid fee; everything else
+on `useElectricityTariff()` and `useGridFee()`. The site has at most one cascade, and Z2 has a
+**consumption tariff only** — all feed-in leaves through Z1.
+
+**Split rule.** PV and battery cover Z2 first; Z2 only pays the cascade tariff for what Z1 imports at the
+same moment. Z1 importing 2 kW, battery 1 kW, Z2 drawing 2 kW → Z2 grid share 1 kW, Z2 self-consumed
+1 kW, household grid share 1 kW.
+
+Topology — is there a cascade, is it working, who is behind it:
+
+```typescript
+const cascade = energyApp.useCascade();
+
+const details = await cascade.getCascade();   // active, status, estimated, meterApplianceId?, applianceIds
+if (details?.active && details.status !== EnyoCascadeStatusEnum.Live) {
+    // 'noCascadeSource' (nothing assigned yet) or 'noGridReading' (no Z1 reading)
+}
+cascade.onCascadeChanged(event => reassignPrices(event.cascade));
+```
+
+With `estimated: true`, Z2 is the sum of its appliances and has no meter (`meterApplianceId` absent).
+A physical Z2 meter carries the topology feature `CascadeSubMeter` — skip it when looking for the grid
+meter.
+
+Prices — to price a device, use `useElectricityTariff().getPricesForAppliance(applianceId, range)`. It
+works for every appliance and picks Z2 or Z1 itself, returning the **effective** price per 15-minute slot,
+grid fee and taxes included. `cascade.getPrices(range)` returns Z2's effective prices directly. Never add
+a grid fee on top:
+
+```typescript
+const prices = await energyApp.useElectricityTariff().getPricesForAppliance('heatpump-1', { fromIso, untilIso });
+// prices.billingMeter: 'cascade' | 'primary'
+// entry.fallback: Z2 had no price for that slot, the site's was used
+// prices.inheritedFromSite: Z2 has no tariff of its own yet
+```
+
+Until Z2 has its own tariff or grid fee, the hub prices it with the site's — and so do `getTariff`,
+`getPrices`, `getGridFee` and `getGridFeeValues`: they return the site's values with
+`inheritedFromSite: true` rather than `null`. The grid fee methods are informational (to show the fee
+separately).
+
+What Z2 is actually drawing and costing — live via the `CascadeSplitUpdateV1` data bus message
+(`householdGridW`, `cascadeGridW`, `cascadeSelfConsumedW`, `subMeterPowerW`, `status`, `estimated` — the
+same values the cockpit shows), and as history:
+
+```typescript
+energyApp.useDataBus().listenForMessages([EnyoDataBusMessageEnum.CascadeSplitUpdateV1], msg => {
+    const { cascadeGridW, status } = (msg as EnyoDataBusCascadeSplitUpdateV1).data;
+});
+
+const history = await cascade.getCascadeTimeseries({ fromIso, untilIso, resolution: '1d' });
+// resolution: '1m' (kept 31 days) | '15m' | '1d' | '1mo'
+// per bucket: householdGridKwh, cascadeGridKwh, cascadeSelfConsumedKwh,
+//             householdCostCt, cascadeCostCt, cascadePriceCt, estimated
+```
+
+History costs are in **ct**, priced when read with the tariffs then in force.
+
+**The core owns the cascade tariff by default** — the user enters it in the hub. The cascade **grid fee
+comes with the tariff**: it is provided by the core, or by the app that owns the cascade tariff, and goes
+away with that app's ownership. An app that provides a
+**dynamic** tariff can offer itself for Z2 and take it over once the user selects it, then publish its
+prices:
+
+```typescript
+// Registering the handler is what lists this app in the hub's cascade tariff selection.
+cascade.onTariffSelected(async () => {
+    if (!await isAuthenticated()) {
+        return {
+            status: EnyoTariffActivationStatusEnum.AuthenticationRequired,
+            authenticationUrl: buildOAuthUrl('cascade'),
+        };
+    }
+    await cascade.setTariff({                                 // takes over the slot from the core
+        name: 'Tibber Wärmepumpe',
+        vendorName: 'Tibber',
+        currency: EnyoCurrencyEnum.EUR,
+        pricing: { type: EnyoTariffPricingTypeEnum.Dynamic }, // only dynamic tariffs can be app-provided
+        externalTariffId: contract.id,
+    });
+    return { status: EnyoTariffActivationStatusEnum.Success };
+});
+
+await cascade.publishPrices({ includes: [], entries });      // only while this app owns Z2's tariff
+await cascade.registerGridFee(reducedGridFee);              // optional: the Z2 grid fee comes with the tariff
+
+cascade.onTariffChanged(event => {
+    if (event.tariff?.externalTariffId !== contract.id) stopPublishing(); // lost ownership
+});
+```
+
+| Group | Methods | Permission |
+|---|---|---|
+| Topology | `isActive`, `getCascade`, `getApplianceIds`, `isApplianceBehindCascade`, `onCascadeChanged` | none |
+| Prices & tariff (read) | `getTariff`, `getPrices`, `onTariffChanged` | none |
+| History | `getCascadeTimeseries` | `Timeseries` |
+| Grid fee | `getGridFee`, `getGridFeeValues`, `onGridFeeChanged` / `registerGridFee`, `removeGridFee` (cascade tariff owner only) | `GridFeeUse` / `GridFeeRegister` |
+| Dynamic tariff provider | `onTariffSelected`, `setTariff`, `publishPrices` | `ElectricityTariff` |
+| Data bus | `CascadeSplitUpdateV1`, `AggregatedStateUpdateV1.data.cascade` | `SubscribeDataBus` |
+
+Without a cascade, topology getters resolve to `null` / `false` / `[]`, cascade price and grid fee
+getters to `null`, and writes reject; `useElectricityTariff().getPricesForAppliance` returns the site's
+prices. Z1 also counts
+everything that passes Z2, so never add the two meter readings together.
+
 #### `useWeatherForecasting(): EnergyAppWeatherForecasting`
 
 Register a weather-forecast provider (e.g. wraps an external API) and / or consume forecasts by zip code or coordinates.
@@ -1860,6 +1994,11 @@ forecast series concatenate into one timeline without translation. Every measure
 optional: you get what the provider holds and you asked for, and a measure it does not hold is simply
 absent rather than an error.
 
+`timestampIso` is the **start** of the bucket a reading or forecast entry covers. The irradiance
+fields are the mean over `[timestampIso, timestampIso + resolution)` — not the value at that moment,
+and not the mean of the preceding hour. Temperature, wind and cloud cover are the value at the start
+of the bucket for an hourly source, and the time-weighted mean over the bucket at coarser resolutions.
+
 Aggregates per measure live in `statistics`, keyed by `WeatherHistoryMeasureEnum`. `averageValue` is
 time-weighted; for the irradiance measures it is a mean power density in W/m², so multiply by the
 covered duration in hours to get received energy in Wh/m². `symbol` is categorical and therefore
@@ -2954,11 +3093,48 @@ class MyHeatpumpApp extends HeatpumpIntegrationEnergyApp {
 
 Drives a heatpump. Manages building / DHW overheating commands and grid-power-availability announcements.
 
-- **Subscribed commands:** `HeatpumpOverheatingV1`, `HeatpumpAvailablePowerAnnouncementV1`, `GridOperatorPowerLimitationV1` (broadcast)
-- **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleGridOperatorPowerLimitation`
+- **Subscribed commands:** `HeatpumpOverheatingV1`, `HeatpumpAvailablePowerAnnouncementV1`, `SetHeatpumpAvailablePowerV2`, `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleSetHeatpumpAvailablePower`, `handleGridOperatorPowerLimitation`
+- **Optional override:** `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
 - **Publish helpers:**
   - `publishHeatpumpValuesUpdate(applianceId, values)` — operation mode, electrical and thermal power, energies.
-  - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow, return, DHW tanks, heating circuits, buffer tank.
+  - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow / target flow / return, DHW tanks, heating circuits (room, flow, target flow, return), buffer tank.
+
+#### Advanced heatpump metadata
+
+Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata`) can carry what the device is configured to do. Declare each part with its feature flag in `availableFeatures` so consumers know to expect it:
+
+| Feature flag | Where the data lives |
+|---|---|
+| `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` |
+| `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` |
+| `FlowTemperature` / `ReturnTemperature` | `heatpumpFlowTemperatureC`, `heatpumpTargetFlowTemperatureC`, `heatpumpReturnTemperatureC` and per-circuit `flowTemperatureC`, `targetFlowTemperatureC`, `returnTemperatureC` in `HeatpumpTemperaturesUpdateV1` |
+
+`updateAppliance` replaces the whole `heatingCircuits` / `domesticHotWater` array, so use the `ApplianceManager` helpers to change a single entry:
+
+```typescript
+await applianceManager.updateHeatpumpHeatingCircuit(applianceId, 0, {
+    heatingCurve: {
+        points: [
+            { outdoorTemperatureC: -15, flowTemperatureC: 48 },
+            { outdoorTemperatureC: 0, flowTemperatureC: 38 },
+            { outdoorTemperatureC: 15, flowTemperatureC: 27 },
+        ],
+        slope: 0.8,
+        parallelShiftK: 0,
+    },
+    timeProgram: {
+        defaultLevel: EnyoHeatpumpTimeProgramLevelEnum.Reduced,
+        levelTemperaturesC: { Comfort: 21, Reduced: 18 },
+        periods: [{ daysOfWeek: [1, 2, 3, 4, 5], startTimeOfDay: '06:00', endTimeOfDay: '22:00', level: EnyoHeatpumpTimeProgramLevelEnum.Comfort }],
+    },
+});
+await applianceManager.updateHeatpumpDomesticHotWater(applianceId, 0, { timeProgram: dhwProgram });
+```
+
+Validate before publishing with `validateHeatpumpHeatingCurve`, `validateHeatpumpTimeProgram` or `validateHeatpumpAdvancedMetadata` (or their `assertValid*` counterparts). Each returns `{ ok, errors, warnings }`.
 
 ### WallboxIntegrationEnergyApp
 
@@ -3993,6 +4169,12 @@ 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.
+
+**Short-cycling protection.** When an appliance is kept running (or kept off) to honour its minimum on/off time, state `DeviceProtection` with `context.switching` (`EnyoDataBusCommandReasonSwitchingContext`): `hold` (`EnyoSwitchingProtectionHoldEnum.KeptOn` / `KeptOff`), `minOnSeconds`, `minOffSeconds` and `untilIso`. The text can then say "Kept running for another 4 minutes to protect the compressor" instead of a generic "Protecting the device".
+
+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."
+
 ## Dynamic Grid Fees & Tariff Bonuses
 
 An electricity price is rarely one number. It is the energy price, plus the grid operator's network
@@ -4560,6 +4742,28 @@ Notes:
 - V1 is unchanged and remains fully supported. V2 is an additive sibling, not a
   migration.
 
+#### Forecasting When a Heat Pump Runs
+
+A heat pump integration can publish its own forecast of when the heat pump will run with
+`HeatpumpOperationForecastV1` (or `publishHeatpumpOperationForecast()` on `IntegrationEnergyApp`).
+It is a prediction, not a request for power — to offer power, send `ApplianceFlexibilityAnnouncementV2`.
+
+Each entry covers one slot of `resolution`, starting at `timestampIso`. `outdoorTemperatureC` and
+`running` are always present; `flowTemperatureC`, `generatedHeatWh`, `consumptionWh` and
+`averagePowerW` are optional. Energy values are per slot, and `averagePowerW` is averaged over the
+whole slot. Each message replaces the previous forecast for the appliance.
+
+```typescript
+this.publishHeatpumpOperationForecast('heatpump-1', {
+    resolution: ForecastResolutionEnum.OneHour,
+    entries: [
+        {timestampIso: '2026-10-06T06:00:00Z', outdoorTemperatureC: 4.5, running: true,
+         flowTemperatureC: 38, generatedHeatWh: 5200, consumptionWh: 1600, averagePowerW: 1600},
+        {timestampIso: '2026-10-06T07:00:00Z', outdoorTemperatureC: 5.0, running: false},
+    ],
+});
+```
+
 #### Explaining Why a Command Was Issued
 
 Every data bus command can carry an `EnyoDataBusCommandReason`. Its `type`

package/dist/cjs/energy-app-model-feature.enum.cjs

@@ -41,6 +41,8 @@ var EnergyAppModelFeatureEnum;
     EnergyAppModelFeatureEnum["HeatpumpPowerModulation"] = "heatpump-power-modulation";
     /** The model supports the SG Ready interface for smart-grid signalling */
     EnergyAppModelFeatureEnum["HeatpumpSgReady"] = "heatpump-sg-ready";
+    /** The heat pump accepts measured room temperatures from an external sensor as control input */
+    EnergyAppModelFeatureEnum["HeatpumpRoomTemperatureInput"] = "heatpump-room-temperature-input";
     // Climate Control / Air Conditioning
     /** The target temperature setpoint can be controlled */
     EnergyAppModelFeatureEnum["ClimateTemperatureSetpoint"] = "climate-temperature-setpoint";

package/dist/cjs/energy-app-model-feature.enum.d.cts

@@ -33,6 +33,8 @@ export declare enum EnergyAppModelFeatureEnum {
     HeatpumpPowerModulation = "heatpump-power-modulation",
     /** The model supports the SG Ready interface for smart-grid signalling */
     HeatpumpSgReady = "heatpump-sg-ready",
+    /** The heat pump accepts measured room temperatures from an external sensor as control input */
+    HeatpumpRoomTemperatureInput = "heatpump-room-temperature-input",
     /** The target temperature setpoint can be controlled */
     ClimateTemperatureSetpoint = "climate-temperature-setpoint",
     /** The operating mode (heat / cool / fan / off) can be controlled */

package/dist/cjs/energy-app-package-definition.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageCategory = void 0;
+exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = exports.EnergyAppPackageCategory = void 0;
 exports.defineEnergyAppPackage = defineEnergyAppPackage;
 const version_js_1 = require("./version.cjs");
 var EnergyAppPackageCategory;
@@ -27,6 +27,34 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["Vehicle"] = "vehicle";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
+/**
+ * How the Modbus device detection rules in
+ * {@link EnergyAppPackageOptionsDeviceDetection.modbus} are combined.
+ *
+ * Each name has two parts:
+ * - `Registers…`: how the entries (registers) of the `modbus` list combine.
+ *   `Or` means one matching register is enough; `And` means every register has
+ *   to match, all on the same unit id.
+ * - `MatchingValues…`: how the `matchingValues` within one register combine.
+ *   `Or` means the register's value has to match one of them; `And` means it
+ *   has to match all of them.
+ *
+ * Only read from the **first** entry of the `modbus` list and applies to the
+ * whole list; set it there and nowhere else. Defaults to
+ * {@link RegistersOr_MatchingValuesOr} when omitted, which is the behaviour of
+ * all existing rules.
+ */
+var EnergyAppPackageOptionsDeviceDetectionModbusModeEnum;
+(function (EnergyAppPackageOptionsDeviceDetectionModbusModeEnum) {
+    /** One register has to match, with one of its matching values. The default. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersOr_MatchingValuesOr"] = "RegistersOr_MatchingValuesOr";
+    /** One register has to match, with all of its matching values. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersOr_MatchingValuesAnd"] = "RegistersOr_MatchingValuesAnd";
+    /** Every register has to match, each with one of its matching values. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersAnd_MatchingValuesOr"] = "RegistersAnd_MatchingValuesOr";
+    /** Every register has to match, each with all of its matching values. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersAnd_MatchingValuesAnd"] = "RegistersAnd_MatchingValuesAnd";
+})(EnergyAppPackageOptionsDeviceDetectionModbusModeEnum || (exports.EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = {}));
 /**
  * Whether a declared compatibility entry means "this works" or "this is known
  * not to work".

package/dist/cjs/energy-app-package-definition.d.cts

@@ -40,8 +40,85 @@ export interface EnergyAppPackageOptionsDeviceDetectionHostname {
     operation: 'eq' | 'startsWith';
     matchingValue: string;
 }
+/**
+ * Which Modbus register bank a device detection rule reads.
+ * - `'holding'`: holding registers, function code 3
+ * - `'input'`: input registers, function code 4
+ *
+ * The two banks are separate address spaces, so the same address may hold
+ * different data (or nothing) in each.
+ */
+export type EnergyAppPackageOptionsDeviceDetectionModbusRegisterType = 'holding' | 'input';
+/**
+ * How the Modbus device detection rules in
+ * {@link EnergyAppPackageOptionsDeviceDetection.modbus} are combined.
+ *
+ * Each name has two parts:
+ * - `Registers…`: how the entries (registers) of the `modbus` list combine.
+ *   `Or` means one matching register is enough; `And` means every register has
+ *   to match, all on the same unit id.
+ * - `MatchingValues…`: how the `matchingValues` within one register combine.
+ *   `Or` means the register's value has to match one of them; `And` means it
+ *   has to match all of them.
+ *
+ * Only read from the **first** entry of the `modbus` list and applies to the
+ * whole list; set it there and nowhere else. Defaults to
+ * {@link RegistersOr_MatchingValuesOr} when omitted, which is the behaviour of
+ * all existing rules.
+ */
+export declare enum EnergyAppPackageOptionsDeviceDetectionModbusModeEnum {
+    /** One register has to match, with one of its matching values. The default. */
+    RegistersOr_MatchingValuesOr = "RegistersOr_MatchingValuesOr",
+    /** One register has to match, with all of its matching values. */
+    RegistersOr_MatchingValuesAnd = "RegistersOr_MatchingValuesAnd",
+    /** Every register has to match, each with one of its matching values. */
+    RegistersAnd_MatchingValuesOr = "RegistersAnd_MatchingValuesOr",
+    /** Every register has to match, each with all of its matching values. */
+    RegistersAnd_MatchingValuesAnd = "RegistersAnd_MatchingValuesAnd"
+}
+/**
+ * Optional device detection configuration for Modbus TCP register matching:
+ * read a register range and compare its decoded value against the matching
+ * values.
+ *
+ * How several entries and several matching values combine is set by
+ * {@link mode} on the first entry of the list.
+ *
+ * @example
+ * // Vendor name in holding registers AND model id in an input register:
+ * modbus: [
+ *   {
+ *     mode: EnergyAppPackageOptionsDeviceDetectionModbusModeEnum.RegistersAnd_MatchingValuesOr,
+ *     unitIds: [1],
+ *     registerAddress: 40001,
+ *     registerSize: 2,
+ *     type: 'string',
+ *     matchingValues: ['SMA'],
+ *   },
+ *   {
+ *     unitIds: [1],
+ *     registerType: 'input',
+ *     registerAddress: 30053,
+ *     registerSize: 2,
+ *     type: 'UInt32BE',
+ *     matchingValues: ['9401', '9402'],
+ *   },
+ * ]
+ */
 export interface EnergyAppPackageOptionsDeviceDetectionModbus {
+    /**
+     * How all entries of the `modbus` list and their matching values combine.
+     * Only read from the first entry of the list — set it there and leave it
+     * out on the others. Defaults to
+     * {@link EnergyAppPackageOptionsDeviceDetectionModbusModeEnum.RegistersOr_MatchingValuesOr}.
+     */
+    mode?: EnergyAppPackageOptionsDeviceDetectionModbusModeEnum;
     unitIds: number[];
+    /**
+     * Which register bank to read. Defaults to `'holding'` when omitted,
+     * which is the behaviour of all existing rules.
+     */
+    registerType?: EnergyAppPackageOptionsDeviceDetectionModbusRegisterType;
     /** Register address, for example 30001 */
     registerAddress: number;
     /** Register size, for example 2 for 30001 - 30002 */

package/dist/cjs/energy-app.cjs

@@ -506,6 +506,23 @@ class EnergyApp {
     useCommandLog() {
         return this.energyAppSdk.useCommandLog();
     }
+    /**
+     * Gets the Cascade API for the site's meter cascade: a second meter behind
+     * the primary meter (e.g. for a heatpump on a dedicated tariff) with its
+     * own electricity tariff, prices and grid fee.
+     *
+     * Use it to find out whether a cascade is active and which appliances are
+     * behind it, and to read or supply the cascade's tariff, prices and grid
+     * fee — appliances behind an active cascade are billed on those instead of
+     * on {@link useElectricityTariff} and {@link useGridFee}.
+     * @returns The Cascade API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `ElectricityTariff`,
+     *         `GridFeeRegister` or `GridFeeUse` permission required by the
+     *         called method is not granted.
+     */
+    useCascade() {
+        return this.energyAppSdk.useCascade();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/energy-app.d.cts

@@ -50,6 +50,7 @@ import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
+import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -426,6 +427,21 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useCommandLog(): EnergyAppCommandLog;
+    /**
+     * Gets the Cascade API for the site's meter cascade: a second meter behind
+     * the primary meter (e.g. for a heatpump on a dedicated tariff) with its
+     * own electricity tariff, prices and grid fee.
+     *
+     * Use it to find out whether a cascade is active and which appliances are
+     * behind it, and to read or supply the cascade's tariff, prices and grid
+     * fee — appliances behind an active cascade are billed on those instead of
+     * on {@link useElectricityTariff} and {@link useGridFee}.
+     * @returns The Cascade API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `ElectricityTariff`,
+     *         `GridFeeRegister` or `GridFeeUse` permission required by the
+     *         called method is not granted.
+     */
+    useCascade(): EnergyAppCascade;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -49,6 +49,7 @@ import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
+import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -181,4 +182,6 @@ export interface EnyoEnergyAppSdk {
     useGridFee: () => EnergyAppGridFee;
     /** Get the Command Log API for recording which register, configuration key or message this app wrote to an appliance, and reading those commands back */
     useCommandLog: () => EnergyAppCommandLog;
+    /** Get the Cascade API for the meter behind the primary meter: whether it is active, which appliances are behind it, and its own electricity tariff, prices and grid fee */
+    useCascade: () => EnergyAppCascade;
 }

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

@@ -531,6 +531,78 @@ class ApplianceManager {
         await this.energyApp.useAppliances().save(updated, applianceId);
         await this.primeCacheFromSdk(applianceId);
     }
+    /**
+     * Patches a single heating circuit of a heatpump — e.g. to publish a changed
+     * heating curve or time program — without resending the whole
+     * `heatingCircuits` array.
+     *
+     * {@link updateAppliance} merges `heatpump` metadata only one level deep,
+     * so passing `heatingCircuits` there replaces every circuit. This helper
+     * reads the stored array, shallow-merges `patch` into the circuit with the
+     * given `index` (appending a new circuit when none exists), keeps the
+     * array sorted by index, and saves. Other circuits are left untouched.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit to patch
+     * @param patch The circuit fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async updateHeatpumpHeatingCircuit(applianceId, index, patch) {
+        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) {
+            circuits[position] = { ...circuits[position], ...patch, index };
+        }
+        else {
+            circuits.push({ ...patch, index });
+            circuits.sort((a, b) => a.index - b.index);
+        }
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { heatingCircuits: circuits } }), applianceId);
+        await this.primeCacheFromSdk(applianceId);
+    }
+    /**
+     * Patches a single domestic-hot-water zone of a heatpump — e.g. to publish
+     * a changed time program — without resending the whole `domesticHotWater`
+     * array. Works like {@link updateHeatpumpHeatingCircuit}.
+     *
+     * Appending a zone that does not exist yet requires `targetTemperatureC`
+     * in `patch`, because a DHW zone cannot be stored without it.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the DHW zone to patch
+     * @param patch The zone fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
+     */
+    async updateHeatpumpDomesticHotWater(applianceId, index, patch) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return;
+        const zones = [...(appliance.heatpump?.domesticHotWater ?? [])];
+        const position = zones.findIndex(z => z.index === index);
+        if (position >= 0) {
+            zones[position] = { ...zones[position], ...patch, index };
+        }
+        else {
+            const { targetTemperatureC } = patch;
+            if (targetTemperatureC === undefined) {
+                throw new Error(`Cannot add domestic hot water zone ${index} to appliance ${applianceId} without targetTemperatureC`);
+            }
+            zones.push({ ...patch, index, targetTemperatureC });
+            zones.sort((a, b) => a.index - b.index);
+        }
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { domesticHotWater: zones } }), 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, 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 { EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
+import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, 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";
@@ -329,6 +329,42 @@ export declare class ApplianceManager {
      * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
      */
     updateAppliance(applianceId: string, attributes: Partial<PartialEnyoAppliance>): Promise<void>;
+    /**
+     * Patches a single heating circuit of a heatpump — e.g. to publish a changed
+     * heating curve or time program — without resending the whole
+     * `heatingCircuits` array.
+     *
+     * {@link updateAppliance} merges `heatpump` metadata only one level deep,
+     * so passing `heatingCircuits` there replaces every circuit. This helper
+     * reads the stored array, shallow-merges `patch` into the circuit with the
+     * given `index` (appending a new circuit when none exists), keeps the
+     * array sorted by index, and saves. Other circuits are left untouched.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit to patch
+     * @param patch The circuit fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    updateHeatpumpHeatingCircuit(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceHeatingCircuit, 'index'>>): Promise<void>;
+    /**
+     * Patches a single domestic-hot-water zone of a heatpump — e.g. to publish
+     * a changed time program — without resending the whole `domesticHotWater`
+     * array. Works like {@link updateHeatpumpHeatingCircuit}.
+     *
+     * Appending a zone that does not exist yet requires `targetTemperatureC`
+     * in `patch`, because a DHW zone cannot be stored without it.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the DHW zone to patch
+     * @param patch The zone fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
+     */
+    updateHeatpumpDomesticHotWater(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceDomesticHotWater, 'index'>>): 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