# Fronius Binding

This binding uses the [Fronius Solar API V1](https://www.fronius.com/en/solar-energy/installers-partners/technical-data/all-products/system-monitoring/open-interfaces/fronius-solar-api-json-) to obtain data from Fronius devices.

It supports Fronius inverters, smart meters and Ohmpilot devices connected to a Fronius Datamanager 1.0 / 2.0, Fronius Datalogger or with integrated Solar API V1 support.

Inverters with integrated Solar API V1 support include:

- Fronius Galvo
- Fronius Primo
- Fronius Symo
- Fronius Symo Gen24
- Fronius Symo Gen24 Plus

## Supported Things

| Thing Type      | Description                                                                                                                                                    |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `bridge`        | The Bridge                                                                                                                                                     |
| `powerinverter` | Fronius Galvo, Symo and other Fronius inverters: You can add multiple inverters that depend on the same datalogger with different device ids. (default id = 1) |
| `battery`       | Fronius Battery: Battery devices that map to storage controller fields (default id = 0)                                                                        |
| `meter`         | Fronius Smart Meter: You can add multiple smart meters with different device ids. (default id = 0)                                                             |
| `ohmpilot`      | Fronius Ohmpilot (default id = 0)                                                                                                                              |

## Discovery

There is no discovery implemented. You have to create your Things manually and specify the hostname or IP address of the Datalogger and the device id.

## Binding Configuration

The binding has no configuration options, all configuration is done at `bridge`, `powerinverter`, `meter` or `ohmpilot` level.

## Thing Configuration

### Bridge Thing Configuration

| Parameter         | Description                                                                    | Required |
|-------------------|--------------------------------------------------------------------------------|----------|
| `hostname`        | The hostname or IP address of your Fronius Datamanager, Datalogger or inverter | Yes      |
| `username`        | The username to authenticate with the inverter settings for battery control    | No       |
| `password`        | The password to authenticate with the inverter settings for battery control    | No       |
| `refreshInterval` | Refresh interval in seconds                                                    | No       |
| `scheme`          | Set the protocol scheme that is used to connect to your device (default: http) | No       |

### Powerinverter Thing Configuration

| Parameter  | Description                                |
|------------|--------------------------------------------|
| `deviceId` | The identifier of your device (Default: 1) |

### Battery Thing Configuration

| Parameter  | Description                                        |
|------------|----------------------------------------------------|
| `deviceId` | The identifier of your battery device (Default: 0) |

### Meter Thing Configuration

| Parameter  | Description                                     |
|------------|-------------------------------------------------|
| `deviceId` | The identifier of your smart meter (Default: 0) |

### Ohmpilot Thing Configuration

| Parameter  | Description                                  |
|------------|----------------------------------------------|
| `deviceId` | The identifier of your ohmpilot (Default: 0) |

## Channels

### `powerinverter` Thing Channels

| Channel ID                           | Item Type                | Description                                                                                                       |
|--------------------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------|
| `inverterdatachannelpac`             | Number:Power             | AC Power generated                                                                                                |
| `inverterdatachannelpdc`             | Number:Power             | DC Power calculated from DC voltage * DC current                                                                  |
| `inverterdatachannelpdc2`            | Number:Power             | DC Power generated by MPPT tracker 2                                                                              |
| `inverterdatachannelpdc3`            | Number:Power             | DC Power generated by MPPT tracker 3                                                                              |
| `inverterdatachannelfac`             | Number:Frequency         | AC frequency                                                                                                      |
| `inverterdatachanneliac`             | Number:ElectricCurrent   | AC current                                                                                                        |
| `inverterdatachannelidc`             | Number:ElectricCurrent   | DC current                                                                                                        |
| `inverterdatachannelidc2`            | Number:ElectricCurrent   | DC current of MPPT tracker 2                                                                                      |
| `inverterdatachannelidc3`            | Number:ElectricCurrent   | DC current of MPPT tracker 3                                                                                      |
| `inverterdatachanneluac`             | Number:ElectricPotential | AC voltage                                                                                                        |
| `inverterdatachanneludc`             | Number:ElectricPotential | DC voltage                                                                                                        |
| `inverterdatachanneludc2`            | Number:ElectricPotential | DC voltage of MPPT tracker 2                                                                                      |
| `inverterdatachanneludc3`            | Number:ElectricPotential | DC voltage of MPPT tracker 3                                                                                      |
| `inverterdatachanneldayenergy`       | Number:Energy            | Energy generated on current day (GEN24/Tauro/Verto will always report null)                                       |
| `inverterdatachannelyear`            | Number:Energy            | Energy generated in current year (GEN24/Tauro/Verto will always report null)                                      |
| `inverterdatachanneltotal`           | Number:Energy            | Energy generated overall                                                                                          |
| `inverterdatadevicestatuserrorcode`  | Number                   | Device error code                                                                                                 |
| `inverterdatadevicestatusstatuscode` | Number                   | Device status code<br />`0` - `6` Startup<br />`7` Running <br />`8` Standby<br />`9` Bootloading<br />`10` Error |
| `powerflowchannelpgrid`              | Number:Power             | Grid Power (+ from grid, - to grid)                                                                               |
| `powerflowchannelpload`              | Number:Power             | Load Power (+ generator, - consumer)                                                                              |
| `powerflowchannelpakku`              | Number:Power             | Battery Power (+ discharge, - charge)                                                                             |
| `powerflowchannelppv`                | Number:Power             | Solar Power (+ production)                                                                                        |
| `powerflowautonomy`                  | Number:Dimensionless     | The current relative autonomy in %                                                                                |
| `powerflowselfconsumption`           | Number:Dimensionless     | The current relative self consumption in %                                                                        |
| `powerflowinverterpower`             | Number:Power             | Current power of the inverter, null if not running (+ produce/export, - consume/import)                           |
| `powerflowinvertersoc`               | Number:Dimensionless     | Current state of charge of the battery connected to the inverter in percent.                                      |
| `powerflowinverter1power`            | Number:Power             | Current power of inverter 1, null if not running (+ produce/export, - consume/import) - DEPRECATED                |
| `powerflowinverter1soc`              | Number:Dimensionless     | Current state of charge of inverter 1 in percent - DEPRECATED                                                     |

### `battery` Thing Channels

| Channel ID         | Item Type                | Description                            |
|--------------------|--------------------------|----------------------------------------|
| `maximumCapacity`  | Number:Energy            | Current maximum battery capacity in Wh |
| `designedCapacity` | Number:Energy            | Designed battery capacity in Wh        |
| `currentDc`        | Number:ElectricCurrent   | DC current                             |
| `voltageDc`        | Number:ElectricPotential | DC voltage                             |
| `soc`              | Number:Dimensionless     | State of charge in percent             |
| `status`           | String                   | Battery cell status code               |
| `enable`           | Number                   | Enable flag for the battery controller |
| `temperature`      | Number:Temperature       | Cell temperature                       |
| `timestamp`        | DateTime                 | Timestamp of the last measurement      |

### `meter` Thing Channels

| Channel ID              | Item Type                | Description                                                                                                                                                                                                              |
|-------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `enable`                | Number                   | 1 = enabled, 0 = disabled                                                                                                                                                                                                |
| `location`              | Number                   | 0 = grid interconnection point (primary meter)<br/> 1 = load (primary meter)   <br />3 = external generator (secondary meters)(multiple)<br />256-511 = subloads (secondary meters)(unique). Refer to Fronius Solar API. |
| `currentacphase1`       | Number:ElectricCurrent   | AC Current on Phase 1                                                                                                                                                                                                    |
| `currentacphase2`       | Number:ElectricCurrent   | AC Current on Phase 2                                                                                                                                                                                                    |
| `currentacphase3`       | Number:ElectricCurrent   | AC Current on Phase 3                                                                                                                                                                                                    |
| `voltageacphase1`       | Number:ElectricPotential | AC Voltage on Phase 1                                                                                                                                                                                                    |
| `voltageacphase2`       | Number:ElectricPotential | AC Voltage on Phase 2                                                                                                                                                                                                    |
| `voltageacphase3`       | Number:ElectricPotential | AC Voltage on Phase 3                                                                                                                                                                                                    |
| `powerrealphase1`       | Number:Power             | Real Power on Phase 1                                                                                                                                                                                                    |
| `powerrealphase2`       | Number:Power             | Real Power on Phase 2                                                                                                                                                                                                    |
| `powerrealphase3`       | Number:Power             | Real Power on Phase 3                                                                                                                                                                                                    |
| `powerrealsum`          | Number:Power             | Real Power summed up                                                                                                                                                                                                     |
| `powerfactorphase1`     | Number                   | Power Factor on Phase 1                                                                                                                                                                                                  |
| `powerfactorphase2`     | Number                   | Power Factor on Phase 2                                                                                                                                                                                                  |
| `powerfactorphase3`     | Number                   | Power Factor on Phase 3                                                                                                                                                                                                  |
| `energyrealsumconsumed` | Number:Energy            | Real Energy consumed                                                                                                                                                                                                     |
| `energyrealsumproduced` | Number:Energy            | Real Energy produced                                                                                                                                                                                                     |

### `ohmpilot` Thing Channels

| Channel ID              | Item Type          | Description                                                                                                                                                              |
|-------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `energyrealsumconsumed` | Number:Energy      | Real Energy consumed                                                                                                                                                     |
| `powerrealsum`          | Number:Power       | Real Power                                                                                                                                                               |
| `temperaturechannel1`   | Number:Temperature | Temperature                                                                                                                                                              |
| `errorcode`             | Number             | Device error code                                                                                                                                                        |
| `statecode`             | Number             | Device state code<br />`0` up and running <br />`1` keep minimum temperature <br />`2` legionella protection <br />`3` critical fault<br />`4` fault<br />`5` boost mode |

## Properties

### `battery` Thing Properties

| Property       | Description                      |
|----------------|----------------------------------|
| `vendor`       | The manufacturer of the battery  |
| `modelId`      | The model name of the battery    |
| `serialNumber` | The serial number of the battery |

### `meter` Thing Properties

| Property       | Description                    |
|----------------|--------------------------------|
| `modelId`      | The model name of the meter    |
| `serialNumber` | The serial number of the meter |

### `ohmpilot` Thing Properties

| Property       | Description                       |
|----------------|-----------------------------------|
| `modelId`      | The model name of the ohmpilot    |
| `serialNumber` | The serial number of the ohmpilot |

## Actions

:::warning
Battery control uses the battery management's time-dependent battery control settings of the inverter settings and therefore overrides user-specified time of use settings.
Please note that user-specified time of use plans cannot be used together with battery control, as battery control will override the user-specified time of use settings.
:::

The `powerinverter` Thing provides actions to control the battery charging and discharging behaviour of hybrid inverters, such as Symo Gen24 Plus, if username and password are provided in the bridge configuration.
The inverter must have the battery time of use plan settings available in the web interface.

You can retrieve the actions as follows:

:::: tabs

::: tab DSL

```java
val froniusInverterActions = getActions("fronius", "fronius:powerinverter:mybridge:myinverter")
```

:::

::: tab JS

```javascript
var froniusInverterActions = actions.thingActions('fronius', 'fronius:powerinverter:mybridge:myinverter');
```

:::

::: tab JRuby

In JRuby, the action methods are attached to the Thing object.

```rb
my_inverter = things["fronius:powerinverter:mybridge:myinverter"]

# call some actions
my_inverter.prevent_battery_charging
```

:::

::::

Where the first parameter must always be `fronius` and the second must be the full Thing UID of the inverter.

### Available Actions

Once the actions instance has been retrieved, you can invoke the following methods:

- `resetBatteryControl()`: Remove all battery control schedules from the inverter.
- `holdBatteryCharge()`: Prevent the battery from discharging (removes all battery control schedules first and applies all the time).
- `addHoldBatteryChargeSchedule(LocalTime from, LocalTime until)`: Add a schedule to prevent the battery from discharging in the specified time range.
- `addHoldBatteryChargeSchedule(ZonedDateTime from, ZonedDateTime until)`: Add a schedule to prevent the battery from discharging in the specified time range.
- `forceBatteryCharging(QuantityType<Power> power)`: Force the battery to charge with the specified power (removes all battery control schedules first and applies all the time).
- `addForcedBatteryChargingSchedule(LocalTime from, LocalTime until, QuantityType<Power> power)`: Add a schedule to force the battery to charge with the specified power in the specified time range.
- `addForcedBatteryChargingSchedule(ZonedDateTime from, ZonedDateTime until, QuantityType<Power> power)`: Add a schedule to force the battery to charge with the specified power in the specified time range.
- `preventBatteryCharging()`: Prevent the battery from charging (removes all battery control schedules first and applies all the time).
- `addPreventBatteryChargingSchedule(LocalTime from, LocalTime until)`: Add a schedule to prevent the battery from charging in the specified time range.
- `addPreventBatteryChargingSchedule(ZonedDateTime from, ZonedDateTime until)`: Add a schedule to prevent the battery from charging in the specified time range.
- `forceBatteryDischarging(QuantityType<Power> power)`: Force the battery to discharge with the specified power (removes all battery control schedules first and applies all the time).
- `addForcedBatteryDischargingSchedule(LocalTime from, LocalTime until, QuantityType<Power> power)`: Add a schedule to force the battery to discharge with the specified power in the specified time range.
- `addForcedBatteryDischargingSchedule(ZonedDateTime from, ZonedDateTime until, QuantityType<Power> power)`: Add a schedule to force the battery to discharge with the specified power in the specified time range.
- `addSchedule(LocalTime from, LocalTime until, ScheduleType scheduleType, QuantityType<Power> power)`: Add a custom schedule with the specified type and power in the specified time range.
- `addSchedule(ZonedDateTime from, ZonedDateTime until, ScheduleType scheduleType, QuantityType<Power> power)`: Add a custom schedule with the specified type and power in the specified time range.
- `setBackupReservedBatteryCapacity(int percent)`: Set the reserved battery capacity for backup power.
- `setBackupReservedBatteryCapacity(PercentType percent)`: Set the reserved battery capacity for backup power.

The `ScheduleType` enum has the following members:

- `CHARGE_MIN`
- `CHARGE_MAX`
- `DISCHARGE_MIN`
- `DISCHARGE_MAX`

Its full class name is `org.openhab.binding.fronius.internal.api.dto.inverter.batterycontrol.ScheduleType`.
You can also provide the name of the enum member as string and the binding will parse the enum member from it.

All methods return a boolean value indicating whether the action was successful.

### Examples

:::: tabs

::: tab JS

```javascript
var froniusInverterActions = actions.thingActions('fronius', 'fronius:powerinverter:mybridge:myinverter');

froniusInverterActions.resetBatteryControl();
froniusInverterActions.holdBatteryCharge();
froniusInverterActions.forceBatteryCharging(Quantity('5 kW'));

froniusInverterActions.resetBatteryControl();
froniusInverterActions.addHoldBatteryChargeSchedule(time.toZDT('18:00'), time.toZDT('22:00'));
froniusInverterActions.addForcedBatteryChargingSchedule(time.toZDT('22:00'), time.toZDT('23:59'), Quantity('5 kW'));
froniusInverterActions.addForcedBatteryChargingSchedule(time.toZDT('00:00'), time.toZDT('06:00'), Quantity('5 kW'));
froniusInverterActions.addForcedBatteryDischargingSchedule(time.toZDT('07:00'), time.toZDT('09:00'));
froniusInverterActions.addPreventBatteryChargingSchedule(time.toZDT('09:00'), time.toZDT('12:00'));

froniusInverterActions.addSchedule(time.toZDT('10:00'), time.toZDT('11:00'), 'DISCHARGE_MAX', Quantity('500 W'));

froniusInverterActions.setBackupReservedBatteryCapacity(50);
```

:::

::: tab JRuby

```rb
inverter = things["fronius:powerinverter:mybridge:myinverter"]

inverter.reset_battery_control
inverter.hold_battery_charge
inverter.force_battery_charging(5 | "kW")

inverter.reset_battery_control
inverter.add_hold_battery_charge_schedule(LocalTime.parse("18:00"), LocalTime.parse("22:00"))
inverter.add_forced_battery_charging_schedule(LocalTime.parse("22:00"), LocalTime.parse("23:59"), 5 | "kW")
inverter.add_forced_battery_charging_schedule(LocalTime.parse("00:00"), LocalTime.parse("06:00"), 5 | "kW")
inverter.add_forced_battery_discharging_schedule(LocalTime.parse("07:00"), LocalTime.parse("09:00"))
inverter.add_prevent_battery_charging_schedule(LocalTime.parse("09:00"), LocalTime.parse("12:00"))

inverter.add_schedule(LocalTime.parse("10:00"), LocalTime.parse("11:00"), 'DISCHARGE_MAX', 500 | "W")

inverter.set_backup_reserved_battery_capacity(50)
```

:::

::::

## Full Example

demo.things:

```java
Bridge fronius:bridge:mybridge [hostname="192.168.66.148", refreshInterval=5, username="customer", password="someSecretPassword", scheme="http"] {
    Thing powerinverter myinverter [deviceId=1]
    Thing battery mybattery [deviceId=0]
    Thing meter mymeter [deviceId=0]
    Thing ohmpilot myohmpilot [deviceId=0]
}
```

Please note that `username` and `password` are only required if you want to use battery control Thing actions.

demo.items:

```java
Number:Power AC_Power { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachannelpac" }
Number:Energy Day_Energy { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneldayenergy" }
Number:Energy Total_Energy { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneltotal" }
Number:Energy Year_Energy { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachannelyear" }
Number:Frequency FAC { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachannelfac" }
Number:ElectricCurrent IAC { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneliac" }
Number:ElectricCurrent IDC { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachannelidc" }
Number:ElectricPotential UAC { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneluac" }
Number:ElectricPotential UDC { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneludc" }
Number ErrorCode { channel="fronius:powerinverter:mybridge:myinverter:inverterdatadevicestatuserrorcode" }
Number StatusCode { channel="fronius:powerinverter:mybridge:myinverter:inverterdatadevicestatusstatuscode" }
Number:Power Grid_Power { channel="fronius:powerinverter:mybridge:myinverter:powerflowchannelpgrid" }
Number:Power Load_Power { channel="fronius:powerinverter:mybridge:myinverter:powerflowchannelpload" }
Number:Power Battery_Power { channel="fronius:powerinverter:mybridge:myinverter:powerflowchannelpakku" }
Number:Power Production_Power { channel="fronius:powerinverter:mybridge:myinverter:powerflowchannelppv" }
Number:Dimensionless Power_Autonomy { channel="fronius:powerinverter:mybridge:myinverter:powerflowautonomy" }
Number:Dimensionless Power_SelfConsumption { channel="fronius:powerinverter:mybridge:myinverter:powerflowselfconsumption" }
Number:Power Inverter1_Power { channel="fronius:powerinverter:mybridge:myinverter:powerflowinverter1power" }
Number:Dimensionless Inverter1_SOC { channel="fronius:powerinverter:mybridge:myinverter:powerflowinverter1soc" }

Number Meter_Enable { channel="fronius:meter:mybridge:mymeter:enable" }
Number Meter_Location { channel="fronius:meter:mybridge:mymeter:location" }
Number:ElectricCurrent Meter_CurrentPhase1 { channel="fronius:meter:mybridge:mymeter:currentacphase1" }
Number:ElectricCurrent Meter_CurrentPhase2 { channel="fronius:meter:mybridge:mymeter:currentacphase2" }
Number:ElectricCurrent Meter_CurrentPhase3 { channel="fronius:meter:mybridge:mymeter:currentacphase3" }
Number:Voltage Meter_VoltagePhase1 { channel="fronius:meter:mybridge:mymeter:voltageacphase1" }
Number:Voltage Meter_VoltagePhase2 { channel="fronius:meter:mybridge:mymeter:voltageacphase2" }
Number:Voltage Meter_VoltagePhase3 { channel="fronius:meter:mybridge:mymeter:voltageacphase3" }
Number:Power Meter_PowerPhase1 { channel="fronius:meter:mybridge:mymeter:powerrealphase1" }
Number:Power Meter_PowerPhase2 { channel="fronius:meter:mybridge:mymeter:powerrealphase2" }
Number:Power Meter_PowerPhase3 { channel="fronius:meter:mybridge:mymeter:powerrealphase3" }
Number:Power Meter_PowerSum    { channel="fronius:meter:mybridge:mymeter:powerrealsum" }
Number Meter_PowerFactorPhase1 { channel="fronius:meter:mybridge:mymeter:powerfactorphase1" }
Number Meter_PowerFactorPhase2 { channel="fronius:meter:mybridge:mymeter:powerfactorphase2" }
Number Meter_PowerFactorPhase3 { channel="fronius:meter:mybridge:mymeter:powerfactorphase3" }
Number:Energy Meter_EnergyConsumed { channel="fronius:meter:mybridge:mymeter:energyrealsumconsumed" }
Number:Energy Meter_EnergyProduced { channel="fronius:meter:mybridge:mymeter:energyrealsumproduced" }

Number:Energy Ohmpilot_EnergyConsumed { channel="fronius:ohmpilot:mybridge:myohmpilot:energyrealsumconsumed" }
Number:Power Ohmpilot_PowerSum { channel="fronius:ohmpilot:mybridge:myohmpilot:powerrealsum" }
Number:Temperature Ohmpilot_Temperature { channel="fronius:ohmpilot:mybridge:myohmpilot:temperaturechannel1" }
Number Ohmpilot_State { channel="fronius:ohmpilot:mybridge:myohmpilot:statecode" }
Number Ohmpilot_Errorcode { channel="fronius:ohmpilot:mybridge:myohmpilot:errorcode" }

Number:Energy Battery_MaxCapacity { channel="fronius:battery:mybridge:mybattery:maximumCapacity" }
Number:Energy Battery_DesignedCapacity { channel="fronius:battery:mybridge:mybattery:designedCapacity" }
Number:ElectricCurrent Battery_CurrentDC { channel="fronius:battery:mybridge:mybattery:currentDc" }
Number:ElectricPotential Battery_VoltageDC { channel="fronius:battery:mybridge:mybattery:voltageDc" }
Number:Dimensionless Battery_SOC { channel="fronius:battery:mybridge:mybattery:soc" }
Number:Temperature Battery_Temperature { channel="fronius:battery:mybridge:mybattery:temperature" }
DateTime Battery_Timestamp { channel="fronius:battery:mybridge:mybattery:timestamp" }
```

Note: Make sure to turn on the **Night Mode** in the Display Settings on the Fronius inverter to keep it from going offline at night.
