@yyberi/fronius-comm

@yyberi/fronius-comm

A small Node.js library for communicating with Fronius solar inverters. It provides a simple client to fetch real-time and historical energy production data.

Features

• Real-time data: fetch total, yearly, daily energy and instantaneous power
• Archive data parsing: retrieve 5-minute, 15-minute and hourly aggregated production values for any date or date range
• Built on native http and moment-timezone for UTC date handling
• Pluggable logging via @yyberi/logger

Installation

npm install @yyberi/fronius-comm
# or
yarn add @yyberi/fronius-comm

Quick Start

import { FroniusClient, SimpleInverterRealtimeData } from '@yyberi/fronius-comm';

// Instantiate with inverter IP, scope, device ID and device class:
const client = new FroniusClient(
  '192.168.1.100',   // your inverter IP
  'Device',          // scope (e.g. "Device" or "System")
  '1',               // deviceId
  'Inverter'         // deviceClass
);

async function fetchRealtime() {
  try {
    const data: SimpleInverterRealtimeData = await client.getRealtimeData();
    console.log('Total Energy (kWh):', data.totalEnergy);
    console.log('Year Energy  (kWh):', data.yearEnergy);
    console.log('Day Energy   (kWh):', data.dayEnergy);
    console.log('Current Power (W):', data.actPower);
  } catch (err) {
    console.error('Error fetching real-time data:', err);
  }
}

fetchRealtime();

API

new FroniusClient(ip, scope, deviceId, deviceClass, logLevel?)

Creates a new client instance.

• ip: string — Inverter hostname or IP address
• scope: string — API scope (usually "Device" or "System")
• deviceId: string — Numeric device identifier (e.g. "1")
• deviceClass: string — Class of the device (e.g. "Inverter")
• logLevel?: LogLevel — Optional log level from @yyberi/logger (default: LogLevel.INFO)

getRealtimeData(): Promise<SimpleInverterRealtimeData>

Fetches real-time inverter data. Returns a promise resolving to:

export interface SimpleInverterRealtimeData {
  /** Cumulative energy (kWh) */
  totalEnergy?: number;
  /** Energy produced this year (kWh) */
  yearEnergy?: number;
  /** Energy produced today (kWh) */
  dayEnergy?: number;
  /** Instantaneous AC power (W) */
  actPower?: number;
  /** ISO timestamp of the reading */
  ts?: string;
}

Throws on HTTP errors, timeouts or invalid JSON.

Archive data parsers

All archive methods accept either:

• A single date string (YYYY-MM-DD) to fetch one full day, or
• Two ISO date strings (start, end) to fetch an arbitrary range

They all return arrays of:

export interface TimeRangeValueData {
  /** ISO string of interval end time */
  time: string;
  /** Energy produced during the interval */
  value: number;
}

parseEnergyReal_WAC_Sum_Produced_5min(dateOrStart, end?)

Fetches raw 5-minute interval data.

const data5min = await client.parseEnergyReal_WAC_Sum_Produced_5min('2025-06-14');
// or
const data5min = await client.parseEnergyReal_WAC_Sum_Produced_5min('2025-06-13', '2025-06-14');

parseEnergyReal_WAC_Sum_Produced_15min(dateOrStart, end?)

Fetches and groups every three 5-min intervals into 15-min sums.

const { data5min, data15min } =
  await client.parseEnergyReal_WAC_Sum_Produced_15min('2025-06-14');

parseEnergyReal_WAC_Sum_Produced_All(dateOrStart, end?)

Fetches 5-min and 15-min data, and additionally aggregates into hourly sums.

const { data5min, data15min, data60min } =
  await client.parseEnergyReal_WAC_Sum_Produced_All('2025-06-14');

Scripts

• npm run build — compile TypeScript to dist/
• npm test — run Vitest unit tests

Dependencies

• @yyberi/logger
• moment-timezone
• Node.js (v16+)

License

MIT © yyberi