@yyberi/fronius-comm/README.md

Library for communicating with Fronius solar inverters

# @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`](https://www.npmjs.com/package/moment-timezone) for UTC date handling  
- Pluggable logging via [`@yyberi/logger`](https://www.npmjs.com/package/@yyberi/logger)  

## Installation

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

## Quick Start

```ts
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:

```ts
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:

```ts
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.

```ts
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.

```ts
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.

```ts
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`](https://www.npmjs.com/package/@yyberi/logger)
* [`moment-timezone`](https://www.npmjs.com/package/moment-timezone)
* Node.js (v16+)

## License

MIT © yyberi