@enyo-energy/sunspec-sdk 0.0.62 → 0.0.63

package/dist/cjs/sunspec-modbus-client.cjs

@@ -699,23 +699,64 @@ class SunspecModbusClient {
             throw error;
         }
     }
+    /**
+     * SunSpec inverter + meter models come in two encoding families: int+SF (101/103 inverter,
+     * 201/203/204 meter) and float (111/112/113 inverter, 211/212/213/214 meter). Some devices
+     * advertise BOTH for compatibility. We must pick one family and use it consistently across
+     * inverter and meter on the same unit — otherwise we end up decoding the int+SF inverter
+     * while reading the float meter (or vice-versa), which is confusing and risks subtle bugs.
+     *
+     * Rule: count how many models each family contributes to the discovered directory for this
+     * unit; use the family with the higher count. On a tie, prefer int+SF (the SDK's historical
+     * default and the more common encoding in the wild).
+     */
+    getPreferredEncoding(unitId) {
+        const INT_SF_IDS = [101, 103, 201, 203, 204];
+        const FLOAT_IDS = [111, 112, 113, 211, 212, 213, 214];
+        const models = this.discoveredModelsByUnit.get(unitId);
+        if (!models)
+            return 'int_sf';
+        let intSfCount = 0;
+        let floatCount = 0;
+        for (const id of INT_SF_IDS)
+            if (models.has(id))
+                intSfCount++;
+        for (const id of FLOAT_IDS)
+            if (models.has(id))
+                floatCount++;
+        const preferred = floatCount > intSfCount ? 'float' : 'int_sf';
+        if (intSfCount > 0 && floatCount > 0) {
+            console.debug(`Unit ${unitId} advertises both int+SF (${intSfCount}) and float (${floatCount}) models — ` +
+                `using ${preferred} consistently across inverter+meter.`);
+        }
+        return preferred;
+    }
     /**
      * Read inverter data. Detects which SunSpec inverter model the device exposes —
      * int+SF (101/103) or float (111/112/113) — by checking the discovered model directory,
      * and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     async readInverterData(unitId) {
-        const tryOrder = [
+        const intSfOrder = [
             { id: 103, reader: m => this.readThreePhaseInverterData_IntSF(unitId, m) },
+            { id: 101, reader: m => this.readSinglePhaseInverterData(unitId, m) },
+        ];
+        const floatOrder = [
             { id: 113, reader: m => this.readFloatInverterData(unitId, m, 113) },
             { id: 112, reader: m => this.readFloatInverterData(unitId, m, 112) },
-            { id: 101, reader: m => this.readSinglePhaseInverterData(unitId, m) },
             { id: 111, reader: m => this.readFloatInverterData(unitId, m, 111) },
         ];
+        const preferred = this.getPreferredEncoding(unitId);
+        const tryOrder = preferred === 'float'
+            ? [...floatOrder, ...intSfOrder] // fall through to int+SF only if no float model exists
+            : [...intSfOrder, ...floatOrder];
         for (const { id, reader } of tryOrder) {
             const model = this.findModel(unitId, id);
             if (model) {
-                console.debug(`Using inverter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId}`);
+                console.debug(`Using inverter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId} (preferred encoding: ${preferred})`);
                 return reader(model);
             }
         }
@@ -1753,27 +1794,46 @@ class SunspecModbusClient {
      * Read meter data. Detects which SunSpec meter model the device exposes —
      * int+SF (201/203/204) or float (211/212/213/214) — by checking the discovered
      * model directory, and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     async readMeterData(unitId) {
-        const floatIds = [213, 214, 212, 211];
-        for (const id of floatIds) {
-            const model = this.findModel(unitId, id);
-            if (model) {
-                console.debug(`Using meter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId}`);
-                return this.readFloatMeterData(unitId, model, id);
+        const preferred = this.getPreferredEncoding(unitId);
+        const tryFloat = async () => {
+            const floatIds = [213, 214, 212, 211];
+            for (const id of floatIds) {
+                const model = this.findModel(unitId, id);
+                if (model) {
+                    console.debug(`Using meter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId} (preferred encoding: ${preferred})`);
+                    return this.readFloatMeterData(unitId, model, id);
+                }
             }
-        }
-        let model = this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.Meter3Phase);
-        if (!model) {
-            model = this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.MeterWye);
-        }
-        if (!model) {
-            model = this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.MeterSinglePhase);
-        }
-        if (!model) {
-            console.debug(`No meter model found on unit ${unitId}`);
             return null;
-        }
+        };
+        const tryIntSf = async () => {
+            let model = this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.Meter3Phase)
+                ?? this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.MeterWye)
+                ?? this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.MeterSinglePhase);
+            if (!model)
+                return null;
+            console.debug(`Using meter Model ${model.id} at address ${model.address} (length ${model.length}) on unit ${unitId} (preferred encoding: ${preferred})`);
+            return this.readIntSfMeterData(unitId, model);
+        };
+        const primary = preferred === 'float' ? tryFloat : tryIntSf;
+        const fallback = preferred === 'float' ? tryIntSf : tryFloat;
+        const primaryResult = await primary();
+        if (primaryResult)
+            return primaryResult;
+        // Fall back to the other family only when the preferred family has no model at all.
+        return fallback();
+    }
+    /**
+     * Read meter data from an int+SF variant model (201/203/204). Extracted from the original
+     * readMeterData body so the preferred-encoding dispatcher above can branch cleanly without
+     * duplicating ~60 lines of register decoding.
+     */
+    async readIntSfMeterData(unitId, model) {
         console.debug(`Reading Meter Data from Model ${model.id} at base address: ${model.address} (unit ${unitId})`);
         try {
             // Different meter models have different register offsets

package/dist/cjs/sunspec-modbus-client.d.cts

@@ -201,10 +201,25 @@ export declare class SunspecModbusClient {
      * Helper to write register value(s)
      */
     writeRegisterValue(unitId: number, address: number, value: number | number[], dataType?: EnergyAppModbusDataType): Promise<boolean>;
+    /**
+     * SunSpec inverter + meter models come in two encoding families: int+SF (101/103 inverter,
+     * 201/203/204 meter) and float (111/112/113 inverter, 211/212/213/214 meter). Some devices
+     * advertise BOTH for compatibility. We must pick one family and use it consistently across
+     * inverter and meter on the same unit — otherwise we end up decoding the int+SF inverter
+     * while reading the float meter (or vice-versa), which is confusing and risks subtle bugs.
+     *
+     * Rule: count how many models each family contributes to the discovered directory for this
+     * unit; use the family with the higher count. On a tie, prefer int+SF (the SDK's historical
+     * default and the more common encoding in the wild).
+     */
+    private getPreferredEncoding;
     /**
      * Read inverter data. Detects which SunSpec inverter model the device exposes —
      * int+SF (101/103) or float (111/112/113) — by checking the discovered model directory,
      * and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     readInverterData(unitId: number): Promise<SunspecInverterData | null>;
     /**
@@ -318,8 +333,17 @@ export declare class SunspecModbusClient {
      * Read meter data. Detects which SunSpec meter model the device exposes —
      * int+SF (201/203/204) or float (211/212/213/214) — by checking the discovered
      * model directory, and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     readMeterData(unitId: number): Promise<SunspecMeterData | null>;
+    /**
+     * Read meter data from an int+SF variant model (201/203/204). Extracted from the original
+     * readMeterData body so the preferred-encoding dispatcher above can branch cleanly without
+     * duplicating ~60 lines of register decoding.
+     */
+    private readIntSfMeterData;
     /**
      * Read meter data from a float-variant model: 211 (single-phase), 212 (split-phase),
      * 213 (3-phase Wye), or 214 (3-phase Delta).

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.62';
+exports.SDK_VERSION = '0.0.63';
 /**
  * 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.62";
+export declare const SDK_VERSION = "0.0.63";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/sunspec-modbus-client.d.ts

@@ -201,10 +201,25 @@ export declare class SunspecModbusClient {
      * Helper to write register value(s)
      */
     writeRegisterValue(unitId: number, address: number, value: number | number[], dataType?: EnergyAppModbusDataType): Promise<boolean>;
+    /**
+     * SunSpec inverter + meter models come in two encoding families: int+SF (101/103 inverter,
+     * 201/203/204 meter) and float (111/112/113 inverter, 211/212/213/214 meter). Some devices
+     * advertise BOTH for compatibility. We must pick one family and use it consistently across
+     * inverter and meter on the same unit — otherwise we end up decoding the int+SF inverter
+     * while reading the float meter (or vice-versa), which is confusing and risks subtle bugs.
+     *
+     * Rule: count how many models each family contributes to the discovered directory for this
+     * unit; use the family with the higher count. On a tie, prefer int+SF (the SDK's historical
+     * default and the more common encoding in the wild).
+     */
+    private getPreferredEncoding;
     /**
      * Read inverter data. Detects which SunSpec inverter model the device exposes —
      * int+SF (101/103) or float (111/112/113) — by checking the discovered model directory,
      * and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     readInverterData(unitId: number): Promise<SunspecInverterData | null>;
     /**
@@ -318,8 +333,17 @@ export declare class SunspecModbusClient {
      * Read meter data. Detects which SunSpec meter model the device exposes —
      * int+SF (201/203/204) or float (211/212/213/214) — by checking the discovered
      * model directory, and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     readMeterData(unitId: number): Promise<SunspecMeterData | null>;
+    /**
+     * Read meter data from an int+SF variant model (201/203/204). Extracted from the original
+     * readMeterData body so the preferred-encoding dispatcher above can branch cleanly without
+     * duplicating ~60 lines of register decoding.
+     */
+    private readIntSfMeterData;
     /**
      * Read meter data from a float-variant model: 211 (single-phase), 212 (split-phase),
      * 213 (3-phase Wye), or 214 (3-phase Delta).

package/dist/sunspec-modbus-client.js

@@ -694,23 +694,64 @@ export class SunspecModbusClient {
             throw error;
         }
     }
+    /**
+     * SunSpec inverter + meter models come in two encoding families: int+SF (101/103 inverter,
+     * 201/203/204 meter) and float (111/112/113 inverter, 211/212/213/214 meter). Some devices
+     * advertise BOTH for compatibility. We must pick one family and use it consistently across
+     * inverter and meter on the same unit — otherwise we end up decoding the int+SF inverter
+     * while reading the float meter (or vice-versa), which is confusing and risks subtle bugs.
+     *
+     * Rule: count how many models each family contributes to the discovered directory for this
+     * unit; use the family with the higher count. On a tie, prefer int+SF (the SDK's historical
+     * default and the more common encoding in the wild).
+     */
+    getPreferredEncoding(unitId) {
+        const INT_SF_IDS = [101, 103, 201, 203, 204];
+        const FLOAT_IDS = [111, 112, 113, 211, 212, 213, 214];
+        const models = this.discoveredModelsByUnit.get(unitId);
+        if (!models)
+            return 'int_sf';
+        let intSfCount = 0;
+        let floatCount = 0;
+        for (const id of INT_SF_IDS)
+            if (models.has(id))
+                intSfCount++;
+        for (const id of FLOAT_IDS)
+            if (models.has(id))
+                floatCount++;
+        const preferred = floatCount > intSfCount ? 'float' : 'int_sf';
+        if (intSfCount > 0 && floatCount > 0) {
+            console.debug(`Unit ${unitId} advertises both int+SF (${intSfCount}) and float (${floatCount}) models — ` +
+                `using ${preferred} consistently across inverter+meter.`);
+        }
+        return preferred;
+    }
     /**
      * Read inverter data. Detects which SunSpec inverter model the device exposes —
      * int+SF (101/103) or float (111/112/113) — by checking the discovered model directory,
      * and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     async readInverterData(unitId) {
-        const tryOrder = [
+        const intSfOrder = [
             { id: 103, reader: m => this.readThreePhaseInverterData_IntSF(unitId, m) },
+            { id: 101, reader: m => this.readSinglePhaseInverterData(unitId, m) },
+        ];
+        const floatOrder = [
             { id: 113, reader: m => this.readFloatInverterData(unitId, m, 113) },
             { id: 112, reader: m => this.readFloatInverterData(unitId, m, 112) },
-            { id: 101, reader: m => this.readSinglePhaseInverterData(unitId, m) },
             { id: 111, reader: m => this.readFloatInverterData(unitId, m, 111) },
         ];
+        const preferred = this.getPreferredEncoding(unitId);
+        const tryOrder = preferred === 'float'
+            ? [...floatOrder, ...intSfOrder] // fall through to int+SF only if no float model exists
+            : [...intSfOrder, ...floatOrder];
         for (const { id, reader } of tryOrder) {
             const model = this.findModel(unitId, id);
             if (model) {
-                console.debug(`Using inverter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId}`);
+                console.debug(`Using inverter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId} (preferred encoding: ${preferred})`);
                 return reader(model);
             }
         }
@@ -1748,27 +1789,46 @@ export class SunspecModbusClient {
      * Read meter data. Detects which SunSpec meter model the device exposes —
      * int+SF (201/203/204) or float (211/212/213/214) — by checking the discovered
      * model directory, and dispatches to the appropriate decoder.
+     *
+     * When a device advertises BOTH encodings, picks the family with more discovered models
+     * for this unit (see getPreferredEncoding). Never reads both.
      */
     async readMeterData(unitId) {
-        const floatIds = [213, 214, 212, 211];
-        for (const id of floatIds) {
-            const model = this.findModel(unitId, id);
-            if (model) {
-                console.debug(`Using meter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId}`);
-                return this.readFloatMeterData(unitId, model, id);
+        const preferred = this.getPreferredEncoding(unitId);
+        const tryFloat = async () => {
+            const floatIds = [213, 214, 212, 211];
+            for (const id of floatIds) {
+                const model = this.findModel(unitId, id);
+                if (model) {
+                    console.debug(`Using meter Model ${id} at address ${model.address} (length ${model.length}) on unit ${unitId} (preferred encoding: ${preferred})`);
+                    return this.readFloatMeterData(unitId, model, id);
+                }
             }
-        }
-        let model = this.findModel(unitId, SunspecModelId.Meter3Phase);
-        if (!model) {
-            model = this.findModel(unitId, SunspecModelId.MeterWye);
-        }
-        if (!model) {
-            model = this.findModel(unitId, SunspecModelId.MeterSinglePhase);
-        }
-        if (!model) {
-            console.debug(`No meter model found on unit ${unitId}`);
             return null;
-        }
+        };
+        const tryIntSf = async () => {
+            let model = this.findModel(unitId, SunspecModelId.Meter3Phase)
+                ?? this.findModel(unitId, SunspecModelId.MeterWye)
+                ?? this.findModel(unitId, SunspecModelId.MeterSinglePhase);
+            if (!model)
+                return null;
+            console.debug(`Using meter Model ${model.id} at address ${model.address} (length ${model.length}) on unit ${unitId} (preferred encoding: ${preferred})`);
+            return this.readIntSfMeterData(unitId, model);
+        };
+        const primary = preferred === 'float' ? tryFloat : tryIntSf;
+        const fallback = preferred === 'float' ? tryIntSf : tryFloat;
+        const primaryResult = await primary();
+        if (primaryResult)
+            return primaryResult;
+        // Fall back to the other family only when the preferred family has no model at all.
+        return fallback();
+    }
+    /**
+     * Read meter data from an int+SF variant model (201/203/204). Extracted from the original
+     * readMeterData body so the preferred-encoding dispatcher above can branch cleanly without
+     * duplicating ~60 lines of register decoding.
+     */
+    async readIntSfMeterData(unitId, model) {
         console.debug(`Reading Meter Data from Model ${model.id} at base address: ${model.address} (unit ${unitId})`);
         try {
             // Different meter models have different register offsets

package/dist/version.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/sunspec-sdk",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",