vallox-modbus 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vallox_modbus-0.1.0/.github/workflows/tests.yml +19 -0
- vallox_modbus-0.1.0/.gitignore +9 -0
- vallox_modbus-0.1.0/LICENSE +21 -0
- vallox_modbus-0.1.0/PKG-INFO +218 -0
- vallox_modbus-0.1.0/README.md +187 -0
- vallox_modbus-0.1.0/docs/hardware-validation.md +94 -0
- vallox_modbus-0.1.0/pyproject.toml +80 -0
- vallox_modbus-0.1.0/script/query.py +231 -0
- vallox_modbus-0.1.0/src/vallox_modbus/__init__.py +38 -0
- vallox_modbus-0.1.0/src/vallox_modbus/configuration.py +79 -0
- vallox_modbus-0.1.0/src/vallox_modbus/device.py +200 -0
- vallox_modbus-0.1.0/src/vallox_modbus/enums.py +60 -0
- vallox_modbus-0.1.0/src/vallox_modbus/exceptions.py +9 -0
- vallox_modbus-0.1.0/src/vallox_modbus/inputs.py +19 -0
- vallox_modbus-0.1.0/src/vallox_modbus/measurements.py +57 -0
- vallox_modbus-0.1.0/src/vallox_modbus/py.typed +1 -0
- vallox_modbus-0.1.0/src/vallox_modbus/runtime.py +29 -0
- vallox_modbus-0.1.0/src/vallox_modbus/sensors.py +91 -0
- vallox_modbus-0.1.0/src/vallox_modbus/settings.py +61 -0
- vallox_modbus-0.1.0/src/vallox_modbus/validators.py +98 -0
- vallox_modbus-0.1.0/tests/test_configuration.py +83 -0
- vallox_modbus-0.1.0/tests/test_device.py +122 -0
- vallox_modbus-0.1.0/tests/test_inputs.py +36 -0
- vallox_modbus-0.1.0/tests/test_measurements.py +69 -0
- vallox_modbus-0.1.0/tests/test_probe.py +108 -0
- vallox_modbus-0.1.0/tests/test_runtime.py +97 -0
- vallox_modbus-0.1.0/tests/test_sensors.py +92 -0
- vallox_modbus-0.1.0/tests/test_settings.py +58 -0
- vallox_modbus-0.1.0/tests/test_writes.py +126 -0
- vallox_modbus-0.1.0/uv.lock +222 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
name: Tests
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
tests:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v5
|
|
13
|
+
- uses: astral-sh/setup-uv@v6
|
|
14
|
+
- uses: actions/setup-python@v6
|
|
15
|
+
with:
|
|
16
|
+
python-version: "3.12"
|
|
17
|
+
- run: uv run ruff check .
|
|
18
|
+
- run: uv run ruff format --check .
|
|
19
|
+
- run: uv run pytest
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 vallox-modbus contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: vallox-modbus
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Vallox MV Modbus device library
|
|
5
|
+
Project-URL: Homepage, https://github.com/Tra1n84/vallox-modbus
|
|
6
|
+
Project-URL: Source, https://github.com/Tra1n84/vallox-modbus
|
|
7
|
+
Project-URL: Issues, https://github.com/Tra1n84/vallox-modbus/issues
|
|
8
|
+
Author: Tra1n84
|
|
9
|
+
Maintainer: Tra1n84
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: asyncio,home-assistant,home-automation,hvac,modbus,vallox,ventilation
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Framework :: AsyncIO
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Home Automation
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
24
|
+
Classifier: Topic :: System :: Hardware
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.12
|
|
27
|
+
Requires-Dist: modbus-connection>=4.12.1
|
|
28
|
+
Provides-Extra: serial
|
|
29
|
+
Requires-Dist: modbus-connection[tmodbus]>=4.12.1; extra == 'serial'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# vallox-modbus
|
|
33
|
+
|
|
34
|
+
`vallox-modbus` is a Python library for reading and controlling Vallox MV
|
|
35
|
+
ventilation units through the Home Assistant `modbus-connection` architecture.
|
|
36
|
+
|
|
37
|
+
## Status
|
|
38
|
+
|
|
39
|
+
The core read model and the main documented control writes are implemented.
|
|
40
|
+
|
|
41
|
+
Write support is intentionally scoped to semantic operations for profile
|
|
42
|
+
selection, power, profile fan speeds, temperature targets, timers/durations,
|
|
43
|
+
Extra profile settings, and bypass lock. Bypass-lock and Automatic profile
|
|
44
|
+
writes still need hardware validation. Broad Vallox MV model compatibility has
|
|
45
|
+
not yet been validated.
|
|
46
|
+
|
|
47
|
+
Hardware communication has been tested against one Vallox ValloPlus 510 MV
|
|
48
|
+
installation over Modbus RTU with unit ID 1, 19200 baud, 8 data bits, even
|
|
49
|
+
parity and 1 stop bit. Other Vallox MV models and firmware versions still need
|
|
50
|
+
validation.
|
|
51
|
+
|
|
52
|
+
## Installation
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install vallox-modbus
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
For a serial transport, for example to run the diagnostic script from a source
|
|
59
|
+
checkout, install the optional `serial` extra:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install "vallox-modbus[serial]"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Architecture
|
|
66
|
+
|
|
67
|
+
The library models the Vallox register map and expects the caller to provide a
|
|
68
|
+
`modbus_connection.ModbusUnit`. It does not create or own the physical Modbus
|
|
69
|
+
connection.
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
Home Assistant
|
|
73
|
+
|
|
|
74
|
+
| provides Modbus unit
|
|
75
|
+
v
|
|
76
|
+
vallox-modbus
|
|
77
|
+
|
|
|
78
|
+
v
|
|
79
|
+
modbus-connection
|
|
80
|
+
|
|
|
81
|
+
v
|
|
82
|
+
Serial RTU / TCP / other supported transport
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Vallox MV units use holding registers directly. This library does not apply a
|
|
86
|
+
global `-1` or `+1` address offset.
|
|
87
|
+
|
|
88
|
+
## Supported Data
|
|
89
|
+
|
|
90
|
+
Measurement registers `4353..4364`:
|
|
91
|
+
|
|
92
|
+
- current fan speed
|
|
93
|
+
- extract, exhaust, outdoor, supply cell, and supply air temperatures
|
|
94
|
+
- RH and CO2 levels
|
|
95
|
+
- extract and supply fan RPM
|
|
96
|
+
- humidity
|
|
97
|
+
- CO2
|
|
98
|
+
|
|
99
|
+
Input registers `4365..4370`:
|
|
100
|
+
|
|
101
|
+
- fireplace switch
|
|
102
|
+
- digital input
|
|
103
|
+
- analog control input
|
|
104
|
+
- raw multisensor values
|
|
105
|
+
|
|
106
|
+
Runtime registers `4609..4621`:
|
|
107
|
+
|
|
108
|
+
- basic profile: Home, Away, or Automatic on firmware that supports Automatic
|
|
109
|
+
- system mode
|
|
110
|
+
- defrosting state
|
|
111
|
+
- Boost, Fireplace, and Extra runtime timers
|
|
112
|
+
- weekly timer enabled
|
|
113
|
+
- heat exchanger state
|
|
114
|
+
- total and current uptime
|
|
115
|
+
- filter remaining
|
|
116
|
+
- fault / limp state
|
|
117
|
+
|
|
118
|
+
Optional sensor registers:
|
|
119
|
+
|
|
120
|
+
- internal humidity sensor
|
|
121
|
+
- RH sensors 0..5
|
|
122
|
+
- CO2 sensors 0..5
|
|
123
|
+
- optional temperature sensor
|
|
124
|
+
- VOC level and VOC sensors 0..3
|
|
125
|
+
|
|
126
|
+
Settings registers:
|
|
127
|
+
|
|
128
|
+
- Away, Home, and Boost RH/CO2 control flags
|
|
129
|
+
- Away, Home, and Boost fan speed settings
|
|
130
|
+
- Away, Home, and Boost supply air temperature targets
|
|
131
|
+
- configured Boost and Fireplace durations
|
|
132
|
+
|
|
133
|
+
Configuration registers:
|
|
134
|
+
|
|
135
|
+
- Modbus address, baudrate, parity, and stop bits
|
|
136
|
+
- fan balance base settings
|
|
137
|
+
- fireplace and Extra profile fan settings
|
|
138
|
+
- Extra profile supply air temperature target and duration
|
|
139
|
+
- filter change interval
|
|
140
|
+
- heat recovery cell and heater types
|
|
141
|
+
|
|
142
|
+
Writable registers:
|
|
143
|
+
|
|
144
|
+
- power on/off through documented system mode values
|
|
145
|
+
- Home/Away/Automatic basic profile
|
|
146
|
+
- current Boost, Fireplace, and Extra timers
|
|
147
|
+
- Away, Home, and Boost fan speed settings
|
|
148
|
+
- Away, Home, and Boost supply air temperature targets
|
|
149
|
+
- configured Boost, Fireplace, and Extra durations
|
|
150
|
+
- Extra profile fan and supply air temperature settings
|
|
151
|
+
- heat recovery cell bypass lock
|
|
152
|
+
|
|
153
|
+
## Polling Model
|
|
154
|
+
|
|
155
|
+
`ValloxDevice.async_probe()` validates a `modbus_connection.ModbusUnit` for
|
|
156
|
+
setup flows by reading only the measurements and runtime register groups and
|
|
157
|
+
checking a small set of live values for plausibility. It performs no writes.
|
|
158
|
+
|
|
159
|
+
`async_update_readings()` updates frequently changing values from the
|
|
160
|
+
measurements, runtime, inputs, and sensors components.
|
|
161
|
+
|
|
162
|
+
`async_update_settings()` updates slower changing values from the settings and
|
|
163
|
+
configuration components.
|
|
164
|
+
|
|
165
|
+
`async_update()` runs both groups and returns one combined update report.
|
|
166
|
+
|
|
167
|
+
Write methods are exposed as explicit semantic operations on `ValloxDevice`,
|
|
168
|
+
such as `async_set_power()`, `async_set_basic_profile()`,
|
|
169
|
+
`async_set_home_fan_speed()`, and
|
|
170
|
+
`async_set_home_air_temperature_target()`. The library does not expose a
|
|
171
|
+
generic arbitrary register write API.
|
|
172
|
+
|
|
173
|
+
## Example
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
from vallox_modbus import ValloxDevice
|
|
177
|
+
|
|
178
|
+
device = await ValloxDevice.async_probe(unit)
|
|
179
|
+
await device.async_update_readings()
|
|
180
|
+
|
|
181
|
+
print(device.measurements.outdoor_air_temperature)
|
|
182
|
+
print(device.measurements.humidity)
|
|
183
|
+
print(device.runtime.basic_profile)
|
|
184
|
+
print(device.runtime.heat_exchanger_state)
|
|
185
|
+
|
|
186
|
+
await device.async_update_settings()
|
|
187
|
+
print(device.settings.home_fan_speed)
|
|
188
|
+
print(device.configuration.modbus_baudrate)
|
|
189
|
+
print(device.sensors.rh_sensors)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Diagnostic Query
|
|
193
|
+
|
|
194
|
+
The diagnostic script is an application and may create a physical serial
|
|
195
|
+
connection. The reusable package code does not.
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
uv run --extra serial python script/query.py \
|
|
199
|
+
/dev/serial/by-id/usb-1a86_USB2.0-Ser_-if00-port0 \
|
|
200
|
+
--unit 1 \
|
|
201
|
+
--baudrate 19200 \
|
|
202
|
+
--parity E \
|
|
203
|
+
--stopbits 1
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Defaults are unit `1`, baudrate `19200`, bytesize `8`, parity `E`, and stopbits
|
|
207
|
+
`1`. Pass `--details` to print optional input and sensor readings. Pass
|
|
208
|
+
`--settings` to read and print the settings and configuration components as
|
|
209
|
+
well.
|
|
210
|
+
|
|
211
|
+
## References
|
|
212
|
+
|
|
213
|
+
- Vallox manual search:
|
|
214
|
+
<https://www.vallox.com/en/support-and-instructions/manual-search/>
|
|
215
|
+
- Home Assistant Modbus developer documentation:
|
|
216
|
+
<https://developers.home-assistant.io/docs/modbus/introduction/>
|
|
217
|
+
- `modbus-connection`:
|
|
218
|
+
<https://home-assistant-libs.github.io/modbus-connection/>
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# vallox-modbus
|
|
2
|
+
|
|
3
|
+
`vallox-modbus` is a Python library for reading and controlling Vallox MV
|
|
4
|
+
ventilation units through the Home Assistant `modbus-connection` architecture.
|
|
5
|
+
|
|
6
|
+
## Status
|
|
7
|
+
|
|
8
|
+
The core read model and the main documented control writes are implemented.
|
|
9
|
+
|
|
10
|
+
Write support is intentionally scoped to semantic operations for profile
|
|
11
|
+
selection, power, profile fan speeds, temperature targets, timers/durations,
|
|
12
|
+
Extra profile settings, and bypass lock. Bypass-lock and Automatic profile
|
|
13
|
+
writes still need hardware validation. Broad Vallox MV model compatibility has
|
|
14
|
+
not yet been validated.
|
|
15
|
+
|
|
16
|
+
Hardware communication has been tested against one Vallox ValloPlus 510 MV
|
|
17
|
+
installation over Modbus RTU with unit ID 1, 19200 baud, 8 data bits, even
|
|
18
|
+
parity and 1 stop bit. Other Vallox MV models and firmware versions still need
|
|
19
|
+
validation.
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install vallox-modbus
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
For a serial transport, for example to run the diagnostic script from a source
|
|
28
|
+
checkout, install the optional `serial` extra:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install "vallox-modbus[serial]"
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Architecture
|
|
35
|
+
|
|
36
|
+
The library models the Vallox register map and expects the caller to provide a
|
|
37
|
+
`modbus_connection.ModbusUnit`. It does not create or own the physical Modbus
|
|
38
|
+
connection.
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
Home Assistant
|
|
42
|
+
|
|
|
43
|
+
| provides Modbus unit
|
|
44
|
+
v
|
|
45
|
+
vallox-modbus
|
|
46
|
+
|
|
|
47
|
+
v
|
|
48
|
+
modbus-connection
|
|
49
|
+
|
|
|
50
|
+
v
|
|
51
|
+
Serial RTU / TCP / other supported transport
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Vallox MV units use holding registers directly. This library does not apply a
|
|
55
|
+
global `-1` or `+1` address offset.
|
|
56
|
+
|
|
57
|
+
## Supported Data
|
|
58
|
+
|
|
59
|
+
Measurement registers `4353..4364`:
|
|
60
|
+
|
|
61
|
+
- current fan speed
|
|
62
|
+
- extract, exhaust, outdoor, supply cell, and supply air temperatures
|
|
63
|
+
- RH and CO2 levels
|
|
64
|
+
- extract and supply fan RPM
|
|
65
|
+
- humidity
|
|
66
|
+
- CO2
|
|
67
|
+
|
|
68
|
+
Input registers `4365..4370`:
|
|
69
|
+
|
|
70
|
+
- fireplace switch
|
|
71
|
+
- digital input
|
|
72
|
+
- analog control input
|
|
73
|
+
- raw multisensor values
|
|
74
|
+
|
|
75
|
+
Runtime registers `4609..4621`:
|
|
76
|
+
|
|
77
|
+
- basic profile: Home, Away, or Automatic on firmware that supports Automatic
|
|
78
|
+
- system mode
|
|
79
|
+
- defrosting state
|
|
80
|
+
- Boost, Fireplace, and Extra runtime timers
|
|
81
|
+
- weekly timer enabled
|
|
82
|
+
- heat exchanger state
|
|
83
|
+
- total and current uptime
|
|
84
|
+
- filter remaining
|
|
85
|
+
- fault / limp state
|
|
86
|
+
|
|
87
|
+
Optional sensor registers:
|
|
88
|
+
|
|
89
|
+
- internal humidity sensor
|
|
90
|
+
- RH sensors 0..5
|
|
91
|
+
- CO2 sensors 0..5
|
|
92
|
+
- optional temperature sensor
|
|
93
|
+
- VOC level and VOC sensors 0..3
|
|
94
|
+
|
|
95
|
+
Settings registers:
|
|
96
|
+
|
|
97
|
+
- Away, Home, and Boost RH/CO2 control flags
|
|
98
|
+
- Away, Home, and Boost fan speed settings
|
|
99
|
+
- Away, Home, and Boost supply air temperature targets
|
|
100
|
+
- configured Boost and Fireplace durations
|
|
101
|
+
|
|
102
|
+
Configuration registers:
|
|
103
|
+
|
|
104
|
+
- Modbus address, baudrate, parity, and stop bits
|
|
105
|
+
- fan balance base settings
|
|
106
|
+
- fireplace and Extra profile fan settings
|
|
107
|
+
- Extra profile supply air temperature target and duration
|
|
108
|
+
- filter change interval
|
|
109
|
+
- heat recovery cell and heater types
|
|
110
|
+
|
|
111
|
+
Writable registers:
|
|
112
|
+
|
|
113
|
+
- power on/off through documented system mode values
|
|
114
|
+
- Home/Away/Automatic basic profile
|
|
115
|
+
- current Boost, Fireplace, and Extra timers
|
|
116
|
+
- Away, Home, and Boost fan speed settings
|
|
117
|
+
- Away, Home, and Boost supply air temperature targets
|
|
118
|
+
- configured Boost, Fireplace, and Extra durations
|
|
119
|
+
- Extra profile fan and supply air temperature settings
|
|
120
|
+
- heat recovery cell bypass lock
|
|
121
|
+
|
|
122
|
+
## Polling Model
|
|
123
|
+
|
|
124
|
+
`ValloxDevice.async_probe()` validates a `modbus_connection.ModbusUnit` for
|
|
125
|
+
setup flows by reading only the measurements and runtime register groups and
|
|
126
|
+
checking a small set of live values for plausibility. It performs no writes.
|
|
127
|
+
|
|
128
|
+
`async_update_readings()` updates frequently changing values from the
|
|
129
|
+
measurements, runtime, inputs, and sensors components.
|
|
130
|
+
|
|
131
|
+
`async_update_settings()` updates slower changing values from the settings and
|
|
132
|
+
configuration components.
|
|
133
|
+
|
|
134
|
+
`async_update()` runs both groups and returns one combined update report.
|
|
135
|
+
|
|
136
|
+
Write methods are exposed as explicit semantic operations on `ValloxDevice`,
|
|
137
|
+
such as `async_set_power()`, `async_set_basic_profile()`,
|
|
138
|
+
`async_set_home_fan_speed()`, and
|
|
139
|
+
`async_set_home_air_temperature_target()`. The library does not expose a
|
|
140
|
+
generic arbitrary register write API.
|
|
141
|
+
|
|
142
|
+
## Example
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
from vallox_modbus import ValloxDevice
|
|
146
|
+
|
|
147
|
+
device = await ValloxDevice.async_probe(unit)
|
|
148
|
+
await device.async_update_readings()
|
|
149
|
+
|
|
150
|
+
print(device.measurements.outdoor_air_temperature)
|
|
151
|
+
print(device.measurements.humidity)
|
|
152
|
+
print(device.runtime.basic_profile)
|
|
153
|
+
print(device.runtime.heat_exchanger_state)
|
|
154
|
+
|
|
155
|
+
await device.async_update_settings()
|
|
156
|
+
print(device.settings.home_fan_speed)
|
|
157
|
+
print(device.configuration.modbus_baudrate)
|
|
158
|
+
print(device.sensors.rh_sensors)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Diagnostic Query
|
|
162
|
+
|
|
163
|
+
The diagnostic script is an application and may create a physical serial
|
|
164
|
+
connection. The reusable package code does not.
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
uv run --extra serial python script/query.py \
|
|
168
|
+
/dev/serial/by-id/usb-1a86_USB2.0-Ser_-if00-port0 \
|
|
169
|
+
--unit 1 \
|
|
170
|
+
--baudrate 19200 \
|
|
171
|
+
--parity E \
|
|
172
|
+
--stopbits 1
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Defaults are unit `1`, baudrate `19200`, bytesize `8`, parity `E`, and stopbits
|
|
176
|
+
`1`. Pass `--details` to print optional input and sensor readings. Pass
|
|
177
|
+
`--settings` to read and print the settings and configuration components as
|
|
178
|
+
well.
|
|
179
|
+
|
|
180
|
+
## References
|
|
181
|
+
|
|
182
|
+
- Vallox manual search:
|
|
183
|
+
<https://www.vallox.com/en/support-and-instructions/manual-search/>
|
|
184
|
+
- Home Assistant Modbus developer documentation:
|
|
185
|
+
<https://developers.home-assistant.io/docs/modbus/introduction/>
|
|
186
|
+
- `modbus-connection`:
|
|
187
|
+
<https://home-assistant-libs.github.io/modbus-connection/>
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Hardware Validation
|
|
2
|
+
|
|
3
|
+
This file records hardware behavior that has been validated against a real
|
|
4
|
+
Vallox installation. It intentionally avoids installation-specific paths,
|
|
5
|
+
addresses, and private Home Assistant details.
|
|
6
|
+
|
|
7
|
+
## Vallox ValloPlus 510 MV
|
|
8
|
+
|
|
9
|
+
Validated on 2026-09-25 against one Vallox ValloPlus 510 MV installation over
|
|
10
|
+
Modbus RTU.
|
|
11
|
+
|
|
12
|
+
Connection settings:
|
|
13
|
+
|
|
14
|
+
- Unit ID: 1
|
|
15
|
+
- Baudrate: 19200
|
|
16
|
+
- Data bits: 8
|
|
17
|
+
- Parity: even
|
|
18
|
+
- Stop bits: 1
|
|
19
|
+
|
|
20
|
+
Validated read paths:
|
|
21
|
+
|
|
22
|
+
- `async_update_readings()`
|
|
23
|
+
- `async_update_settings()`
|
|
24
|
+
- `script/query.py --details --settings`
|
|
25
|
+
|
|
26
|
+
Validated read groups:
|
|
27
|
+
|
|
28
|
+
- measurements
|
|
29
|
+
- runtime
|
|
30
|
+
- inputs
|
|
31
|
+
- optional sensors
|
|
32
|
+
- settings
|
|
33
|
+
- configuration
|
|
34
|
+
|
|
35
|
+
Observed read behavior:
|
|
36
|
+
|
|
37
|
+
- Home/Away basic profile, normal system mode, fault state, defrost state, fan
|
|
38
|
+
speed, temperatures, humidity, fan RPM, heat exchanger state, filter
|
|
39
|
+
remaining, and timers decoded plausibly.
|
|
40
|
+
- Automatic basic profile is documented for register `4609` as value `2`, but
|
|
41
|
+
was not observed on this installation during validation.
|
|
42
|
+
- `CO2 level: No Sensor` was observed with raw CO2 value `0`; the library maps
|
|
43
|
+
that CO2 value to unavailable.
|
|
44
|
+
- Internal humidity sensor raw value `56` decoded to an impossible negative
|
|
45
|
+
humidity by the documented formula; the library maps out-of-range internal
|
|
46
|
+
humidity values to unavailable.
|
|
47
|
+
- RH and CO2 sensor arrays were unavailable on the tested installation.
|
|
48
|
+
- VOC sensor values returned `0 ppm`; these were left as reported because the
|
|
49
|
+
documented no-sensor marker for individual VOC sensors is `65535`.
|
|
50
|
+
- Optional temperature reported a very low celsius value; this was left as
|
|
51
|
+
reported because no register-specific no-sensor marker was verified.
|
|
52
|
+
|
|
53
|
+
Validated write paths:
|
|
54
|
+
|
|
55
|
+
- `async_set_home_fan_speed(60)`
|
|
56
|
+
- `async_set_away_fan_speed(30)`
|
|
57
|
+
- `async_set_boost_fan_speed(90)`
|
|
58
|
+
- `async_set_away_air_temperature_target(15.0)`
|
|
59
|
+
- `async_set_home_air_temperature_target(13.0)`
|
|
60
|
+
- `async_set_boost_air_temperature_target(15.0)`
|
|
61
|
+
- `async_set_boost_duration(30)`
|
|
62
|
+
- `async_set_fireplace_duration(15)`
|
|
63
|
+
- `async_set_extra_duration(10)`
|
|
64
|
+
- `async_set_extra_air_temperature_target(15.0)`
|
|
65
|
+
- `async_set_extra_extract_fan(50)`
|
|
66
|
+
- `async_set_extra_supply_fan(50)`
|
|
67
|
+
- `async_set_basic_profile()` by switching Away -> Home -> Away
|
|
68
|
+
- `async_set_power()` by switching normal operation off -> on
|
|
69
|
+
- `async_set_boost_timer()` by setting the current timer 0 -> 1 -> 0
|
|
70
|
+
- `async_set_fireplace_timer()` by setting the current timer 0 -> 1 -> 0
|
|
71
|
+
- `async_set_extra_timer()` by setting the current timer 0 -> 1 -> 0
|
|
72
|
+
|
|
73
|
+
Write behavior notes:
|
|
74
|
+
|
|
75
|
+
- `async_set_fireplace_duration(15)` timed out when register `20545` was written
|
|
76
|
+
with FC06.
|
|
77
|
+
- A direct FC16 write to register `20545` succeeded.
|
|
78
|
+
- The library therefore uses FC16 for `fireplace_duration`.
|
|
79
|
+
- `boost_duration` and `extra_duration` were validated without this FC16
|
|
80
|
+
workaround.
|
|
81
|
+
- Runtime timer registers remained distinct from configured duration registers.
|
|
82
|
+
- `async_set_power(False)` set system mode to `Off`, fan speed to `0 %`, and
|
|
83
|
+
extract and supply fan speeds to `0 RPM`.
|
|
84
|
+
- `async_set_power(True)` restored system mode to `Normal`.
|
|
85
|
+
|
|
86
|
+
Not yet hardware-validated:
|
|
87
|
+
|
|
88
|
+
- `async_set_basic_profile(BasicProfile.AUTOMATIC)`
|
|
89
|
+
- `async_set_bypass_locked()`
|
|
90
|
+
|
|
91
|
+
Scope:
|
|
92
|
+
|
|
93
|
+
- This validates one Vallox ValloPlus 510 MV installation only.
|
|
94
|
+
- Broader Vallox MV model and firmware compatibility still needs validation.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "vallox-modbus"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Vallox MV Modbus device library"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Tra1n84" }]
|
|
14
|
+
maintainers = [{ name = "Tra1n84" }]
|
|
15
|
+
keywords = [
|
|
16
|
+
"asyncio",
|
|
17
|
+
"home-assistant",
|
|
18
|
+
"home-automation",
|
|
19
|
+
"hvac",
|
|
20
|
+
"modbus",
|
|
21
|
+
"vallox",
|
|
22
|
+
"ventilation",
|
|
23
|
+
]
|
|
24
|
+
classifiers = [
|
|
25
|
+
"Development Status :: 3 - Alpha",
|
|
26
|
+
"Framework :: AsyncIO",
|
|
27
|
+
"Intended Audience :: Developers",
|
|
28
|
+
"Operating System :: OS Independent",
|
|
29
|
+
"Programming Language :: Python :: 3",
|
|
30
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
31
|
+
"Programming Language :: Python :: 3.12",
|
|
32
|
+
"Programming Language :: Python :: 3.13",
|
|
33
|
+
"Programming Language :: Python :: 3.14",
|
|
34
|
+
"Topic :: Home Automation",
|
|
35
|
+
"Topic :: System :: Hardware",
|
|
36
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
37
|
+
"Typing :: Typed",
|
|
38
|
+
]
|
|
39
|
+
dependencies = ["modbus-connection>=4.12.1"]
|
|
40
|
+
|
|
41
|
+
[project.urls]
|
|
42
|
+
Homepage = "https://github.com/Tra1n84/vallox-modbus"
|
|
43
|
+
Source = "https://github.com/Tra1n84/vallox-modbus"
|
|
44
|
+
Issues = "https://github.com/Tra1n84/vallox-modbus/issues"
|
|
45
|
+
|
|
46
|
+
[project.optional-dependencies]
|
|
47
|
+
serial = ["modbus-connection[tmodbus]>=4.12.1"]
|
|
48
|
+
|
|
49
|
+
[dependency-groups]
|
|
50
|
+
dev = [
|
|
51
|
+
"pytest>=8.0",
|
|
52
|
+
"pytest-asyncio>=1.0",
|
|
53
|
+
"ruff>=0.13.0",
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
[tool.hatch.build.targets.wheel]
|
|
57
|
+
packages = ["src/vallox_modbus"]
|
|
58
|
+
|
|
59
|
+
[tool.hatch.build.targets.sdist]
|
|
60
|
+
include = [
|
|
61
|
+
"/.github/workflows/tests.yml",
|
|
62
|
+
"/docs",
|
|
63
|
+
"/script",
|
|
64
|
+
"/src",
|
|
65
|
+
"/tests",
|
|
66
|
+
"/LICENSE",
|
|
67
|
+
"/README.md",
|
|
68
|
+
"/pyproject.toml",
|
|
69
|
+
"/uv.lock",
|
|
70
|
+
]
|
|
71
|
+
|
|
72
|
+
[tool.pytest.ini_options]
|
|
73
|
+
testpaths = ["tests"]
|
|
74
|
+
|
|
75
|
+
[tool.ruff]
|
|
76
|
+
line-length = 88
|
|
77
|
+
target-version = "py312"
|
|
78
|
+
|
|
79
|
+
[tool.ruff.lint]
|
|
80
|
+
select = ["B", "E", "F", "I", "UP"]
|