@enyo-energy/energy-app-sdk 1.45.0 → 1.46.0

package/README.md

@@ -1282,6 +1282,41 @@ settings.listenForSettingsChanges((event) => {
 });
 ```
 
+##### Expert settings and onboarding
+
+These two optional flags work on a single setting and on a setting group:
+
+- `expertSetting: true` hides the setting from the default view and shows it only in the expert / advanced section,
+  e.g. for installers.
+- `showInOnboarding: true` shows the setting during onboarding, so the user can set it while setting up the app.
+
+A setting without its own value inherits the flag from its group. A value set on the setting overrides the group's.
+Both default to `false`.
+
+```typescript
+await settings.addSettingGroup({
+    groupName: 'modbus',
+    caption: [{ language: 'en', value: 'Modbus' }, { language: 'de', value: 'Modbus' }],
+    expertSetting: true,                 // all settings of the group are expert settings ...
+    settings: [
+        {
+            name: 'modbus-host',
+            type: 'text',
+            required: true,
+            fieldName: [{ language: 'en', value: 'IP address' }, { language: 'de', value: 'IP-Adresse' }],
+            expertSetting: false,        // ... except this one, which overrides the group
+            showInOnboarding: true,
+        },
+        {
+            name: 'modbus-unit-id',
+            type: 'integer',
+            required: false,
+            fieldName: [{ language: 'en', value: 'Unit ID' }, { language: 'de', value: 'Unit-ID' }],
+        },
+    ],
+});
+```
+
 #### `useConfigurationManager(): EnergyAppConfigurationManager`
 
 Register **internal**, non user-facing configurations for your package and react to value changes. Unlike `useSettings()`, configurations registered here are NOT rendered in the Energy App UI — they are intended for values the package itself reads and writes at runtime (e.g. internal feature toggles, tuning parameters, calibration values) and need to be persisted across restarts.
@@ -4380,6 +4415,26 @@ Two charger facts belong on the appliance rather than on a forecast, and `EnyoCh
 
 Both are for marking on the same power scale a consumer already draws from `maxChargingPowerKw`, instead of hard-coding thresholds only the EMS knows.
 
+**DC chargers.** A DC charger (CCS, CHAdeMO) declares the `DcCharging` feature in `availableFeatures`. The EMS
+controls it by power in watts, not by current per phase. These fields apply:
+- `minChargingPowerKw`: the DC minimum, often several kW.
+- `maxChargingPowerKw`: the maximum power.
+- `powerStepW`: the granularity of power setpoints, e.g. `500` for 0.5 kW steps. Omit it when the charger accepts
+  any watt value.
+
+The current- and phase-based fields (`minChargingCurrentAmpere`, `ampereStep`, `availablePhases`, phase switching)
+do not apply to DC chargers.
+
+```typescript
+charger: {
+    availableFeatures: [EnyoChargerApplianceAvailableFeaturesEnum.DcCharging, EnyoChargerApplianceAvailableFeaturesEnum.PowerLimitation],
+    minChargingPowerKw: 5,
+    maxChargingPowerKw: 22,
+    powerStepW: 500,
+    // status, authorizationMode, ...
+}
+```
+
 ### BatteryCommandForecast
 
 A discriminated union on `mode`:

package/dist/cjs/types/enyo-charger-appliance.cjs

@@ -75,4 +75,17 @@ var EnyoChargerApplianceAvailableFeaturesEnum;
      * started remotely; the customer has to unplug the vehicle and plug it in again.
      */
     EnyoChargerApplianceAvailableFeaturesEnum["DisconnectToRestartCharge"] = "DisconnectToRestartCharge";
+    /**
+     * If the charger is a DC charger (e.g. CCS or CHAdeMO), converting to DC
+     * itself instead of feeding AC to the vehicle's on-board charger.
+     *
+     * A DC charger is controlled by power in Watts, not by current per phase:
+     * the EMS uses {@link EnyoChargerApplianceMetadata.minChargingPowerKw},
+     * {@link EnyoChargerApplianceMetadata.maxChargingPowerKw} and
+     * {@link EnyoChargerApplianceMetadata.powerStepW}, and ignores the
+     * Ampere-based fields ({@link EnyoChargerApplianceMetadata.minChargingCurrentAmpere},
+     * {@link EnyoChargerApplianceMetadata.ampereStep}) and phase switching
+     * ({@link EnyoChargerApplianceMetadata.availablePhases}).
+     */
+    EnyoChargerApplianceAvailableFeaturesEnum["DcCharger"] = "DcCharger";
 })(EnyoChargerApplianceAvailableFeaturesEnum || (exports.EnyoChargerApplianceAvailableFeaturesEnum = EnyoChargerApplianceAvailableFeaturesEnum = {}));

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

@@ -88,7 +88,20 @@ export declare enum EnyoChargerApplianceAvailableFeaturesEnum {
      * Once the charger is in {@link EnyoChargerApplianceStatusEnum.Finishing}, no new charge can be
      * started remotely; the customer has to unplug the vehicle and plug it in again.
      */
-    DisconnectToRestartCharge = "DisconnectToRestartCharge"
+    DisconnectToRestartCharge = "DisconnectToRestartCharge",
+    /**
+     * If the charger is a DC charger (e.g. CCS or CHAdeMO), converting to DC
+     * itself instead of feeding AC to the vehicle's on-board charger.
+     *
+     * A DC charger is controlled by power in Watts, not by current per phase:
+     * the EMS uses {@link EnyoChargerApplianceMetadata.minChargingPowerKw},
+     * {@link EnyoChargerApplianceMetadata.maxChargingPowerKw} and
+     * {@link EnyoChargerApplianceMetadata.powerStepW}, and ignores the
+     * Ampere-based fields ({@link EnyoChargerApplianceMetadata.minChargingCurrentAmpere},
+     * {@link EnyoChargerApplianceMetadata.ampereStep}) and phase switching
+     * ({@link EnyoChargerApplianceMetadata.availablePhases}).
+     */
+    DcCharger = "DcCharger"
 }
 /**
  * Phase configurations a charger can operate in.
@@ -126,7 +139,9 @@ export interface EnyoChargerApplianceMetadata {
      * Lowest power the charger can hold a session at, in kilowatts.
      *
      * The floor below which a session cannot be throttled but only paused —
-     * typically 6 A on one phase (≈ 1.4 kW). Consumers mark it on the power
+     * typically 6 A on one phase (≈ 1.4 kW) on an AC charger. A DC charger
+     * ({@link EnyoChargerApplianceAvailableFeaturesEnum.DcCharger}) states its
+     * own DC minimum here, often several kW. Consumers mark it on the power
      * scale so an owner can see why a plan pauses instead of trickling, and
      * the EMS must not issue a non-zero setpoint below it.
      */
@@ -195,6 +210,18 @@ export interface EnyoChargerApplianceMetadata {
      * @default 1
      */
     ampereStep?: number;
+    /**
+     * Granularity, in Watts, at which the charging power can be set on this
+     * charger. Any non-zero power the EMS issues
+     * ({@link EnyoDataBusSetChargerAvailablePowerV2}) should be a multiple of
+     * this step, e.g. `500` for a DC charger that regulates in 0.5 kW steps.
+     *
+     * The power counterpart of {@link ampereStep}, used by chargers controlled
+     * by power rather than current — above all DC chargers
+     * ({@link EnyoChargerApplianceAvailableFeaturesEnum.DcCharging}). Omit when
+     * the charger accepts any Watt value.
+     */
+    powerStepW?: number;
     /**
      * Phase configurations the charger supports. Each value indicates
      * a phase mode the hardware can operate in:

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

@@ -132,6 +132,27 @@ export interface EnyoPackageConfigurationSetting {
     priorityOptions?: EnyoPackageConfigurationSettingPriorityOption[];
     /** Configuration for action-type settings (a button). Required when `type` is `'action'`. */
     actionOptions?: EnyoPackageConfigurationSettingActionOptions;
+    /**
+     * Marks the setting as an expert setting. The host hides expert settings
+     * from the default view and shows them only in an expert / advanced
+     * section, e.g. for installers.
+     *
+     * When omitted, the setting inherits
+     * {@link EnyoPackageConfigurationSettingGroup.expertSetting} of its group,
+     * and is a normal setting outside a group. An explicit value overrides
+     * the group's.
+     */
+    expertSetting?: boolean;
+    /**
+     * Shows the setting during onboarding, so the user can set it while
+     * setting up the app instead of looking for it in the settings later.
+     *
+     * When omitted, the setting inherits
+     * {@link EnyoPackageConfigurationSettingGroup.showInOnboarding} of its
+     * group, and is not shown in onboarding outside a group. An explicit value
+     * overrides the group's.
+     */
+    showInOnboarding?: boolean;
 }
 /**
  * Represents a change event when a setting value is modified.
@@ -175,6 +196,18 @@ export interface EnyoPackageConfigurationSettingGroup {
     caption?: EnyoPackageConfigurationTranslatedValue[];
     /** The settings belonging to this group (1 or more) */
     settings: EnyoPackageConfigurationSetting[];
+    /**
+     * Marks every setting of the group as an expert setting (see
+     * {@link EnyoPackageConfigurationSetting.expertSetting}). A setting can
+     * override it with its own value. Defaults to `false`.
+     */
+    expertSetting?: boolean;
+    /**
+     * Shows every setting of the group during onboarding (see
+     * {@link EnyoPackageConfigurationSetting.showInOnboarding}). A setting can
+     * override it with its own value. Defaults to `false`.
+     */
+    showInOnboarding?: boolean;
 }
 /**
  * Represents a setting group with resolved setting values.
@@ -187,4 +220,8 @@ export interface EnyoSettingGroupWithValues {
     caption?: EnyoPackageConfigurationTranslatedValue[];
     /** The settings belonging to this group, including IDs and current values */
     settings: EnyoSettingConfigWithValue[];
+    /** Whether the group is an expert group, see {@link EnyoPackageConfigurationSettingGroup.expertSetting}. */
+    expertSetting?: boolean;
+    /** Whether the group is shown during onboarding, see {@link EnyoPackageConfigurationSettingGroup.showInOnboarding}. */
+    showInOnboarding?: boolean;
 }

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.45.0';
+exports.SDK_VERSION = '1.46.0';
 /**
  * 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 = "1.45.0";
+export declare const SDK_VERSION = "1.46.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/types/enyo-charger-appliance.d.ts

@@ -88,7 +88,20 @@ export declare enum EnyoChargerApplianceAvailableFeaturesEnum {
      * Once the charger is in {@link EnyoChargerApplianceStatusEnum.Finishing}, no new charge can be
      * started remotely; the customer has to unplug the vehicle and plug it in again.
      */
-    DisconnectToRestartCharge = "DisconnectToRestartCharge"
+    DisconnectToRestartCharge = "DisconnectToRestartCharge",
+    /**
+     * If the charger is a DC charger (e.g. CCS or CHAdeMO), converting to DC
+     * itself instead of feeding AC to the vehicle's on-board charger.
+     *
+     * A DC charger is controlled by power in Watts, not by current per phase:
+     * the EMS uses {@link EnyoChargerApplianceMetadata.minChargingPowerKw},
+     * {@link EnyoChargerApplianceMetadata.maxChargingPowerKw} and
+     * {@link EnyoChargerApplianceMetadata.powerStepW}, and ignores the
+     * Ampere-based fields ({@link EnyoChargerApplianceMetadata.minChargingCurrentAmpere},
+     * {@link EnyoChargerApplianceMetadata.ampereStep}) and phase switching
+     * ({@link EnyoChargerApplianceMetadata.availablePhases}).
+     */
+    DcCharger = "DcCharger"
 }
 /**
  * Phase configurations a charger can operate in.
@@ -126,7 +139,9 @@ export interface EnyoChargerApplianceMetadata {
      * Lowest power the charger can hold a session at, in kilowatts.
      *
      * The floor below which a session cannot be throttled but only paused —
-     * typically 6 A on one phase (≈ 1.4 kW). Consumers mark it on the power
+     * typically 6 A on one phase (≈ 1.4 kW) on an AC charger. A DC charger
+     * ({@link EnyoChargerApplianceAvailableFeaturesEnum.DcCharger}) states its
+     * own DC minimum here, often several kW. Consumers mark it on the power
      * scale so an owner can see why a plan pauses instead of trickling, and
      * the EMS must not issue a non-zero setpoint below it.
      */
@@ -195,6 +210,18 @@ export interface EnyoChargerApplianceMetadata {
      * @default 1
      */
     ampereStep?: number;
+    /**
+     * Granularity, in Watts, at which the charging power can be set on this
+     * charger. Any non-zero power the EMS issues
+     * ({@link EnyoDataBusSetChargerAvailablePowerV2}) should be a multiple of
+     * this step, e.g. `500` for a DC charger that regulates in 0.5 kW steps.
+     *
+     * The power counterpart of {@link ampereStep}, used by chargers controlled
+     * by power rather than current — above all DC chargers
+     * ({@link EnyoChargerApplianceAvailableFeaturesEnum.DcCharging}). Omit when
+     * the charger accepts any Watt value.
+     */
+    powerStepW?: number;
     /**
      * Phase configurations the charger supports. Each value indicates
      * a phase mode the hardware can operate in:

package/dist/types/enyo-charger-appliance.js

@@ -72,4 +72,17 @@ export var EnyoChargerApplianceAvailableFeaturesEnum;
      * started remotely; the customer has to unplug the vehicle and plug it in again.
      */
     EnyoChargerApplianceAvailableFeaturesEnum["DisconnectToRestartCharge"] = "DisconnectToRestartCharge";
+    /**
+     * If the charger is a DC charger (e.g. CCS or CHAdeMO), converting to DC
+     * itself instead of feeding AC to the vehicle's on-board charger.
+     *
+     * A DC charger is controlled by power in Watts, not by current per phase:
+     * the EMS uses {@link EnyoChargerApplianceMetadata.minChargingPowerKw},
+     * {@link EnyoChargerApplianceMetadata.maxChargingPowerKw} and
+     * {@link EnyoChargerApplianceMetadata.powerStepW}, and ignores the
+     * Ampere-based fields ({@link EnyoChargerApplianceMetadata.minChargingCurrentAmpere},
+     * {@link EnyoChargerApplianceMetadata.ampereStep}) and phase switching
+     * ({@link EnyoChargerApplianceMetadata.availablePhases}).
+     */
+    EnyoChargerApplianceAvailableFeaturesEnum["DcCharger"] = "DcCharger";
 })(EnyoChargerApplianceAvailableFeaturesEnum || (EnyoChargerApplianceAvailableFeaturesEnum = {}));

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

@@ -132,6 +132,27 @@ export interface EnyoPackageConfigurationSetting {
     priorityOptions?: EnyoPackageConfigurationSettingPriorityOption[];
     /** Configuration for action-type settings (a button). Required when `type` is `'action'`. */
     actionOptions?: EnyoPackageConfigurationSettingActionOptions;
+    /**
+     * Marks the setting as an expert setting. The host hides expert settings
+     * from the default view and shows them only in an expert / advanced
+     * section, e.g. for installers.
+     *
+     * When omitted, the setting inherits
+     * {@link EnyoPackageConfigurationSettingGroup.expertSetting} of its group,
+     * and is a normal setting outside a group. An explicit value overrides
+     * the group's.
+     */
+    expertSetting?: boolean;
+    /**
+     * Shows the setting during onboarding, so the user can set it while
+     * setting up the app instead of looking for it in the settings later.
+     *
+     * When omitted, the setting inherits
+     * {@link EnyoPackageConfigurationSettingGroup.showInOnboarding} of its
+     * group, and is not shown in onboarding outside a group. An explicit value
+     * overrides the group's.
+     */
+    showInOnboarding?: boolean;
 }
 /**
  * Represents a change event when a setting value is modified.
@@ -175,6 +196,18 @@ export interface EnyoPackageConfigurationSettingGroup {
     caption?: EnyoPackageConfigurationTranslatedValue[];
     /** The settings belonging to this group (1 or more) */
     settings: EnyoPackageConfigurationSetting[];
+    /**
+     * Marks every setting of the group as an expert setting (see
+     * {@link EnyoPackageConfigurationSetting.expertSetting}). A setting can
+     * override it with its own value. Defaults to `false`.
+     */
+    expertSetting?: boolean;
+    /**
+     * Shows every setting of the group during onboarding (see
+     * {@link EnyoPackageConfigurationSetting.showInOnboarding}). A setting can
+     * override it with its own value. Defaults to `false`.
+     */
+    showInOnboarding?: boolean;
 }
 /**
  * Represents a setting group with resolved setting values.
@@ -187,4 +220,8 @@ export interface EnyoSettingGroupWithValues {
     caption?: EnyoPackageConfigurationTranslatedValue[];
     /** The settings belonging to this group, including IDs and current values */
     settings: EnyoSettingConfigWithValue[];
+    /** Whether the group is an expert group, see {@link EnyoPackageConfigurationSettingGroup.expertSetting}. */
+    expertSetting?: boolean;
+    /** Whether the group is shown during onboarding, see {@link EnyoPackageConfigurationSettingGroup.showInOnboarding}. */
+    showInOnboarding?: boolean;
 }

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.45.0";
+export declare const SDK_VERSION = "1.46.0";
 /**
  * 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 = '1.45.0';
+export const SDK_VERSION = '1.46.0';
 /**
  * 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": "1.45.0",
+  "version": "1.46.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",