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

package/README.md

@@ -33,6 +33,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [NetworkDeviceManager](#networkdevicemanager)
   - [Startup pattern](#startup-pattern)
 - [Package Files](#package-files)
+- [Printable Manual Setup Guide](#printable-manual-setup-guide)
 - [Firmware Update Registry](#firmware-update-registry)
   - [Declaring firmware](#declaring-firmware)
   - [Firmware modes](#firmware-modes)
@@ -2851,6 +2852,43 @@ It checks that names are unique slugs, that paths stay inside the package and ca
 extension, and that any declared MIME type is well formed; two names pointing at one
 path is a warning.
 
+## Printable Manual Setup Guide
+
+A package can declare **one optional** onboarding guide (v2) as static data in its package
+definition. The enyo CLI reads it during `enyo release`, and enyo renders it as a printable
+PDF installation manual. It is separate from the interactive guides an app returns from
+`useOnboardingV2().registerOnboardingGuidesHandler()`: it never takes part in an onboarding
+run, so it needs no `name` and doesn't conflict with those guides in any way.
+
+Paper cannot scan the network or ask the app anything, so the guide must describe a
+**manual setup**:
+
+- `startVariant: EnyoOnboardingV2StartVariant.ManualSetup` and `requiresNetworkScan: false`
+- no `network-scan` / `device-test` actions, no `device-select` / `eebus-device-select`
+  blocks, no `dynamic` blocks, no `start-variant` targets
+- no `applianceId`, `vendorId` or `modelIds`
+- plain JSON only, and every image block `file` declared in `files`
+
+```typescript
+import {
+    defineEnergyAppPackage,
+    definePublicFile,
+    validatePackageOnboardingGuide
+} from '@enyo-energy/energy-app-sdk';
+import {manualSetupGuide} from './src/onboarding/manual-setup.guide.js';
+
+const packageDef = defineEnergyAppPackage({
+    // ...
+    files: [definePublicFile({name: 'modbus-menu', path: './assets/modbus-menu.png'})],
+    onboardingGuide: manualSetupGuide
+});
+
+const {ok, errors, warnings} = validatePackageOnboardingGuide(packageDef);
+```
+
+The complete authoring guide, with the reason behind each rule and a full example, is the
+JSDoc of `EnergyAppPackageDefinition.onboardingGuide`.
+
 ## Firmware Update Registry
 
 Ship firmware images with your package and hand them to devices at runtime. You declare the files by local path in the package definition, the enyo CLI uploads them during `enyo release`, and the app reaches them through `energyApp.useFirmwareRegistry()`. The release tarball never carries the bytes.
@@ -3110,13 +3148,76 @@ class MyHeatpumpApp extends HeatpumpIntegrationEnergyApp {
 
 Drives a heatpump. Manages building / DHW overheating commands and grid-power-availability announcements.
 
-- **Subscribed commands:** `HeatpumpOverheatingV1`, `HeatpumpAvailablePowerAnnouncementV1`, `SetHeatpumpAvailablePowerV2`, `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+> **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)
 - **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`.
+- **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`.
+  - `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.
+- **Helpers for a V3 implementation:** `checkHeatpumpControlActions(message)` (validates every action against metadata and offer), `isHeatpumpControlChanged(message)` (new session or changed actions?), and the exported `computeHeatpumpSetpointRaise(...)` and `combineHeatpumpControlAnswers(...)`.
 - **Publish helpers:**
+  - `publishHeatpumpControlStatus(applianceId, {sessionId, actions})` — how a session's actions progress (`HeatpumpControlStatusV3`).
+  - `publishHeatpumpFlexibility(applianceId, options, {validForSeconds?, repeatEverySeconds?})` — offer per zone how far the heatpump can be raised right now (`HeatpumpFlexibilityAnnouncementV3`); repeated automatically until replaced (see below).
   - `publishHeatpumpValuesUpdate(applianceId, values)` — operation mode, electrical and thermal power, energies.
   - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow / target flow / return, DHW tanks, heating circuits (room, flow, target flow, return), buffer tank.
 
+#### HeatpumpControlV3
+
+**The preferred way to control a heatpump.** Energy managers send `HeatpumpControlV3` / `HeatpumpControlCancelV3` to heatpumps declaring `ControlV3`, and the deprecated `HeatpumpOverheatingV1` / `SetHeatpumpAvailablePowerV2` to all others — the choice comes from the metadata, not from probing. Integrations override `handleHeatpumpControl`, declare `ControlV3` (and `PvSurplusSignal` where the device takes a PV surplus signal), and report progress with `publishHeatpumpControlStatus`.
+
+One message per control session says **how much** power (`availablePowerW`), **from where** (`powerSources`: PV / battery / grid), **which zones to heat now** (`actions`: DHW, buffer tank or room, each with `index`, `deltaK` and an optional `heatSource`) and **until when** (`validUntilIso`).
+
+```typescript
+{
+    sessionId: 'night-tariff-2026-10-15',          // the same across every repeat
+    validUntilIso: '2026-10-15T00:01:00.000Z',     // liveness: repeated ~every 10 s, ~60 s ahead
+    availablePowerW: 3000,
+    powerSources: [{ source: EnyoPowerSourceEnum.Grid, powerW: 3000 }],
+    actions: [{ target: EnyoHeatpumpControlTargetEnum.Dhw, index: 0, deltaK: 5 }],
+}
+```
+
+- **An action means "heat this zone now".** It pulls heating into a cheap or sunny period — e.g. night tariff 0–5 h. Answer it `Accepted` only when the device will actually start heating. A setpoint-only heatpump (Stiebel Eltron, Nibe) only starts once the temperature is a hysteresis below the setpoint, so write at least `currentTemperature + hysteresisK` (`domesticHotWater[].hysteresisK` / `bufferTanks[].hysteresisK`) even if `deltaK` asks for less. If `maxTemperatureC` leaves no such setpoint, answer `Rejected` — never `Accepted` with nothing happening. `computeHeatpumpSetpointRaise({setpointC, deltaK, currentTemperatureC, hysteresisK, maxTemperatureC})` does the arithmetic the same way for every app.
+- **Room `deltaK` is always Kelvin of room temperature.** On an outdoor-controlled circuit (`heatingControlReference: Outdoor`) the app translates it into a heating-curve shift, on a room-controlled one into a higher room setpoint. The energy manager never sends a curve shift. Above the circuit's `heatingCutoffOutdoorTemperatureC` a room action cannot take effect and is `Rejected`.
+- **Report what was written.** Each `actionResults` entry carries `appliedTargetTemperatureC` (the setpoint written), `appliedDeltaK` (the effective raise, possibly above `deltaK`) and, for a room on an outdoor-controlled circuit, `appliedHeatingCurveShiftK`.
+- **Sessions.** Repeats arrive about every 10 s with the same `sessionId`; apply the actions only when `isHeatpumpControlChanged(message)` says the session or its actions changed, and just update the power otherwise. The base class handles liveness for every V3 implementation: it rejects a message whose `validUntilIso` is invalid or past, and calls `onHeatpumpControlEnded` when no repeat arrives by `validUntilIso` (`Expired`), on a message with no actions and no `availablePowerW` (`Ended` — passed to `handleHeatpumpControl` first, so the device can be reset at once), or on a cancel (`Cancelled`).
+- **Cancelling.** `HeatpumpControlCancelV3` with a `sessionId` cancels that session right away, instead of waiting up to ~60 s for `validUntilIso` to lapse. It only touches the named session, so a newer one that replaced it is safe, which an empty `HeatpumpControlV3` cannot guarantee. Idempotent: `Accepted` also when the session is no longer running. Stop repeating the session first, or the next repeat starts it again.
+- **Answers per action.** The acknowledgment carries one `actionResults` entry per action; return them in `IntegrationCommandResponse.actionResults` and the base class passes them through. The top-level `answer` is `Accepted` as soon as the power or one action is accepted, `NotSupported` only when nothing is supported, otherwise `Rejected` (`combineHeatpumpControlAnswers`).
+- **Progress.** `HeatpumpControlStatusV3` reports each action as `Waiting` (accepted, not heating yet — defrost, minimum off-time), `Running`, `Completed` (target reached — the energy manager may end the session early) or `Aborted` (stopped or refused — the energy manager re-plans), with `currentTemperatureC`, `appliedTargetTemperatureC`, `startedAtIso`, `endedAtIso` and a `reason`. Send it on every state change and once more when the session ends.
+- **Validation** (`checkHeatpumpControlActions(message)`, or `validateHeatpumpControlAction(action, metadata, powerSources, offer?)` directly):
+  - A heating rod (`heatSource` `HeatingRod` / `Both`) runs on PV surplus only: rejected unless `powerSources` are PV alone, and `NotSupported` without `HeatingRodControllable`.
+  - Each target needs its overheating feature (`DomesticHotWaterOverheating`, `BufferTankOverheating`, `RoomOverheating`), else `NotSupported`.
+  - 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.
+
+#### 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`.
+
+```typescript
+const offerId = await this.publishHeatpumpFlexibility('heatpump-1', [{
+    target: EnyoHeatpumpControlTargetEnum.Dhw,
+    index: 0,
+    currentTemperatureC: 47,
+    setpointC: 50,
+    maxDeltaK: 10,
+    heatSources: [
+        { heatSource: EnyoHeatpumpHeatSourceEnum.Compressor, power: { minWatt: 800, maxWatt: 2300, stepWatt: 100 }, estimatedElectricalKwh: 1.4 },
+        { heatSource: EnyoHeatpumpHeatSourceEnum.HeatingRod, power: { minWatt: 3000, maxWatt: 3000, stepWatt: 3000 }, estimatedElectricalKwh: 4.1 },
+    ],
+    required: { deltaK: 3, byIso: '2026-10-14T18:00:00.000Z' },
+}]);
+```
+
+- **Lifecycle.** The latest offer per appliance replaces the previous one and holds until `validUntilIso`. `publishHeatpumpFlexibility` repeats it with a fresh `validUntilIso` (default: valid 15 min, repeated every 5 min) until you call it again, and stops repeating on `stop()`. Publish `[]` to withdraw the offer.
+- **`offerId`** is derived from what is offered (`heatpumpFlexibilityOfferId`), ignoring measured values and order — it stays the same while the tank warms up and changes when the offer changes.
+- **Answering an offer.** The energy manager answers with `HeatpumpControlV3` — one action per offered zone, `deltaK` ≤ `maxDeltaK`, a `heatSource` from the offered ones — and names the offer in `data.offerId`. When a session names an `offerId`, the base class checks every action against the heatpump's current offer and rejects what was not offered. A session without `offerId` is the energy manager's own plan and is checked against the metadata only.
+- **Validation** (`validateHeatpumpFlexibilityAnnouncement(data, metadata?)`, run by `publishHeatpumpFlexibility` before sending): `maxDeltaK` positive; at least one heat source, none twice, a sane power band; start window and `required.byIso` valid, `required.deltaK` ≤ `maxDeltaK`; each zone at most once; and against the metadata, DHW `setpointC + maxDeltaK` ≤ `maxTemperatureC`, a heating rod only with `HeatingRodControllable`, and each target's overheating feature declared.
+
 #### 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:
@@ -3127,6 +3228,11 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 | `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` |
+| `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 |
+| — | `heatingCircuits[].heatingControlReference` — what the circuit steers by: `Outdoor` (heating curve) or `Room`. Independent of `roomTemperatureSource`, which says where the room is measured |
+| — | `heatingCircuits[].heatingCutoffOutdoorTemperatureC` — the heatpump's own heating cut-off (Heizgrenze / Sommerabschaltung) setting. Above it a room action cannot take effect. Unlike the learned `building.heatingLimitC`; the validator warns when the two differ by more than 3 K |
 | `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:
@@ -4211,7 +4317,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.
+**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 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 %)."
 

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

@@ -1,6 +1,7 @@
 import { EnergyAppPermissionType } from "./energy-app-permission.type.cjs";
 import { EnergyAppModelFeatureEnum } from "./energy-app-model-feature.enum.cjs";
 import type { EnyoFileTranslation } from "./types/enyo-file.cjs";
+import type { EnyoOnboardingV2Guide } from "./types/enyo-onboarding-v2.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -658,6 +659,147 @@ export interface EnergyAppPackageDefinition {
      * Only relevant when {@link firmware} is declared.
      */
     firmwareMode?: EnergyAppPackageFirmwareMode;
+    /**
+     * The package's static **manual setup** onboarding guide (v2). It is
+     * optional and there is at most one. The enyo CLI reads it at release time
+     * and ships it with the package version, where enyo renders it as a
+     * printable PDF installation manual.
+     *
+     * ## What it is for
+     *
+     * The guides an app returns from
+     * {@link EnergyAppOnboardingV2.registerOnboardingGuidesHandler} are
+     * interactive and only exist on a device where the app is running. This
+     * guide is the opposite: a fixed document that exists as soon as the
+     * package is released. An installer can read it on paper before the
+     * device is even powered. It is written with the same v2 guide model, so
+     * an app that already has an interactive manual setup flow can usually
+     * declare the same steps here.
+     *
+     * It does not take part in onboarding runs. It is never offered by the
+     * host, never addressed by name and never compared against the guides from
+     * the runtime handler, so there are no naming or precedence rules between
+     * the two.
+     *
+     * ## What it may contain
+     *
+     * Paper cannot scan the network or ask the app anything, so the guide is
+     * limited to a manual setup the installer can follow by reading. The
+     * following rules are enforced by `validatePackageOnboardingGuide()`, and
+     * the CLI refuses the release if any of them is broken:
+     *
+     * | Rule | Why |
+     * |---|---|
+     * | `startVariant` is {@link EnyoOnboardingV2StartVariant.ManualSetup} | The document describes a manual setup, nothing else. |
+     * | `requiresNetworkScan: false` is set explicitly | The default is `true`, and a printed manual has no scan to rely on. |
+     * | No `network-scan` or `device-test` action blocks | Both act on devices found by a scan. |
+     * | No `device-select` or `eebus-device-select` blocks | Both pick from devices the host discovered. |
+     * | No `dynamic` blocks | Their value is resolved by the app at runtime and does not exist when the PDF is rendered. |
+     * | No `start-variant` targets | They lead into another, scan-based guide that is not part of the document. |
+     * | No `applianceId`, `vendorId` or `modelIds` | A document is not bound to an appliance, and enyo derives vendor and models from the package. |
+     * | Plain JSON only (no functions, `Date`s, `undefined` in arrays, class instances) | The CLI serializes the guide into the release. |
+     * | Every image block `file` is declared in {@link files} | Otherwise the PDF has a hole where the image belongs. |
+     *
+     * Everything else is allowed. Content blocks (text, headline, bullets,
+     * image, hint, link) render as they are. Interactive blocks (choice,
+     * select, input, credentials, auth, additional-setup and the
+     * `connection-check` / `ocpp-connect` actions) render as instructions,
+     * and their outcomes and transitions become the branches of the document
+     * ("if the device is not reachable, continue with …"). Give every
+     * outcome a label that reads well on paper.
+     *
+     * `name` is optional and has no meaning here.
+     *
+     * ## How to write one
+     *
+     * 1. Put the guide in its own file (for example
+     *    `src/onboarding/manual-setup.guide.ts`) and build it with
+     *    `defineOnboardingGuideV2()`, the `onboardingV2Block.*` and
+     *    `onboardingV2Target.*` factories, and the `onContinueV2()` /
+     *    `onOutcomeV2()` transition helpers.
+     * 2. Keep the file free of runtime dependencies. The CLI loads it while
+     *    loading this definition, outside the app sandbox, so it must not
+     *    touch the SDK instance, storage, the network or environment state.
+     * 3. Import it here and assign it to `onboardingGuide`.
+     * 4. Check it locally with `validatePackageOnboardingGuide(definition)`.
+     * 5. Release. The CLI validates the guide again and aborts on errors.
+     *
+     * ```typescript
+     * // src/onboarding/manual-setup.guide.ts
+     * import {
+     *     defineOnboardingGuideV2,
+     *     EnyoDeviceTestOutcomeEnum,
+     *     EnyoOnboardingV2InputValueType,
+     *     EnyoOnboardingV2StartVariant,
+     *     onboardingV2Block,
+     *     onboardingV2Target,
+     *     onContinueV2,
+     *     onOutcomeV2,
+     * } from '@enyo-energy/energy-app-sdk';
+     *
+     * const t = (de: string, en: string) => [
+     *     {language: 'de' as const, value: de},
+     *     {language: 'en' as const, value: en},
+     * ];
+     *
+     * export const manualSetupGuide = defineOnboardingGuideV2({
+     *     title: t('Wechselrichter manuell einrichten', 'Set up the inverter manually'),
+     *     startVariant: EnyoOnboardingV2StartVariant.ManualSetup,
+     *     requiresNetworkScan: false,
+     *     startStepId: 'prepare',
+     *     steps: [
+     *         {
+     *             id: 'prepare',
+     *             name: 'modbus-aktivieren',
+     *             title: t('Modbus TCP aktivieren', 'Enable Modbus TCP'),
+     *             blocks: [
+     *                 onboardingV2Block.text('intro', t(
+     *                     'Aktiviere Modbus TCP im Webinterface des Wechselrichters.',
+     *                     'Enable Modbus TCP in the inverter web interface.',
+     *                 )),
+     *                 onboardingV2Block.imageFile('menu', 'modbus-menu', t('Menü', 'Menu')),
+     *             ],
+     *             transitions: [onContinueV2(onboardingV2Target.step('ip'))],
+     *         },
+     *         {
+     *             id: 'ip',
+     *             name: 'ip-eingeben',
+     *             title: t('IP-Adresse eingeben', 'Enter the IP address'),
+     *             blocks: [
+     *                 onboardingV2Block.input(
+     *                     'device-ip',
+     *                     EnyoOnboardingV2InputValueType.IpAddress,
+     *                     t('IP-Adresse des Wechselrichters', 'Inverter IP address'),
+     *                     t('Verbindung prüfen', 'Check connection'),
+     *                     [
+     *                         {id: 'ok', value: EnyoDeviceTestOutcomeEnum.AppliancesCreated, label: t('Verbunden', 'Connected')},
+     *                         {id: 'unreachable', value: EnyoDeviceTestOutcomeEnum.Unreachable, label: t('Nicht erreichbar', 'Unreachable')},
+     *                     ],
+     *                     {placeholder: t('z. B. 192.168.1.42', 'e.g. 192.168.1.42')},
+     *                 ),
+     *             ],
+     *             transitions: [
+     *                 onOutcomeV2('device-ip', 'ok', onboardingV2Target.success()),
+     *                 onOutcomeV2('device-ip', 'unreachable', onboardingV2Target.step('prepare')),
+     *             ],
+     *         },
+     *     ],
+     * });
+     *
+     * // energy-app.package.ts
+     * import {defineEnergyAppPackage, definePublicFile} from '@enyo-energy/energy-app-sdk';
+     * import {manualSetupGuide} from './src/onboarding/manual-setup.guide.js';
+     *
+     * export default defineEnergyAppPackage({
+     *     // ...
+     *     files: [definePublicFile({name: 'modbus-menu', path: './assets/modbus-menu.png'})],
+     *     onboardingGuide: manualSetupGuide,
+     * });
+     * ```
+     *
+     * Omit the field for packages that have no manual setup to document.
+     */
+    onboardingGuide?: EnyoOnboardingV2Guide;
 }
 /**
  * Defines an Energy App package with automatic SDK version injection.

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

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeatpumpControlSessionTracker = exports.HeatpumpControlEndCauseEnum = void 0;
+exports.heatpumpControlActionKey = heatpumpControlActionKey;
+exports.heatpumpControlActionsKey = heatpumpControlActionsKey;
+/**
+ * Why a `HeatpumpControlV3` session ended — passed to
+ * `HeatpumpIntegrationEnergyApp.onHeatpumpControlEnded`.
+ */
+var HeatpumpControlEndCauseEnum;
+(function (HeatpumpControlEndCauseEnum) {
+    /** `validUntilIso` passed without a newer message (the energy manager stopped repeating it). */
+    HeatpumpControlEndCauseEnum["Expired"] = "expired";
+    /** The energy manager sent a `HeatpumpControlV3` with no actions and no power. */
+    HeatpumpControlEndCauseEnum["Ended"] = "ended";
+    /** The energy manager cancelled the session with `HeatpumpControlCancelV3`. */
+    HeatpumpControlEndCauseEnum["Cancelled"] = "cancelled";
+})(HeatpumpControlEndCauseEnum || (exports.HeatpumpControlEndCauseEnum = HeatpumpControlEndCauseEnum = {}));
+/**
+ * Key that identifies an action within a session — its target and zone index.
+ *
+ * @param action - The action.
+ * @returns E.g. `dhw:0`, or `room:` for an action without index.
+ */
+function heatpumpControlActionKey(action) {
+    return `${action.target}:${action.index ?? ''}`;
+}
+/**
+ * Stable key of a whole action list, independent of the order the actions
+ * were sent in. Two lists with the same key ask for the same thing.
+ *
+ * @param actions - The session's actions.
+ * @returns A string that changes whenever any action's target, index,
+ *   `deltaK` or `heatSource` changes.
+ */
+function heatpumpControlActionsKey(actions) {
+    return actions
+        .map((a) => [a.target, a.index ?? '', a.deltaK ?? '', a.heatSource ?? ''].join('|'))
+        .sort()
+        .join(';');
+}
+/**
+ * Tracks the `HeatpumpControlV3` session of each heatpump: which session is
+ * running, which of its actions have been applied, and when it lapses.
+ *
+ * Rules:
+ * - Same `sessionId` and same actions → the session continues; only
+ *   {@link HeatpumpControlSessionState.validUntilMs} moves.
+ * - New `sessionId` or changed actions → a fresh state; every action is
+ *   applied anew.
+ * - No new message by `validUntilIso` → the state is dropped and `onExpired`
+ *   is called for that appliance.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp`; exported so integrations that
+ * override `handleHeatpumpControl` can reuse the same rules.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new HeatpumpControlSessionTracker((applianceId) => resetHeatpump(applianceId));
+ * const {state, isNew} = tracker.track(message.applianceId, message.data);
+ * if (isNew) applyActions(message.data.actions);
+ * ```
+ */
+class HeatpumpControlSessionTracker {
+    onExpired;
+    now;
+    sessions = new Map();
+    timers = new Map();
+    /**
+     * @param onExpired - Called when an appliance's session lapses because no
+     *   message arrived by its `validUntilIso`. Not called by {@link end}.
+     * @param now - Clock in epoch milliseconds; injectable for tests.
+     */
+    constructor(onExpired, now = () => Date.now()) {
+        this.onExpired = onExpired;
+        this.now = now;
+    }
+    /**
+     * The current session state of an appliance, if one is running.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns The state, or `undefined`.
+     */
+    get(applianceId) {
+        return this.sessions.get(applianceId);
+    }
+    /**
+     * Records a received session message and (re)arms its expiry.
+     *
+     * @param applianceId - The heatpump appliance the message is for.
+     * @param data - The message's data.
+     * @returns The appliance's state, and `isNew` when the session or its
+     *   actions changed — the moment to apply the actions anew.
+     * @throws {Error} When `validUntilIso` is not an ISO 8601 timestamp.
+     */
+    track(applianceId, data) {
+        const validUntilMs = Date.parse(data.validUntilIso);
+        if (!Number.isFinite(validUntilMs)) {
+            throw new Error(`validUntilIso is not an ISO 8601 timestamp: ${data.validUntilIso}`);
+        }
+        const actionsKey = heatpumpControlActionsKey(data.actions ?? []);
+        const current = this.sessions.get(applianceId);
+        const isNew = !current || current.sessionId !== data.sessionId || current.actionsKey !== actionsKey;
+        const state = isNew
+            ? { sessionId: data.sessionId, actionsKey, validUntilMs }
+            : { ...current, validUntilMs };
+        this.sessions.set(applianceId, state);
+        this.armExpiry(applianceId, validUntilMs);
+        return { state, isNew };
+    }
+    /**
+     * Ends an appliance's session without calling `onExpired` — for an
+     * explicit end the caller handles itself.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns `true` when a session was running.
+     */
+    end(applianceId) {
+        this.clearTimer(applianceId);
+        return this.sessions.delete(applianceId);
+    }
+    /** Drops every session and timer. Call on shutdown. */
+    dispose() {
+        for (const applianceId of [...this.timers.keys()])
+            this.clearTimer(applianceId);
+        this.sessions.clear();
+    }
+    armExpiry(applianceId, validUntilMs) {
+        this.clearTimer(applianceId);
+        const delayMs = Math.max(0, validUntilMs - this.now());
+        this.timers.set(applianceId, setTimeout(() => {
+            this.timers.delete(applianceId);
+            const state = this.sessions.get(applianceId);
+            if (!state || state.validUntilMs > this.now())
+                return;
+            this.sessions.delete(applianceId);
+            this.onExpired(applianceId);
+        }, delayMs));
+    }
+    clearTimer(applianceId) {
+        const timer = this.timers.get(applianceId);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.delete(applianceId);
+    }
+}
+exports.HeatpumpControlSessionTracker = HeatpumpControlSessionTracker;

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

@@ -0,0 +1,107 @@
+import { EnyoDataBusHeatpumpControlV3, EnyoHeatpumpControlAction } from '../../types/enyo-data-bus-value.cjs';
+/**
+ * Why a `HeatpumpControlV3` session ended — passed to
+ * `HeatpumpIntegrationEnergyApp.onHeatpumpControlEnded`.
+ */
+export declare enum HeatpumpControlEndCauseEnum {
+    /** `validUntilIso` passed without a newer message (the energy manager stopped repeating it). */
+    Expired = "expired",
+    /** The energy manager sent a `HeatpumpControlV3` with no actions and no power. */
+    Ended = "ended",
+    /** The energy manager cancelled the session with `HeatpumpControlCancelV3`. */
+    Cancelled = "cancelled"
+}
+/**
+ * The state the SDK keeps for one heatpump's current `HeatpumpControlV3`
+ * session.
+ */
+export interface HeatpumpControlSessionState {
+    /** The session's `sessionId`. */
+    sessionId: string;
+    /** A stable key of the session's actions — changes when any action changes. */
+    actionsKey: string;
+    /** The latest `validUntilIso`, as epoch milliseconds. */
+    validUntilMs: number;
+}
+/**
+ * Key that identifies an action within a session — its target and zone index.
+ *
+ * @param action - The action.
+ * @returns E.g. `dhw:0`, or `room:` for an action without index.
+ */
+export declare function heatpumpControlActionKey(action: Pick<EnyoHeatpumpControlAction, 'target' | 'index'>): string;
+/**
+ * Stable key of a whole action list, independent of the order the actions
+ * were sent in. Two lists with the same key ask for the same thing.
+ *
+ * @param actions - The session's actions.
+ * @returns A string that changes whenever any action's target, index,
+ *   `deltaK` or `heatSource` changes.
+ */
+export declare function heatpumpControlActionsKey(actions: EnyoHeatpumpControlAction[]): string;
+/**
+ * Tracks the `HeatpumpControlV3` session of each heatpump: which session is
+ * running, which of its actions have been applied, and when it lapses.
+ *
+ * Rules:
+ * - Same `sessionId` and same actions → the session continues; only
+ *   {@link HeatpumpControlSessionState.validUntilMs} moves.
+ * - New `sessionId` or changed actions → a fresh state; every action is
+ *   applied anew.
+ * - No new message by `validUntilIso` → the state is dropped and `onExpired`
+ *   is called for that appliance.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp`; exported so integrations that
+ * override `handleHeatpumpControl` can reuse the same rules.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new HeatpumpControlSessionTracker((applianceId) => resetHeatpump(applianceId));
+ * const {state, isNew} = tracker.track(message.applianceId, message.data);
+ * if (isNew) applyActions(message.data.actions);
+ * ```
+ */
+export declare class HeatpumpControlSessionTracker {
+    private readonly onExpired;
+    private readonly now;
+    private readonly sessions;
+    private readonly timers;
+    /**
+     * @param onExpired - Called when an appliance's session lapses because no
+     *   message arrived by its `validUntilIso`. Not called by {@link end}.
+     * @param now - Clock in epoch milliseconds; injectable for tests.
+     */
+    constructor(onExpired: (applianceId: string) => void, now?: () => number);
+    /**
+     * The current session state of an appliance, if one is running.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns The state, or `undefined`.
+     */
+    get(applianceId: string): HeatpumpControlSessionState | undefined;
+    /**
+     * Records a received session message and (re)arms its expiry.
+     *
+     * @param applianceId - The heatpump appliance the message is for.
+     * @param data - The message's data.
+     * @returns The appliance's state, and `isNew` when the session or its
+     *   actions changed — the moment to apply the actions anew.
+     * @throws {Error} When `validUntilIso` is not an ISO 8601 timestamp.
+     */
+    track(applianceId: string, data: EnyoDataBusHeatpumpControlV3['data']): {
+        state: HeatpumpControlSessionState;
+        isNew: boolean;
+    };
+    /**
+     * Ends an appliance's session without calling `onExpired` — for an
+     * explicit end the caller handles itself.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns `true` when a session was running.
+     */
+    end(applianceId: string): boolean;
+    /** Drops every session and timer. Call on shutdown. */
+    dispose(): void;
+    private armExpiry;
+    private clearTimer;
+}