Fronius plugin

Reads a Fronius inverter (GEN24, Tauro, Verto, Symo, Primo) or Datamanager over its local Solar API v1 and brings its values into Nexus as sensors. Values flow one way only, from the inverter to Nexus: the plugin is read-only.

What it does

• Sensors: PV, grid, load and battery power, autonomy and self-consumption, energy counters, smart meter readings (power, voltage, current, frequency, energy), battery charge and temperature, and Ohm Pilot values, polled every few seconds.
• Catalog: the site, each inverter, meter, battery and Ohm Pilot the installation reports, with every value ready to add.
• Panel: current PV, grid, load and battery power, battery charge and autonomy as tiles, whether the inverter can be read (green or red), the time of the last successful poll and the last error. It refreshes after every poll.

Before you start

• A Fronius inverter or Datamanager that Nexus can reach over HTTP on your network, and its address (IP or host name).
• The Solar API switched on. On GEN24, Tauro and Verto it is in the inverter's web interface under Communication, Solar API ("Activate communication via Solar API"); it is off by default there.
• No account or password: the Solar API has no login.

Configuration

Nothing is secret: the Solar API has no authentication.

Sensors and actuators

The plugin has no actuators: the Solar API v1 can't write anything.

Good to know

• Add values from the catalog instead of typing a data path. The catalog fills in the path, a readable name and the unit.
• The catalog is empty until the first successful poll, and lists only what this installation reports: no meter or battery, no meter or battery entries.
• PV power is null while the inverter sleeps at night. Many inverters stop answering then altogether: the instance shows degraded with the reason and goes back to running with the next successful poll. Sensors keep their last value in between.
• An unreachable inverter never fails the start, and a night-long outage is one status change and one log line, not one per poll.
• On GEN24, Tauro and Verto the daily and yearly energy counters (E_Day, E_Year) are always null; E_Total is updated only every 5 minutes.

More

The full reference (the value sensor's params, common data paths with units, the catalog tree, panel fields, status and error messages, limits, what was fixed compared to the old integration, and development notes) is in REFERENCE.md next to this file, and on the plugin's page in the Nexus documentation.

How polling works

Every poll reads three Solar API v1 endpoints in parallel (below solar_api/v1/ of the configured address):

The first poll runs right after the start without holding it up; after that the plugin polls every pollInterval seconds. A poll that is due while one is still running joins it instead of starting a second one. A successful poll keeps the result as the latest snapshot, which the sensors, the catalog and the panel read. When the power flow can't be read, the previous snapshot stays and the meter and storage results of that poll are ignored.

Test connection in the settings form reads the power flow once and says how many inverters answered and the PV power.

Sensor value

One value of the poll data, value type any.

Most users never type the path: adding a value from the catalog fills it in.

• Numbers, strings, booleans and null pass through as the matching value. null means the component is inactive, e.g. PV power at night.
• The sensor emits after every successful poll (the bus drops repeats), and once when it is added if data is already there.
• A new value warns that it is stale after 5 minutes without a successful poll (Warn when no value for in the signal's form); with a long poll interval, raise it to a few intervals.
• A path that doesn't resolve, or that points to an object or a list, emits nothing. The device behind it may be missing, or its endpoint failed this time; the sensor keeps its last value.
• Device ids are the keys the inverter uses, written as plain path segments (meter.0.…). Inverters usually start at 1. Meters and batteries often start at 0, but not always: one GEN24 reports its grid meter as 2 and a secondary meter as 3. The catalog shows the ids your installation uses.

Common paths

Catalog

The catalog is built from the latest successful poll and lists only what this installation reports. Before the first successful poll it is empty.

• Each entry is a ready-to-add value sensor with a readable suggested name (P_PV is PV power, meter phases are L1 to L3), its current value and, where the field has one, its unit (W, Wh, VA, var, V, A, Hz, %, °C).
• A secondary meter (e.g. one for a second PV inverter) is named after the label the installer gave it, e.g. Meter 3 (Solax) with entries such as Solax power, instead of after its model.
• Fields that are null are left out, because they mean the component is missing (no meter, no battery). The exceptions are PV power and inverter AC power, which are only null while the inverter sleeps.
• Nodes without any usable field are left out.

Panel

Two sections. The page refreshes after every poll (and when reading starts or stops failing) instead of asking every few seconds.

Power flow, as tiles at the top of the page:

Inverter:

Meter and battery endpoint failures don't appear in the panel; they are in the log.

Debug log

With Debug for 15 min on the instance's log card, the log also gets a line per poll: how long it took and the outcome of the power flow, meter and storage endpoints.

Status and errors

• The instance is degraded with the reason while the power flow can't be read, and goes back to running with the next successful poll. Reasons name the endpoint and what went wrong, e.g. GetPowerFlowRealtimeData: HTTP 503, … no answer within 5 s, … unreachable (connect ECONNREFUSED …), … device answered with status 255 (…), … expected JSON, got text/html: "…" or … unexpected response: ….
• Only changes are reported, so a night-long outage is one status change and one log line.
• An unreachable inverter never fails the start. The instance starts and stays degraded until the inverter answers.
• A failing meter or storage endpoint only writes a log line (once, and again on recovery). The values of that part stay unchanged until it answers again. While the power flow fails too, meter and storage failures aren't reported, since they say nothing about those devices.

Fixed compared to the old integration

• Polls no longer overlap: a poll that is due while one is still running joins it.
• Every request has a timeout.
• Responses are parsed as JSON whatever their content type says (older Datamanager devices send text/javascript); a body that isn't JSON is reported with its content type.
• Device id 0 is a device.
• Failures show up as the instance status.
• A missing meter or battery no longer fails the whole poll.

Known limitations

• Read-only: the Solar API v1 has no write access. Battery or export control (Modbus) is not supported.
• No per-device scope for polling: the plugin always reads the whole system (Scope=System). The client supports Scope=Device (SolarApi.meter(id), SolarApi.storage(id)).
• GetInverterRealtimeData (DC voltages and currents per string) and the archive endpoints aren't polled.
• Each request opens a new connection (Connection: close), so nothing outlives a stop. At poll intervals of seconds this costs nothing worth keeping a socket for.

Development

npm test                                      # from the repo root; tests live next to the code in src/
npm run build -w @lox-nexus/plugin-fronius    # dist/plugin.js, one ESM bundle (esbuild)

Tests run against a local fixture server. The fixtures in test/fixtures/ are partly recorded from two real GEN24 inverters (one with a grid meter and a secondary meter labelled "Solax", one with a BYD battery and an Ohm Pilot; serial numbers replaced) and partly synthesized from the Solar API v1 documentation to cover what those installations don't have (a missing meter, device errors). The fixtures' own README lists every file.