@enyo-energy/energy-app-sdk 1.21.0 → 1.22.0

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCategory = void 0;
+exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageCategory = void 0;
 exports.defineEnergyAppPackage = defineEnergyAppPackage;
 const version_js_1 = require("./version.cjs");
 var EnergyAppPackageCategory;
@@ -27,6 +27,24 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["Vehicle"] = "vehicle";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
+/**
+ * Whether a declared compatibility entry means "this works" or "this is known
+ * not to work".
+ *
+ * Used by {@link EnergyAppPackageCompatibilityVendor.status} and
+ * {@link EnergyAppPackageCompatibilityModel.status} so a package can
+ * list a vendor or model it has explicitly tested and found unsupported,
+ * instead of silently leaving it out. The enyo Store and onboarding flows can
+ * then tell the user "this device is not supported by this app" rather than
+ * showing nothing at all.
+ */
+var EnergyAppPackageCompatibilityStatus;
+(function (EnergyAppPackageCompatibilityStatus) {
+    /** The package supports this vendor or model. */
+    EnergyAppPackageCompatibilityStatus["Compatible"] = "compatible";
+    /** The package has been verified **not** to work with this vendor or model. */
+    EnergyAppPackageCompatibilityStatus["NotCompatible"] = "not-compatible";
+})(EnergyAppPackageCompatibilityStatus || (exports.EnergyAppPackageCompatibilityStatus = EnergyAppPackageCompatibilityStatus = {}));
 /**
  * Enum form of {@link EnergyAppPackageFirmwareMode} for use in package
  * definitions.

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

@@ -213,6 +213,23 @@ export interface EnergyAppPackagePermission {
     /** Internal documentation describing what this permission is used for */
     internalComment: string;
 }
+/**
+ * Whether a declared compatibility entry means "this works" or "this is known
+ * not to work".
+ *
+ * Used by {@link EnergyAppPackageCompatibilityVendor.status} and
+ * {@link EnergyAppPackageCompatibilityModel.status} so a package can
+ * list a vendor or model it has explicitly tested and found unsupported,
+ * instead of silently leaving it out. The enyo Store and onboarding flows can
+ * then tell the user "this device is not supported by this app" rather than
+ * showing nothing at all.
+ */
+export declare enum EnergyAppPackageCompatibilityStatus {
+    /** The package supports this vendor or model. */
+    Compatible = "compatible",
+    /** The package has been verified **not** to work with this vendor or model. */
+    NotCompatible = "not-compatible"
+}
 /**
  * A specific device model supported by an Energy App package.
  * the concrete models the package has been verified to work with.
@@ -249,6 +266,16 @@ export interface EnergyAppPackageCompatibilityModel {
     category?: EnergyAppPackageCategory;
     /** Optional internal note explaining model-specific caveats or limitations */
     internalComment?: string;
+    /**
+     * Whether this model is supported or explicitly unsupported.
+     *
+     * Defaults to {@link EnergyAppPackageCompatibilityStatus.Compatible} when
+     * omitted, so existing definitions keep their meaning. Set it to
+     * {@link EnergyAppPackageCompatibilityStatus.NotCompatible} to document a
+     * model you have tested and found not to work — use
+     * {@link internalComment} to say why.
+     */
+    status?: EnergyAppPackageCompatibilityStatus;
     /**
      * Important capabilities this specific model supports (e.g. charging the
      * battery from grid, limiting the charge, or forcing a heat pump DHW boost).
@@ -277,6 +304,16 @@ export interface EnergyAppPackageCompatibilityVendor {
      * worse than listing none.
      */
     models: EnergyAppPackageCompatibilityModel[];
+    /**
+     * Whether this vendor is supported or explicitly unsupported.
+     *
+     * Defaults to {@link EnergyAppPackageCompatibilityStatus.Compatible} when
+     * omitted. Set it to
+     * {@link EnergyAppPackageCompatibilityStatus.NotCompatible} to declare a
+     * brand the package is known not to work with; individual models may still
+     * override it with their own {@link EnergyAppPackageCompatibilityModel.status}.
+     */
+    status?: EnergyAppPackageCompatibilityStatus;
     /**
      * Marks this package as the default Energy App for the vendor when no
      * concrete model has been selected.

package/dist/cjs/implementations/firmware/firmware-validators.cjs

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FirmwareRegistryValidationError = void 0;
 exports.validateFirmwareRegistry = validateFirmwareRegistry;
 exports.assertValidFirmwareRegistry = assertValidFirmwareRegistry;
+const energy_app_package_definition_js_1 = require("../../energy-app-package-definition.cjs");
 const energy_app_permission_type_js_1 = require("../../energy-app-permission.type.cjs");
 const define_firmware_file_js_1 = require("./define-firmware-file.cjs");
 /**
@@ -269,11 +270,12 @@ function findDanglingSources(files) {
 }
 /**
  * Reports vendors and models referenced by firmware entries that the package
- * does not declare in its `compatibility` list.
+ * does not declare in its `compatibility` list, or that it declares as
+ * {@link EnergyAppPackageCompatibilityStatus.NotCompatible}.
  *
  * @param files - All declared firmware entries.
  * @param compatibility - The package's declared vendors and models.
- * @returns One warning per unknown vendor or model.
+ * @returns One warning per unknown or explicitly incompatible vendor or model.
  */
 function findUnknownCompatibility(files, compatibility) {
     const warnings = [];
@@ -281,15 +283,27 @@ function findUnknownCompatibility(files, compatibility) {
         return warnings;
     const vendors = new Set(compatibility.map(vendor => vendor.vendorName));
     const models = new Set(compatibility.flatMap(vendor => vendor.models.map(model => model.modelName)));
+    const incompatibleVendors = new Set(compatibility
+        .filter(vendor => vendor.status === energy_app_package_definition_js_1.EnergyAppPackageCompatibilityStatus.NotCompatible)
+        .map(vendor => vendor.vendorName));
+    const incompatibleModels = new Set(compatibility.flatMap(vendor => vendor.models
+        .filter(model => model.status === energy_app_package_definition_js_1.EnergyAppPackageCompatibilityStatus.NotCompatible)
+        .map(model => model.modelName)));
     for (const [index, file] of files.entries()) {
         const at = describe(file, index);
         if (file.vendorName && !vendors.has(file.vendorName)) {
             warnings.push(`${at}: vendorName "${file.vendorName}" is not listed in compatibility.`);
         }
+        else if (file.vendorName && incompatibleVendors.has(file.vendorName)) {
+            warnings.push(`${at}: vendorName "${file.vendorName}" is declared as not-compatible.`);
+        }
         for (const model of file.modelNames ?? []) {
             if (!models.has(model)) {
                 warnings.push(`${at}: modelName "${model}" is not listed in compatibility.`);
             }
+            else if (incompatibleModels.has(model)) {
+                warnings.push(`${at}: modelName "${model}" is declared as not-compatible.`);
+            }
         }
     }
     return warnings;

package/dist/cjs/packages/energy-app-modbus-rtu.d.cts

@@ -28,6 +28,21 @@ export interface ModbusRtuOptions {
      */
     waitBetweenMessagesMs?: number;
 }
+/**
+ * Which register bank an RTU read addresses, and therefore which Modbus
+ * function code goes on the wire.
+ *
+ * Holding and input registers are two separate address spaces: a device may
+ * answer register 30001 as an input register and hold something entirely
+ * different — or nothing at all — at the same address in the holding bank.
+ * Reading the wrong bank yields an illegal-data-address exception, not a
+ * timeout, so this is a correctness knob rather than a recovery one.
+ */
+export type ModbusRtuRegisterType = 
+/** Holding registers, read with function code 3 (`mbpoll -t 4`). */
+'holding'
+/** Input registers, read with function code 4 (`mbpoll -t 3`). */
+ | 'input';
 /**
  * Request parameters for reading Modbus RTU registers.
  */
@@ -38,6 +53,14 @@ export interface ModbusRtuReadRegistersRequest {
     startRegister: number;
     /** Number of consecutive registers to read */
     count: number;
+    /**
+     * Which register bank to read from.
+     *
+     * `'holding'` issues function code 3 and `'input'` issues function code 4.
+     * Defaults to `'holding'` when omitted, which is what every existing caller
+     * gets today.
+     */
+    registerType?: ModbusRtuRegisterType;
 }
 /**
  * Response containing register values read from a Modbus RTU device.
@@ -63,9 +86,15 @@ export interface ModbusRtuWriteRegistersRequest {
  * Provides methods for reading and writing registers over a serial connection.
  */
 export interface EnergyAppModbusRtuInstance {
-    /** Read register values from the connected Modbus RTU device */
+    /**
+     * Read register values from the connected Modbus RTU device.
+     *
+     * Reads holding registers (function code 3) unless the request sets
+     * {@link ModbusRtuReadRegistersRequest.registerType} to `'input'`, which
+     * reads input registers with function code 4 instead.
+     */
     readRegisters: (request: ModbusRtuReadRegistersRequest) => Promise<ModbusRtuReadRegistersResponse>;
-    /** Write register values to the connected Modbus RTU device */
+    /** Write register values to the connected Modbus RTU device (holding registers only) */
     writeRegisters: (request: ModbusRtuWriteRegistersRequest) => Promise<void>;
 }
 /**

package/dist/cjs/version.cjs

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

package/dist/energy-app-package-definition.d.ts

@@ -213,6 +213,23 @@ export interface EnergyAppPackagePermission {
     /** Internal documentation describing what this permission is used for */
     internalComment: string;
 }
+/**
+ * Whether a declared compatibility entry means "this works" or "this is known
+ * not to work".
+ *
+ * Used by {@link EnergyAppPackageCompatibilityVendor.status} and
+ * {@link EnergyAppPackageCompatibilityModel.status} so a package can
+ * list a vendor or model it has explicitly tested and found unsupported,
+ * instead of silently leaving it out. The enyo Store and onboarding flows can
+ * then tell the user "this device is not supported by this app" rather than
+ * showing nothing at all.
+ */
+export declare enum EnergyAppPackageCompatibilityStatus {
+    /** The package supports this vendor or model. */
+    Compatible = "compatible",
+    /** The package has been verified **not** to work with this vendor or model. */
+    NotCompatible = "not-compatible"
+}
 /**
  * A specific device model supported by an Energy App package.
  * the concrete models the package has been verified to work with.
@@ -249,6 +266,16 @@ export interface EnergyAppPackageCompatibilityModel {
     category?: EnergyAppPackageCategory;
     /** Optional internal note explaining model-specific caveats or limitations */
     internalComment?: string;
+    /**
+     * Whether this model is supported or explicitly unsupported.
+     *
+     * Defaults to {@link EnergyAppPackageCompatibilityStatus.Compatible} when
+     * omitted, so existing definitions keep their meaning. Set it to
+     * {@link EnergyAppPackageCompatibilityStatus.NotCompatible} to document a
+     * model you have tested and found not to work — use
+     * {@link internalComment} to say why.
+     */
+    status?: EnergyAppPackageCompatibilityStatus;
     /**
      * Important capabilities this specific model supports (e.g. charging the
      * battery from grid, limiting the charge, or forcing a heat pump DHW boost).
@@ -277,6 +304,16 @@ export interface EnergyAppPackageCompatibilityVendor {
      * worse than listing none.
      */
     models: EnergyAppPackageCompatibilityModel[];
+    /**
+     * Whether this vendor is supported or explicitly unsupported.
+     *
+     * Defaults to {@link EnergyAppPackageCompatibilityStatus.Compatible} when
+     * omitted. Set it to
+     * {@link EnergyAppPackageCompatibilityStatus.NotCompatible} to declare a
+     * brand the package is known not to work with; individual models may still
+     * override it with their own {@link EnergyAppPackageCompatibilityModel.status}.
+     */
+    status?: EnergyAppPackageCompatibilityStatus;
     /**
      * Marks this package as the default Energy App for the vendor when no
      * concrete model has been selected.

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

@@ -23,6 +23,24 @@ export var EnergyAppPackageCategory;
     EnergyAppPackageCategory["Vehicle"] = "vehicle";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (EnergyAppPackageCategory = {}));
+/**
+ * Whether a declared compatibility entry means "this works" or "this is known
+ * not to work".
+ *
+ * Used by {@link EnergyAppPackageCompatibilityVendor.status} and
+ * {@link EnergyAppPackageCompatibilityModel.status} so a package can
+ * list a vendor or model it has explicitly tested and found unsupported,
+ * instead of silently leaving it out. The enyo Store and onboarding flows can
+ * then tell the user "this device is not supported by this app" rather than
+ * showing nothing at all.
+ */
+export var EnergyAppPackageCompatibilityStatus;
+(function (EnergyAppPackageCompatibilityStatus) {
+    /** The package supports this vendor or model. */
+    EnergyAppPackageCompatibilityStatus["Compatible"] = "compatible";
+    /** The package has been verified **not** to work with this vendor or model. */
+    EnergyAppPackageCompatibilityStatus["NotCompatible"] = "not-compatible";
+})(EnergyAppPackageCompatibilityStatus || (EnergyAppPackageCompatibilityStatus = {}));
 /**
  * Enum form of {@link EnergyAppPackageFirmwareMode} for use in package
  * definitions.

package/dist/implementations/firmware/firmware-validators.js

@@ -19,6 +19,7 @@
  * Use {@link validateFirmwareRegistry} for the non-throwing result, or
  * {@link assertValidFirmwareRegistry} to throw on failure.
  */
+import { EnergyAppPackageCompatibilityStatus } from '../../energy-app-package-definition.js';
 import { EnergyAppPermissionTypeEnum } from '../../energy-app-permission.type.js';
 import { resolveNextFirmware } from './define-firmware-file.js';
 /**
@@ -263,11 +264,12 @@ function findDanglingSources(files) {
 }
 /**
  * Reports vendors and models referenced by firmware entries that the package
- * does not declare in its `compatibility` list.
+ * does not declare in its `compatibility` list, or that it declares as
+ * {@link EnergyAppPackageCompatibilityStatus.NotCompatible}.
  *
  * @param files - All declared firmware entries.
  * @param compatibility - The package's declared vendors and models.
- * @returns One warning per unknown vendor or model.
+ * @returns One warning per unknown or explicitly incompatible vendor or model.
  */
 function findUnknownCompatibility(files, compatibility) {
     const warnings = [];
@@ -275,15 +277,27 @@ function findUnknownCompatibility(files, compatibility) {
         return warnings;
     const vendors = new Set(compatibility.map(vendor => vendor.vendorName));
     const models = new Set(compatibility.flatMap(vendor => vendor.models.map(model => model.modelName)));
+    const incompatibleVendors = new Set(compatibility
+        .filter(vendor => vendor.status === EnergyAppPackageCompatibilityStatus.NotCompatible)
+        .map(vendor => vendor.vendorName));
+    const incompatibleModels = new Set(compatibility.flatMap(vendor => vendor.models
+        .filter(model => model.status === EnergyAppPackageCompatibilityStatus.NotCompatible)
+        .map(model => model.modelName)));
     for (const [index, file] of files.entries()) {
         const at = describe(file, index);
         if (file.vendorName && !vendors.has(file.vendorName)) {
             warnings.push(`${at}: vendorName "${file.vendorName}" is not listed in compatibility.`);
         }
+        else if (file.vendorName && incompatibleVendors.has(file.vendorName)) {
+            warnings.push(`${at}: vendorName "${file.vendorName}" is declared as not-compatible.`);
+        }
         for (const model of file.modelNames ?? []) {
             if (!models.has(model)) {
                 warnings.push(`${at}: modelName "${model}" is not listed in compatibility.`);
             }
+            else if (incompatibleModels.has(model)) {
+                warnings.push(`${at}: modelName "${model}" is declared as not-compatible.`);
+            }
         }
     }
     return warnings;

package/dist/packages/energy-app-modbus-rtu.d.ts

@@ -28,6 +28,21 @@ export interface ModbusRtuOptions {
      */
     waitBetweenMessagesMs?: number;
 }
+/**
+ * Which register bank an RTU read addresses, and therefore which Modbus
+ * function code goes on the wire.
+ *
+ * Holding and input registers are two separate address spaces: a device may
+ * answer register 30001 as an input register and hold something entirely
+ * different — or nothing at all — at the same address in the holding bank.
+ * Reading the wrong bank yields an illegal-data-address exception, not a
+ * timeout, so this is a correctness knob rather than a recovery one.
+ */
+export type ModbusRtuRegisterType = 
+/** Holding registers, read with function code 3 (`mbpoll -t 4`). */
+'holding'
+/** Input registers, read with function code 4 (`mbpoll -t 3`). */
+ | 'input';
 /**
  * Request parameters for reading Modbus RTU registers.
  */
@@ -38,6 +53,14 @@ export interface ModbusRtuReadRegistersRequest {
     startRegister: number;
     /** Number of consecutive registers to read */
     count: number;
+    /**
+     * Which register bank to read from.
+     *
+     * `'holding'` issues function code 3 and `'input'` issues function code 4.
+     * Defaults to `'holding'` when omitted, which is what every existing caller
+     * gets today.
+     */
+    registerType?: ModbusRtuRegisterType;
 }
 /**
  * Response containing register values read from a Modbus RTU device.
@@ -63,9 +86,15 @@ export interface ModbusRtuWriteRegistersRequest {
  * Provides methods for reading and writing registers over a serial connection.
  */
 export interface EnergyAppModbusRtuInstance {
-    /** Read register values from the connected Modbus RTU device */
+    /**
+     * Read register values from the connected Modbus RTU device.
+     *
+     * Reads holding registers (function code 3) unless the request sets
+     * {@link ModbusRtuReadRegistersRequest.registerType} to `'input'`, which
+     * reads input registers with function code 4 instead.
+     */
     readRegisters: (request: ModbusRtuReadRegistersRequest) => Promise<ModbusRtuReadRegistersResponse>;
-    /** Write register values to the connected Modbus RTU device */
+    /** Write register values to the connected Modbus RTU device (holding registers only) */
     writeRegisters: (request: ModbusRtuWriteRegistersRequest) => Promise<void>;
 }
 /**

package/dist/version.d.ts

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