modbus-ventilation

Description

The modbus-ventilation block is used to integrate a ventilation unit controlled over Modbus RTU via RS485. The block periodically reads the device state and exposes it through the associated vlogic virtual device.

The first version supports the Systemair SAVE model. The value map for this model is built in, so the user does not configure register addresses or byte order.

The block has no inputs and no standard logic outputs. Values are read and written through the associated virtual device and the standard input and output blocks.

The first read from the device takes place after project initialization. Subsequent reads are performed cyclically every refreshInterval milliseconds.

Configuration parameters

Parameter name	Value
Name (`name`)	Optional block name. It is used as the default name of the associated virtual device.
Device model (`deviceModel`)	Required ventilation unit model. In this version, the supported value is `Systemair SAVE`.
Device address (`deviceAddress`)	Required Modbus slave address. For `Systemair SAVE`, the allowed range is 1-247. The address must be unique among `modbus-ventilation` blocks using the same RS485 configuration (`server`).
Refresh interval (`refreshInterval`)	Required time between consecutive read cycles in milliseconds. Allowed range: 1-3600000 ms.
Response timeout (`responseTimeout`)	Required maximum time to wait for the device response in milliseconds. Allowed range: 10-60000 ms.
RS485 configuration (`server`)	Required identifier of the `modbus-client` block from which the RS485 port configuration is taken.

For the Systemair SAVE model, the referenced RS485 configuration must meet the following requirements:

RS485 setting	Requirement
Baudrate	One of: 9600, 19200, 38400, 57600, 115200.
Parity	`None`, `Even`, or `Odd`.
Stop bits	Exactly 1 stop bit.

Input handling

The modbus-ventilation block has no inputs and does not accept events from other blocks.

To read ventilation unit values, use the input block configured for a property of the associated virtual device. To change writable values, use the output block or the virtual device user interface.

Block outputs

The modbus-ventilation block does not expose standard logic outputs for further connections in the flow.

The ventilation unit state is exposed through the associated virtual device. For the Systemair SAVE model, the following properties are available:

Property	Direction	Description
`relative_humidity`	RO	Relative humidity in percent.
`supply_fan_rpm`	RO	Supply fan speed in rpm.
`extract_fan_rpm`	RO	Extract fan speed in rpm.
`outdoor_air_temperature`	RO	Outdoor air temperature in degrees Celsius.
`supply_air_temperature`	RO	Supply air temperature in degrees Celsius.
`supply_air_temperature_setpoint`	RW	Supply air temperature setpoint in degrees Celsius.
`operation_mode`	RW	Current ventilation unit operation mode.
`manual_airflow_level`	RW	Fan level in manual mode.

RO properties are read-only. RW properties can be read and written.

Values may be unknown. In the web interface, such a value is shown as null. In the mobile application, it is sent with the unknown status. In the input and output blocks, this means that the device is attached, but the current value of the property is not known at the moment.

If a function is not supported by the device model, the corresponding property is not exposed. For Systemair SAVE, all properties listed in the table are supported.

Supply air temperature setpoint

For the Systemair SAVE model, the supply_air_temperature_setpoint property has the range 12.0-30.0°C and the step 0.1°C.

A value outside the range is ignored and is not sent to the device. A value inside the range but not aligned to the step is rounded to the nearest 0.1°C step. Values exactly halfway between two steps are rounded up.

Writing a value does not optimistically change the local state. The new value becomes visible only after it is read back from the ventilation unit.

Operation mode

For the Systemair SAVE model, read operation modes may have the following values:

auto
manual
crowded
refresh
fireplace
away
holiday
cooker_hood
vacuum_cleaner
cdi1
cdi2
cdi3
pressure_guard

Writable values are:

auto
manual
crowded
refresh
fireplace
away
holiday

The other modes may be read from the device, but they are not set by the block in this version.

Manual airflow level

For the Systemair SAVE model, the manual_airflow_level property supports the following values:

low
normal
high

The off value is not supported in this version. If the device returns a level outside the supported list, the property changes to the unknown state.

Read error behavior

A single Modbus read error does not detach the virtual device and does not immediately remove the last valid value. After the retry limit configured in the associated modbus-client block is exceeded, only the value that could not be read becomes unknown.

Invalid block configuration causes a configuration error and detaches the associated virtual device. A temporary communication problem with the ventilation unit does not detach the device if the block configuration is valid.

Errors returned by the block

The block can display the following error messages:

Error code	Error description
`Invalid name configuration.`	The `name` parameter has an invalid type or format.
`Invalid device model configuration.`	The `deviceModel` parameter is missing, empty, has an invalid type, or points to a model unsupported by the current block version.
`Invalid device address configuration.`	The `deviceAddress` parameter is missing, has an invalid type, or is outside the allowed range. For `Systemair SAVE`, the allowed range is 1-247.
`Invalid refresh interval configuration.`	The `refreshInterval` parameter is missing, has an invalid type, or is outside the 1-3600000 ms range.
`Invalid response timeout configuration.`	The `responseTimeout` parameter is missing, has an invalid type, or is outside the 10-60000 ms range.
`Missing RS485 configuration.`	The `server` parameter is missing, empty, or does not point to an existing `modbus-client` block.
`Duplicated device address configuration.`	Another `modbus-ventilation` block uses the same `server` and `deviceAddress` pair.
`Invalid baudrate configuration.`	The common RS485 configuration does not contain a valid baudrate value.
`Baudrate configuration mismatch.`	The block uses an RS485 configuration inconsistent with other Modbus blocks in the project.
`Systemair SAVE requires RS485 baudrate 9600, 19200, 38400, 57600 or 115200.`	The RS485 configuration uses a baudrate outside the list allowed for `Systemair SAVE`.
`Invalid parity configuration.`	The common RS485 configuration does not contain a valid parity value.
`Parity configuration mismatch.`	The block uses parity inconsistent with other Modbus blocks in the project.
`Invalid stop bits configuration.`	The common RS485 configuration does not contain a valid stop bits value.
`Stop bits configuration mismatch.`	The block uses stop bits inconsistent with other Modbus blocks in the project.
`Invalid parity or stop bits configuration.`	The RS485 configuration combines parity other than `None` with two stop bits, which is not allowed by the shared RS485 layer of the project.
`Systemair SAVE requires RS485 stop bits 1.`	The RS485 configuration uses a stop bits value other than 1.

Examples

To show the ventilation unit humidity in the logic project, configure the input block for the relative_humidity property of the associated modbus-ventilation device.
To set the supply air temperature setpoint to 21.5°C, send the numeric value 21.5 to the supply_air_temperature_setpoint property through the output block or the virtual device interface.
To switch the ventilation unit to refresh mode, set the operation_mode property to refresh.
If several consecutive reads of the supply air temperature fail, the supply_air_temperature property becomes unknown, but the virtual device remains attached as long as the configuration is valid.