@enyo-energy/sunspec-sdk 0.0.1

package/README.md

@@ -0,0 +1 @@
+# enyo Sunspec SDK

package/dist/cjs/sunspec-devices.cjs

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SunspecMeter = exports.SunspecBattery = exports.SunspecInverter = exports.BaseSunspecDevice = void 0;
+const sunspec_interfaces_js_1 = require("./sunspec-interfaces.cjs");
+const node_crypto_1 = require("node:crypto");
+const enyo_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js");
+const enyo_data_bus_value_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js");
+const enyo_source_enum_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-source.enum.js");
+/**
+ * Base abstract class for all Sunspec devices
+ */
+class BaseSunspecDevice {
+    energyApp;
+    name;
+    networkDevice;
+    sunspecClient;
+    applianceManager;
+    unitId;
+    applianceId;
+    lastUpdateTime = 0;
+    constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1) {
+        this.energyApp = energyApp;
+        this.name = name;
+        this.networkDevice = networkDevice;
+        this.sunspecClient = sunspecClient;
+        this.applianceManager = applianceManager;
+        this.unitId = unitId;
+    }
+    /**
+     * Check if the device is connected
+     */
+    isConnected() {
+        return this.sunspecClient.isConnected();
+    }
+    /**
+     * Get the appliance IDs managed by this device
+     */
+    /**
+     * Ensure the Sunspec client is connected and models are discovered
+     */
+    async ensureConnected() {
+        if (!this.sunspecClient.isConnected()) {
+            await this.sunspecClient.connect(this.networkDevice.ipAddress, 502, this.unitId);
+            await this.sunspecClient.discoverModels();
+        }
+    }
+}
+exports.BaseSunspecDevice = BaseSunspecDevice;
+/**
+ * Sunspec Inverter implementation using dynamic model discovery
+ */
+class SunspecInverter extends BaseSunspecDevice {
+    async connect() {
+        // Ensure Sunspec client is connected
+        if (!this.sunspecClient.isConnected()) {
+            await this.sunspecClient.connect(this.networkDevice.ipAddress, 502, this.unitId);
+            await this.sunspecClient.discoverModels();
+        }
+        // Get device info from common block
+        const commonData = await this.sunspecClient.readCommonBlock();
+        // Create or update appliance
+        try {
+            this.applianceId = await this.applianceManager.createOrUpdateAppliance({
+                name: this.name,
+                type: enyo_appliance_js_1.EnyoApplianceTypeEnum.Inverter,
+                networkDevices: [this.networkDevice],
+                metadata: {
+                    connectionType: enyo_appliance_js_1.EnyoApplianceConnectionType.Connector,
+                    state: enyo_appliance_js_1.EnyoApplianceStateEnum.Connected,
+                    serialNumber: commonData?.serialNumber,
+                    modelName: commonData?.model,
+                    vendorName: commonData?.manufacturer,
+                }
+            });
+            console.log(`Sunspec Inverter connected: ${this.networkDevice.hostname} (${this.applianceId})`);
+        }
+        catch (error) {
+            console.error(`Failed to create inverter appliance: ${error}`);
+        }
+        // Check for MPPT models
+        const mpptModel = this.sunspecClient.findModel(sunspec_interfaces_js_1.SunspecModelId.MPPT);
+        if (mpptModel) {
+            console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
+        }
+    }
+    async disconnect() {
+        if (this.applianceId) {
+            await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
+        }
+        // Note: We don't disconnect the sunspecClient as it may be shared
+    }
+    isConnected() {
+        return this.sunspecClient.isConnected();
+    }
+    async readData(clockId, resolution) {
+        if (!this.isConnected()) {
+            return [];
+        }
+        const messages = [];
+        const timestamp = new Date();
+        try {
+            // Read inverter data
+            const inverterData = await this.sunspecClient.readInverterData();
+            const mpptDataList = await this.sunspecClient.readAllMPPTData();
+            if (inverterData) {
+                const inverterMessage = {
+                    id: (0, node_crypto_1.randomUUID)(),
+                    message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.InverterValuesUpdateV1,
+                    type: 'message',
+                    source: enyo_source_enum_js_1.EnyoSourceEnum.Device,
+                    applianceId: this.applianceId,
+                    clockId,
+                    timestampIso: timestamp.toISOString(),
+                    resolution,
+                    data: {
+                        pvPowerW: inverterData.acPower || 0,
+                        activePowerLimitationW: inverterData.acPower || 0, // Using AC power as default
+                        state: this.mapOperatingState(inverterData.operatingState),
+                        voltageL1: inverterData.voltageAN || 0,
+                        voltageL2: inverterData.voltageBN,
+                        voltageL3: inverterData.voltageCN,
+                        strings: this.mapMPPTToStrings(mpptDataList)
+                    }
+                };
+                messages.push(inverterMessage);
+            }
+            this.lastUpdateTime = timestamp.getTime();
+        }
+        catch (error) {
+            console.error(`Error updating inverter data: ${error}`);
+        }
+        return messages;
+    }
+    mapOperatingState(state) {
+        if (!state)
+            return enyo_data_bus_value_js_1.EnyoInverterStateEnum.Off;
+        const stateMap = {
+            1: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Off,
+            2: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Sleeping,
+            3: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Starting,
+            4: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Mppt,
+            5: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Throttled,
+            6: enyo_data_bus_value_js_1.EnyoInverterStateEnum.ShuttingDown,
+            7: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Fault,
+            8: enyo_data_bus_value_js_1.EnyoInverterStateEnum.Standby
+        };
+        return stateMap[state] || enyo_data_bus_value_js_1.EnyoInverterStateEnum.Off;
+    }
+    /**
+     * Map MPPT data to DC string structure for data bus
+     */
+    mapMPPTToStrings(mpptDataList) {
+        const result = [];
+        mpptDataList.forEach((mppt, index) => {
+            result.push({
+                index: index + 1,
+                voltage: mppt.dcVoltage,
+                powerW: mppt.dcPower
+            });
+        });
+        return result;
+    }
+}
+exports.SunspecInverter = SunspecInverter;
+/**
+ * Sunspec Battery implementation
+ */
+class SunspecBattery extends BaseSunspecDevice {
+    /**
+     * Connect to the battery and create/update the appliance
+     */
+    async connect() {
+        // Ensure Sunspec client is connected
+        await this.ensureConnected();
+        // Check if battery models exist
+        const hasBattery = this.sunspecClient.findModel(sunspec_interfaces_js_1.SunspecModelId.Battery) !== undefined ||
+            this.sunspecClient.findModel(sunspec_interfaces_js_1.SunspecModelId.BatteryBase) !== undefined;
+        if (!hasBattery) {
+            throw new Error('No battery model found in device');
+        }
+        // Get device info
+        const commonData = await this.sunspecClient.readCommonBlock();
+        // Create or update appliance
+        try {
+            this.applianceId = await this.applianceManager.createOrUpdateAppliance({
+                name: this.name,
+                type: enyo_appliance_js_1.EnyoApplianceTypeEnum.Storage,
+                networkDevices: [this.networkDevice],
+                metadata: {
+                    connectionType: enyo_appliance_js_1.EnyoApplianceConnectionType.Connector,
+                    state: enyo_appliance_js_1.EnyoApplianceStateEnum.Connected,
+                    serialNumber: commonData?.serialNumber ? `${commonData.serialNumber}-BAT` : undefined,
+                    modelName: commonData?.model ? `${commonData.model} Battery` : 'Battery',
+                    vendorName: commonData?.manufacturer,
+                }
+            });
+            console.log(`Sunspec Battery connected: ${this.networkDevice.hostname} (${this.applianceId})`);
+        }
+        catch (error) {
+            console.error(`Failed to create battery appliance: ${error}`);
+        }
+    }
+    async disconnect() {
+        if (this.applianceId) {
+            await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
+        }
+    }
+    /**
+     * Update battery data and return data bus messages
+     */
+    async readData(clockId, resolution) {
+        if (!this.isConnected()) {
+            return [];
+        }
+        const messages = [];
+        const timestamp = new Date();
+        try {
+            // For now, return basic battery data
+            // In a real implementation, we would read from battery models
+            const batteryMessage = {
+                id: (0, node_crypto_1.randomUUID)(),
+                message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.BatteryValuesUpdateV1,
+                type: 'message',
+                source: enyo_source_enum_js_1.EnyoSourceEnum.Device,
+                applianceId: this.applianceId,
+                clockId,
+                timestampIso: timestamp.toISOString(),
+                resolution,
+                data: {
+                    batterySoC: 50, // Placeholder - would read from battery model
+                    batteryPowerW: 0,
+                    state: enyo_data_bus_value_js_1.EnyoBatteryStateEnum.Holding
+                }
+            };
+            messages.push(batteryMessage);
+            this.lastUpdateTime = timestamp.getTime();
+        }
+        catch (error) {
+            console.error(`Error updating battery data: ${error}`);
+        }
+        return messages;
+    }
+}
+exports.SunspecBattery = SunspecBattery;
+/**
+ * Sunspec Meter implementation
+ */
+class SunspecMeter extends BaseSunspecDevice {
+    /**
+     * Connect to the meter and create/update the appliance
+     */
+    async connect() {
+        // Connect with specific unit ID for meter
+        await this.ensureConnected();
+        // Check if meter models exist
+        const hasMeter = this.sunspecClient.findModel(sunspec_interfaces_js_1.SunspecModelId.Meter3Phase) !== undefined ||
+            this.sunspecClient.findModel(sunspec_interfaces_js_1.SunspecModelId.MeterWye) !== undefined ||
+            this.sunspecClient.findModel(sunspec_interfaces_js_1.SunspecModelId.MeterSinglePhase) !== undefined;
+        if (!hasMeter) {
+            throw new Error('No meter model found in device');
+        }
+        // Get device info
+        const commonData = await this.sunspecClient.readCommonBlock();
+        // Create or update appliance
+        try {
+            this.applianceId = await this.applianceManager.createOrUpdateAppliance({
+                name: this.name,
+                type: enyo_appliance_js_1.EnyoApplianceTypeEnum.Meter,
+                networkDevices: [this.networkDevice],
+                metadata: {
+                    connectionType: enyo_appliance_js_1.EnyoApplianceConnectionType.Connector,
+                    state: enyo_appliance_js_1.EnyoApplianceStateEnum.Connected,
+                    serialNumber: commonData?.serialNumber ? `${commonData.serialNumber}-MTR` : undefined,
+                    modelName: commonData?.model ? `${commonData.model} Meter` : 'Meter',
+                    vendorName: commonData?.manufacturer,
+                }
+            });
+            console.log(`Sunspec Meter connected: ${this.networkDevice.hostname} unit ${this.unitId} (${this.applianceId})`);
+        }
+        catch (error) {
+            console.error(`Failed to create meter appliance: ${error}`);
+        }
+    }
+    /**
+     * Disconnect from the meter and update appliance state
+     */
+    async disconnect() {
+        if (this.applianceId) {
+            await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
+        }
+        // Disconnect the client since meter uses its own connection
+        await this.sunspecClient.disconnect();
+    }
+    /**
+     * Update meter data and return data bus messages
+     */
+    async readData(clockId, resolution) {
+        if (!this.isConnected()) {
+            return [];
+        }
+        const messages = [];
+        const timestamp = new Date();
+        try {
+            // Read meter data
+            const meterData = await this.sunspecClient.readMeterData();
+            if (meterData) {
+                const meterMessage = {
+                    id: (0, node_crypto_1.randomUUID)(),
+                    message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.MeterValuesUpdateV1,
+                    type: 'message',
+                    source: enyo_source_enum_js_1.EnyoSourceEnum.Device,
+                    applianceId: this.applianceId,
+                    clockId,
+                    timestampIso: timestamp.toISOString(),
+                    resolution,
+                    data: {
+                        gridPowerW: meterData.totalPower || 0,
+                        gridFeedInWh: Number(meterData.exportedEnergy || 0),
+                        gridConsumptionWh: Number(meterData.importedEnergy || 0),
+                        selfConsumptionW: undefined,
+                        selfConsumptionWh: undefined
+                    }
+                };
+                messages.push(meterMessage);
+            }
+            this.lastUpdateTime = timestamp.getTime();
+        }
+        catch (error) {
+            console.error(`Error updating meter data: ${error}`);
+        }
+        return messages;
+    }
+}
+exports.SunspecMeter = SunspecMeter;

package/dist/cjs/sunspec-devices.d.cts

@@ -0,0 +1,87 @@
+import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
+import { EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
+import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-network-device.js";
+import { SunspecModbusClient } from "./sunspec-modbus-client.cjs";
+import { EnyoDataBusMessage } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+/**
+ * Base abstract class for all Sunspec devices
+ */
+export declare abstract class BaseSunspecDevice {
+    protected readonly energyApp: EnergyApp;
+    readonly name: EnyoApplianceName[];
+    readonly networkDevice: EnyoNetworkDevice;
+    protected readonly sunspecClient: SunspecModbusClient;
+    protected readonly applianceManager: ApplianceManager;
+    protected readonly unitId: number;
+    protected applianceId?: string;
+    protected lastUpdateTime: number;
+    protected constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number);
+    /**
+     * Connect to the device and create/update the appliance
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Disconnect from the device and update appliance state
+     */
+    abstract disconnect(): Promise<void>;
+    /**
+     * Update device data and return data bus messages
+     */
+    abstract readData(clockId: string, resolution: '10s' | '30s' | '1m' | '15m'): Promise<EnyoDataBusMessage[]>;
+    /**
+     * Check if the device is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get the appliance IDs managed by this device
+     */
+    /**
+     * Ensure the Sunspec client is connected and models are discovered
+     */
+    protected ensureConnected(): Promise<void>;
+}
+/**
+ * Sunspec Inverter implementation using dynamic model discovery
+ */
+export declare class SunspecInverter extends BaseSunspecDevice {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    readData(clockId: string, resolution: '10s' | '30s' | '1m' | '15m'): Promise<EnyoDataBusMessage[]>;
+    private mapOperatingState;
+    /**
+     * Map MPPT data to DC string structure for data bus
+     */
+    private mapMPPTToStrings;
+}
+/**
+ * Sunspec Battery implementation
+ */
+export declare class SunspecBattery extends BaseSunspecDevice {
+    /**
+     * Connect to the battery and create/update the appliance
+     */
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Update battery data and return data bus messages
+     */
+    readData(clockId: string, resolution: '10s' | '30s' | '1m' | '15m'): Promise<EnyoDataBusMessage[]>;
+}
+/**
+ * Sunspec Meter implementation
+ */
+export declare class SunspecMeter extends BaseSunspecDevice {
+    /**
+     * Connect to the meter and create/update the appliance
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the meter and update appliance state
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Update meter data and return data bus messages
+     */
+    readData(clockId: string, resolution: '10s' | '30s' | '1m' | '15m'): Promise<EnyoDataBusMessage[]>;
+}

package/dist/cjs/sunspec-interfaces.cjs

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * SunSpec block interfaces with block numbers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecModelId = void 0;
+/**
+ * Common Sunspec Model IDs
+ */
+var SunspecModelId;
+(function (SunspecModelId) {
+    SunspecModelId[SunspecModelId["Common"] = 1] = "Common";
+    SunspecModelId[SunspecModelId["Inverter3Phase"] = 103] = "Inverter3Phase";
+    SunspecModelId[SunspecModelId["InverterSinglePhase"] = 101] = "InverterSinglePhase";
+    SunspecModelId[SunspecModelId["MPPT"] = 160] = "MPPT";
+    SunspecModelId[SunspecModelId["Battery"] = 124] = "Battery";
+    SunspecModelId[SunspecModelId["BatteryBase"] = 802] = "BatteryBase";
+    SunspecModelId[SunspecModelId["BatteryControl"] = 803] = "BatteryControl";
+    SunspecModelId[SunspecModelId["MeterSinglePhase"] = 201] = "MeterSinglePhase";
+    SunspecModelId[SunspecModelId["Meter3Phase"] = 203] = "Meter3Phase";
+    SunspecModelId[SunspecModelId["MeterWye"] = 204] = "MeterWye";
+    SunspecModelId[SunspecModelId["Nameplate"] = 120] = "Nameplate";
+    SunspecModelId[SunspecModelId["Settings"] = 121] = "Settings";
+    SunspecModelId[SunspecModelId["Status"] = 122] = "Status";
+    SunspecModelId[SunspecModelId["Controls"] = 123] = "Controls";
+    SunspecModelId[SunspecModelId["EndMarker"] = 65535] = "EndMarker";
+})(SunspecModelId || (exports.SunspecModelId = SunspecModelId = {}));
+/**
+ * Enum values for connection control
+ */
+var SunspecConnectionControl;
+(function (SunspecConnectionControl) {
+    SunspecConnectionControl[SunspecConnectionControl["DISCONNECT"] = 0] = "DISCONNECT";
+    SunspecConnectionControl[SunspecConnectionControl["CONNECT"] = 1] = "CONNECT";
+})(SunspecConnectionControl || (exports.SunspecConnectionControl = SunspecConnectionControl = {}));
+/**
+ * Enum values for enable/disable controls
+ */
+var SunspecEnableControl;
+(function (SunspecEnableControl) {
+    SunspecEnableControl[SunspecEnableControl["DISABLED"] = 0] = "DISABLED";
+    SunspecEnableControl[SunspecEnableControl["ENABLED"] = 1] = "ENABLED";
+})(SunspecEnableControl || (exports.SunspecEnableControl = SunspecEnableControl = {}));
+/**
+ * Enum values for VAR percent mode
+ */
+var SunspecVArPctMode;
+(function (SunspecVArPctMode) {
+    SunspecVArPctMode[SunspecVArPctMode["NONE"] = 0] = "NONE";
+    SunspecVArPctMode[SunspecVArPctMode["WMAX"] = 1] = "WMAX";
+    SunspecVArPctMode[SunspecVArPctMode["VARMAX"] = 2] = "VARMAX";
+})(SunspecVArPctMode || (exports.SunspecVArPctMode = SunspecVArPctMode = {}));