@enyo-energy/sunspec-sdk 0.0.1

package/dist/sunspec-interfaces.d.ts

@@ -0,0 +1,240 @@
+/**
+ * SunSpec block interfaces with block numbers
+ */
+/**
+ * Base interface for all SunSpec blocks
+ */
+export interface SunspecBlock {
+    blockNumber: number;
+    blockAddress?: number;
+    blockLength?: number;
+}
+/**
+ * Common Sunspec Model IDs
+ */
+export declare enum SunspecModelId {
+    Common = 1,
+    Inverter3Phase = 103,
+    InverterSinglePhase = 101,
+    MPPT = 160,
+    Battery = 124,
+    BatteryBase = 802,
+    BatteryControl = 803,
+    MeterSinglePhase = 201,
+    Meter3Phase = 203,
+    MeterWye = 204,
+    Nameplate = 120,
+    Settings = 121,
+    Status = 122,
+    Controls = 123,
+    EndMarker = 65535
+}
+/**
+ * Model information discovered during scanning
+ */
+export interface SunspecModel {
+    id: number;
+    address: number;
+    length: number;
+}
+/**
+ * Data types for Sunspec registers
+ */
+export type RegisterValue = number | string | bigint;
+/**
+ * Scale factor cache
+ */
+export interface ScaleFactors {
+    [key: string]: number;
+}
+/**
+ * Common block (Model 1) data structure
+ */
+export interface SunspecCommonBlock extends SunspecBlock {
+    blockNumber: 1;
+    manufacturer?: string;
+    model?: string;
+    options?: string;
+    version?: string;
+    serialNumber?: string;
+    deviceAddress?: number;
+}
+/**
+ * Inverter data structure based on Model 103
+ */
+export interface SunspecInverterData extends SunspecBlock {
+    blockNumber: 103 | 101;
+    acCurrent?: number;
+    phaseACurrent?: number;
+    phaseBCurrent?: number;
+    phaseCCurrent?: number;
+    voltageAB?: number;
+    voltageBC?: number;
+    voltageCA?: number;
+    voltageAN?: number;
+    voltageBN?: number;
+    voltageCN?: number;
+    acPower?: number;
+    frequency?: number;
+    apparentPower?: number;
+    reactivePower?: number;
+    powerFactor?: number;
+    acEnergy?: bigint;
+    dcCurrent?: number;
+    dcVoltage?: number;
+    dcPower?: number;
+    cabinetTemperature?: number;
+    heatSinkTemperature?: number;
+    transformerTemperature?: number;
+    otherTemperature?: number;
+    operatingState?: number;
+    vendorState?: number;
+    events?: number;
+    events2?: number;
+    vendorEvents1?: number;
+    vendorEvents2?: number;
+    vendorEvents3?: number;
+    vendorEvents4?: number;
+}
+/**
+ * MPPT data structure based on Model 160
+ */
+export interface SunspecMPPTData extends SunspecBlock {
+    blockNumber: 160;
+    id: number;
+    stringId?: string;
+    dcCurrent?: number;
+    dcCurrentSF?: number;
+    dcVoltage?: number;
+    dcVoltageSF?: number;
+    dcPower?: number;
+    dcPowerSF?: number;
+    dcEnergy?: bigint;
+    dcEnergySF?: number;
+    timestamp?: number;
+    temperature?: number;
+    temperatureSF?: number;
+    operatingState?: number;
+    vendorState?: number;
+    events?: number;
+}
+/**
+ * Battery data structure
+ */
+export interface SunspecBatteryData extends SunspecBlock {
+    blockNumber: 124 | 802 | 803;
+    soc?: number;
+    soh?: number;
+    chargePower?: number;
+    dischargePower?: number;
+    voltage?: number;
+    current?: number;
+    temperature?: number;
+    status?: number;
+}
+/**
+ * Meter data structure
+ */
+export interface SunspecMeterData extends SunspecBlock {
+    blockNumber: 201 | 203 | 204;
+    totalPower?: number;
+    phaseAPower?: number;
+    phaseBPower?: number;
+    phaseCPower?: number;
+    totalEnergy?: bigint;
+    exportedEnergy?: bigint;
+    importedEnergy?: bigint;
+    voltage?: number;
+    current?: number;
+    frequency?: number;
+}
+/**
+ * Block 121 - Inverter Basic Settings
+ * Reference: SunSpec Model 121
+ */
+export interface SunspecInverterSettings extends SunspecBlock {
+    blockNumber: 121;
+    WMax?: number;
+    WMax_SF?: number;
+    VRef?: number;
+    VRef_SF?: number;
+    VRefOfs?: number;
+    VRefOfs_SF?: number;
+    VMax?: number;
+    VMin?: number;
+    VMinMax_SF?: number;
+    VAMax?: number;
+    VAMax_SF?: number;
+    VArMaxQ1?: number;
+    VArMaxQ2?: number;
+    VArMaxQ3?: number;
+    VArMaxQ4?: number;
+    VArMax_SF?: number;
+    WGra?: number;
+    WGra_SF?: number;
+    PFMinQ1?: number;
+    PFMinQ2?: number;
+    PFMinQ3?: number;
+    PFMinQ4?: number;
+    PFMin_SF?: number;
+    VArAct?: number;
+    ClcTotVA?: number;
+    MaxRmpRte?: number;
+    MaxRmpRte_SF?: number;
+    ECPNomHz?: number;
+    ECPNomHz_SF?: number;
+    ConnPh?: number;
+}
+/**
+ * Block 123 - Immediate Inverter Controls
+ * Reference: SunSpec Model 123
+ */
+export interface SunspecInverterControls extends SunspecBlock {
+    blockNumber: 123;
+    Conn_WinTms?: number;
+    Conn_RvrtTms?: number;
+    Conn?: number;
+    WMaxLimPct?: number;
+    WMaxLimPct_SF?: number;
+    WMaxLimPct_WinTms?: number;
+    WMaxLimPct_RvrtTms?: number;
+    WMaxLimPct_RmpTms?: number;
+    WMaxLim_Ena?: number;
+    OutPFSet?: number;
+    OutPFSet_SF?: number;
+    OutPFSet_WinTms?: number;
+    OutPFSet_RvrtTms?: number;
+    OutPFSet_RmpTms?: number;
+    OutPFSet_Ena?: number;
+    VArWMaxPct?: number;
+    VArMaxPct?: number;
+    VArAvalPct?: number;
+    VArPct_SF?: number;
+    VArPct_WinTms?: number;
+    VArPct_RvrtTms?: number;
+    VArPct_RmpTms?: number;
+    VArPct_Mod?: number;
+    VArPct_Ena?: number;
+}
+/**
+ * Enum values for connection control
+ */
+export declare enum SunspecConnectionControl {
+    DISCONNECT = 0,
+    CONNECT = 1
+}
+/**
+ * Enum values for enable/disable controls
+ */
+export declare enum SunspecEnableControl {
+    DISABLED = 0,
+    ENABLED = 1
+}
+/**
+ * Enum values for VAR percent mode
+ */
+export declare enum SunspecVArPctMode {
+    NONE = 0,
+    WMAX = 1,
+    VARMAX = 2
+}

package/dist/sunspec-interfaces.js

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

package/dist/sunspec-modbus-client.d.ts

@@ -0,0 +1,111 @@
+import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData } from "./sunspec-interfaces.js";
+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>;
+}