[BUG] Rerun of configuration Dialogue fails

[timmost]

Version of the plugin
2.1.3.
Home-Assistant Version
26.2.1.
Enviroment (Docker, HAOS, ...)
HAOS
Version of your Solvis software/hardware
Version NBG: 3.00
Version SC2: 2.1.3

Describe the bug
Rerunning the configuration dialogue crashed because of trying to establish another Modbus connection.

To Reproduce
Steps to reproduce the behavior:

Expected behavior
Go through configuration dialogue independtn if already configured or not

Screenshots
N/A

Additional context
Add any other context about the problem here.
Debugged the topic successfully with the help of Claude ;-) - seems to work, pls find findings in next comment

[github-actions]

A user reported a bug with the Solvis plugin version 2.1.3 running on Home Assistant OS (HAOS) version 26.2.1. When attempting to rerun the configuration dialogue, the process crashes due to the plugin trying to establish a second Modbus connection. The expected functionality is for the configuration dialogue to proceed smoothly regardless of whether configurations are already in place. The user successfully debugged the issue, with assistance from Claude, and provided a file named "SOLVIS_CHANGES_SUMMARY.md" that contains details of their findings as additional context.

[timmost]

Solvis Control Integration - Changes Summary

Date: February 8, 2026
Status: Resolved

---

Environment Information

Component	Version	Details
Home Assistant	2026.2.1	Core platform version
Solvis Control Integration	2.1.3	Custom integration for Solvis devices
Solvis Device Model	Solvis Control 2 (SC2)	Device Type ID: 2
Solvis Device Variant	SolvisMax 757 Solo/WP	Heat pump enabled variant
Solvis Software Version	2.05.08	Device firmware (VERSIONSC)
Solvis Hardware Version	3.00.00	Hardware revision (VERSIONNBG)
Device Address	192.168.178.55:502	Modbus TCP endpoint
Device MAC	00:08:dc:50:06:f7	Hardware identifier

---

Executive Summary

Fixed critical Modbus connection errors in Home Assistant's Solvis Control integration by implementing retry logic and architectural changes to handle device's single-connection limitation.

Problem: Options dialog failed with "ConnectionException: Modbus Error: [Connection] Not connected"
Root Cause: Solvis device accepts only 1 concurrent Modbus TCP connection; config flow attempts created new connections while coordinator held existing one
Solution: Added retry logic for initial setup; removed connectivity validation from options flow to reuse coordinator's existing connection

---

Issues Addressed

1. Solvis Integration Connection Errors ❌ → ✅

• Error: ConnectionException: Modbus Error: [Connection] Not connected (error 111)
• When Triggered: Opening Solvis options dialog in Home Assistant
• Network Status: Device was reachable (ping successful) but port 502 connections refused
• Discovery: Existing TCP connection from Home Assistant coordinator already active
• Fix: Implemented retry mechanism for new setup; removed validation from options flow

---

Technical Changes

File 1: custom_components/solvis_control/utils/helpers.py

Change 1.1: Added asyncio Import (Line 11)

import asyncio

Purpose: Enable non-blocking sleep during retry delays in async context

Change 1.2: Fixed Type Annotation in generate_device_info() (Line 70)

# Before
}.get(device_version, "Solvis Control (unbekannt)")

# After
}.get(device_version if device_version is not None else 0, "Solvis Control (unbekannt)")

Purpose: Safely handle None device_version by defaulting to 0 for dictionary lookup

Change 1.3: Fixed Type Annotation in create_modbus_client() (Line 532)

# Before
device_version: int = None,

# After
device_version: int | None = None,

Purpose: Proper type hint following Python 3.10+ union syntax; matches actual optional parameter

Change 1.4: Added New Function fetch_modbus_value_with_retry() (Lines 429-489)

async def fetch_modbus_value_with_retry(
    register,
    register_type,
    host: str,
    port: int,
    device_version: int = 0,
    datatype="INT16",
    order="big",
    retries: int = 3,
    retry_delay: float = 1.0,
) -> int | list[int] | None:

Features:

• Wraps fetch_modbus_value() with retry loop
• Configurable retry attempts (default 3)
• Configurable delay between retries (default 1.0 second)
• Catches ConnectionException and generic exceptions
• Logs each attempt and wait duration
• Raises last caught exception after all retries exhausted
• Non-blocking: Uses await asyncio.sleep() instead of blocking sleep

Logic Flow:

1. Loop retries times
2. Attempt fetch_modbus_value()
3. On success: return result immediately
4. On ConnectionException: log, wait, retry
5. After loop: raise last error or generic failure message

---

File 2: custom_components/solvis_control/config_flow.py

Change 2.1: Updated Import Statement (Line 18)

# Before
from .utils.helpers import fetch_modbus_value, get_mac

# After
from .utils.helpers import fetch_modbus_value, fetch_modbus_value_with_retry, get_mac

Change 2.2: Modified async_step_user() - Added Retry Logic

# Before (Single attempt)
versionsc_raw, versionnbg_raw = await fetch_modbus_value(
    [32770, 32771], 1,
    user_input[CONF_HOST], 
    user_input[CONF_PORT]
)

# After (Retry with 6 attempts × 5 second delays)
versionsc_raw, versionnbg_raw = await fetch_modbus_value_with_retry(
    [32770, 32771], 1,
    user_input[CONF_HOST], 
    user_input[CONF_PORT],
    device_version=int(self.data.get(DEVICE_VERSION, 0)),
    retries=6,
    retry_delay=5.0
)

Rationale: Initial device setup may experience timeout during connection establishment; retry with 30-second total timeout (6 × 5s) accommodates slow device responses

Change 2.3: Modified async_step_features() - Added Retry Logic

# Before (Single attempt)
amount_hkr = await fetch_modbus_value(
    2, 1,
    self.data[CONF_HOST], 
    self.data[CONF_PORT],
    device_version=int(self.data.get(DEVICE_VERSION, 0))
)

# After (Retry with 6 attempts × 5 second delays)
amount_hkr = await fetch_modbus_value_with_retry(
    2, 1,
    self.data[CONF_HOST], 
    self.data[CONF_PORT],
    device_version=int(self.data.get(DEVICE_VERSION, 0)),
    retries=6,
    retry_delay=5.0
)

Rationale: Auto-detection of HKR count during setup benefits from same retry strategy

Change 2.4: Architectural Change to async_step_init() in OptionsFlow - MAJOR

# Before (Attempted new Modbus connection)
if user_input is not None:
    self.data.update(user_input)
    try:
        versionsc_raw, versionnbg_raw = await fetch_modbus_value([32770, 32771], 1, 
            user_input[CONF_HOST], user_input[CONF_PORT])
        # Processed versions...
        return await self.async_step_device()
    except ConnectionException as exc:
        errors["base"] = "cannot_connect"
        errors["device"] = str(exc)
        return self.async_show_form(...)

# After (Skip validation, reuse coordinator connection)
if user_input is not None:
    self.data.update(user_input)
    return await self.async_step_device()

return self.async_show_form(
    step_id="init",
    data_schema=get_host_schema_options(self.data),
    errors=errors,
)

Critical Insight:

• Options flow runs AFTER integration is already configured
• Coordinator maintains persistent Modbus connection
• Creating new connection causes "Connection refused" (single-connection device limit)
• Solution: Skip validation, let subsequent steps reuse coordinator's connection
• Removes 10-30 second connection attempt timeout from user experience

---

Device Behavior Analysis

Solvis Control Modbus Characteristics

Property	Value
Device	Solvis heating controller
Protocol	Modbus TCP
Port	502
Max Concurrent Connections	1
Connection Timeout	~30 seconds
Network	Reachable (ping successful)
Error on Conflict	Connection refused (errno 111)

Architecture Pattern

Home Assistant
    ├─ DataUpdateCoordinator
    │   └─ AsyncModbusTcpClient (persistent connection)
    │
    └─ ConfigFlow
        ├─ async_step_user (new setup) → create new connection + retry
        ├─ async_step_features (new setup) → create new connection + retry
        └─ async_step_init (options) → reuse coordinator connection [NO validation]

---

Code Quality Improvements

Type Safety

• ✅ Union type hint: device_version: int | None = None (Python 3.10+)
• ✅ Null-safe dictionary lookup in generate_device_info()
• ✅ Return type hints preserved: -> int | list[int] | None

Error Handling

• ✅ Distinguishes ConnectionException from generic Exception
• ✅ Logs each retry attempt with timestamp
• ✅ Preserves last error for meaningful failure reporting
• ✅ Graceful degradation with defaults (e.g., amount_hkr = 1)

Performance

• ✅ Non-blocking async sleep via asyncio.sleep()
• ✅ Early return on success (no unnecessary retries)
• ✅ Configurable retry parameters for tuning

User Experience

• ✅ Options dialog now opens immediately (no connection validation)
• ✅ Initial setup tolerates slow device responses (30-second timeout via retries)
• ✅ Clear logging for debugging connection issues

---

Testing Checklist

• Reload Solvis Control integration in Home Assistant
• Verify options dialog opens without "Connection refused" error
• Check Home Assistant logs for successful Modbus communications
• Test new device setup (should handle transient timeouts)
• Check that integration updates work with configured settings

---

Commit Message Template

Fix: Solvis Control integration connection errors and irrigation template syntax

- Add retry logic with configurable attempts/delays for new device setup
- Remove Modbus validation from options flow to reuse coordinator connection
- Fix type annotations: int | None for optional device_version parameter
- Handle None device_version safely in generate_device_info()

Resolves single-connection limitation of Solvis device by respecting
existing coordinator connection instead of creating new ones in options flow.

Files Changed:
  - custom_components/solvis_control/utils/helpers.py
  - custom_components/solvis_control/config_flow.py

---

References

GitHub Repository: https://github.com/LarsK1/hass_solvis_control
Home Assistant Docs: https://developers.home-assistant.io/
pymodbus: https://github.com/riptideio/pymodbus
Asyncio: https://docs.python.org/3/library/asyncio.html

---

Revision History

Version	Date	Author	Changes
1.0	2026-02-08	AI Assistant	Initial summary of changes

[fkhr79]

Apart from the fact that this is an SC2 issue (I love the SC2...), it would be helpful if you could fill out the template. What I need to understand is exactly how the error occurs.

A debug log would also be helpful.

And regarding the AI solution: did you have the ENTIRE source code analyzed, including all dependencies, or only individual parts? Even that is almost beside the point: the AI can’t reliably analyze or understand certain logic. One or two levels of complexity are fine, but after that it’s over. You have to look at it yourself — especially when it comes to the Modbus connection logic. I spent several days (!) on that. That doesn’t necessarily mean it’s error-free or doesn’t have the occasional weak spot, but the topic isn’t trivial, and I’m skeptical of any AI by default.

Long story short: I wouldn’t want to vibe-code this — I’d rather identify the exact problem first.

[timmost]

Hi Lars,

absolutely, will do.

SC2 - I love it (again) after my technician offered an SC3 upgrade well north of 1000€ - and you do not get them separately to fix it yourself.

On the config workflow, the pattern was pretty visible in the logs that the modbus seemed to be open, and SC2 not being able to reopen / close it. Debug log etc - will do.

Will look into the topic during the week / on the weekend.

AI - understand the scepticism, however it provides surprisingly good analyses and suggestions, esp with the latest (paid) versions and if you include the repos, full workflows with codeVS plus proper deployment checks etc.

[timmost]

Hi Lars,

anbei das Log der aktuellen Version (frisch installiert), mit Log enabled.

Details:
Version of the plugin
2.1.3.
Home-Assistant Version
26.2.1.
Enviroment (Docker, HAOS, ...)
HAOS
Version of your Solvis software/hardware
Version NBG: 3.00
Version SC2: 2.1.3

Describe the bug
Rerunning config dialogue crashed because of trying to establish another Modbus connection with second config screen:

Solvis Control Basic Setup
Please select a name and enter the connection parameters for your Solvis heating system. Before proceeding with the setup, please ensure that the TCP Modbus interface is enabled. You can find instructions on how to do this in the help section.

An error occurred while establishing the Modbus connection.

To Reproduce
Steps to reproduce the behavior:
Call config dialogue

Expected behavior
Go through configuration dialogue allowing to set different timing etc.

Additional context

  logs:
    homeassistant.components.modbus: warn
    custom_components.solvis_control: debug
    pymodbus: debug

config_entry-solvis_control-01KJ0JGAF4XQ1B3P1G69G2Y868.json

solvis log.txt

Here are the summarized changes I had made with Claude, which worked. The hypothesis was that, with a configured and running Solvis integration, reopening the configuration dialog runs into an existing Modbus connection and therefore fails.

Changes in custom_components/solvis_control/utils/helpers.py in the diff (LarsK1/main → timmost:my-changes) are:

Added retry-capable Modbus read helper

New fetch_modbus_value_with_retry(...) async function.
Wraps fetch_modbus_value(...) and retries on failures (especially ConnectionException) with configurable retries and retry_delay.
Uses asyncio.sleep(...) between attempts and re-raises the last error if all attempts fail.
New import to support retry delays

Added import asyncio at the top of the file.
Device model mapping made safer

In generate_device_info(...), the model mapping now handles device_version being None:
changed from .get(device_version, ...) to .get(device_version if device_version is not None else 0, ...)
Prevents unexpected behavior if parsing DEVICE_VERSION fails.
Type hint improvement

In create_modbus_client(...), device_version annotation changed from int = None to int | None = None (more correct typing).
That’s it for helpers.py in the compare diff you linked. (The diff also changes config_flow.py to use the new retry helper, and adds some extra MAC logging, but that’s outside this file.)

Github: https://github.com/timmost/hass_solvis_control/tree/my-changes

[github-actions]

This issue is stale because it has been open for 30 days with no activity.