@enyo-energy/energy-app-sdk 0.0.167 → 0.0.168

package/dist/cjs/energy-app-package-definition.cjs

@@ -17,6 +17,7 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["StaticElectricityTariff"] = "static-electricity-tariff";
     EnergyAppPackageCategory["TemperatureSensor"] = "temperature-sensor";
     EnergyAppPackageCategory["SmartPlug"] = "smart-plug";
+    EnergyAppPackageCategory["HeatingRod"] = "heating-rod";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
 /**

package/dist/cjs/energy-app-package-definition.d.cts

@@ -14,6 +14,7 @@ export declare enum EnergyAppPackageCategory {
     StaticElectricityTariff = "static-electricity-tariff",
     TemperatureSensor = "temperature-sensor",
     SmartPlug = "smart-plug",
+    HeatingRod = "heating-rod",
     Other = "other"
 }
 /**

package/dist/cjs/energy-app-permission.type.cjs

@@ -48,4 +48,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Wifi"] = "Wifi";
     EnergyAppPermissionTypeEnum["ChildProcess"] = "ChildProcess";
     EnergyAppPermissionTypeEnum["Udp"] = "Udp";
+    EnergyAppPermissionTypeEnum["ProvidedFiles"] = "ProvidedFiles";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

package/dist/cjs/energy-app-permission.type.d.cts

@@ -1,4 +1,4 @@
-export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
+export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp' | 'ProvidedFiles';
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -44,5 +44,6 @@ export declare enum EnergyAppPermissionTypeEnum {
     Bluetooth = "Bluetooth",
     Wifi = "Wifi",
     ChildProcess = "ChildProcess",
-    Udp = "Udp"
+    Udp = "Udp",
+    ProvidedFiles = "ProvidedFiles"
 }

package/dist/cjs/energy-app.cjs

@@ -323,6 +323,19 @@ class EnergyApp {
     useBatteries() {
         return this.energyAppSdk.useBatteries();
     }
+    /**
+     * Gets the File API for providing user-facing files.
+     * Files are registered with a translated display name and optional
+     * translated explanation; their content (base64 + MIME type + concrete
+     * file name) is produced on demand by the registered handler when the user
+     * chooses to store the file.
+     * @returns The File API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `ProvidedFiles`
+     *         permission is not granted.
+     */
+    useFiles() {
+        return this.energyAppSdk.useFiles();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -37,6 +37,7 @@ import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connect
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.cjs";
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
+import { EnergyAppFile } from "./packages/energy-app-file.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -256,6 +257,17 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Battery API instance
      */
     useBatteries(): EnergyAppBattery;
+    /**
+     * Gets the File API for providing user-facing files.
+     * Files are registered with a translated display name and optional
+     * translated explanation; their content (base64 + MIME type + concrete
+     * file name) is produced on demand by the registered handler when the user
+     * chooses to store the file.
+     * @returns The File API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `ProvidedFiles`
+     *         permission is not granted.
+     */
+    useFiles(): EnergyAppFile;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -36,6 +36,7 @@ import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connect
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.cjs";
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
+import { EnergyAppFile } from "./packages/energy-app-file.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -137,4 +138,6 @@ export interface EnyoEnergyAppSdk {
     useApplianceEnergyManagerForecast: () => EnergyAppApplianceEnergyManagerForecast;
     /** Get the Battery API for retrieving the current runtime state of each battery storage (SoC, stored kWh, average price per kWh, optional solar share) */
     useBatteries: () => EnergyAppBattery;
+    /** Get the File API for providing user-facing files whose translated names/explanations are shown by the host and whose content is produced on demand when the user stores them */
+    useFiles: () => EnergyAppFile;
 }

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;
+}