@enyo-energy/energy-app-sdk 0.0.34

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -0,0 +1,67 @@
+import { EnergyAppInterval } from "./packages/energy-app-interval.cjs";
+import { EnergyAppModbus } from "./packages/energy-app-modbus.cjs";
+import { EnergyAppStorage } from "./packages/energy-app-storage.cjs";
+import { EnergyAppAppliance } from "./packages/energy-app-appliance.cjs";
+import { EnergyAppNetworkDevice } from "./packages/energy-app-network-device.cjs";
+import { EnergyAppDataBus } from "./packages/energy-app-data-bus.cjs";
+import { EnergyAppOcpp } from "./packages/energy-app-ocpp.cjs";
+import { EnergyAppCharge } from "./packages/energy-app-charge.cjs";
+import { EnergyAppVehicle } from "./packages/energy-app-vehicle.cjs";
+import { EnergyAppChargingCard } from "./packages/energy-app-charging-card.cjs";
+import { EnergyAppAuthentication } from "./packages/energy-app-authentication.cjs";
+import { EnergyAppSettings } from "./packages/energy-app-settings.cjs";
+import { EnergyAppElectricityPrices } from "./packages/energy-app-electricity-prices.cjs";
+import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
+export declare enum EnergyAppStateEnum {
+    Launching = "launching",
+    Running = "running",
+    /** This state tells the user that a configuration is required which blocks the energy app from running*/
+    ConfigurationRequired = "configuration-required",
+    /** This state tells the user that an internet connection of the system is required which blocks the energy app from running*/
+    InternetConnectionRequired = "internet-connection-required"
+}
+/**
+ * Main API interface for enyo Energy App packages.
+ * Provides access to all system capabilities including lifecycle management,
+ * network operations, storage, and device communication.
+ */
+export interface EnyoEnergyAppSdk {
+    /** Register a callback that gets called when the package is initialized */
+    register: (callback: (packageName: string, version: number) => void) => void;
+    /** Register a callback that gets called when the system is shutting down */
+    onShutdown: (callback: () => Promise<void>) => void;
+    /** Update the state of the Energy App. Default state set is launching*/
+    updateEnergyAppState: (state: EnergyAppStateEnum) => void;
+    /** Check if the system is currently online */
+    isSystemOnline: () => boolean;
+    /** Get the fetch API for HTTP requests */
+    useFetch: () => typeof fetch;
+    /** Get the interval management API */
+    useInterval: () => EnergyAppInterval;
+    /** Get the Modbus communication API */
+    useModbus: () => EnergyAppModbus;
+    /** Get the network device discovery API */
+    useNetworkDevices: () => EnergyAppNetworkDevice;
+    /** Get the persistent storage API */
+    useStorage: () => EnergyAppStorage;
+    /** Get the Appliance API */
+    useAppliances: () => EnergyAppAppliance;
+    /** Get the Data Bus API */
+    useDataBus: () => EnergyAppDataBus;
+    /** Get the OCPP API */
+    useOcpp: () => EnergyAppOcpp;
+    /** Get the Charge API*/
+    useCharge: () => EnergyAppCharge;
+    /** Get the Vehicle API*/
+    useVehicle: () => EnergyAppVehicle;
+    /** Get the Charging Card API*/
+    useChargingCard: () => EnergyAppChargingCard;
+    /** Get the Authentication API */
+    useAuthentication: () => EnergyAppAuthentication;
+    /** Get the Settings API */
+    useSettings: () => EnergyAppSettings;
+    /** Get the Electricity Prices API */
+    useElectricityPrices: () => EnergyAppElectricityPrices;
+    /** Get the Notification API */
+    useNotification: () => EnergyAppNotification;
+}

package/dist/cjs/hems-one-energy-app-sdk.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyAppStateEnum = void 0;
+var EnergyAppStateEnum;
+(function (EnergyAppStateEnum) {
+    EnergyAppStateEnum["Launching"] = "launching";
+    EnergyAppStateEnum["Running"] = "running";
+    /** This state tells the user that a configuration is required which blocks the energy app from running*/
+    EnergyAppStateEnum["ConfigurationRequired"] = "configuration-required";
+    /** This state tells the user that an internet connection of the system is required which blocks the energy app from running*/
+    EnergyAppStateEnum["InternetConnectionRequired"] = "internet-connection-required";
+})(EnergyAppStateEnum || (exports.EnergyAppStateEnum = EnergyAppStateEnum = {}));

package/dist/cjs/hems-one-energy-app-sdk.d.cts

@@ -0,0 +1,64 @@
+import { EnergyAppInterval } from "./packages/energy-app-interval.cjs";
+import { EnergyAppModbus } from "./packages/energy-app-modbus.cjs";
+import { EnergyAppStorage } from "./packages/energy-app-storage.cjs";
+import { EnergyAppAppliance } from "./packages/energy-app-appliance.cjs";
+import { EnergyAppNetworkDevice } from "./packages/energy-app-network-device.cjs";
+import { EnergyAppDataBus } from "./packages/energy-app-data-bus.cjs";
+import { EnergyAppOcpp } from "./packages/energy-app-ocpp.cjs";
+import { EnergyAppCharge } from "./packages/energy-app-charge.cjs";
+import { EnergyAppVehicle } from "./packages/energy-app-vehicle.cjs";
+import { EnergyAppChargingCard } from "./packages/energy-app-charging-card.cjs";
+import { EnergyAppAuthentication } from "./packages/energy-app-authentication.cjs";
+import { EnergyAppSettings } from "./packages/energy-app-settings.cjs";
+import { EnergyAppElectricityPrices } from "./packages/energy-app-electricity-prices.cjs";
+export declare enum EnergyAppStateEnum {
+    Launching = "launching",
+    Running = "running",
+    /** This state tells the user that a configuration is required which blocks the energy app from running*/
+    ConfigurationRequired = "configuration-required",
+    /** This state tells the user that an internet connection of the system is required which blocks the energy app from running*/
+    InternetConnectionRequired = "internet-connection-required"
+}
+/**
+ * Main API interface for HEMS One Energy App packages.
+ * Provides access to all system capabilities including lifecycle management,
+ * network operations, storage, and device communication.
+ */
+export interface HemsOneEnergyAppSdk {
+    /** Register a callback that gets called when the package is initialized */
+    register: (callback: (packageName: string, version: number) => void) => void;
+    /** Register a callback that gets called when the system is shutting down */
+    onShutdown: (callback: () => Promise<void>) => void;
+    /** Update the state of the Energy App. Default state set is launching*/
+    updateEnergyAppState: (state: EnergyAppStateEnum) => void;
+    /** Check if the system is currently online */
+    isSystemOnline: () => boolean;
+    /** Get the fetch API for HTTP requests */
+    useFetch: () => typeof fetch;
+    /** Get the interval management API */
+    useInterval: () => EnergyAppInterval;
+    /** Get the Modbus communication API */
+    useModbus: () => EnergyAppModbus;
+    /** Get the network device discovery API */
+    useNetworkDevices: () => EnergyAppNetworkDevice;
+    /** Get the persistent storage API */
+    useStorage: () => EnergyAppStorage;
+    /** Get the Appliance API */
+    useAppliances: () => EnergyAppAppliance;
+    /** Get the Data Bus API */
+    useDataBus: () => EnergyAppDataBus;
+    /** Get the OCPP API */
+    useOcpp: () => EnergyAppOcpp;
+    /** Get the Charge API*/
+    useCharge: () => EnergyAppCharge;
+    /** Get the Vehicle API*/
+    useVehicle: () => EnergyAppVehicle;
+    /** Get the Charging Card API*/
+    useChargingCard: () => EnergyAppChargingCard;
+    /** Get the Authentication API */
+    useAuthentication: () => EnergyAppAuthentication;
+    /** Get the Settings API */
+    useSettings: () => EnergyAppSettings;
+    /** Get the Electricity Prices API */
+    useElectricityPrices: () => EnergyAppElectricityPrices;
+}

package/dist/cjs/implementations/modbus/EnergyAppModbusBattery.cjs

@@ -0,0 +1,388 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyAppModbusBattery = void 0;
+const node_crypto_1 = require("node:crypto");
+const enyo_appliance_js_1 = require("../../types/enyo-appliance.cjs");
+const enyo_appliance_js_2 = require("../../types/enyo-appliance.cjs");
+const enyo_data_bus_value_js_1 = require("../../types/enyo-data-bus-value.cjs");
+const enyo_source_enum_js_1 = require("../../types/enyo-source.enum.cjs");
+const interfaces_js_1 = require("./interfaces.cjs");
+const EnergyAppModbusRegisterMapper_js_1 = require("./EnergyAppModbusRegisterMapper.cjs");
+const EnergyAppModbusFaultTolerantReader_js_1 = require("./EnergyAppModbusFaultTolerantReader.cjs");
+class EnergyAppModbusBattery {
+    client;
+    config;
+    inverter;
+    _registerMapper;
+    _appliance;
+    _batteryMetadata;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+        this.config = config;
+        this.client = client;
+        this.inverter = config.inverter;
+        this._registerMapper = new EnergyAppModbusRegisterMapper_js_1.EnergyAppModbusRegisterMapper();
+        // Validate configuration
+        const validation = this._registerMapper.validateRegisterMap(config.registers);
+        if (!validation.valid) {
+            throw new interfaces_js_1.EnergyAppModbusConfigurationError(`Invalid battery configuration: ${validation.errors.join(', ')}`);
+        }
+        if (!config.inverter) {
+            throw new interfaces_js_1.EnergyAppModbusConfigurationError('Battery requires an inverter reference');
+        }
+    }
+    get appliance() {
+        if (!this._appliance) {
+            throw new Error('Battery appliance not initialized. Call connect() first.');
+        }
+        return this._appliance;
+    }
+    get networkDevice() {
+        if (!this.inverter) {
+            throw new Error('Battery requires an inverter reference');
+        }
+        return this.inverter.networkDevice;
+    }
+    async connect() {
+        if (!this.inverter) {
+            throw new Error('Battery requires an inverter reference');
+        }
+        if (!this.inverter.isConnected()) {
+            throw new Error('Inverter must be connected before connecting battery');
+        }
+        console.log(`Connecting battery to inverter ${this.config.name[0]?.name}...`);
+        // Discover battery metadata during connection
+        this._batteryMetadata = await this._discoverBatteryMetadata();
+        // Initialize appliance
+        await this._initializeAppliance();
+        console.log(`Successfully connected battery ${this.config.name[0]?.name}`);
+    }
+    async disconnect() {
+        try {
+            await this.inverter?.disconnect();
+            console.log(`Disconnected from battery at ${this.networkDevice.hostname}`);
+        }
+        catch (error) {
+            console.warn(`Error disconnecting from battery: ${error.message}`);
+        }
+    }
+    isConnected() {
+        return this.inverter?.isConnected() || false;
+    }
+    async updateData() {
+        if (!this.inverter || !this.inverter.isConnected() || !this._appliance) {
+            throw new Error('Battery not connected. Call connect() first.');
+        }
+        // Use the inverter's modbus instance
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            throw new Error('Inverter modbus instance not available');
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const registerData = await this._registerMapper.readMultipleRegisters(reader, this.config.registers);
+        // Extract battery data
+        const batteryCurrent = registerData.current || undefined;
+        const batteryVoltage = registerData.voltage || undefined;
+        const batterySoC = registerData.soc || undefined;
+        const batteryPowerW = await this.getPower();
+        // Read current battery state if available
+        let batteryState;
+        try {
+            batteryState = await this.getBatteryState() || undefined;
+        }
+        catch (error) {
+            console.warn(`Failed to read battery state: ${error.message}`);
+        }
+        const message = {
+            type: 'message',
+            source: enyo_source_enum_js_1.EnyoSourceEnum.Device,
+            id: (0, node_crypto_1.randomUUID)(),
+            timestampIso: new Date().toISOString(),
+            message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.BatteryValuesUpdateV1,
+            applianceId: this._appliance.id,
+            data: {
+                state: batteryState,
+                batteryPowerW: batteryPowerW ?? undefined,
+                batterySoC
+            },
+            resolution: '10s'
+        };
+        console.log(`Battery Data (${this.config.name[0]?.name}): State=${batteryState || 'N/A'}, Power=${batteryPowerW}W, SoC=${batterySoC}%, Current=${batteryCurrent}A, Voltage=${batteryVoltage}V`);
+        return [message];
+    }
+    // Convenience methods for accessing specific register values
+    async getSoc() {
+        if (!this.inverter || !this.config.registers.soc) {
+            return null;
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.soc);
+        return result.success ? result.value : null;
+    }
+    async getCurrent() {
+        if (!this.inverter || !this.config.registers.current) {
+            return null;
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.current);
+        return result.success ? result.value : null;
+    }
+    async getPower() {
+        if (!this.inverter) {
+            return null;
+        }
+        // Priority 1: Direct power register
+        if (this.config.registers.power) {
+            const modbusInstance = this.inverter._modbusInstance;
+            const connectionHealth = this.inverter._connectionHealth;
+            if (!modbusInstance) {
+                return null;
+            }
+            const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+            const result = await this._registerMapper.readRegister(reader, this.config.registers.power);
+            if (result.success && result.value !== undefined) {
+                return result.value;
+            }
+        }
+        // Priority 2: Calculate from percentage registers
+        if (this.config.registers.drainPercentage || this.config.registers.loadPercentage) {
+            const drainPercentage = await this.getDrainPercentage();
+            const loadPercentage = await this.getLoadPercentage();
+            const maxCapacityWh = this._batteryMetadata?.maxCapacityWh || null;
+            const percentagePower = this._calculatePowerFromPercentages(drainPercentage, loadPercentage, maxCapacityWh);
+            if (percentagePower !== null) {
+                return percentagePower;
+            }
+        }
+        // Priority 3: Calculate from current and voltage
+        const current = await this.getCurrent();
+        const voltage = await this.getVoltage();
+        if (current !== null && voltage !== null) {
+            return current * voltage;
+        }
+        return null;
+    }
+    async getVoltage() {
+        if (!this.inverter || !this.config.registers.voltage) {
+            return null;
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.voltage);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Reads the drain percentage from modbus register.
+     * Drain percentage represents the percentage of maximum capacity being discharged.
+     *
+     * @returns Drain percentage (0-100), or null if not available
+     */
+    async getDrainPercentage() {
+        if (!this.inverter || !this.config.registers.drainPercentage) {
+            return null;
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.drainPercentage);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Reads the load percentage from modbus register.
+     * Load percentage represents the percentage of maximum capacity being charged.
+     *
+     * @returns Load percentage (0-100), or null if not available
+     */
+    async getLoadPercentage() {
+        if (!this.inverter || !this.config.registers.loadPercentage) {
+            return null;
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            return null;
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const result = await this._registerMapper.readRegister(reader, this.config.registers.loadPercentage);
+        return result.success ? result.value : null;
+    }
+    /**
+     * Reads the current battery state from modbus registers.
+     * Maps the register value to EnyoBatteryApplianceStateEnum using the configured value mapping.
+     */
+    async getBatteryState() {
+        if (!this.inverter || !this.config.registers.state) {
+            return null;
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            return null;
+        }
+        try {
+            const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, 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 battery state value: ${result.value}. Available mappings: ${this.config.registers.state.valueMapping.map(m => m.value).join(', ')}`);
+                    return null;
+                }
+            }
+            else {
+                console.warn('Battery state register configured without value mapping. Please configure valueMapping in register config.');
+                return null;
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to read battery state: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Calculates battery power from drain and load percentages.
+     *
+     * @param drainPercentage - Percentage of max capacity being drained (discharging, positive power)
+     * @param loadPercentage - Percentage of max capacity being loaded (charging, negative power)
+     * @param maxCapacityWh - Maximum battery capacity in Wh
+     * @returns Power in watts (positive for discharging, negative for charging), or null if calculation not possible
+     */
+    _calculatePowerFromPercentages(drainPercentage, loadPercentage, maxCapacityWh) {
+        if (!maxCapacityWh) {
+            return null;
+        }
+        // Priority: drain percentage takes precedence over load percentage
+        if (drainPercentage !== null && drainPercentage !== undefined) {
+            // Discharging: positive power value
+            return (drainPercentage / 100) * maxCapacityWh;
+        }
+        if (loadPercentage !== null && loadPercentage !== undefined) {
+            // Charging: negative power value
+            return -(loadPercentage / 100) * maxCapacityWh;
+        }
+        return null;
+    }
+    /**
+     * Discovers and caches battery metadata from modbus registers during connection.
+     * This method reads static metadata like max capacity and power limits once
+     * and stores them for later use in appliance creation.
+     */
+    async _discoverBatteryMetadata() {
+        if (!this.inverter || !this.inverter.isConnected()) {
+            throw new Error('Inverter must be connected before discovering battery metadata');
+        }
+        const modbusInstance = this.inverter._modbusInstance;
+        const connectionHealth = this.inverter._connectionHealth;
+        if (!modbusInstance) {
+            throw new Error('Inverter modbus instance not available');
+        }
+        const reader = new EnergyAppModbusFaultTolerantReader_js_1.EnergyAppModbusFaultTolerantReader(modbusInstance, connectionHealth);
+        const metadata = {};
+        try {
+            // Read max capacity if configured
+            if (this.config.registers.maxCapacityWh) {
+                const result = await this._registerMapper.readRegister(reader, this.config.registers.maxCapacityWh);
+                if (result.success && result.value !== undefined) {
+                    metadata.maxCapacityWh = result.value;
+                    console.log(`Discovered battery max capacity: ${result.value} Wh`);
+                }
+            }
+            // Read max discharge power if configured
+            if (this.config.registers.maxDischargePowerW) {
+                const result = await this._registerMapper.readRegister(reader, this.config.registers.maxDischargePowerW);
+                if (result.success && result.value !== undefined) {
+                    metadata.maxDischargePowerW = result.value;
+                    console.log(`Discovered battery max discharge power: ${result.value} W`);
+                }
+            }
+            // Read max charging power if configured
+            if (this.config.registers.maxChargingPowerW) {
+                const result = await this._registerMapper.readRegister(reader, this.config.registers.maxChargingPowerW);
+                if (result.success && result.value !== undefined) {
+                    metadata.maxChargingPowerW = result.value;
+                    console.log(`Discovered battery max charging power: ${result.value} W`);
+                }
+            }
+            // Set connected appliance ID to the inverter's appliance ID if available
+            if (this.inverter.appliance?.id) {
+                metadata.connectedToApplianceId = this.inverter.appliance.id;
+            }
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to discover some battery metadata: ${error.message}`);
+        }
+        return metadata;
+    }
+    async _initializeAppliance() {
+        if (!this.inverter) {
+            throw new Error('Battery requires an inverter reference');
+        }
+        const appliances = await this.client.useAppliances().list();
+        let existingAppliance = appliances.find(a => a.networkDeviceIds.includes(this.inverter.networkDevice.id) &&
+            a.type === enyo_appliance_js_2.EnyoApplianceTypeEnum.Storage);
+        if (!existingAppliance) {
+            // Create new appliance
+            existingAppliance = {
+                id: (0, node_crypto_1.randomUUID)(),
+                type: enyo_appliance_js_2.EnyoApplianceTypeEnum.Storage,
+                networkDeviceIds: [this.inverter.networkDevice.id],
+                name: this.config.name,
+                metadata: {
+                    state: enyo_appliance_js_2.EnyoApplianceStateEnum.Connected,
+                    connectionType: enyo_appliance_js_1.EnyoApplianceConnectionType.Connector,
+                    ...this.config.options?.topology && { topology: this.config.options.topology }
+                },
+                battery: this._batteryMetadata
+            };
+            await this.client.useAppliances().save(existingAppliance, undefined);
+            console.log(`Created new battery appliance: ${this.config.name[0]?.name}`);
+        }
+        else {
+            // Update existing appliance
+            existingAppliance = {
+                ...existingAppliance,
+                name: this.config.name,
+                metadata: {
+                    ...existingAppliance.metadata,
+                    state: enyo_appliance_js_2.EnyoApplianceStateEnum.Connected,
+                    connectionType: enyo_appliance_js_1.EnyoApplianceConnectionType.Connector,
+                    ...this.config.options?.topology && { topology: this.config.options.topology }
+                },
+                battery: this._batteryMetadata
+            };
+            await this.client.useAppliances().save(existingAppliance, existingAppliance.id);
+            console.log(`Updated existing battery appliance: ${this.config.name[0]?.name}`);
+        }
+        this._appliance = existingAppliance;
+    }
+    modbusClient() {
+        return this.inverter?.modbusClient();
+    }
+}
+exports.EnergyAppModbusBattery = EnergyAppModbusBattery;

package/dist/cjs/implementations/modbus/EnergyAppModbusBattery.d.cts

@@ -0,0 +1,59 @@
+import { EnyoAppliance } from "../../types/enyo-appliance.cjs";
+import { EnyoBatteryStateEnum, type EnyoDataBusMessage } from "../../types/enyo-data-bus-value.cjs";
+import { type EnergyAppModbusDevice, type EnergyAppModbusBatteryConfig, type IEnergyAppModbusInverter } from './interfaces.cjs';
+import { EnergyApp } from "../../index.cjs";
+export declare class EnergyAppModbusBattery implements EnergyAppModbusDevice {
+    readonly client: EnergyApp;
+    readonly config: EnergyAppModbusBatteryConfig;
+    readonly inverter?: IEnergyAppModbusInverter;
+    private readonly _registerMapper;
+    private _appliance?;
+    private _batteryMetadata?;
+    constructor(client: EnergyApp, config: EnergyAppModbusBatteryConfig);
+    get appliance(): EnyoAppliance;
+    get networkDevice(): import("../../types/enyo-network-device.cjs").EnyoNetworkDevice;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    updateData(): Promise<EnyoDataBusMessage[]>;
+    getSoc(): Promise<number | null>;
+    getCurrent(): Promise<number | null>;
+    getPower(): Promise<number | null>;
+    getVoltage(): Promise<number | null>;
+    /**
+     * Reads the drain percentage from modbus register.
+     * Drain percentage represents the percentage of maximum capacity being discharged.
+     *
+     * @returns Drain percentage (0-100), or null if not available
+     */
+    getDrainPercentage(): Promise<number | null>;
+    /**
+     * Reads the load percentage from modbus register.
+     * Load percentage represents the percentage of maximum capacity being charged.
+     *
+     * @returns Load percentage (0-100), or null if not available
+     */
+    getLoadPercentage(): Promise<number | null>;
+    /**
+     * Reads the current battery state from modbus registers.
+     * Maps the register value to EnyoBatteryApplianceStateEnum using the configured value mapping.
+     */
+    getBatteryState(): Promise<EnyoBatteryStateEnum | null>;
+    /**
+     * Calculates battery power from drain and load percentages.
+     *
+     * @param drainPercentage - Percentage of max capacity being drained (discharging, positive power)
+     * @param loadPercentage - Percentage of max capacity being loaded (charging, negative power)
+     * @param maxCapacityWh - Maximum battery capacity in Wh
+     * @returns Power in watts (positive for discharging, negative for charging), or null if calculation not possible
+     */
+    private _calculatePowerFromPercentages;
+    /**
+     * Discovers and caches battery metadata from modbus registers during connection.
+     * This method reads static metadata like max capacity and power limits once
+     * and stores them for later use in appliance creation.
+     */
+    private _discoverBatteryMetadata;
+    private _initializeAppliance;
+    modbusClient(): import("../../packages/energy-app-modbus.cjs").EnergyAppModbusInstance | undefined;
+}

package/dist/cjs/implementations/modbus/EnergyAppModbusConnectionHealth.cjs

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyAppModbusConnectionHealth = void 0;
+class EnergyAppModbusConnectionHealth {
+    _consecutiveFailures = 0;
+    _lastError;
+    _lastSuccessTime = new Date();
+    _maxFailures = 5;
+    _staleThresholdMs = 5 * 60 * 1000; // 5 minutes
+    recordSuccess() {
+        this._consecutiveFailures = 0;
+        this._lastError = undefined;
+        this._lastSuccessTime = new Date();
+    }
+    recordFailure(error) {
+        this._consecutiveFailures++;
+        this._lastError = error;
+    }
+    isHealthy() {
+        const isNotFailing = this._consecutiveFailures < this._maxFailures;
+        const isNotStale = (Date.now() - this._lastSuccessTime.getTime()) < this._staleThresholdMs;
+        return isNotFailing && isNotStale;
+    }
+    getConsecutiveFailures() {
+        return this._consecutiveFailures;
+    }
+    getLastError() {
+        return this._lastError;
+    }
+    getLastSuccessTime() {
+        return new Date(this._lastSuccessTime);
+    }
+    isStale() {
+        return (Date.now() - this._lastSuccessTime.getTime()) > this._staleThresholdMs;
+    }
+}
+exports.EnergyAppModbusConnectionHealth = EnergyAppModbusConnectionHealth;

package/dist/cjs/implementations/modbus/EnergyAppModbusConnectionHealth.d.cts

@@ -0,0 +1,15 @@
+import type { IConnectionHealth } from './interfaces.cjs';
+export declare class EnergyAppModbusConnectionHealth implements IConnectionHealth {
+    private _consecutiveFailures;
+    private _lastError?;
+    private _lastSuccessTime;
+    private readonly _maxFailures;
+    private readonly _staleThresholdMs;
+    recordSuccess(): void;
+    recordFailure(error: Error): void;
+    isHealthy(): boolean;
+    getConsecutiveFailures(): number;
+    getLastError(): Error | undefined;
+    getLastSuccessTime(): Date;
+    isStale(): boolean;
+}