{"id":13060,"date":"2026-09-18T07:35:00","date_gmt":"2026-09-18T05:35:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=13060"},"modified":"2026-08-31T15:15:29","modified_gmt":"2026-08-31T13:15:29","slug":"tutorial-reading-sunspec-registers-from-a-pv-inverter-over-modbus-tcp","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/smart-home\/tutorials-en-smart-home\/tutorial-reading-sunspec-registers-from-a-pv-inverter-over-modbus-tcp\/","title":{"rendered":"Tutorial: Reading SunSpec Registers From a PV Inverter Over Modbus TCP"},"content":{"rendered":"

A register number found in a forum post works. It works until a firmware update, until the next model of the same inverter, until a second device joins that stores the same value somewhere else. Then the number is wrong, and nothing says so: Modbus returns whatever is at that address, and a plausible number is indistinguishable from a correct one.<\/p>\n

SunSpec exists for this reason. It is a directory laid over the register space, and reading it takes four steps that work identically on every inverter that implements it.<\/p>\n

\n\"A
The chain is self-describing: every model states its own length, so the address of the next one follows from the current one. Only the starting point has to be found.<\/figcaption><\/figure>\n

Why a Register Number Alone Is Not Enough<\/h2>\n

Modbus has no notion of names, units or types. A read returns sixteen bits, and every interpretation of those bits happens in the reader. A register holding 1234 might be 1234 watts, 123.4 volts or 12.34 amperes, and the protocol has nothing to say about which.<\/p>\n

SunSpec adds three things on top of that, and all three are stored in the register space itself: a marker that says the map is present, a chain of blocks that says which measurements exist and where, and per group of values a scale factor that says where the decimal point goes.<\/p>\n

The practical consequence is that a reader written once works on the next device too. That is worth more than it sounds, because the alternative – a table of addresses per manufacturer and firmware version – is exactly the thing that quietly goes out of date.<\/p>\n

Finding the Base Address and the Marker<\/h2>\n

The map begins at one of three addresses, and the first two registers say whether it does. They hold the four characters SunS<\/code>, which as a 32-bit value is 0x53756E53.<\/p>\n

from pymodbus.client import ModbusTcpClient\n\nc = ModbusTcpClient(\"192.168.1.50\", port=502)\nc.connect()\n\nfor basis in (40000, 0, 50000):\n    r = c.read_holding_registers(basis, count=2, slave=1)\n    if not r.isError() and r.registers == [0x5375, 0x6E53]:\n        print(\"SunSpec at\", basis)\n        break<\/code><\/pre>\n
Two stumbling blocks live in that short piece of code. The first is the off-by-one that catches everybody once: documentation numbers registers from one, the protocol addresses them from zero. An address printed as 40001 in a manual is offset 40000 on the wire, and reading at 40001 returns the second half of the marker and no match.<\/p>\n
The second is the unit id. An inverter with a built-in smart meter answers as two devices on the same connection, each with its own id and its own SunSpec map. Reading the meter’s power from the inverter’s id gives a value that is not an error and not the truth. Which ids are in use is shown in the Modbus page of the device’s own web interface – and that page is also where Modbus TCP has to be switched on in the first place, because it is off by default on most inverters.<\/p>\n
Walking the Model Chain<\/h2>\n
After the marker comes a sequence of blocks, and each block begins with two registers: its model number and its length. Adding the length to the current position gives the start of the next block, and a model number of 65535 ends the chain.<\/p>\n
pos = basis + 2\nwhile True:\n    kopf = c.read_holding_registers(pos, count=2, slave=1).registers\n    modell, laenge = kopf[0], kopf[1]\n    if modell == 0xFFFF:\n        break\n    print(f\"model {modell:5d}  length {laenge:3d}  data at {pos + 2}\")\n    pos += 2 + laenge<\/code><\/pre>\n
A typical inverter answers with three or four models, and the numbers say what each of them is.<\/p>\n\n\n\n\n\n\n\n\n\n
Model<\/th>\nContent<\/th>\n<\/tr>\n<\/thead>\n
1<\/td>\nCommon: manufacturer, model designation, serial number, firmware version<\/td>\n<\/tr>\n
101, 102, 103<\/td>\nInverter, single phase, split phase, three phase – integers with scale factors<\/td>\n<\/tr>\n
111, 112, 113<\/td>\nThe same measurements as floating point numbers, without scale factors<\/td>\n<\/tr>\n
160<\/td>\nThe individual strings, one repeating block per MPP tracker<\/td>\n<\/tr>\n
201 to 204<\/td>\nMeter, one model per wiring type<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Whether a device offers 103 or 113 is usually a setting rather than a property. Many inverters have a switch between integer with scale factors and floating point, and it decides which of the two model families appears in the chain. A reader that expects one and finds the other reports no measurements at all, which is a confusing symptom for a setting nobody remembers changing.<\/p>\n
Scale Factors, Data Types and the Sentinels<\/h2>\n
Inside a model block, the position of a value is fixed by the specification and counted from the start of the data. The phase A current sits at offset 2, and the scale factor that belongs to it at offset 5.<\/p>\n
Model 103, data starting at 40071\n\n  offset 1   A      uint16   total current\n  offset 2   AphA   uint16   phase A\n  offset 3   AphB   uint16   phase B\n  offset 4   AphC   uint16   phase C\n  offset 5   A_SF   int16    scale factor for all four\n\n  40072 = 1234        raw value\n  40075 = 0xFFFE      two's complement, so \u22122\n\n  1234 \u00d7 10\u207b\u00b2 = 12.34 A<\/code><\/pre>\n
The scale factor is a signed exponent to base ten and applies to a whole group of values, not to one. That is why it appears once for four currents, and why reading a current without it produces a number a hundred times too large – which on a domestic system still looks like a plausible reading.<\/p>\n
Three more properties of the encoding matter in practice. Values spanning two registers are big-endian with the high word first, which is the Modbus convention and which almost every library gets right by default. Text fields are fixed-length and padded with null bytes rather than terminated by them. And a value that the device does not implement is not zero but a sentinel: 0x8000 for int16, 0xFFFF for uint16, 0x80000000 for int32. A reader that treats those as numbers reports 65535 volts, and a rule that discards them is three lines long.<\/p>\n
LEER = {\"int16\": 0x8000, \"uint16\": 0xFFFF,\n        \"int32\": 0x80000000, \"uint32\": 0xFFFFFFFF}\n\ndef wert(roh, typ, sf):\n    if roh == LEER.get(typ):\n        return None\n    return roh * (10 ** sf)<\/code><\/pre>\n
Reading One Value End to End<\/h2>\n
The pieces together give a reader that finds the model rather than assuming its address.<\/p>\n
def modell_finden(c, basis, gesucht, slave=1):\n    pos = basis + 2\n    while True:\n        m, laenge = c.read_holding_registers(pos, count=2, slave=slave).registers\n        if m == 0xFFFF:\n            return None\n        if m == gesucht:\n            return pos + 2, laenge\n        pos += 2 + laenge\n\ndef vorzeichen(r):\n    return r - 0x10000 if r > 0x7FFF else r\n\nstart, _ = modell_finden(c, 40000, 103)\nblock    = c.read_holding_registers(start, count=6, slave=1).registers\n\nstrom = block[1]                 # AphA, offset 2 counted from one\nsf    = vorzeichen(block[4])     # A_SF, offset 5\nprint(f\"{strom * 10 ** sf:.2f} A\")<\/code><\/pre>\n
Worth reading the whole block in one request rather than each value on its own. A Modbus read takes a few milliseconds of round trip regardless of length, so six registers in one call cost what one register in one call costs – and, more importantly, all six values then come from the same moment. Six separate reads of a current, a voltage and a power give three quantities that do not multiply together, and a plausibility check built on them fails for no reason.<\/p>\n
A note on polling frequency: an inverter is not a database. A request every five seconds is unproblematic, once a second is at the limit on some devices, and faster than that produces timeouts that look like network faults. The measured values themselves rarely update faster than every second anyway.<\/p>\n
Putting It into Home Assistant<\/h2>\n
With the addresses known, the same reading works declaratively. Home Assistant’s Modbus integration handles the data type and the sign; only the scale factor has to be entered as a number, because the integration does not read it from the device.<\/p>\n
modbus:\n  - name: wechselrichter\n    type: tcp\n    host: 192.168.1.50\n    port: 502\n    sensors:\n      - name: \"Strom Phase A\"\n        slave: 1\n        address: 40072\n        data_type: uint16\n        scale: 0.01\n        precision: 2\n        unit_of_measurement: \"A\"\n        device_class: current\n        state_class: measurement\n        scan_interval: 10\n      - name: \"Wirkleistung\"\n        slave: 1\n        address: 40084\n        data_type: int16\n        scale: 1\n        precision: 0\n        unit_of_measurement: \"W\"\n        device_class: power\n        state_class: measurement\n        scan_interval: 10<\/code><\/pre>\n
The hard-coded scale<\/code> is the compromise in this approach, and it is worth noting where it comes from. The scale factor was read once with the script above; it is stored in the device and practically never changes, but it is not guaranteed. After a firmware update, one comparison between the displayed value and the inverter’s own screen takes ten seconds and catches a factor of a hundred immediately.<\/p>\n
One last field decides whether the value ends up in the energy statistics rather than only on a card. A power reading in watts is device_class: power<\/code> with state_class: measurement<\/code>; a meter reading in kilowatt-hours is device_class: energy<\/code> with state_class: total_increasing<\/code>. The two are not interchangeable, and only the second can be selected as an energy source.<\/p>\n
\n
Sources<\/h2>\n