Skip to content
This repository was archived by the owner on Apr 12, 2026. It is now read-only.

quickstart.md

Latest commit

 

History

History
98 lines (64 loc) · 2.6 KB

quickstart.md

File metadata and controls

98 lines (64 loc) · 2.6 KB

Quick Start

Get luxtronik2-modbus-proxy running from source in under 15 minutes.

Prerequisites

  • Python 3.10 or newer
  • pip (comes with Python)
  • git
  • Docker (optional, for the Docker track in Docker Alternative)

Clone and Install

git clone https://github.com/OWNER/PUBLIC-luxtronik2-modbus-proxy.git
cd PUBLIC-luxtronik2-modbus-proxy
pip install -e ".[dev]"

The [dev] extra installs pytest, ruff, and mypy for development work. Omit it if you only want to run the proxy.

Configure

cp config.example.yaml config.yaml

Open config.yaml in your editor and set luxtronik_host to your heat pump's IP address:

luxtronik_host: "192.168.x.x"   # Replace with your heat pump IP

All other defaults are suitable for most installations. See the User Guide for a full description of every config field.

Run

luxtronik2-modbus-proxy --config config.yaml

On startup you will see structured log output. Expected events:

{"event": "proxy_starting", "modbus_port": 502, "luxtronik_host": "192.168.x.x", ...}
{"event": "proxy_running", "poll_interval": 30, ...}

After the first poll cycle completes:

{"event": "poll_cycle_complete", "registers_updated": 12, ...}

The proxy is now listening on port 502 for Modbus TCP clients.

Verify

Use modpoll (a command-line Modbus client) to confirm the proxy is responding:

modpoll -m tcp -a 1 -r 1 -c 5 -t 4:int 127.0.0.1

This reads 5 holding registers starting at address 1, which correspond to temperature values. You should see five integer values in the output.

Install modpoll: pip install modpoll or download from https://www.modbusdriver.com/modpoll.html.

Run Tests

pytest

With coverage report:

pytest --cov=src

The test suite uses pytest-asyncio with asyncio_mode = auto; no additional flags are needed for async tests.

Docker Alternative

If you prefer to run in a container rather than from source:

docker compose up -d
docker compose logs -f proxy

The container reads config.yaml from the current directory. Make sure you have created and configured it before starting.

Next Steps

  • User Guide — complete configuration reference, Docker install walkthrough, and troubleshooting
  • evcc Integration Guide — configure evcc to control your heat pump via SG-ready
  • HA Coexistence Guide — run the proxy alongside the BenPru Home Assistant integration without connection conflicts