Repository navigation
Development and Testing
Tip
See Contributions-workflow for the branch and pull-request workflow.
The ownership rules are maintained in Architecture-and-internals rather than repeated on every developer page.
Use the routing table there to decide whether a change belongs in
trovis-modbus-hass, trovis-modbus, modbus-connection, tmodbus, or
serialx.
Tip
Moving another Home Assistant Modbus integration toward modbus-connection?
Start with Architecture-and-internals, then continue with
Connections-and-transports.
The project intentionally tests each layer where that layer is owned.
Controller semantics, datapoint decoding, grouped reads, hydronic roles and library-side write validation are tested in the library repository.
See the library's Development and contributions page for its test workflow.
The integration test suite focuses on Home Assistant-specific behavior such as:
- config flow and reconfiguration,
- device and entity creation,
- entity gating and identity,
- the Write access gate,
- translations,
- coordinator behavior,
- connection lifecycle at the integration boundary.
Real-controller tests complement both repositories where mocks cannot fully prove controller behavior.
The HAOS / VS Code shell is intentionally lightweight and does not necessarily provide a full Home Assistant development environment.
When testing integration changes against an unreleased trovis-modbus branch,
prefer the local source override instead of repeatedly reinstalling the library.
Create the gitignored file:
custom_components/trovis557x/local_dev.py
with:
LOCAL_TROVIS_MODBUS_SRC = "/config/dev/trovis-modbus/src"After a Home Assistant restart, the integration will prefer that local source tree. This makes it much easier to work on both repositories side by side.
When checking dependency upgrades, remember that
importlib.metadata.version("trovis-modbus") reports the installed distribution
version. With the local source override active, the imported source tree can be
newer than that version string.
A temporary runtime diagnostic can be useful:
from importlib.metadata import version
_LOGGER.warning(
"TROVIS stack: trovis-modbus=%s, modbus-connection=%s, tmodbus=%s",
version("trovis-modbus"),
version("modbus-connection"),
version("tmodbus"),
)Keep that kind of diagnostic at WARNING only while testing; it is not intended
as permanent normal logging.
Install the local checking tools when required:
python -m pip install --upgrade ruff pytest pytest-asyncioDo not assume that uv, uvx, or uv sync are available in the HAOS / VS Code
shell. The repository can use uv in a prepared development environment, but
the supported local scripts do not require it merely to format and check the
source tree.
Run formatting and repository checks with:
cd /config/dev/trovis-modbus-hass
script/format.sh
script/hasscheck.shscript/format.sh applies safe Ruff fixes and formats the repository.
script/hasscheck.sh verifies formatting and linting, compiles the integration
and test files, and validates JSON files. It does not run pytest.
For diagnosis or in a minimal shell, the core checks can also be run directly:
python -m ruff format --check .
python -m ruff check .
python -m compileall custom_components testsRun the available test suite in an environment containing the declared development dependencies:
python -m pytestThe complete Home Assistant custom-component test suite requires a prepared Home Assistant development environment and is also executed by GitHub Actions.
The integration is regularly verified with the following controllers:
- one TROVIS 5576 in a live heating installation, system 2.1, with four additional Pt 1000 sensors,
- one dedicated TROVIS 5578 test controller, system 6.1, with all 17 sensor inputs equipped with Pt 1000 sensors,
- one dedicated TROVIS 5579 test controller, system 5.1, with all 17 sensor inputs equipped with Pt 1000 sensors.
The hardware tests complement the automated software tests. They are especially important for controller probing, model- and hydronic-aware entity creation, grouped reads, write-access handling, and real register and coil writes.
After local checks:
- make sure the intended
trovis-modbussource/version is active, - restart Home Assistant,
- confirm that every configured TROVIS entry loads,
- check the detected model, hydronic system, Rk roles, optional subsystems, and physical sensors,
- verify normal polling and availability,
- test representative reads on each affected device,
- enable Write access only for deliberate write tests,
- verify representative register and coil writes on real hardware,
- confirm the resulting value on the controller display where possible,
- disable Write access again after the test.
Use additional care with a controller operating a live heating installation. Prefer harmless test values and restore the original setting immediately.
Do not maintain a second copy of the architecture rules here.
Use the dedicated references instead:
- Architecture-and-internals — project ownership and boundaries
- Connections-and-transports — connection ownership
- Devices-and-entities — device/entity mapping and static topology
- Writing-and-write-access — write path and safety gate
- Coordinator-and-runtime-updates — polling and runtime recovery
Changes to setup or reconfiguration should verify:
- Network and Serial setup paths build the expected
modbus-connectionparameters, - switching transport during reconfiguration does not leave stale connection settings behind,
- the selected unit ID is validated,
- controller probing reports a useful error,
- display names can change without changing the stored slug,
- reconfiguration keeps existing entity identities stable,
- newly detected sensors are added without unnecessarily removing known ones,
- multiple controller entries do not collide.
Keep German and English translations synchronized. New entity descriptions, config-flow fields, errors, device names, and options should be added to the appropriate translation files and validated as JSON.
Visible sensor names should retain the documented TROVIS abbreviations such as
AF, VF, RüF, RF, SF, FG, and IMP. ASCII-safe entity IDs use forms
such as ruef.
A change that affects setup, device structure, entity identity, writing, connection behavior, or user-visible limitations should update the relevant Wiki page. Keep release-specific migration notes out of the permanent README.
Disclaimer: Any information on this wiki is informal advice only. It is not supported nor endorsed by Samson, Sauter, YADOS, Pewo or any other equipment maker or OEM. There is no warranty expressed or implied: you take sole responsibility for everything you do with your heating controller.
-
Wozu dieses Projekt?
What is this project about?
-
Wie funktioniert das?
How does it work?
- Was wird benötigt? Kosten?
What's required? Costs?
- Supported controllers
- Connecting your TROVIS
- Installation and setup
- Current limits and migration
- Troubleshooting
- Architecture and internals
- Connections and transports
- Config flow and reconfiguration
- Coordinator and runtime updates
- Devices and entities
- Writing and write access
- Development and testing
- LAN/WLAN
USR-TCP232-T2, USR-TCP232-410S, USR-K7, USR-DR301 (Hutschiene), Elfin-EE10 (WLAN) - USB
AZDelivery FT232RL, Waveshare USB 2 RS232/485/TTL - ESP
ESP-01, Wemos D1 - SPS
S7 1200, Wago 750-889 - KNX
Masifi Modbus Gateway
- Edomi
- espHome/HomeAssitant
- FHEM
- HomeAssistant
- ioBroker
- KNX
- Loxone
- NodeRed
- openHAB
- SIMATIC Step7
- smarthomeNG
- Tasmota/MQTT
- Wago CODESYS
Wiki - Start