@enyo-energy/energy-app-sdk 0.0.34

package/dist/implementations/modbus/EnergyAppModbusDataTypeConverter.js

@@ -0,0 +1,126 @@
+/**
+ * Data Type Converter for Modbus Register Values
+ *
+ * @description Converts raw buffer data from Modbus registers into appropriate JavaScript types
+ */
+export class EnergyAppModbusDataTypeConverter {
+    /**
+     * Converts raw buffer data from Modbus registers into appropriate JavaScript types
+     *
+     * @param buffer - Raw buffer data from Modbus registers
+     * @param dataType - The expected data type for conversion
+     * @param scale - Optional scaling factor for numeric types (divide by 10^scale)
+     * @param quantity - Required for string types, specifies the string length in characters
+     * @returns Converted value (number for numeric types, string for string type)
+     */
+    convertFromBuffer(buffer, dataType, scale, quantity) {
+        try {
+            switch (dataType) {
+                case 'uint16': {
+                    const value = buffer.readUInt16BE(0);
+                    return this.applyScale(value, scale);
+                }
+                case 'int16': {
+                    const value = buffer.readInt16BE(0);
+                    return this.applyScale(value, scale);
+                }
+                case 'uint32': {
+                    const value = buffer.readUInt32BE(0);
+                    return this.applyScale(value, scale);
+                }
+                case 'int32': {
+                    const value = buffer.readInt32BE(0);
+                    return this.applyScale(value, scale);
+                }
+                case 'float32': {
+                    const value = buffer.readFloatBE(0);
+                    return this.applyScale(value, scale);
+                }
+                case 'string': {
+                    if (!quantity || quantity <= 0) {
+                        throw new Error('String data type requires a valid quantity parameter');
+                    }
+                    // Convert buffer to string, handling null termination and trimming whitespace
+                    return buffer.toString('ascii', 0, Math.min(buffer.length, quantity * 2))
+                        .replace(/\u0000/gmi, '') // Remove null terminators
+                        .trim(); // Remove leading/trailing whitespace
+                }
+                default:
+                    throw new Error(`Unsupported data type: ${dataType}`);
+            }
+        }
+        catch (error) {
+            console.error(`Failed to convert Buffer (length ${buffer.length}) to ${dataType}: ${error}`, error);
+            throw error;
+        }
+    }
+    /**
+     * Applies scaling to numeric values
+     *
+     * @param value - The numeric value to scale
+     * @param scale - Optional scaling factor (divide by 10^scale)
+     * @returns Scaled value or original value if no scale provided
+     */
+    applyScale(value, scale) {
+        if (scale !== undefined && scale > 0) {
+            return value / Math.pow(10, scale);
+        }
+        return value;
+    }
+    /**
+     * Validates if a value is valid for the given data type
+     *
+     * @param value - The value to validate
+     * @param dataType - The expected data type
+     * @returns True if the value is valid, false otherwise
+     */
+    isValidValue(value, dataType) {
+        if (value === null || value === undefined) {
+            return false;
+        }
+        switch (dataType) {
+            case 'string': {
+                // For strings, check if it's a valid string and not empty
+                return typeof value === 'string' && value.length > 0;
+            }
+            case 'uint16':
+            case 'int16':
+            case 'uint32':
+            case 'int32':
+            case 'float32': {
+                // For numeric types, check if it's a valid number and not a common NaN value
+                if (typeof value !== 'number' || isNaN(value)) {
+                    return false;
+                }
+                // Check for common NaN values used in Modbus devices
+                const nanValues = [0x8000, 0xFFFF, 0x80000000, 0xFFFFFFFF];
+                // For signed values, also check negative NaN indicators
+                if (dataType === 'int16' || dataType === 'int32') {
+                    nanValues.push(-32768, -2147483648);
+                }
+                return !nanValues.includes(value);
+            }
+            default:
+                return false;
+        }
+    }
+    /**
+     * Calculates the number of Modbus registers required for a given data type
+     *
+     * @param dataType - The data type to calculate register quantity for
+     * @returns Number of 16-bit registers required
+     */
+    getRegisterQuantity(dataType) {
+        switch (dataType) {
+            case 'uint16':
+            case 'int16':
+                return 1;
+            case 'uint32':
+            case 'int32':
+            case 'float32':
+                return 2;
+            default:
+                throw new Error(`Unsupported data type: ${dataType}`);
+        }
+    }
+}

package/dist/implementations/modbus/EnergyAppModbusFaultTolerantReader.d.ts

@@ -0,0 +1,10 @@
+import type { EnergyAppModbusInstance } from "../../packages/energy-app-modbus.js";
+import type { IRegisterReader, IConnectionHealth, RegisterReadResult } from './interfaces.js';
+export declare class EnergyAppModbusFaultTolerantReader implements IRegisterReader {
+    private readonly _modbusInstance;
+    private readonly _connectionHealth;
+    constructor(modbusInstance: EnergyAppModbusInstance, connectionHealth: IConnectionHealth);
+    readHoldingRegisters(startAddress: number, quantity: number): Promise<RegisterReadResult<Buffer>>;
+    readInputRegisters(startAddress: number, quantity: number): Promise<RegisterReadResult<Buffer>>;
+    isHealthy(): boolean;
+}

package/dist/implementations/modbus/EnergyAppModbusFaultTolerantReader.js

@@ -0,0 +1,45 @@
+export class EnergyAppModbusFaultTolerantReader {
+    _modbusInstance;
+    _connectionHealth;
+    constructor(modbusInstance, connectionHealth) {
+        this._modbusInstance = modbusInstance;
+        this._connectionHealth = connectionHealth;
+    }
+    async readHoldingRegisters(startAddress, quantity) {
+        try {
+            const result = await this._modbusInstance.readHoldingRegisters(startAddress, quantity);
+            this._connectionHealth.recordSuccess();
+            return {
+                success: true,
+                value: result
+            };
+        }
+        catch (error) {
+            const err = error;
+            this._connectionHealth.recordFailure(err);
+            console.warn(`Failed to read registers ${startAddress}-${startAddress + quantity - 1}: ${err.message} ` +
+                `(consecutive failures: ${this._connectionHealth.getConsecutiveFailures()})`);
+            return {
+                success: false,
+                error: err
+            };
+        }
+    }
+    async readInputRegisters(startAddress, quantity) {
+        try {
+            // Note: This would need to be implemented in the SDK if input registers are needed
+            throw new Error('Input registers not supported by current SDK');
+        }
+        catch (error) {
+            const err = error;
+            this._connectionHealth.recordFailure(err);
+            return {
+                success: false,
+                error: err
+            };
+        }
+    }
+    isHealthy() {
+        return this._connectionHealth.isHealthy();
+    }
+}

package/dist/implementations/modbus/EnergyAppModbusInverter.d.ts

@@ -0,0 +1,56 @@
+import type { EnergyAppModbusInstance } from "../../packages/energy-app-modbus.js";
+import { EnyoAppliance } from "../../types/enyo-appliance.js";
+import type { EnyoNetworkDevice } from "../../types/enyo-network-device.js";
+import { EnyoDataBusMessage, EnyoInverterStateEnum } from "../../types/enyo-data-bus-value.js";
+import { type EnergyAppModbusDevice, type EnergyAppModbusInverterConfig } from './interfaces.js';
+import { EnergyApp } from "../../index.js";
+export declare class EnergyAppModbusInverter implements EnergyAppModbusDevice {
+    readonly client: EnergyApp;
+    readonly config: EnergyAppModbusInverterConfig;
+    readonly networkDevice: EnyoNetworkDevice;
+    private readonly _registerMapper;
+    private readonly _connectionHealth;
+    private _modbusInstance?;
+    private _appliance?;
+    private _inverterMetadata?;
+    constructor(client: EnergyApp, config: EnergyAppModbusInverterConfig, networkDevice: EnyoNetworkDevice);
+    get appliance(): EnyoAppliance;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    updateData(): Promise<EnyoDataBusMessage[]>;
+    getSerialNumber(): Promise<string | null>;
+    getCurrentPower(): Promise<number | null>;
+    getTotalEnergy(): Promise<number | null>;
+    /**
+     * Reads the current inverter state from modbus registers.
+     * Maps the register value to EnyoInverterStateEnum using the configured value mapping.
+     */
+    getInverterState(): Promise<EnyoInverterStateEnum | null>;
+    /**
+     * Reads the current active power limitation from modbus registers.
+     */
+    getActivePowerLimitation(): Promise<number | null>;
+    /**
+     * Reads the power value for a specific string from modbus registers.
+     *
+     * @param stringIndex - The string index (1-4)
+     * @returns Promise resolving to power value in Watts or null if not available
+     */
+    getStringPower(stringIndex: number): Promise<number | null>;
+    /**
+     * Reads the voltage value for a specific string from modbus registers.
+     *
+     * @param stringIndex - The string index (1-4)
+     * @returns Promise resolving to voltage value in Volts or null if not available
+     */
+    getStringVoltage(stringIndex: number): Promise<number | null>;
+    /**
+     * Discovers and caches inverter metadata from modbus registers during connection.
+     * This method reads static metadata like max PV production once
+     * and stores them for later use in appliance creation.
+     */
+    private _discoverInverterMetadata;
+    private _initializeAppliance;
+    modbusClient(): EnergyAppModbusInstance | undefined;
+}

package/dist/implementations/modbus/EnergyAppModbusInverter.js

@@ -0,0 +1,344 @@
+import { randomUUID } from "node:crypto";
+import { EnyoApplianceConnectionType } from "../../types/enyo-appliance.js";
+import { EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.js";
+import { EnyoDataBusMessageEnum } from "../../types/enyo-data-bus-value.js";
+import { EnyoSourceEnum } from "../../types/enyo-source.enum.js";
+import { EnergyAppModbusConfigurationError, EnergyAppModbusConnectionError } from './interfaces.js';
+import { EnergyAppModbusRegisterMapper } from './EnergyAppModbusRegisterMapper.js';
+import { EnergyAppModbusConnectionHealth } from './EnergyAppModbusConnectionHealth.js';
+import { EnergyAppModbusFaultTolerantReader } from './EnergyAppModbusFaultTolerantReader.js';
+export class EnergyAppModbusInverter {
+    client;
+    config;
+    networkDevice;
+    _registerMapper;
+    _connectionHealth;
+    _modbusInstance;
+    _appliance;
+    _inverterMetadata;
+    constructor(client, config, networkDevice) {
+        this.client = client;
+        this.config = config;
+        this.networkDevice = networkDevice;
+        this._registerMapper = new EnergyAppModbusRegisterMapper();
+        this._connectionHealth = new EnergyAppModbusConnectionHealth();
+        // Validate configuration
+        const validation = this._registerMapper.validateRegisterMap(config.registers);
+        if (!validation.valid) {
+            throw new EnergyAppModbusConfigurationError(`Invalid inverter configuration: ${validation.errors.join(', ')}`);
+        }
+        this.client = client;
+        this.config = config;
+        this.networkDevice = networkDevice;
+    }
+    get appliance() {
+        if (!this._appliance) {
+            throw new Error('Appliance not initialized. Call connect() first.');
+        }
+        return this._appliance;
+    }
+    async connect() {
+        try {
+            console.log(`Connecting to inverter at ${this.networkDevice.hostname}...`);
+            // Create modbus connection
+            this._modbusInstance = await this.client.useModbus().connect({
+                host: this.networkDevice.hostname,
+                unitId: this.config.options?.unitId || 1,
+                port: this.config.options?.port || 502,
+                timeout: this.config.options?.timeout || 5000
+            });
+            // Discover inverter metadata during connection
+            this._inverterMetadata = await this._discoverInverterMetadata();
+            // Initialize appliance
+            await this._initializeAppliance();
+            console.log(`Successfully connected to inverter ${this.config.name[0]?.name} at ${this.networkDevice.hostname}`);
+        }
+        catch (error) {
+            throw new EnergyAppModbusConnectionError(`Failed to connect to inverter at ${this.networkDevice.hostname}: ${error.message}`, error);
+        }
+    }
+    async disconnect() {
+        if (this._modbusInstance) {
+            try {
+                await this._modbusInstance.disconnect();
+                console.log(`Disconnected from inverter at ${this.networkDevice.hostname}`);
+            }
+            catch (error) {
+                console.warn(`Error disconnecting from inverter: ${error.message}`);
+            }
+            finally {
+                this._modbusInstance = undefined;
+            }
+        }
+    }
+    isConnected() {
+        return this._modbusInstance !== undefined && this._connectionHealth.isHealthy();
+    }
+    async updateData() {
+        if (!this._modbusInstance || !this._appliance) {
+            throw new Error('Inverter not connected. Call connect() first.');
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const registerData = await this._registerMapper.readMultipleRegisters(reader, this.config.registers);
+        // Extract known values with fallbacks
+        const pvPowerW = registerData.power || 0; // Required field, default to 0 if not available
+        const voltageL1 = registerData.voltageL1 || 0; // Required field, default to 0 if not available
+        const voltageL2 = registerData.voltageL2 || undefined;
+        const voltageL3 = registerData.voltageL3 || undefined;
+        // Read current inverter state if available
+        let inverterState;
+        try {
+            inverterState = await this.getInverterState() || undefined;
+        }
+        catch (error) {
+            console.warn(`Failed to read inverter state: ${error.message}`);
+        }
+        // Read active power limitation if available
+        let activePowerLimitationW;
+        try {
+            activePowerLimitationW = await this.getActivePowerLimitation() || undefined;
+        }
+        catch (error) {
+            console.warn(`Failed to read active power limitation: ${error.message}`);
+        }
+        // Read string data if available
+        const strings = [];
+        for (let stringIndex = 1; stringIndex <= 4; stringIndex++) {
+            let stringPower;
+            let stringVoltage;
+            let hasData = false;
+            // Try to read string power
+            try {
+                const power = await this.getStringPower(stringIndex);
+                if (power !== null) {
+                    stringPower = power;
+                    hasData = true;
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to read string${stringIndex} power: ${error.message}`);
+            }
+            // Try to read string voltage
+            try {
+                const voltage = await this.getStringVoltage(stringIndex);
+                if (voltage !== null) {
+                    stringVoltage = voltage;
+                    hasData = true;
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to read string${stringIndex} voltage: ${error.message}`);
+            }
+            // Only add string to array if we have at least one value
+            if (hasData) {
+                strings.push({
+                    index: stringIndex,
+                    ...(stringVoltage !== undefined && { voltage: stringVoltage }),
+                    ...(stringPower !== undefined && { powerW: stringPower })
+                });
+            }
+        }
+        const message = {
+            type: 'message',
+            source: EnyoSourceEnum.Device,
+            id: randomUUID(),
+            timestampIso: new Date().toISOString(),
+            message: EnyoDataBusMessageEnum.InverterValuesUpdateV1,
+            applianceId: this._appliance.id,
+            data: {
+                state: inverterState,
+                pvPowerW,
+                voltageL1,
+                voltageL2,
+                voltageL3,
+                activePowerLimitationW,
+                ...(strings.length > 0 && { strings })
+            },
+            resolution: '10s'
+        };
+        // Create logging info with string data if available
+        const stringInfo = strings.length > 0
+            ? `, Strings=[${strings.map(s => `${s.index}:${s.powerW || 'N/A'}W/${s.voltage || 'N/A'}V`).join(',')}]`
+            : '';
+        console.log(`Inverter Data (${this.config.name[0]?.name}): State=${inverterState || 'N/A'}, Power=${pvPowerW}W, Voltage=${voltageL1}V, PowerLimit=${activePowerLimitationW || 'N/A'}W${stringInfo}`);
+        return [message];
+    }
+    // Convenience methods for accessing specific register values
+    async getSerialNumber() {
+        if (!this._modbusInstance || !this.config.registers.serialNumber) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.serialNumber);
+        return result.success ? result.value : null;
+    }
+    async getCurrentPower() {
+        if (!this._modbusInstance || !this.config.registers.power) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.power);
+        return result.success ? result.value : null;
+    }
+    async getTotalEnergy() {
+        if (!this._modbusInstance || !this.config.registers.totalEnergy) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.totalEnergy);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Reads the current inverter state from modbus registers.
+     * Maps the register value to EnyoInverterStateEnum using the configured value mapping.
+     */
+    async getInverterState() {
+        if (!this._modbusInstance || !this.config.registers.state) {
+            return null;
+        }
+        try {
+            const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+            const result = await this._registerMapper.readRegister(reader, this.config.registers.state);
+            if (!result.success || result.value === undefined) {
+                return null;
+            }
+            // Use configured value mapping if available
+            if (this.config.registers.state.valueMapping) {
+                const mapping = this.config.registers.state.valueMapping
+                    .find(m => m.value === result.value);
+                if (mapping) {
+                    return mapping.mappedState;
+                }
+                else {
+                    console.warn(`No mapping found for inverter state value: ${result.value} (Address ${this.config.registers.state.address}, ${this.config.registers.state.dataType}). Available mappings: ${this.config.registers.state.valueMapping.map(m => m.value).join(', ')}`);
+                    return null;
+                }
+            }
+            else {
+                console.warn('Inverter state register configured without value mapping. Please configure valueMapping in register config.');
+                return null;
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to read inverter state: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Reads the current active power limitation from modbus registers.
+     */
+    async getActivePowerLimitation() {
+        if (!this._modbusInstance || !this.config.registers.activePowerLimitationW) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.activePowerLimitationW);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Reads the power value for a specific string from modbus registers.
+     *
+     * @param stringIndex - The string index (1-4)
+     * @returns Promise resolving to power value in Watts or null if not available
+     */
+    async getStringPower(stringIndex) {
+        if (!this._modbusInstance || stringIndex < 1 || stringIndex > 4) {
+            return null;
+        }
+        const registerKey = `string${stringIndex}Power`;
+        const registerConfig = this.config.registers[registerKey];
+        if (!registerConfig) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, registerConfig);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Reads the voltage value for a specific string from modbus registers.
+     *
+     * @param stringIndex - The string index (1-4)
+     * @returns Promise resolving to voltage value in Volts or null if not available
+     */
+    async getStringVoltage(stringIndex) {
+        if (!this._modbusInstance || stringIndex < 1 || stringIndex > 4) {
+            return null;
+        }
+        const registerKey = `string${stringIndex}Voltage`;
+        const registerConfig = this.config.registers[registerKey];
+        if (!registerConfig) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, registerConfig);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Discovers and caches inverter metadata from modbus registers during connection.
+     * This method reads static metadata like max PV production once
+     * and stores them for later use in appliance creation.
+     */
+    async _discoverInverterMetadata() {
+        if (!this._modbusInstance) {
+            throw new Error('Modbus instance not available');
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader(this._modbusInstance, this._connectionHealth);
+        const metadata = {};
+        try {
+            // Read max PV production if configured
+            if (this.config.registers.maxPvProductionW) {
+                const result = await this._registerMapper.readRegister(reader, this.config.registers.maxPvProductionW);
+                if (result.success && result.value !== undefined) {
+                    metadata.maxPvProductionW = result.value;
+                    console.log(`Discovered inverter max PV production: ${result.value} W`);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to discover some inverter metadata: ${error.message}`);
+        }
+        return metadata;
+    }
+    async _initializeAppliance() {
+        const appliances = await this.client.useAppliances().list();
+        let existingAppliance = appliances.find(a => a.networkDeviceIds.includes(this.networkDevice.id) &&
+            a.type === EnyoApplianceTypeEnum.Inverter);
+        if (!existingAppliance) {
+            // Create new appliance
+            existingAppliance = {
+                id: randomUUID(),
+                type: EnyoApplianceTypeEnum.Inverter,
+                networkDeviceIds: [this.networkDevice.id],
+                name: this.config.name,
+                metadata: {
+                    state: EnyoApplianceStateEnum.Connected,
+                    connectionType: EnyoApplianceConnectionType.Connector,
+                    ...this.config.options?.topology && { topology: this.config.options.topology }
+                },
+                inverter: this._inverterMetadata
+            };
+            await this.client.useAppliances().save(existingAppliance, undefined);
+            console.log(`Created new inverter appliance: ${this.config.name[0]?.name}`);
+        }
+        else {
+            // Update existing appliance
+            existingAppliance = {
+                ...existingAppliance,
+                name: this.config.name,
+                metadata: {
+                    ...existingAppliance.metadata,
+                    connectionType: EnyoApplianceConnectionType.Connector,
+                    state: EnyoApplianceStateEnum.Connected,
+                    ...this.config.options?.topology && { topology: this.config.options.topology }
+                },
+                inverter: this._inverterMetadata
+            };
+            await this.client.useAppliances().save(existingAppliance, existingAppliance?.id);
+            console.log(`Updated existing inverter appliance: ${this.config.name[0]?.name}`);
+        }
+        this._appliance = existingAppliance;
+    }
+    modbusClient() {
+        return this._modbusInstance;
+    }
+}

package/dist/implementations/modbus/EnergyAppModbusMeter.d.ts

@@ -0,0 +1,26 @@
+import type { EnergyAppModbusInstance } from "../../packages/energy-app-modbus.js";
+import { EnyoAppliance } from "../../types/enyo-appliance.js";
+import type { EnyoNetworkDevice } from "../../types/enyo-network-device.js";
+import { type EnyoDataBusMessage } from "../../types/enyo-data-bus-value.js";
+import { type EnergyAppModbusDevice, type EnergyAppModbusMeterConfig } from './interfaces.js';
+import { EnergyApp } from "../../index.js";
+export declare class EnergyAppModbusMeter implements EnergyAppModbusDevice {
+    readonly client: EnergyApp;
+    readonly config: EnergyAppModbusMeterConfig;
+    readonly networkDevice: EnyoNetworkDevice;
+    private readonly _registerMapper;
+    private readonly _connectionHealth;
+    private _modbusInstance?;
+    private _appliance?;
+    constructor(client: EnergyApp, config: EnergyAppModbusMeterConfig, networkDevice: EnyoNetworkDevice);
+    get appliance(): EnyoAppliance;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    updateData(): Promise<EnyoDataBusMessage[]>;
+    getGridPower(): Promise<number | null>;
+    getGridFeedInEnergy(): Promise<number | null>;
+    getGridConsumptionEnergy(): Promise<number | null>;
+    private _initializeAppliance;
+    modbusClient(): EnergyAppModbusInstance | undefined;
+}