@enyo-energy/energy-app-sdk 0.0.158 → 0.0.160

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

@@ -1,4 +1,4 @@
-import { EnyoCharge, EnyoChargeFilter } from "../types/enyo-charge.cjs";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.cjs";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
@@ -14,4 +14,24 @@ export interface EnergyAppCharge {
     findActiveCharge: (applianceId: string) => Promise<EnyoCharge | null>;
     /** Find the currently active charge by appliance ID and transaction ID */
     findActiveChargeByTransactionId: (applianceId: string, transactionId: string) => Promise<EnyoCharge | null>;
+    /**
+     * Sets the default charging mode for a specific appliance, optionally
+     * with a target completion time and its timezone.
+     *
+     * **Required permission:** `EnergyManager`.
+     *
+     * @param applianceId - The appliance (charger) the default charge mode applies to.
+     * @param defaultChargeMode - The default charge mode configuration to apply.
+     * @returns Promise that resolves once the default charge mode is stored.
+     */
+    setDefaultChargeMode: (applianceId: string, defaultChargeMode: EnyoDefaultChargeMode) => Promise<void>;
+    /**
+     * Retrieves the currently configured default charging mode for a specific appliance.
+     *
+     * No permission is required to read the default charge mode.
+     *
+     * @param applianceId - The appliance (charger) to read the default charge mode for.
+     * @returns Promise resolving to the configured default charge mode
+     */
+    getDefaultChargeMode: (applianceId: string) => Promise<EnyoDefaultChargeMode>;
 }

package/dist/cjs/packages/energy-app-udp.cjs

@@ -1,2 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyAppUdpBindError = void 0;
+/**
+ * Thrown by {@link EnergyAppUdp.bind} when the underlying socket cannot be
+ * bound — for example `EADDRINUSE`, an invalid multicast group address
+ * supplied via {@link UdpBindOptions.multicastGroups}, or a failure to join
+ * one of the requested groups after the socket starts listening.
+ *
+ * Implementations should wrap the originating `Error` and preserve its
+ * `message` so callers can `instanceof`-check this class while still
+ * surfacing the root cause in logs.
+ */
+class EnergyAppUdpBindError extends Error {
+    /**
+     * Create a new `EnergyAppUdpBindError`.
+     *
+     * @param message - Human-readable description of the bind failure. Should
+     *                  include the root cause (e.g. the originating `Error`'s
+     *                  `message`) so it is preserved for logging.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'EnergyAppUdpBindError';
+    }
+}
+exports.EnergyAppUdpBindError = EnergyAppUdpBindError;

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

@@ -9,9 +9,37 @@ export interface UdpBindOptions {
      * sockets may bind to the same address/port. Maps to the `reuseAddr`
      * option of `node:dgram`'s `createSocket`.
      *
+     * Particularly useful in combination with {@link multicastGroups} so
+     * that multiple processes on the same host can receive the same
+     * multicast stream.
+     *
      * Defaults to `false`.
      */
     reuseAddr?: boolean;
+    /**
+     * IPv4 multicast group addresses to join after the socket is bound.
+     *
+     * Each entry must be a dotted-quad IPv4 address in the multicast range
+     * `224.0.0.0/4` (i.e. first octet 224–239). The runtime joins every
+     * listed group on the socket once the `listening` event fires; if any
+     * join fails or any entry is not a valid multicast address, the socket
+     * is closed and {@link EnergyAppUdp.bind} rejects with
+     * {@link EnergyAppUdpBindError}.
+     *
+     * Typical use: SMA Speedwire receivers join `239.12.255.254`.
+     *
+     * Defaults to `undefined` (no multicast membership — unicast bind only).
+     */
+    multicastGroups?: string[];
+    /**
+     * Optional local interface address (IPv4 dotted-quad) to bind the
+     * multicast membership(s) to. When omitted, the operating system
+     * selects an interface — usually the one carrying the default route.
+     *
+     * Only meaningful in combination with {@link multicastGroups}. Most
+     * callers should leave this `undefined`.
+     */
+    multicastInterface?: string;
 }
 /**
  * A single inbound datagram delivered to a handler registered with
@@ -84,6 +112,31 @@ export interface EnergyAppUdpSocket {
      *          its `close` event.
      */
     close(): Promise<void>;
+    /**
+     * Join an additional IPv4 multicast group on this already-bound socket.
+     *
+     * The address must be a dotted-quad in the multicast range
+     * `224.0.0.0/4`. Implementations forward to the underlying
+     * `dgram.Socket.addMembership` call.
+     *
+     * @param group - IPv4 multicast group address to join.
+     * @param interfaceAddress - Optional local interface (IPv4 dotted-quad)
+     *                           to bind the membership to. When omitted,
+     *                           the operating system selects an interface.
+     * @throws If the address is not a valid multicast address, the socket
+     *         has been closed, or the underlying join fails.
+     */
+    addMembership(group: string, interfaceAddress?: string): void;
+    /**
+     * Leave a previously joined IPv4 multicast group.
+     *
+     * @param group - IPv4 multicast group address to leave.
+     * @param interfaceAddress - Optional local interface (IPv4 dotted-quad)
+     *                           the membership was originally bound to.
+     * @throws If the address is not a valid multicast address, the socket
+     *         has been closed, or no matching membership exists.
+     */
+    dropMembership(group: string, interfaceAddress?: string): void;
 }
 /**
  * Interface for raw UDP communication in enyo packages.
@@ -102,17 +155,54 @@ export interface EnergyAppUdpSocket {
  * socket.off(handlerId);
  * await socket.close();
  * ```
+ *
+ * @example Multicast receiver (SMA Speedwire)
+ * ```typescript
+ * const udp = energyApp.useUdp();
+ * const socket = await udp.bind({
+ *     port: 9522,
+ *     reuseAddr: true,
+ *     multicastGroups: ['239.12.255.254'],
+ * });
+ * socket.onMessage((msg) => {
+ *     // Inbound SMA Speedwire datagram on 239.12.255.254:9522
+ * });
+ * ```
  */
 export interface EnergyAppUdp {
     /**
      * Bind a UDP socket on the requested host/port.
      *
      * Resolves once the underlying socket has emitted its `listening` event.
+     * When {@link UdpBindOptions.multicastGroups} is provided, the runtime
+     * also joins each listed group before the returned promise resolves.
      *
      * @param options - Bind configuration (see {@link UdpBindOptions}).
      * @returns A bound socket ready to send and receive datagrams.
      * @throws {EnergyAppUdpBindError} If the requested port is already in use
-     *         (EADDRINUSE). Other errors propagate as their original Error.
+     *         (EADDRINUSE), any entry in {@link UdpBindOptions.multicastGroups}
+     *         is not a valid IPv4 multicast address, or joining a requested
+     *         group fails. Other errors propagate as their original Error.
      */
     bind(options: UdpBindOptions): Promise<EnergyAppUdpSocket>;
 }
+/**
+ * Thrown by {@link EnergyAppUdp.bind} when the underlying socket cannot be
+ * bound — for example `EADDRINUSE`, an invalid multicast group address
+ * supplied via {@link UdpBindOptions.multicastGroups}, or a failure to join
+ * one of the requested groups after the socket starts listening.
+ *
+ * Implementations should wrap the originating `Error` and preserve its
+ * `message` so callers can `instanceof`-check this class while still
+ * surfacing the root cause in logs.
+ */
+export declare class EnergyAppUdpBindError extends Error {
+    /**
+     * Create a new `EnergyAppUdpBindError`.
+     *
+     * @param message - Human-readable description of the bind failure. Should
+     *                  include the root cause (e.g. the originating `Error`'s
+     *                  `message`) so it is preserved for logging.
+     */
+    constructor(message: string);
+}

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

@@ -83,6 +83,27 @@ export interface EnyoChargeScheduleEntry {
     /** Current limit in Ampere for this schedule period */
     limitAmpere: number;
 }
+/**
+ * Default charging preference applied to charging sessions when no
+ * per-session mode is explicitly provided.
+ */
+export interface EnyoDefaultChargeMode {
+    /** The default charging mode (e.g. immediate, cost-optimized, price-limit) */
+    chargeMode: EnyoChargeModeEnum;
+    /**
+     * Optional target completion time as a wall-clock time in the
+     * accompanying {@link EnyoDefaultChargeMode.timezone} (e.g. `"07:30"`).
+     * When set, optimized modes plan the session to finish by this time.
+     */
+    completeAtTime?: string;
+    /**
+     * IANA timezone the {@link EnyoDefaultChargeMode.completeAtTime} is
+     * expressed in (e.g. `"Europe/Berlin"`). Should be provided whenever
+     * `completeAtTime` is set so the wall-clock time can be resolved
+     * unambiguously.
+     */
+    timezone?: string;
+}
 export interface EnyoChargeFilter {
     /** Filter by specific appliance ID */
     applianceId?: string;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
+exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -23,7 +23,51 @@ var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationActive"] = "grid-operator-power-limitation-active";
     /** Command issued because a grid operator power limitation is inactive */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationInactive"] = "grid-operator-power-limitation-inactive";
+    /** Command issued because the battery state of charge is low */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCLow"] = "battery-soc-low";
+    /** Command issued because the battery state of charge is high */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCHigh"] = "battery-soc-high";
+    /** Command issued to follow the planned EV charging schedule */
+    EnyoDataBusCommandReasonTypeEnum["EvChargingSchedule"] = "ev-charging-schedule";
+    /** Command issued as part of a planned/scheduled optimization */
+    EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
+    /** Command issued because the user explicitly requested it */
+    EnyoDataBusCommandReasonTypeEnum["UserRequest"] = "user-request";
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    EnyoDataBusCommandReasonTypeEnum["DeviceProtection"] = "device-protection";
+    /** Command issued because home consumption is high */
+    EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
+    /** Command issued to optimize self-consumption */
+    EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
 })(EnyoDataBusCommandReasonTypeEnum || (exports.EnyoDataBusCommandReasonTypeEnum = EnyoDataBusCommandReasonTypeEnum = {}));
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+var EnyoDataBusCommandReasonCategoryEnum;
+(function (EnyoDataBusCommandReasonCategoryEnum) {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnyoDataBusCommandReasonCategoryEnum["EnergyPrice"] = "energy-price";
+    /** Driven by available/unavailable PV surplus. */
+    EnyoDataBusCommandReasonCategoryEnum["PvSurplus"] = "pv-surplus";
+    /** Driven by battery capacity or state of charge. */
+    EnyoDataBusCommandReasonCategoryEnum["BatteryState"] = "battery-state";
+    /** Driven by a grid operator power limitation. */
+    EnyoDataBusCommandReasonCategoryEnum["GridLimitation"] = "grid-limitation";
+    /** Driven by following a planned schedule. */
+    EnyoDataBusCommandReasonCategoryEnum["Schedule"] = "schedule";
+    /** Driven by an explicit user request. */
+    EnyoDataBusCommandReasonCategoryEnum["UserRequest"] = "user-request";
+    /** Driven by device protection / safety (e.g. overheating). */
+    EnyoDataBusCommandReasonCategoryEnum["DeviceProtection"] = "device-protection";
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    EnyoDataBusCommandReasonCategoryEnum["Temperature"] = "temperature";
+    /** Driven by self-consumption optimization. */
+    EnyoDataBusCommandReasonCategoryEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
+    /** Any reason not covered by the categories above. */
+    EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
+})(EnyoDataBusCommandReasonCategoryEnum || (exports.EnyoDataBusCommandReasonCategoryEnum = EnyoDataBusCommandReasonCategoryEnum = {}));
 var EnyoBatteryStateEnum;
 (function (EnyoBatteryStateEnum) {
     EnyoBatteryStateEnum["Off"] = "off";
@@ -107,6 +151,16 @@ var EnyoChargeModeEnum;
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     EnyoChargeModeEnum["PriceLimit"] = "price-limit";
 })(EnyoChargeModeEnum || (exports.EnyoChargeModeEnum = EnyoChargeModeEnum = {}));
+/**
+ * Identifies who initiated a charging session.
+ */
+var EnyoChargeInitiatorEnum;
+(function (EnyoChargeInitiatorEnum) {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    EnyoChargeInitiatorEnum["App"] = "app";
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    EnyoChargeInitiatorEnum["Charger"] = "charger";
+})(EnyoChargeInitiatorEnum || (exports.EnyoChargeInitiatorEnum = EnyoChargeInitiatorEnum = {}));
 var EnyoDataBusMessageEnum;
 (function (EnyoDataBusMessageEnum) {
     EnyoDataBusMessageEnum["InverterValuesUpdateV1"] = "InverterValuesUpdateV1";

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

@@ -8,6 +8,7 @@ import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.cjs";
 import { EnyoAirConditioningApplianceModeEnum } from "./enyo-air-conditioning-appliance.cjs";
 import { EnergyAppPackageCategory } from "../energy-app-package-definition.cjs";
+import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.cjs";
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -28,7 +29,50 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     /** Command issued because a grid operator power limitation is active */
     GridOperatorPowerLimitationActive = "grid-operator-power-limitation-active",
     /** Command issued because a grid operator power limitation is inactive */
-    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive"
+    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive",
+    /** Command issued because the battery state of charge is low */
+    BatterySoCLow = "battery-soc-low",
+    /** Command issued because the battery state of charge is high */
+    BatterySoCHigh = "battery-soc-high",
+    /** Command issued to follow the planned EV charging schedule */
+    EvChargingSchedule = "ev-charging-schedule",
+    /** Command issued as part of a planned/scheduled optimization */
+    ScheduledOptimization = "scheduled-optimization",
+    /** Command issued because the user explicitly requested it */
+    UserRequest = "user-request",
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    DeviceProtection = "device-protection",
+    /** Command issued because home consumption is high */
+    HomeConsumptionHigh = "home-consumption-high",
+    /** Command issued to optimize self-consumption */
+    SelfConsumptionOptimization = "self-consumption-optimization"
+}
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+export declare enum EnyoDataBusCommandReasonCategoryEnum {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnergyPrice = "energy-price",
+    /** Driven by available/unavailable PV surplus. */
+    PvSurplus = "pv-surplus",
+    /** Driven by battery capacity or state of charge. */
+    BatteryState = "battery-state",
+    /** Driven by a grid operator power limitation. */
+    GridLimitation = "grid-limitation",
+    /** Driven by following a planned schedule. */
+    Schedule = "schedule",
+    /** Driven by an explicit user request. */
+    UserRequest = "user-request",
+    /** Driven by device protection / safety (e.g. overheating). */
+    DeviceProtection = "device-protection",
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    Temperature = "temperature",
+    /** Driven by self-consumption optimization. */
+    SelfConsumptionOptimization = "self-consumption-optimization",
+    /** Any reason not covered by the categories above. */
+    Other = "other"
 }
 /**
  * Interface describing the reason why a data bus command was issued.
@@ -37,6 +81,10 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
 export interface EnyoDataBusCommandReason {
     /** The reason type indicating why this command was issued */
     type: EnyoDataBusCommandReasonTypeEnum;
+    /** Coarse category for grouping, iconography, and analytics */
+    category?: EnyoDataBusCommandReasonCategoryEnum;
+    /** Per-language, end-user-facing explanation of this reason */
+    translation?: EnyoPackageConfigurationTranslatedValue[];
     /** Electricity price per kWh that triggered this command */
     electricityPricePerKwh?: number;
     /** Currency of the electricity price */
@@ -47,6 +95,10 @@ export interface EnyoDataBusCommandReason {
     powerW?: number;
     /** Relevant energy in Watt hours */
     powerWh?: number;
+    /** Relevant temperature in Celsius (e.g. heatpump-driven reasons) */
+    temperatureC?: number;
+    /** Relevant state of charge as a percentage (battery-driven reasons) */
+    socPercent?: number;
 }
 export declare enum EnyoBatteryStateEnum {
     Off = "off",
@@ -125,6 +177,15 @@ export declare enum EnyoChargeModeEnum {
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     PriceLimit = "price-limit"
 }
+/**
+ * Identifies who initiated a charging session.
+ */
+export declare enum EnyoChargeInitiatorEnum {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    App = "app",
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    Charger = "charger"
+}
 export interface EnyoAggregatedStateApplianceValues {
     powerW?: number;
     batterySoC?: number;
@@ -440,6 +501,8 @@ export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
         transactionId: string;
         /** used charging card */
         chargingCardId?: string;
+        /** Who initiated the charging session — the enyo app or the charger itself */
+        initiator: EnyoChargeInitiatorEnum;
         /** The charge mode of the started charge. If initiated by wallbox, use either user settings or immediate as default */
         chargeMode: EnyoChargeModeEnum;
         /** ISO timestamp for target completion time (optional) */

package/dist/cjs/version.cjs

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

package/dist/cjs/version.d.cts

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

package/dist/packages/energy-app-charge.d.ts

@@ -1,4 +1,4 @@
-import { EnyoCharge, EnyoChargeFilter } from "../types/enyo-charge.js";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.js";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
@@ -14,4 +14,24 @@ export interface EnergyAppCharge {
     findActiveCharge: (applianceId: string) => Promise<EnyoCharge | null>;
     /** Find the currently active charge by appliance ID and transaction ID */
     findActiveChargeByTransactionId: (applianceId: string, transactionId: string) => Promise<EnyoCharge | null>;
+    /**
+     * Sets the default charging mode for a specific appliance, optionally
+     * with a target completion time and its timezone.
+     *
+     * **Required permission:** `EnergyManager`.
+     *
+     * @param applianceId - The appliance (charger) the default charge mode applies to.
+     * @param defaultChargeMode - The default charge mode configuration to apply.
+     * @returns Promise that resolves once the default charge mode is stored.
+     */
+    setDefaultChargeMode: (applianceId: string, defaultChargeMode: EnyoDefaultChargeMode) => Promise<void>;
+    /**
+     * Retrieves the currently configured default charging mode for a specific appliance.
+     *
+     * No permission is required to read the default charge mode.
+     *
+     * @param applianceId - The appliance (charger) to read the default charge mode for.
+     * @returns Promise resolving to the configured default charge mode
+     */
+    getDefaultChargeMode: (applianceId: string) => Promise<EnyoDefaultChargeMode>;
 }

package/dist/packages/energy-app-udp.d.ts

@@ -9,9 +9,37 @@ export interface UdpBindOptions {
      * sockets may bind to the same address/port. Maps to the `reuseAddr`
      * option of `node:dgram`'s `createSocket`.
      *
+     * Particularly useful in combination with {@link multicastGroups} so
+     * that multiple processes on the same host can receive the same
+     * multicast stream.
+     *
      * Defaults to `false`.
      */
     reuseAddr?: boolean;
+    /**
+     * IPv4 multicast group addresses to join after the socket is bound.
+     *
+     * Each entry must be a dotted-quad IPv4 address in the multicast range
+     * `224.0.0.0/4` (i.e. first octet 224–239). The runtime joins every
+     * listed group on the socket once the `listening` event fires; if any
+     * join fails or any entry is not a valid multicast address, the socket
+     * is closed and {@link EnergyAppUdp.bind} rejects with
+     * {@link EnergyAppUdpBindError}.
+     *
+     * Typical use: SMA Speedwire receivers join `239.12.255.254`.
+     *
+     * Defaults to `undefined` (no multicast membership — unicast bind only).
+     */
+    multicastGroups?: string[];
+    /**
+     * Optional local interface address (IPv4 dotted-quad) to bind the
+     * multicast membership(s) to. When omitted, the operating system
+     * selects an interface — usually the one carrying the default route.
+     *
+     * Only meaningful in combination with {@link multicastGroups}. Most
+     * callers should leave this `undefined`.
+     */
+    multicastInterface?: string;
 }
 /**
  * A single inbound datagram delivered to a handler registered with
@@ -84,6 +112,31 @@ export interface EnergyAppUdpSocket {
      *          its `close` event.
      */
     close(): Promise<void>;
+    /**
+     * Join an additional IPv4 multicast group on this already-bound socket.
+     *
+     * The address must be a dotted-quad in the multicast range
+     * `224.0.0.0/4`. Implementations forward to the underlying
+     * `dgram.Socket.addMembership` call.
+     *
+     * @param group - IPv4 multicast group address to join.
+     * @param interfaceAddress - Optional local interface (IPv4 dotted-quad)
+     *                           to bind the membership to. When omitted,
+     *                           the operating system selects an interface.
+     * @throws If the address is not a valid multicast address, the socket
+     *         has been closed, or the underlying join fails.
+     */
+    addMembership(group: string, interfaceAddress?: string): void;
+    /**
+     * Leave a previously joined IPv4 multicast group.
+     *
+     * @param group - IPv4 multicast group address to leave.
+     * @param interfaceAddress - Optional local interface (IPv4 dotted-quad)
+     *                           the membership was originally bound to.
+     * @throws If the address is not a valid multicast address, the socket
+     *         has been closed, or no matching membership exists.
+     */
+    dropMembership(group: string, interfaceAddress?: string): void;
 }
 /**
  * Interface for raw UDP communication in enyo packages.
@@ -102,17 +155,54 @@ export interface EnergyAppUdpSocket {
  * socket.off(handlerId);
  * await socket.close();
  * ```
+ *
+ * @example Multicast receiver (SMA Speedwire)
+ * ```typescript
+ * const udp = energyApp.useUdp();
+ * const socket = await udp.bind({
+ *     port: 9522,
+ *     reuseAddr: true,
+ *     multicastGroups: ['239.12.255.254'],
+ * });
+ * socket.onMessage((msg) => {
+ *     // Inbound SMA Speedwire datagram on 239.12.255.254:9522
+ * });
+ * ```
  */
 export interface EnergyAppUdp {
     /**
      * Bind a UDP socket on the requested host/port.
      *
      * Resolves once the underlying socket has emitted its `listening` event.
+     * When {@link UdpBindOptions.multicastGroups} is provided, the runtime
+     * also joins each listed group before the returned promise resolves.
      *
      * @param options - Bind configuration (see {@link UdpBindOptions}).
      * @returns A bound socket ready to send and receive datagrams.
      * @throws {EnergyAppUdpBindError} If the requested port is already in use
-     *         (EADDRINUSE). Other errors propagate as their original Error.
+     *         (EADDRINUSE), any entry in {@link UdpBindOptions.multicastGroups}
+     *         is not a valid IPv4 multicast address, or joining a requested
+     *         group fails. Other errors propagate as their original Error.
      */
     bind(options: UdpBindOptions): Promise<EnergyAppUdpSocket>;
 }
+/**
+ * Thrown by {@link EnergyAppUdp.bind} when the underlying socket cannot be
+ * bound — for example `EADDRINUSE`, an invalid multicast group address
+ * supplied via {@link UdpBindOptions.multicastGroups}, or a failure to join
+ * one of the requested groups after the socket starts listening.
+ *
+ * Implementations should wrap the originating `Error` and preserve its
+ * `message` so callers can `instanceof`-check this class while still
+ * surfacing the root cause in logs.
+ */
+export declare class EnergyAppUdpBindError extends Error {
+    /**
+     * Create a new `EnergyAppUdpBindError`.
+     *
+     * @param message - Human-readable description of the bind failure. Should
+     *                  include the root cause (e.g. the originating `Error`'s
+     *                  `message`) so it is preserved for logging.
+     */
+    constructor(message: string);
+}

package/dist/packages/energy-app-udp.js

@@ -1 +1,23 @@
-export {};
+/**
+ * Thrown by {@link EnergyAppUdp.bind} when the underlying socket cannot be
+ * bound — for example `EADDRINUSE`, an invalid multicast group address
+ * supplied via {@link UdpBindOptions.multicastGroups}, or a failure to join
+ * one of the requested groups after the socket starts listening.
+ *
+ * Implementations should wrap the originating `Error` and preserve its
+ * `message` so callers can `instanceof`-check this class while still
+ * surfacing the root cause in logs.
+ */
+export class EnergyAppUdpBindError extends Error {
+    /**
+     * Create a new `EnergyAppUdpBindError`.
+     *
+     * @param message - Human-readable description of the bind failure. Should
+     *                  include the root cause (e.g. the originating `Error`'s
+     *                  `message`) so it is preserved for logging.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'EnergyAppUdpBindError';
+    }
+}

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

@@ -83,6 +83,27 @@ export interface EnyoChargeScheduleEntry {
     /** Current limit in Ampere for this schedule period */
     limitAmpere: number;
 }
+/**
+ * Default charging preference applied to charging sessions when no
+ * per-session mode is explicitly provided.
+ */
+export interface EnyoDefaultChargeMode {
+    /** The default charging mode (e.g. immediate, cost-optimized, price-limit) */
+    chargeMode: EnyoChargeModeEnum;
+    /**
+     * Optional target completion time as a wall-clock time in the
+     * accompanying {@link EnyoDefaultChargeMode.timezone} (e.g. `"07:30"`).
+     * When set, optimized modes plan the session to finish by this time.
+     */
+    completeAtTime?: string;
+    /**
+     * IANA timezone the {@link EnyoDefaultChargeMode.completeAtTime} is
+     * expressed in (e.g. `"Europe/Berlin"`). Should be provided whenever
+     * `completeAtTime` is set so the wall-clock time can be resolved
+     * unambiguously.
+     */
+    timezone?: string;
+}
 export interface EnyoChargeFilter {
     /** Filter by specific appliance ID */
     applianceId?: string;

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

@@ -8,6 +8,7 @@ import { EnyoCurrencyEnum } from "./enyo-currency.js";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.js";
 import { EnyoAirConditioningApplianceModeEnum } from "./enyo-air-conditioning-appliance.js";
 import { EnergyAppPackageCategory } from "../energy-app-package-definition.js";
+import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.js";
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -28,7 +29,50 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     /** Command issued because a grid operator power limitation is active */
     GridOperatorPowerLimitationActive = "grid-operator-power-limitation-active",
     /** Command issued because a grid operator power limitation is inactive */
-    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive"
+    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive",
+    /** Command issued because the battery state of charge is low */
+    BatterySoCLow = "battery-soc-low",
+    /** Command issued because the battery state of charge is high */
+    BatterySoCHigh = "battery-soc-high",
+    /** Command issued to follow the planned EV charging schedule */
+    EvChargingSchedule = "ev-charging-schedule",
+    /** Command issued as part of a planned/scheduled optimization */
+    ScheduledOptimization = "scheduled-optimization",
+    /** Command issued because the user explicitly requested it */
+    UserRequest = "user-request",
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    DeviceProtection = "device-protection",
+    /** Command issued because home consumption is high */
+    HomeConsumptionHigh = "home-consumption-high",
+    /** Command issued to optimize self-consumption */
+    SelfConsumptionOptimization = "self-consumption-optimization"
+}
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+export declare enum EnyoDataBusCommandReasonCategoryEnum {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnergyPrice = "energy-price",
+    /** Driven by available/unavailable PV surplus. */
+    PvSurplus = "pv-surplus",
+    /** Driven by battery capacity or state of charge. */
+    BatteryState = "battery-state",
+    /** Driven by a grid operator power limitation. */
+    GridLimitation = "grid-limitation",
+    /** Driven by following a planned schedule. */
+    Schedule = "schedule",
+    /** Driven by an explicit user request. */
+    UserRequest = "user-request",
+    /** Driven by device protection / safety (e.g. overheating). */
+    DeviceProtection = "device-protection",
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    Temperature = "temperature",
+    /** Driven by self-consumption optimization. */
+    SelfConsumptionOptimization = "self-consumption-optimization",
+    /** Any reason not covered by the categories above. */
+    Other = "other"
 }
 /**
  * Interface describing the reason why a data bus command was issued.
@@ -37,6 +81,10 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
 export interface EnyoDataBusCommandReason {
     /** The reason type indicating why this command was issued */
     type: EnyoDataBusCommandReasonTypeEnum;
+    /** Coarse category for grouping, iconography, and analytics */
+    category?: EnyoDataBusCommandReasonCategoryEnum;
+    /** Per-language, end-user-facing explanation of this reason */
+    translation?: EnyoPackageConfigurationTranslatedValue[];
     /** Electricity price per kWh that triggered this command */
     electricityPricePerKwh?: number;
     /** Currency of the electricity price */
@@ -47,6 +95,10 @@ export interface EnyoDataBusCommandReason {
     powerW?: number;
     /** Relevant energy in Watt hours */
     powerWh?: number;
+    /** Relevant temperature in Celsius (e.g. heatpump-driven reasons) */
+    temperatureC?: number;
+    /** Relevant state of charge as a percentage (battery-driven reasons) */
+    socPercent?: number;
 }
 export declare enum EnyoBatteryStateEnum {
     Off = "off",
@@ -125,6 +177,15 @@ export declare enum EnyoChargeModeEnum {
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     PriceLimit = "price-limit"
 }
+/**
+ * Identifies who initiated a charging session.
+ */
+export declare enum EnyoChargeInitiatorEnum {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    App = "app",
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    Charger = "charger"
+}
 export interface EnyoAggregatedStateApplianceValues {
     powerW?: number;
     batterySoC?: number;
@@ -440,6 +501,8 @@ export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
         transactionId: string;
         /** used charging card */
         chargingCardId?: string;
+        /** Who initiated the charging session — the enyo app or the charger itself */
+        initiator: EnyoChargeInitiatorEnum;
         /** The charge mode of the started charge. If initiated by wallbox, use either user settings or immediate as default */
         chargeMode: EnyoChargeModeEnum;
         /** ISO timestamp for target completion time (optional) */

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

@@ -20,7 +20,51 @@ export var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationActive"] = "grid-operator-power-limitation-active";
     /** Command issued because a grid operator power limitation is inactive */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationInactive"] = "grid-operator-power-limitation-inactive";
+    /** Command issued because the battery state of charge is low */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCLow"] = "battery-soc-low";
+    /** Command issued because the battery state of charge is high */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCHigh"] = "battery-soc-high";
+    /** Command issued to follow the planned EV charging schedule */
+    EnyoDataBusCommandReasonTypeEnum["EvChargingSchedule"] = "ev-charging-schedule";
+    /** Command issued as part of a planned/scheduled optimization */
+    EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
+    /** Command issued because the user explicitly requested it */
+    EnyoDataBusCommandReasonTypeEnum["UserRequest"] = "user-request";
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    EnyoDataBusCommandReasonTypeEnum["DeviceProtection"] = "device-protection";
+    /** Command issued because home consumption is high */
+    EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
+    /** Command issued to optimize self-consumption */
+    EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
 })(EnyoDataBusCommandReasonTypeEnum || (EnyoDataBusCommandReasonTypeEnum = {}));
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+export var EnyoDataBusCommandReasonCategoryEnum;
+(function (EnyoDataBusCommandReasonCategoryEnum) {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnyoDataBusCommandReasonCategoryEnum["EnergyPrice"] = "energy-price";
+    /** Driven by available/unavailable PV surplus. */
+    EnyoDataBusCommandReasonCategoryEnum["PvSurplus"] = "pv-surplus";
+    /** Driven by battery capacity or state of charge. */
+    EnyoDataBusCommandReasonCategoryEnum["BatteryState"] = "battery-state";
+    /** Driven by a grid operator power limitation. */
+    EnyoDataBusCommandReasonCategoryEnum["GridLimitation"] = "grid-limitation";
+    /** Driven by following a planned schedule. */
+    EnyoDataBusCommandReasonCategoryEnum["Schedule"] = "schedule";
+    /** Driven by an explicit user request. */
+    EnyoDataBusCommandReasonCategoryEnum["UserRequest"] = "user-request";
+    /** Driven by device protection / safety (e.g. overheating). */
+    EnyoDataBusCommandReasonCategoryEnum["DeviceProtection"] = "device-protection";
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    EnyoDataBusCommandReasonCategoryEnum["Temperature"] = "temperature";
+    /** Driven by self-consumption optimization. */
+    EnyoDataBusCommandReasonCategoryEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
+    /** Any reason not covered by the categories above. */
+    EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
+})(EnyoDataBusCommandReasonCategoryEnum || (EnyoDataBusCommandReasonCategoryEnum = {}));
 export var EnyoBatteryStateEnum;
 (function (EnyoBatteryStateEnum) {
     EnyoBatteryStateEnum["Off"] = "off";
@@ -104,6 +148,16 @@ export var EnyoChargeModeEnum;
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     EnyoChargeModeEnum["PriceLimit"] = "price-limit";
 })(EnyoChargeModeEnum || (EnyoChargeModeEnum = {}));
+/**
+ * Identifies who initiated a charging session.
+ */
+export var EnyoChargeInitiatorEnum;
+(function (EnyoChargeInitiatorEnum) {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    EnyoChargeInitiatorEnum["App"] = "app";
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    EnyoChargeInitiatorEnum["Charger"] = "charger";
+})(EnyoChargeInitiatorEnum || (EnyoChargeInitiatorEnum = {}));
 export var EnyoDataBusMessageEnum;
 (function (EnyoDataBusMessageEnum) {
     EnyoDataBusMessageEnum["InverterValuesUpdateV1"] = "InverterValuesUpdateV1";

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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