@enyo-energy/energy-app-sdk 1.14.0 → 1.16.0

package/README.md

@@ -779,25 +779,102 @@ await appliances.removeById(applianceId);
 
 #### `useVehicle(): EnergyAppVehicle`
 
-Access electric vehicle information:
+Access electric vehicles and the charging behaviour configured on them:
 
 ```typescript
 const vehicles = energyApp.useVehicle();
 
 // Get all vehicles
-const vehicleList = await vehicles.getVehicles();
+const vehicleList = await vehicles.list();
 
 // Get vehicle details
-const vehicle = await vehicles.getVehicleById(vehicleId);
+const vehicle = await vehicles.getById(vehicleId);
+
+// How this car wants to be charged — the behaviour travels with the car,
+// not with the wallbox it happens to be plugged into
+vehicle?.defaultChargeMode;          // EnyoChargeModeEnum
+vehicle?.defaultChargeLimitPercent;  // target SoC for every session
+vehicle?.priceLimitMode;             // how the ceiling is expressed, or none
+vehicle?.priceLimitCtPerKwh;         // ct/kWh ceiling, under 'ct-per-kwh'
+vehicle?.priceLimitSharePercent;     // cheapest n % of the day, under 'cheapest-share'
+vehicle?.immediateReserveKwh;        // full-power reserve before any mode
+vehicle?.departureTimeHHmm;          // daily deadline, wall-clock "07:30"
+vehicle?.departureTimezone;          // IANA zone the time is read in
+
+// State of charge is a reading with an age, not a property of the car
+const soc = await vehicles.getSoc(vehicleId);
+if (soc && Date.now() - Date.parse(soc.measuredAtIso) < 60 * 60 * 1000) {
+    console.log(`${soc.socPercent} % as of ${soc.measuredAtIso}`);
+}
+```
 
-// Update vehicle state
-await vehicles.updateVehicleState(vehicleId, {
-    batteryLevel: 80,
-    isPluggedIn: true,
-    estimatedRange: 320
-});
+`EnergyAppVehicle` is read-only — there is no `update()`. An app that can read
+the car (ISO 15118, a manufacturer integration, OCPP meter values carrying SoC)
+**writes a state of charge by publishing `VehicleSocUpdateV1` on the data bus**,
+and the host makes it readable through `getSoc()`:
+
+```typescript
+energyApp.useDataBus().sendMessage([{
+    type: 'message',
+    message: 'VehicleSocUpdateV1',
+    data: {
+        vehicleId,
+        socPercent: 62,
+        // omit only when the reading came straight off the wire
+        measuredAtIso: new Date().toISOString(),
+    },
+}]);
 ```
 
+That message is the only write path for a state of charge; it needs the
+`SendDataBusValues` permission. `getSoc()` resolves to `undefined` when nothing
+is known — an ordinary answer for a car with no SoC source, not an error.
+
+##### Charge modes
+
+Three modes, one meaning each, identical with and without a dynamic tariff — a
+tariff changes only what happens *inside* a mode:
+
+| UI (German) | `EnyoChargeModeEnum` | Behaviour |
+|---|---|---|
+| **Sofort laden** | `Immediate` | Full power, no optimisation, no deadline. |
+| **Nur Sonne** | `PriceLimit` | Strictly PV surplus. Never imports, has no deadline, never has to finish "in time". A price ceiling is meaningless here and is ignored. |
+| **Sonne zuerst** | `CostOptimized` | PV first; whatever is missing by the deadline comes from the grid — in the cheapest hours with a dynamic tariff, as late as possible without one. Takes an **optional** ceiling. |
+
+- **The ceiling belongs to `CostOptimized`**, the only mode that imports at all,
+  and it is optional there: "Preisgrenze: Aus" is a normal answer, not a missing
+  value — spelled as `priceLimitMode` being absent.
+- **A ceiling has two spellings**, picked by `priceLimitMode`
+  (`EnyoPriceLimitModeEnum`) and mutually exclusive:
+  `ct-per-kwh` reads `priceLimitCtPerKwh` ("never above 25 ct/kWh"), while
+  `cheapest-share` reads `priceLimitSharePercent` ("only the cheapest 25 % of
+  the day"). An absolute ceiling says exactly what the user pays but may select
+  no hours at all on a uniformly expensive day; a relative one always selects
+  some hours but says nothing about what they cost. A relative ceiling ranks the
+  intervals *known* for the day, so its effective threshold moves as later
+  prices publish — re-evaluate it instead of resolving it once at session start.
+- **`PriceLimit` without a ceiling is strict PV-only** — an instruction, not an
+  under-specified state. It exists as its own mode rather than as "`CostOptimized`
+  at 0 ct" because the 0 ct spelling breaks the moment wholesale prices go
+  negative, which is exactly when the customer would be glad to import.
+- **An immediate reserve runs ahead of every mode.** With
+  `immediateReserveKwh > 0` on the vehicle, the session charges at full power
+  until that much energy has gone in — counted from the SoC at plug-in — and
+  only then hands over to the selected mode. That includes "Nur Sonne": the
+  driver may have to leave unexpectedly and the sun is not a guarantee.
+
+The values reach an app already resolved, per session, on `StartChargeV1`
+(`startSocPercent`, `targetSocPercent`, `priceLimitMode` + the ceiling it names)
+and on `ChangeChargeModeV1` (the ceiling only — the plug-in SoC is fixed for the
+duration of a session and a mode change must never move it). The host merges
+session, vehicle and wallbox first, so an app never reproduces the precedence
+rules.
+
+The house-wide `EnergyManagerSettingEnum.DefaultChargeMode`, `PriceLimitMode`,
+`PriceLimitCtPerKwh`, `PriceLimitSharePercent` and `CostOptimizedTarget` are
+being retired — the default mode becomes per-wallbox, the ceiling and the
+deadline per-vehicle — but keep honouring them until the migration has run.
+
 #### `useCharge(): EnergyAppCharge`
 
 Manage charging sessions:
@@ -1152,6 +1229,24 @@ await client.publish('control/pump', 'on', /* qos */ 1, /* retain */ false);
 
 For external brokers use `connectToExternalBroker(brokerUrl, options)`. Requires the `Mqtt` permission.
 
+The SDK broker may be switched off until an app needs it. Ask for it before connecting:
+
+```typescript
+const result = await mqtt.requestBrokerEnable({
+    reason: 'Publish inverter readings to the local home automation system',
+});
+
+if (!result.enabled) {
+    // `pending` (awaiting confirmation) or `rejected` (policy / permission) — not an error
+    console.warn(`Local broker unavailable: ${result.status}`);
+    return;
+}
+
+console.log(`Broker ready at ${result.connection?.url}`);
+```
+
+The call is idempotent — an already running broker resolves with `already-enabled`.
+
 #### `useBluetooth(): EnergyAppBluetooth`
 
 Scan for BLE peripherals and perform GATT read / write / notify against them.
@@ -1269,7 +1364,9 @@ A closed, SDK-defined set of user-facing controls the active energy manager hono
 | `HeatingRodMode` | `pv-surplus-only` \| `boost` |
 | `ChargerControl` | boolean |
 | `DefaultChargeMode` | `EnyoChargeModeEnum` |
-| `PriceLimitCtPerKwh` | number, **ct/kWh** (`7` = 7 ct/kWh) |
+| `PriceLimitMode` | `ct-per-kwh` \| `cheapest-share` (absent = no ceiling) |
+| `PriceLimitCtPerKwh` | number, **ct/kWh** (`7` = 7 ct/kWh; only under `ct-per-kwh`) |
+| `PriceLimitSharePercent` | integer **%** of the day (`25` = cheapest quarter; only under `cheapest-share`) |
 | `CostOptimizedTarget` | wall-clock `"07:30"` + IANA timezone |
 
 An energy manager declares what it honours, next to `registerFeatures()`:
@@ -1310,8 +1407,9 @@ Three things to get right:
 
 - **Absent is not `false`.** `undefined` means unsupported or never chosen; `false` means the user switched it off. Check `supported` first, then the value — collapsing the two steers hardware someone deliberately disabled.
 - **How the battery may feed a charging EV is one mode plus its parameter.** `BatteryEvDischargeMode` picks the strategy; `BatteryEvDischargeFixedWh` and `BatteryEvDischargeSocLimitPercent` are read only under their own mode. `block-discharge` (actively hold the battery back) and `unmanaged` (do not intervene either way) are **not** synonyms.
-- **Eight settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `price-limit`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
+- **Ten settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
 - **`priceLimitCtPerKwh` is in cents**, unlike the SDK's machine-readable price fields (`electricityPricePerKwh`, EUR/kWh). Divide by 100 when comparing. `validateEnergyManagerSettingsState()` warns on values outside a plausible ct band, which catches the mix-up.
+- **A price ceiling is one mode plus its parameter**, the same shape as the battery-to-EV one. `PriceLimitMode` picks how the ceiling is expressed — an absolute `ct-per-kwh` or a relative `cheapest-share` — and each value is read only under its own mode; the mode being absent means no ceiling at all. A relative ceiling ranks the price intervals *known* for the day and treats the cheapest `n` % as importable (the same rule as the `cheapest-share-of-day` automation trigger), so its effective threshold moves when tomorrow's prices publish — re-evaluate it rather than resolving it once.
 
 #### `useElectricityTariff(): EnergyAppElectricityTariff`
 

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

@@ -211,7 +211,7 @@ class ApplianceManager {
             airConditioning: appliance.airConditioning,
             heatingRod: appliance.heatingRod,
             smartPlug: appliance.smartPlug,
-            // Conditionally spread the two optional top-level fields that are NOT
+            // Conditionally spread the optional top-level fields that are NOT
             // covered by MERGEABLE_METADATA_KEYS. If they were always materialized
             // as explicit keys, an omitted (undefined) value would clobber the
             // stored value during mergeApplianceData's `{...existing, ...update}`
@@ -219,6 +219,7 @@ class ApplianceManager {
             // while dropping omitted fields so the existing value is preserved.
             ...(appliance.cloudPackageId !== undefined && { cloudPackageId: appliance.cloudPackageId }),
             ...(appliance.availableFeatures !== undefined && { availableFeatures: appliance.availableFeatures }),
+            ...(appliance.compatibilityModes !== undefined && { compatibilityModes: appliance.compatibilityModes }),
         };
         let applianceData = newApplianceData;
         if (existingApplianceId) {

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

@@ -65,6 +65,13 @@ export interface ApplianceConfig {
     heatingRod?: EnyoHeatingRodApplianceMetadata;
     smartPlug?: EnyoSmartPlugApplianceMetadata;
     availableFeatures?: EnyoApplianceAvailableFeaturesEnum[];
+    /**
+     * Optional vendor- or integration-specific compatibility modes. Forwarded to
+     * {@link EnyoAppliance.compatibilityModes} when the appliance is created or
+     * updated. Omit to keep the stored value on an update; pass an explicit `[]`
+     * to clear it.
+     */
+    compatibilityModes?: string[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Forwarded to {@link EnyoAppliance.cloudPackageId} when the
@@ -443,6 +450,11 @@ export interface PartialEnyoAppliance {
     smartPlug?: Partial<EnyoSmartPlugApplianceMetadata>;
     /** Optional custom name for the appliance, defined by the user */
     customName?: string;
+    /**
+     * Optional list of vendor- or integration-specific compatibility modes that
+     * are active for this appliance. Mirrors {@link EnyoAppliance.compatibilityModes}.
+     */
+    compatibilityModes?: string[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Mirrors {@link EnyoAppliance.cloudPackageId}.

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

@@ -54,7 +54,8 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
         };
         // Build the incoming appliance data covering every ApplianceConfig field.
         // The two optional top-level fields that are NOT shallow-merged by
-        // mergeApplianceData (`cloudPackageId`, `availableFeatures`) are only
+        // mergeApplianceData (`cloudPackageId`, `availableFeatures`,
+        // `compatibilityModes`) are only
         // materialized when provided so an omitted value cannot clobber the stored
         // one during an update; pass an explicit value (e.g. `[]`) to clear them.
         const newApplianceData = {
@@ -73,6 +74,7 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
             heatingRod: appliance.heatingRod,
             ...(appliance.cloudPackageId !== undefined && { cloudPackageId: appliance.cloudPackageId }),
             ...(appliance.availableFeatures !== undefined && { availableFeatures: appliance.availableFeatures }),
+            ...(appliance.compatibilityModes !== undefined && { compatibilityModes: appliance.compatibilityModes }),
         };
         // On update, merge onto the stored appliance so type-specific metadata and
         // top-level fields that were not supplied in this call are preserved.

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.cjs

@@ -9,9 +9,9 @@
  *    an IANA zone, a price that is not a finite number. These fail at planning
  *    time, in the dark, on the night the charge was supposed to happen.
  * 2. **Values that can never take effect.** A heating-rod mode stored while rod
- *    control is off, a price limit while the default charge mode is
- *    cost-optimized. Nothing rejects these — they simply do nothing, which reads
- *    to a user as "the app ignored me".
+ *    control is off, a ct/kWh ceiling while the price limit is expressed as a
+ *    share of the day. Nothing rejects these — they simply do nothing, which
+ *    reads to a user as "the app ignored me".
  *
  * The second class is why {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} exists as
  * data: the gate tree is checked here rather than restated by every surface.
@@ -73,6 +73,20 @@ const EV_DISCHARGE_MODES = new Set(Object.values(enyo_energy_manager_settings_js
 const BATTERY_CHARGING_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerBatteryChargingModeEnum));
 const HEATING_ROD_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerHeatingRodModeEnum));
 const CHARGE_MODES = new Set(Object.values(enyo_data_bus_value_js_1.EnyoChargeModeEnum));
+const PRICE_LIMIT_MODES = new Set(Object.values(enyo_data_bus_value_js_1.EnyoPriceLimitModeEnum));
+/**
+ * The band a relative price ceiling must lie in, in percent of the day.
+ *
+ * Matches the automation validators' `AUTOMATION_MIN/MAX_CHEAPEST_SHARE_PERCENT`
+ * on purpose: "the cheapest 25 % of the day" means the same thing whether it
+ * drives a charging session or an automation, and a user who learns one band
+ * should not meet a different one elsewhere.
+ *
+ * `0` is excluded because it selects no hours at all — that is "never import",
+ * which is {@link EnyoChargeModeEnum.PriceLimit}, not a ceiling.
+ */
+const PRICE_LIMIT_SHARE_MIN_PERCENT = 1;
+const PRICE_LIMIT_SHARE_MAX_PERCENT = 100;
 /**
  * True when `timezone` is an IANA zone this runtime recognises.
  *
@@ -116,6 +130,9 @@ function gateValue(values, setting) {
  *   zone the runtime resolves (**error**).
  * - `priceLimitCtPerKwh` is a finite number (**error**), and lies in a plausible
  *   ct/kWh band (**warning** — catches a EUR/kWh value in a ct/kWh field).
+ * - `priceLimitMode` holds an enum member (**error**).
+ * - `priceLimitSharePercent` is an integer in 1…100 (**error**), and not `100`
+ *   (**warning** — the whole day counts as cheap, so it is no ceiling at all).
  * - `batteryEvDischargeMode` holds an enum member (**error**).
  * - `batteryEvDischargeFixedWh` is a finite non-negative number (**error**), and
  *   is neither `0` nor a negligible positive figure (**warning** — the first
@@ -194,6 +211,27 @@ function validateEnergyManagerSettingsState(state) {
                 'cents per kWh, not EUR per kWh.');
         }
     }
+    if (values.priceLimitMode !== undefined && !PRICE_LIMIT_MODES.has(values.priceLimitMode)) {
+        errors.push(`\`priceLimitMode\` "${values.priceLimitMode}" is not an EnyoPriceLimitModeEnum member.`);
+    }
+    if (values.priceLimitSharePercent !== undefined) {
+        const share = values.priceLimitSharePercent;
+        if (typeof share !== 'number' || !Number.isFinite(share)) {
+            errors.push('`priceLimitSharePercent` must be a finite number when set.');
+        }
+        else if (!Number.isInteger(share)) {
+            errors.push(`\`priceLimitSharePercent\` is ${share}; a share of the day is a whole ` +
+                'percentage and must be an integer.');
+        }
+        else if (share < PRICE_LIMIT_SHARE_MIN_PERCENT || share > PRICE_LIMIT_SHARE_MAX_PERCENT) {
+            errors.push(`\`priceLimitSharePercent\` is ${share}; it is a percentage of the day and must ` +
+                `lie between ${PRICE_LIMIT_SHARE_MIN_PERCENT} and ${PRICE_LIMIT_SHARE_MAX_PERCENT}.`);
+        }
+        else if (share === PRICE_LIMIT_SHARE_MAX_PERCENT) {
+            warnings.push('`priceLimitSharePercent` is 100, which treats the whole day as cheap and so ' +
+                'imposes no ceiling at all. Leave `priceLimitMode` unset to say that outright.');
+        }
+    }
     if (values.batteryEvDischargeMode !== undefined
         && !EV_DISCHARGE_MODES.has(values.batteryEvDischargeMode)) {
         errors.push(`\`batteryEvDischargeMode\` "${values.batteryEvDischargeMode}" is not an ` +

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.d.cts

@@ -8,9 +8,9 @@
  *    an IANA zone, a price that is not a finite number. These fail at planning
  *    time, in the dark, on the night the charge was supposed to happen.
  * 2. **Values that can never take effect.** A heating-rod mode stored while rod
- *    control is off, a price limit while the default charge mode is
- *    cost-optimized. Nothing rejects these — they simply do nothing, which reads
- *    to a user as "the app ignored me".
+ *    control is off, a ct/kWh ceiling while the price limit is expressed as a
+ *    share of the day. Nothing rejects these — they simply do nothing, which
+ *    reads to a user as "the app ignored me".
  *
  * The second class is why {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} exists as
  * data: the gate tree is checked here rather than restated by every surface.
@@ -56,6 +56,9 @@ export interface EnergyManagerSettingsValidationResult {
  *   zone the runtime resolves (**error**).
  * - `priceLimitCtPerKwh` is a finite number (**error**), and lies in a plausible
  *   ct/kWh band (**warning** — catches a EUR/kWh value in a ct/kWh field).
+ * - `priceLimitMode` holds an enum member (**error**).
+ * - `priceLimitSharePercent` is an integer in 1…100 (**error**), and not `100`
+ *   (**warning** — the whole day counts as cheap, so it is no ceiling at all).
  * - `batteryEvDischargeMode` holds an enum member (**error**).
  * - `batteryEvDischargeFixedWh` is a finite non-negative number (**error**), and
  *   is neither `0` nor a negligible positive figure (**warning** — the first

package/dist/cjs/index.cjs

@@ -94,6 +94,8 @@ __exportStar(require("./types/enyo-charging-card.cjs"), exports);
 __exportStar(require("./packages/energy-app-charging-card.cjs"), exports);
 __exportStar(require("./types/enyo-charge.cjs"), exports);
 __exportStar(require("./packages/energy-app-charge.cjs"), exports);
+__exportStar(require("./types/enyo-vehicle.cjs"), exports);
+__exportStar(require("./packages/energy-app-vehicle.cjs"), exports);
 __exportStar(require("./types/enyo-battery-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-heatpump-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-inverter-appliance.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -78,6 +78,8 @@ export * from './types/enyo-charging-card.cjs';
 export * from './packages/energy-app-charging-card.cjs';
 export * from './types/enyo-charge.cjs';
 export * from './packages/energy-app-charge.cjs';
+export * from './types/enyo-vehicle.cjs';
+export * from './packages/energy-app-vehicle.cjs';
 export * from './types/enyo-battery-appliance.cjs';
 export * from './types/enyo-heatpump-appliance.cjs';
 export * from './types/enyo-inverter-appliance.cjs';

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

@@ -1,4 +1,4 @@
-import { MqttConnectOptions, MqttExternalConnectOptions, MqttConnectionStatus, MqttSubscribeOptions, MqttPublishOptions, MqttMessage, EnyoMqttAvailableConnectionDetails } from "../types/enyo-mqtt.cjs";
+import { MqttConnectOptions, MqttExternalConnectOptions, MqttConnectionStatus, MqttSubscribeOptions, MqttPublishOptions, MqttMessage, EnyoMqttAvailableConnectionDetails, EnyoMqttBrokerEnableOptions, EnyoMqttBrokerEnableResult } from "../types/enyo-mqtt.cjs";
 /**
  * Interface for MQTT communication in enyo packages.
  * Provides MQTT client functionality with support for both the SDK-provided
@@ -79,6 +79,37 @@ export interface EnergyAppMqtt {
      * ```
      */
     getAvailableConnectionDetails: () => Promise<EnyoMqttAvailableConnectionDetails>;
+    /**
+     * Request that the SDK-provided local MQTT broker be enabled.
+     *
+     * The local broker is not guaranteed to be running: the host may keep it
+     * switched off until an installed app actually needs it. Call this before
+     * {@link connectInternal} or {@link getAvailableConnectionDetails} when the
+     * app depends on the local broker, and treat a non-enabled outcome as a
+     * normal runtime state rather than an error — the host may require a user
+     * or installer confirmation, or refuse the request by policy.
+     *
+     * The call is idempotent: if the broker is already running it resolves with
+     * {@link EnyoMqttBrokerEnableStatus.AlreadyEnabled} without restarting it.
+     *
+     * @param options - Optional reason shown with the request and a wait timeout
+     * @returns The outcome of the request, including the broker connection details when it is running
+     *
+     * @example
+     * ```typescript
+     * const result = await mqtt.requestBrokerEnable({
+     *     reason: 'Publish inverter readings to the local home automation system',
+     * });
+     *
+     * if (!result.enabled) {
+     *     console.warn(`Local broker not available (${result.status}): ${result.message ?? ''}`);
+     *     return;
+     * }
+     *
+     * const client = await mqtt.connectInternal();
+     * ```
+     */
+    requestBrokerEnable: (options?: EnyoMqttBrokerEnableOptions) => Promise<EnyoMqttBrokerEnableResult>;
 }
 /**
  * Represents an active MQTT client connection.

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

@@ -1,11 +1,54 @@
-import { EnyoVehicle } from "../types/enyo-vehicle.cjs";
+import { EnyoVehicle, EnyoVehicleSoc } from "../types/enyo-vehicle.cjs";
 /**
  * Interface for managing vehicles in enyo packages.
- * Provides read-only operations for vehicle information.
+ *
+ * Reading is **read-only by design**: a vehicle's identity and its charging
+ * behaviour are configured by the user in the enyo app, and an energy app
+ * plans against them rather than changing them. There is no `update()` — if
+ * you are looking for one, see the note on the state of charge below.
+ *
+ * ## Writing a state of charge
+ *
+ * An app that can read the car — a wallbox speaking ISO 15118, a manufacturer
+ * cloud integration, an OCPP charge point reporting SoC in its meter values —
+ * publishes it on the data bus as `EnyoDataBusVehicleSocUpdateV1`. The host
+ * ingests the message and it becomes readable through {@link getSoc}:
+ *
+ * ```typescript
+ * energyApp.useDataBus().sendMessage([{
+ *     type: 'message',
+ *     message: 'VehicleSocUpdateV1',
+ *     data: {
+ *         vehicleId,
+ *         socPercent: 62,
+ *         measuredAtIso: new Date().toISOString(),
+ *     },
+ * }]);
+ * ```
+ *
+ * That message is the only write path for a state of charge; publishing it
+ * requires the `SendDataBusValues` permission.
  */
 export interface EnergyAppVehicle {
     /** Get a list of all registered vehicles */
     list: () => Promise<EnyoVehicle[]>;
     /** Get a specific vehicle by its ID */
     getById: (id: string) => Promise<EnyoVehicle | null>;
+    /**
+     * Get the most recent state-of-charge reading for a vehicle.
+     *
+     * Resolves to `undefined` when nothing is known about the car's charge —
+     * no source has ever reported one, or the host does not keep readings
+     * this old. `undefined` is an ordinary answer, not an error: plenty of
+     * vehicles have no SoC source at all, and a planner must cope without one
+     * rather than assume a number.
+     *
+     * The reading carries {@link EnyoVehicleSoc.measuredAtIso}, so decide for
+     * yourself how old is too old before showing it to a user or sizing a
+     * session against it.
+     *
+     * @param id - ID of the vehicle to read.
+     * @returns The reading and its age, or `undefined` when none is known.
+     */
+    getSoc: (id: string) => Promise<EnyoVehicleSoc | undefined>;
 }

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

@@ -277,6 +277,14 @@ export interface EnyoAppliance {
     smartPlug?: EnyoSmartPlugApplianceMetadata;
     /** Optional custom name for the appliance, defined by the user */
     customName?: string;
+    /**
+     * Optional list of vendor- or integration-specific compatibility modes that
+     * are active for this appliance. Each entry is a free-form, non-localized
+     * identifier describing a behavioural deviation the appliance requires
+     * (e.g. a firmware quirk workaround or a legacy protocol dialect).
+     * Consumers that do not know a given mode should ignore it.
+     */
+    compatibilityModes?: string[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Set when the appliance is provisioned and operated by a

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoPowerSourceEnum = exports.EnyoHeatpumpHeatSourceEnum = exports.EnyoHeatpumpControlPurposeEnum = exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageControlDirectionEnum = exports.EnyoStorageControlModeEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoChargingLimitRequestResultEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoHeatingRodStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoGridOperatorLimitTypeEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
+exports.EnyoPowerSourceEnum = exports.EnyoHeatpumpHeatSourceEnum = exports.EnyoHeatpumpControlPurposeEnum = exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageControlDirectionEnum = exports.EnyoStorageControlModeEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoChargingLimitRequestResultEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoPriceLimitModeEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoHeatingRodStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoGridOperatorLimitTypeEnum = 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.
@@ -205,17 +205,101 @@ var EnyoChargingStopReason;
     EnyoChargingStopReason["Other"] = "Other";
 })(EnyoChargingStopReason || (exports.EnyoChargingStopReason = EnyoChargingStopReason = {}));
 /**
- * Mode for charging session
+ * Mode for a charging session.
+ *
+ * Three modes, one meaning each, identical with and without a dynamic tariff —
+ * the tariff changes only what happens *inside* a mode, never which modes
+ * exist. The user-facing German names map one to one:
+ *
+ * | UI | Member | Behaviour |
+ * |---|---|---|
+ * | Sofort laden | {@link Immediate} | full power, no optimisation |
+ * | Nur Sonne | {@link PriceLimit} | strictly PV surplus, never imports |
+ * | Sonne zuerst | {@link CostOptimized} | PV first, grid tops up by the deadline |
+ *
+ * **An immediate reserve runs ahead of every mode.** When the vehicle carries
+ * `immediateReserveKwh > 0` (see `EnyoVehicle`), the session first charges at
+ * full power until that much energy has gone in — counted from the state of
+ * charge at plug-in — and only then hands over to the selected mode. This
+ * applies to {@link PriceLimit} too: the point of the reserve is that the
+ * driver may have to leave unexpectedly, and the sun is not a guarantee.
  */
 var EnyoChargeModeEnum;
 (function (EnyoChargeModeEnum) {
-    /** Start charging immediately at maximum rate */
+    /**
+     * "Sofort laden" — charge at the highest power the car and the wallbox
+     * jointly allow, immediately, with no optimisation and no deadline.
+     */
     EnyoChargeModeEnum["Immediate"] = "immediate";
-    /** Optimize charging schedule for lowest cost */
+    /**
+     * "Sonne zuerst" — PV surplus first; whatever is still missing by
+     * `completeChargeAtIso` is imported from the grid, in the cheapest hours
+     * with a dynamic tariff and as late as possible without one.
+     *
+     * This is the only mode that imports, so it is the only one a price
+     * ceiling applies to: it takes an **optional**
+     * {@link EnyoDataBusStartChargeV1.data.priceLimitCtPerKwh}, and no ceiling
+     * is a normal answer rather than a missing one.
+     */
     EnyoChargeModeEnum["CostOptimized"] = "cost-optimized";
-    /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
+    /**
+     * "Nur Sonne" — strictly PV surplus. No grid energy, ever, for this
+     * session. There is no deadline and the session never has to finish "in
+     * time"; it charges what the sun delivers and stops when it does not.
+     *
+     * A price ceiling is meaningless here and must be ignored if one is sent.
+     *
+     * Strict PV-only is its own answer rather than "{@link CostOptimized} at
+     * 0 ct" because the 0 ct spelling fails the moment wholesale prices go
+     * negative — which is precisely when the customer would be glad to import.
+     */
     EnyoChargeModeEnum["PriceLimit"] = "price-limit";
 })(EnyoChargeModeEnum || (exports.EnyoChargeModeEnum = EnyoChargeModeEnum = {}));
+/**
+ * How a price ceiling for grid energy is expressed.
+ *
+ * The two spellings answer the same question — "which grid energy is cheap
+ * enough to charge from?" — in the two ways a user thinks about it, and they
+ * are mutually exclusive: the mode says which of the accompanying values is
+ * read, exactly as {@link EnergyManagerBatteryEvDischargeModeEnum} does for the
+ * battery-to-vehicle parameters.
+ *
+ * No mode at all means **no ceiling**, which is a deliberate and common answer
+ * ("Preisgrenze: Aus") rather than a missing value.
+ *
+ * Both spellings resolve to the same thing at planning time: an absolute price
+ * per kWh above which the session does not import. A relative ceiling simply
+ * resolves late, against the prices actually known for the day.
+ *
+ * A ceiling only applies under {@link EnyoChargeModeEnum.CostOptimized} — the
+ * only mode that imports at all.
+ */
+var EnyoPriceLimitModeEnum;
+(function (EnyoPriceLimitModeEnum) {
+    /**
+     * Absolute ceiling: never import above `priceLimitCtPerKwh` cents per kWh.
+     *
+     * Says exactly what the user pays at most, and is independent of how the
+     * rest of the day looks — on a uniformly expensive day it may mean the car
+     * does not charge from the grid at all.
+     */
+    EnyoPriceLimitModeEnum["CtPerKwh"] = "ct-per-kwh";
+    /**
+     * Relative ceiling: import only during the cheapest `priceLimitSharePercent`
+     * of the day — `25` is the cheapest quarter.
+     *
+     * The intervals known for the day are ranked and the cheapest share is
+     * treated as importable, the same rule
+     * {@link EnyoAutomationCheapestShareOfDayTrigger} applies. Note "the day"
+     * is the prices *known* at evaluation time: before the next day's prices
+     * publish, the share is taken over a shorter horizon and the resulting
+     * threshold moves when they arrive.
+     *
+     * Always yields some importable hours, which an absolute ceiling does not —
+     * but it says nothing about what those hours cost.
+     */
+    EnyoPriceLimitModeEnum["CheapestShare"] = "cheapest-share";
+})(EnyoPriceLimitModeEnum || (exports.EnyoPriceLimitModeEnum = EnyoPriceLimitModeEnum = {}));
 /**
  * Identifies who initiated a charging session.
  */