SunSpec Models Explained

SunSpec models explained

A SunSpec device publishes its data as a chain of numbered blocks, called models. The SunSpec Alliance fixes the layout of each one, so block 103 on a KACO holds the same points as block 103 on a Fronius. The integration walks the chain once, remembers which blocks the device has, and polls the ones you ticked in the options.

This page says what the numbers mean. The options form shows the same labels with the number in brackets.

Which blocks your inverter has

The detected_models array in the diagnostics download. Not scanned_models, which only lists what is being polled: which data blocks does my inverter actually have?

The blocks

Ticked by default means the setup and options forms preselect the block when the device has it. Everything else you tick yourself.

Every device

Block	Name	Holds	Default
1	Common	Manufacturer, model, serial number, firmware version	Read once for the device card. Never a sensor

Inverters

Block	Name	Holds	Default
101 / 102 / 103	Inverter, single / split / three phase	AC power, current and voltage per phase, frequency, power factor, lifetime energy, DC current, voltage and power, temperatures, operating state, event flags. Integers with scale factors	ticked
111 / 112 / 113	The same as floating point	Same points, different encoding. Some inverters let you choose, Fronius among them; a Kostal serves both at once	ticked where the device has no integer twin, see below
160	MPPT	Current, voltage, power and temperature per DC input. One group entry per string input	ticked
120	Nameplate	Rated AC power, apparent power, current, lifetime energy rating	Read once for the plausibility filter. Not ticked
121	Basic settings	The configured maximum power WMax, the voltage reference	Fallback for the plausibility filter. Not ticked
122	Measurements and status	Extended status: connection state, islanding, counters	not ticked

Controls

These are never in the sensor list; their writable points become Number, Switch and Select entities instead, and their other points stay read-only sensors. Block 124 is polled and built whenever the inverter reports a battery, no option to tick. Blocks 123 and 704 need Enable experimental export controls (BETA) in the options. Battery and export control lists the entities; Fronius, SolarEdge and SMA also add their own, see Vendor notes.

Block	Name	Holds	Gated by the export beta
123	Immediate controls	Export limit in percent with its timers, power factor setpoint, grid connection	yes
124	Storage	Battery charge and discharge rate, control mode, reserve, and read-only: available energy ChaState, charge status, storage availability	no
704	DER AC controls	The modern replacement for 123, with an absolute watt setpoint and a revert value. Used instead of 123 where both exist	yes

Meters

Block	Name	Holds	Default
201 / 202 / 203 / 204	Meter, single phase / split phase / three phase wye / three phase delta	Power, current, voltage and power factor per phase, frequency, energy imported and exported	ticked
211 / 212 / 213 / 214	The same as floating point		ticked where the device has no integer twin

A meter connected to the inverter usually answers at its own unit ID on the same IP. Add it as a second config entry; Vendor notes has the IDs.

Environment

Block	Name	Default
302	Irradiance	not ticked
307	Base meteorological	ticked
308	Mini meteorological	ticked

Strings, modules, trackers

Block	Name	Default
401 / 402 / 403 / 404	String combiners	ticked
501 / 502	Solar module with DC-DC converter	ticked
601	Tracker controller	ticked

DER, the 700 family

Newer devices publish these instead of the 100 family. An SMA Tripower X is one example.

Block	Name	Holds	Default
701	DER AC measurement	The AC side, like 103	ticked
702	DER capacity	Ratings	not ticked
703	Enter service	Reconnection envelope	not ticked, never writable
704	DER AC controls	see Controls
705 / 706 / 711 / 712	Volt-Var, Volt-Watt, frequency droop, Watt-Var curves	Grid support curves	not ticked, never writable
713	DER storage capacity		not ticked
714	DER DC measurement	The DC side, like 160	not ticked

Block 701 has a point called St, but it means 0 OFF / 1 ON and not the operating state of block 103. A device that only has 701 therefore cannot tell the integration that it is going to sleep. Switch on Inverter powers down when idle for those.

Batteries

Block	Name	Holds	Default
801	Energy storage base	Deprecated by SunSpec	ticked
802	Battery base	State of charge, state of health, power, voltage, current, cycle count, capacity rating, events	ticked
803 / 804 / 805	Lithium-ion bank / string / module	Cell voltages, temperatures per level	ticked
806 / 808 / 809	Flow battery, module, stack		ticked
807	Flow battery string		not ticked

Not every inverter with a battery publishes block 802. SolarEdge keeps battery data in vendor registers outside SunSpec, and Fronius publishes block 124 only while a battery is connected.

Vendor blocks

Ids from 64000 upwards are manufacturer-defined. The integration reads them like any other block. Points whose label is missing from the definition show their raw SunSpec name instead of a readable one.

Integer and float encodings

The 100 and 200 families exist twice. The original blocks store every value as an integer plus a scale factor point (W_SF for W): a reading of 4312 with scale factor -1 means 431.2. The float variants (111 to 113, 211 to 214) store IEEE floats and need no scale factors.

The integration decodes both, and ticks whichever half a device actually serves. Where it serves both, the integer half wins and the float twin is left unticked, because the block id is part of an entity's unique id: ticking both would build a second sensor for every reading, same value, different number.

Which halves a device has is not the same question for every brand. Fronius calls it SunSpec Model Type and offers int + SF or float, one at a time; pick int + SF, it is what most tools expect. A Kostal publishes 103 and 113 together and needs no choice made. If your device only has the float half, it is ticked for you.

Both halves are in the model list in the options either way, so you can swap one for the other. Doing so is a new set of entity ids and starts the recorder history over.

The definitions

The model definitions ship with the integration under pysunspec2/models/json/, one file per block, and are refreshed from sunspec/models every second month. Each point has a desc with the official description, which is the place to look when a sensor name is not self-explanatory.