SunSpec Model 123 — Immediate Controls
SunSpec Model 123 is a standardized inverter control model defined by the SunSpec Alliance for grid-connected distributed energy resources. This Modbus TCP template targets the Immediate Controls block used by SMA, Fronius, Kostal, and other SunSpec-certified inverters. It exposes grid connection control (conn), active power limiting (wmaxlimpct and wmaxlim_ena), fixed power factor (outpfset and outpfset_ena), and reactive power setpoints (varwmaxpct, varmaxpct, varavalpct, varpct_ena) together with their time-window, reversion, and ramp registers. Importing this template into ModbusCloud gives installers a ready-made interface to read and write Model 123 controls across any compliant device without manual register mapping.
- Protocol
- Modbus TCP
- Connection
- Ethernet, Modbus TCP
- Registers
- 26, read and write
- Brand
- SunSpec
- Last updated
Registers (26)
26 read, 21 write
| Name | Unit | Access | Address (Hidden until you enter your email) | Function (hidden) | Type (hidden) |
|---|---|---|---|---|---|
| id | Read | ||||
| l | Read | ||||
| conn_wintms | Secs | Read and write | |||
| conn_rvrttms | Secs | Read and write | |||
| conn | Read and write | ||||
| wmaxlimpct | % WMax | Read and write | |||
| wmaxlimpct_wintms | Secs | Read and write | |||
| wmaxlimpct_rvrttms | Secs | Read and write | |||
| wmaxlimpct_rmptms | Secs | Read and write | |||
| wmaxlim_ena | Read and write | ||||
| outpfset | cos() | Read and write | |||
| outpfset_wintms | Secs | Read and write | |||
| outpfset_rvrttms | Secs | Read and write | |||
| outpfset_rmptms | Secs | Read and write | |||
| outpfset_ena | Read and write | ||||
| varwmaxpct | % WMax | Read and write | |||
| varmaxpct | % VArMax | Read and write | |||
| varavalpct | % VArAval | Read and write | |||
| varpct_wintms | Secs | Read and write | |||
| varpct_rvrttms | Secs | Read and write | |||
| varpct_rmptms | Secs | Read and write | |||
| varpct_mod | Read and write | ||||
| varpct_ena | Read and write | ||||
| wmaxlimpct_sf | Read | ||||
| outpfset_sf | Read | ||||
| varpct_sf | Read |
Loading registers…
Send your device list
If a device is not in the library yet, we build the template for free as soon as we have the register data.
Use cases
- Monitor active power limit setpoint (wmaxlimpct) to verify curtailment commands are applied as dispatched by a DSO or EMS.
- Track power factor setpoint (outpfset) over time to confirm reactive power compliance with local grid code requirements.
- Alert when the grid connection register (conn) changes unexpectedly, indicating an unplanned inverter disconnect event.
- Compare wmaxlimpct reversion timeout (wmaxlimpct_rvrttms) readings against scheduled curtailment windows to detect missed reversion events.
- Verify reactive power mode (varpct_mod) and enable status (varpct_ena) after firmware updates to ensure control settings were preserved.
Installation
Enable Modbus TCP on the inverter or gateway under the communication or Modbus section of its web interface, and confirm the SunSpec profile is active and byte order is set to big-endian.
Connect the inverter or Modbus gateway to the same LAN segment as the ModbusCloud Gateway, ensuring TCP port 502 is reachable from the Gateway's IP address.
In the ModbusCloud portal, add the device, import the SunSpec Model 123 template, and enter the correct unit ID for your inverter (consult the device's commissioning tool to identify the assigned unit ID).
Spot-check the id register (address 0) in the portal's live register view: it must read 123 to confirm you are polling the correct model block on the device.
Things to watch for
The id register reads a value other than 123. Why?
The SunSpec register map is self-describing and chained: Model 123 is not always at a fixed absolute address. The absolute Modbus address of the model block depends on which models precede it in the chain. Use a SunSpec model discovery scan or consult the device's PICS table to find the correct starting address, then update the template offset in the portal.
I wrote wmaxlimpct but inverter output did not change. What now?
Writing the setpoint register alone is not sufficient. The wmaxlim_ena register must be written to enable the throttle function after the setpoint is set. Control values do not take effect until the associated enable register is written. Confirm wmaxlim_ena is set to the enabled enumeration value after updating wmaxlimpct.
Scaled register values look wrong by a factor of 10 or 100. How do I fix this?
SunSpec uses scale-factor registers (wmaxlimpct_sf, outpfset_sf, varpct_sf) that store a signed exponent applied as a power of ten. If these scale factors return a non-zero value, the raw register value must be multiplied by 10 raised to that exponent. Ensure your ModbusCloud template read them and applies scaling before displaying or comparing values.
The gateway connects but write registers return no response or an error. What should I check?
Several inverter manufacturers protect Model 123 write registers behind an unlock code or restrict writes to a single Modbus client at a time. Check whether another client such as an EMS or data logger already holds an exclusive session. Also verify that write registers (conn, wmaxlimpct, outpfset, var setpoints, and their enable flags) are within the device's stated supported range, as writing an unsupported value returns a Modbus exception 3. Use write registers with caution: issuing a disconnect (conn = 0) or an extreme power limit can affect inverter output and may invalidate grid-operator agreements.
Knowledge base articles for this device
SunSpec Modbus: one register map for many inverters
SunSpec Modbus is the open register map SMA, Fronius, SolarEdge and Kostal share. The layout, int+SF vs float, the TCP port per brand and reading a mixed fleet.
Fronius Modbus: read a Symo GEN24 over Modbus TCP
Fronius Modbus explained: enable Modbus TCP on the Symo GEN24 on port 502, choose between int+SF and float, read the right SunSpec registers and scale them correctly. Practical guide for solar installers.
SMA Modbus: reading a Sunny Boy over Modbus TCP (installers)
SMA Modbus explained: enable the Modbus TCP server on port 502, choose between the SMA profile (unit ID 3) and SunSpec (unit ID 126), read the right registers, and handle the NaN values at night. Practical guide for installers.
Want to see how it works?
