lg-therma-v-modbus

Read and control LG Therma V heat pumps over Modbus, as typed Python objects rather than register numbers. The Eastron SDM120 energy meter that is often wired onto the same RS-485 line is included.

The library maps the registers onto modbus-connection's device model: you hand it a ModbusUnit, call async_update(), and read sub-systems as attributes. It owns no connection and no I/O policy — the caller does.

Supported devices

ThermaV — the heat pump. Every register LG's Modbus register list documents: 17 discrete inputs, 6 coils, input registers 30001 to 30025 and 30037 to 30046, holding registers 40001 to 40010 and 40024, and the two product registers 39998 and 39999. They are split into sub-systems that are read separately, so a block a product refuses cannot take the others with it.

Two heating circuits exist. Each has a target temperature, a room air temperature and an auto-mode shift. The operation mode and the control method (which sensor the target is held against) apply to both.

Products from December 2023

Products from before December 2023 do not have the energy counters (input registers 30037 to 30046) and the compressor modulation (holding register 40024), and refuse a read of them. They are therefore left alone unless you say the product is newer:

heat_pump = ThermaV(unit, from_december_2023=True)

Without it energy_counters and compressor_modulation are None, and a poll never asks for their registers. With it they are polled like the rest; a product that turns out not to have them lists them in the report's failed.

The compressor modulation is 0 (not used) or 40 to 100. Any other value raises ValueError before anything is written.

Sdm120 — the meter. An Eastron SDM120 single-phase energy meter, read over its input registers as IEEE-754 floats: voltage (V), active_power (W) and total_energy (kWh). It is a different unit on the same line, so it takes its own ModbusUnit.

Usage

import asyncio

from modbus_connection import ModbusSerialParams
from modbus_connection.tmodbus import ModbusConnection
from lg_therma_v_modbus import OperationMode, Sdm120, ThermaV


async def main() -> None:
    connection = ModbusConnection(ModbusSerialParams(device="/dev/ttyUSB0"))
    try:
        heat_pump = ThermaV(connection.for_unit(1))
        meter = Sdm120(connection.for_unit(2))

        await heat_pump.async_update()
        await meter.async_update()

        print("Outside:", heat_pump.readings.outside_air_temperature, "°C")
        print("Flow:", heat_pump.readings.flow_rate, "l/min")
        print("Compressor running:", heat_pump.status.compressor)
        print("Mode:", heat_pump.settings.operation_mode)
        print("Pressure:", heat_pump.water_pressure.water_pressure, "bar")
        print("Power:", meter.readings.active_power, "W")

        await heat_pump.settings.write("dhw_target_temperature", 48.0)
        await heat_pump.settings.write("operation_mode", OperationMode.AUTO)
        await heat_pump.controls.write("silent_mode", True)
    finally:
        await connection.close()


asyncio.run(main())

A poll reads each sub-system independently: one slow or refused block does not take the rest of the poll with it. Every update method returns an UpdateReport — a failed component keeps its previous values, does not notify its listeners, and is listed by attribute name with its error, while every other component refreshes and notifies once the whole poll is done. A dead link (ModbusConnectionError) raises, and so does a timeout before any component has answered.

report = await heat_pump.async_update()
for name, error in report.failed.items():
    print(f"{name} kept its previous values: {error}")

ThermaV splits its poll by what it reads:

• async_update_readings() — what the heat pump reports: status, readings, water_pressure, refrigerant_cycle and, if enabled, energy_counters.
• async_update_settings() — what it has been told: controls, settings and, if enabled, compressor_modulation. Run one after a write to read back what took effect.
• async_update() — both, in one merged report.

Writing is by field name through the component: await heat_pump.controls.write( "silent_mode", True). Only the fields of controls, settings and compressor_modulation are writable; writing a reading raises AttributeError.

trigger_dhw_disinfection and trigger_emergency_operation are one-shot triggers: write True to start the operation. The heat pump keeps its status when they are cleared, so they are not states to read back; status reports what is running (dhw_tank_disinfection, emergency_operation_available_*).

How the Therma V wants to be talked to

The heat pump is picky about its Modbus master. Four things matter.

• It answers from the third request. On a fresh link its first requests go unanswered, and they must be aimed at an input register or a coil. The first poll of a ThermaV therefore starts with three reads of input register 0. An unanswered one is expected and does not fail the poll; a dead link still does. This happens once per object, so build a new ThermaV after a reconnect that should warm up again.
• Never stop polling. After five minutes without a request the heat pump shows the error CH 03, and only cutting its power clears it. A caller that starts polling has to keep going. A bridge that polls on its own behalf keeps the heat pump out of that state when the caller is down.
• Poll at a moderate pace. Neither very fast nor very slow polling stays error-free for long. A request spacing of about 100 ms suits a USB adapter and about 30 ms a network bridge; set it on the unit with unit.set_message_spacing().
• Do not read large ranges. The library reads each sub-system as a single small block (at most 17 addresses), which is what the heat pump tolerates. It never reads across the registers LG leaves blank (30015, 30016).

The unit ID is the one set on the heat pump's control panel under Connectivity > Modbus address.

Naming the link

How to name the link depends on what sits between you and the RS-485 line, not on the heat pump:

The heat pump speaks 9600 baud, 8 data bits, no parity and one stop bit, which are the defaults of ModbusSerialParams. ASCII framing is unsupported.

Register reference

Register numbers are LG's; the Modbus address is the number without its leading digit, minus one (30003 is input address 2). LG's installation manual labels the input and holding registers the wrong way round; the tables below are the corrected ones, and what the heat pump answers.

Coils (writable)

Discrete inputs (status)

Input registers

The registers from 30037 on are from December 2023 or later, except 39998 and 39999.

Holding registers (writable)

The energy states are 0 not used, 1 forced off, 2 normal operation, 3 on recommendation, 4 on command, 5 on command step 2, 6 on recommendation step 1, 7 power saving and 8 super power saving. 1 to 4 are the SG Ready states of the terminal block contacts TB_SG1 and TB_SG2.

Where the sources disagree

The names are LG's own English register list. Where the community documentation differs, this is what was decided:

• Pressures. LG gives 30023 and 30024 in mBar. On a 9 kW monobloc those values only make sense at 0.01 bar per step, so that is the scale. Check it against your own heat pump.
• 30022. LG leaves it unnamed. The community documentation calls it the vapor temperature after the evaporator, which is where the name comes from.
• 30018. The community table omits it; LG lists it as "Pipe out temp".
• Product registers. The community table lists the product information as holding register 49999. LG lists 39998 and 39999 under the input registers, as does a working configuration, so those are the ones read.
• Energy counters. The names are LG's constants, which call two of the values "instantaneous" yet give all of them in Wh. Treat the instantaneous ones with care.
• Not modelled. Input register 30036, which another project reads as the internal power, is in no register list found. Registers 40025 and coil 00007, a power limit, appear in one configuration only and not in any register list.

Checking a real device

script/query.py reads one device once and prints every value it serves, which is the quickest way to see whether it is reachable and addressed correctly:

# a USB or serial adapter, heat pump on unit 1
uv run script/query.py /dev/ttyUSB0 --transport serial --unit 1
# the meter on the same line
uv run script/query.py /dev/ttyUSB0 --transport serial --unit 2 --meter
# a box forwarding RTU frames over TCP
uv run script/query.py socket://192.168.1.50:8899 --transport serial --unit 1
# a gateway answering Modbus TCP
uv run script/query.py 192.168.1.60 --port 502 --unit 1

It prints the number of Modbus reads and how long they took. --raw adds every register read, undecoded, which is what an issue about a wrong value should quote.

Development

uv sync
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest

The tests run against modbus-connection's in-memory mock, so no hardware is needed. See RELEASING.md for publishing a version.