@enyo-energy/sunspec-sdk 0.0.1

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

@@ -0,0 +1,111 @@
+import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData } from "./sunspec-interfaces.cjs";
+import { IConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/interfaces.js";
+import { EnergyApp } from "@enyo-energy/energy-app-sdk";
+export declare class SunspecModbusClient {
+    private energyApp;
+    private modbusClient;
+    private discoveredModels;
+    private scaleFactors;
+    private connected;
+    private baseAddress;
+    private connectionHealth;
+    private faultTolerantReader;
+    constructor(energyApp: EnergyApp);
+    /**
+     * Connect to Modbus device
+     */
+    connect(host: string, port?: number, unitId?: number): Promise<void>;
+    /**
+     * Disconnect from Modbus device
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Discover all available Sunspec models
+     * Scans through the address space starting at 40001
+     */
+    discoverModels(): Promise<Map<number, SunspecModel>>;
+    /**
+     * Find a specific model by ID
+     */
+    findModel(modelId: number): SunspecModel | undefined;
+    /**
+     * Read a register value and apply scale factor
+     */
+    readRegisterWithScaleFactor(valueAddress: number, scaleFactorAddress?: number, quantity?: number): Promise<number>;
+    /**
+     * Convert unsigned 16-bit value to signed
+     */
+    private convertToSigned16;
+    /**
+     * Helper to clean string values by removing null characters
+     */
+    private cleanString;
+    /**
+     * Helper to read register value(s) using the fault-tolerant reader with data type conversion
+     */
+    private readRegisterValue;
+    /**
+     * Read inverter data from Model 103 (Three Phase)
+     */
+    readInverterData(): Promise<SunspecInverterData | null>;
+    /**
+     * Read single phase inverter data (Model 101)
+     */
+    private readSinglePhaseInverterData;
+    /**
+     * Read inverter scale factors
+     */
+    private readInverterScaleFactors;
+    /**
+     * Apply scale factor to a value
+     */
+    private applyScaleFactor;
+    /**
+     * Read MPPT data from Model 160
+     */
+    readMPPTData(moduleId?: number): Promise<SunspecMPPTData | null>;
+    /**
+     * Read all available MPPT strings
+     */
+    readAllMPPTData(): Promise<SunspecMPPTData[]>;
+    /**
+     * Read meter data (Model 203 for 3-phase)
+     */
+    readMeterData(): Promise<SunspecMeterData | null>;
+    /**
+     * Read common block data (Model 1)
+     */
+    readCommonBlock(): Promise<any>;
+    /**
+     * Get serial number from device
+     */
+    getSerialNumber(): Promise<string | undefined>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Check if connection is healthy
+     */
+    isHealthy(): boolean;
+    /**
+     * Get connection health details
+     */
+    getConnectionHealth(): IConnectionHealth;
+    /**
+     * Read Block 121 - Inverter Basic Settings
+     */
+    readInverterSettings(): Promise<SunspecInverterSettings | null>;
+    /**
+     * Read Block 123 - Immediate Inverter Controls
+     */
+    readInverterControls(): Promise<SunspecInverterControls | null>;
+    /**
+     * Write Block 121 - Inverter Basic Settings
+     */
+    writeInverterSettings(settings: Partial<SunspecInverterSettings>): Promise<boolean>;
+    /**
+     * Write Block 123 - Immediate Inverter Controls
+     */
+    writeInverterControls(controls: Partial<SunspecInverterControls>): Promise<boolean>;
+}

package/dist/cjs/version.cjs

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Auto-generated file containing the current SDK version.
+ * This file is generated by scripts/extract-version.js and should not be edited manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+exports.getSdkVersion = getSdkVersion;
+/**
+ * Current version of the enyo Energy App SDK.
+ */
+exports.SDK_VERSION = '0.0.1';
+/**
+ * Gets the current SDK version.
+ * @returns The semantic version string of the SDK
+ */
+function getSdkVersion() {
+    return exports.SDK_VERSION;
+}

package/dist/cjs/version.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Auto-generated file containing the current SDK version.
+ * This file is generated by scripts/extract-version.js and should not be edited manually.
+ */
+/**
+ * Current version of the enyo Energy App SDK.
+ */
+export declare const SDK_VERSION = "0.0.1";
+/**
+ * Gets the current SDK version.
+ * @returns The semantic version string of the SDK
+ */
+export declare function getSdkVersion(): string;

package/dist/sunspec-devices.d.ts

@@ -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.js";
+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/sunspec-devices.js

@@ -0,0 +1,327 @@
+import { SunspecModelId } from "./sunspec-interfaces.js";
+import { randomUUID } from "node:crypto";
+import { EnyoApplianceConnectionType, EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
+import { EnyoBatteryStateEnum, EnyoDataBusMessageEnum, EnyoInverterStateEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { EnyoSourceEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-source.enum.js";
+/**
+ * Base abstract class for all Sunspec devices
+ */
+export 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();
+        }
+    }
+}
+/**
+ * Sunspec Inverter implementation using dynamic model discovery
+ */
+export 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: EnyoApplianceTypeEnum.Inverter,
+                networkDevices: [this.networkDevice],
+                metadata: {
+                    connectionType: EnyoApplianceConnectionType.Connector,
+                    state: 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(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, EnyoApplianceConnectionType.Connector, 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: randomUUID(),
+                    message: EnyoDataBusMessageEnum.InverterValuesUpdateV1,
+                    type: 'message',
+                    source: 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 EnyoInverterStateEnum.Off;
+        const stateMap = {
+            1: EnyoInverterStateEnum.Off,
+            2: EnyoInverterStateEnum.Sleeping,
+            3: EnyoInverterStateEnum.Starting,
+            4: EnyoInverterStateEnum.Mppt,
+            5: EnyoInverterStateEnum.Throttled,
+            6: EnyoInverterStateEnum.ShuttingDown,
+            7: EnyoInverterStateEnum.Fault,
+            8: EnyoInverterStateEnum.Standby
+        };
+        return stateMap[state] || 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;
+    }
+}
+/**
+ * Sunspec Battery implementation
+ */
+export 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(SunspecModelId.Battery) !== undefined ||
+            this.sunspecClient.findModel(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: EnyoApplianceTypeEnum.Storage,
+                networkDevices: [this.networkDevice],
+                metadata: {
+                    connectionType: EnyoApplianceConnectionType.Connector,
+                    state: 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, EnyoApplianceConnectionType.Connector, 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: randomUUID(),
+                message: EnyoDataBusMessageEnum.BatteryValuesUpdateV1,
+                type: 'message',
+                source: EnyoSourceEnum.Device,
+                applianceId: this.applianceId,
+                clockId,
+                timestampIso: timestamp.toISOString(),
+                resolution,
+                data: {
+                    batterySoC: 50, // Placeholder - would read from battery model
+                    batteryPowerW: 0,
+                    state: EnyoBatteryStateEnum.Holding
+                }
+            };
+            messages.push(batteryMessage);
+            this.lastUpdateTime = timestamp.getTime();
+        }
+        catch (error) {
+            console.error(`Error updating battery data: ${error}`);
+        }
+        return messages;
+    }
+}
+/**
+ * Sunspec Meter implementation
+ */
+export 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(SunspecModelId.Meter3Phase) !== undefined ||
+            this.sunspecClient.findModel(SunspecModelId.MeterWye) !== undefined ||
+            this.sunspecClient.findModel(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: EnyoApplianceTypeEnum.Meter,
+                networkDevices: [this.networkDevice],
+                metadata: {
+                    connectionType: EnyoApplianceConnectionType.Connector,
+                    state: 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, EnyoApplianceConnectionType.Connector, 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: randomUUID(),
+                    message: EnyoDataBusMessageEnum.MeterValuesUpdateV1,
+                    type: 'message',
+                    source: 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;
+    }
+}