air-conditioner

Description

The air-conditioner block is used to integrate an air conditioner controlled over Modbus RTU via RS485. The block periodically reads the device state and allows it to be controlled from the logic project and through the associated vlogic virtual device.

The block supports five independent functional areas:

• reference temperature
• work mode
• blowing force
• current temperature
• device on/off state

Each of these areas can be enabled or disabled independently in the configuration. If a given area is disabled, the block does not read it from Modbus and does not react to commands related to it.

The block has one main input. It does not require the use of inputs labeled with the tag block and does not expose standard logic outputs. Its state is visible mainly through the virtual device associated with the block.

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

Configuration parameters

Parameter name	Value
Name (name)	Optional block name.
Device model (deviceModel)	Optional text passed to the virtual device as the air conditioner model.
Device address (deviceAddress)	Required Modbus slave address in the range 1 to 255.
Byte order (endianess)	Required method of interpreting multi-byte data. Allowed values: LittleEndian, BigEndian, SwapBytes, SwapWords.
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.

Reference temperature

Parameter name	Value
Enable reference temperature (enableReferenceTemperature)	Enables reading and writing of the reference temperature.
Reference temperature register address (referenceTemperatureRegisterAddress)	Register address in the range 0-65535.
Reference temperature function code (referenceTemperatureFunctionCode)	Read/write mode. Allowed values: 0x03/0x06 or 0x03/0x10.
Reference temperature value type (referenceTemperatureValueType)	Data type stored in the register. For 0x03/0x06, only SIGNED_NUMBER16 and UNSIGNED_NUMBER16 are allowed. For 0x03/0x10, the allowed values are SIGNED_NUMBER16, UNSIGNED_NUMBER16, SIGNED_NUMBER32, UNSIGNED_NUMBER32, and FLOAT.
Reference temperature multiplier/divisor (referenceTemperatureMultiplierDivisor)	Value in the range 1-4294967295. When reading, the value from Modbus is divided by this parameter. When writing, the reference temperature is multiplied by it.
Minimum reference temperature (referenceTemperatureMin)	Minimum allowed temperature value. It cannot be lower than 0°C.
Maximum reference temperature (referenceTemperatureMax)	Maximum allowed temperature value. It cannot be higher than 80°C.

The minimum temperature must be lower than the maximum temperature. If a value outside the configured range is sent to the input, the block does not report a user-visible error. Instead, it clamps the written value to the configured minimum or maximum.

Work mode

Parameter name	Value
Enable work mode (enableWorkMode)	Enables reading and writing of the work mode.
Work mode register address (workModeRegisterAddress)	Register address in the range 0-65535.
Work mode function code (workModeFunctionCode)	Allowed values: 0x03/0x06 or 0x03/0x10.
Work mode value type (workModeValueType)	Allowed values: UNSIGNED_NUMBER16 or UNSIGNED_NUMBER32.
Heating mode value (workModeHeatingValue)	Number written to the register for heating mode.
Cooling mode value (workModeCoolingValue)	Number written to the register for cooling mode.
Auto mode value (workModeAutoValue)	Number written to the register for auto mode.

At least 2 out of the 3 values heating, cooling, and auto must be configured.

Blowing force

Parameter name	Value
Enable blowing force (enableBlowingForce)	Enables reading and writing of the blowing force.
Blowing force register address (blowingForceRegisterAddress)	Register address in the range 0-65535.
Blowing force function code (blowingForceFunctionCode)	Allowed values: 0x03/0x06 or 0x03/0x10.
Blowing force value type (blowingForceValueType)	For 0x03/0x06, only UNSIGNED_NUMBER16 is allowed. For 0x03/0x10, the allowed values are UNSIGNED_NUMBER16 and UNSIGNED_NUMBER32.
Minimum blowing intensity (blowingForceMinimumIntensity)	Minimum allowed intensity value.
Maximum blowing intensity (blowingForceMaximumIntensity)	Maximum allowed intensity value.

The minimum intensity must be lower than the maximum intensity.

Current temperature

Parameter name	Value
Enable current temperature (enableCurrentTemperature)	Enables reading of the current temperature.
Current temperature register address (currentTemperatureRegisterAddress)	Register address in the range 0-65535.
Current temperature read function code (currentTemperatureReadFunctionCode)	Allowed values: 0x03 for holding registers or 0x04 for input registers.
Current temperature value type (currentTemperatureValueType)	Allowed values: SIGNED_NUMBER16, UNSIGNED_NUMBER16, SIGNED_NUMBER32, UNSIGNED_NUMBER32, FLOAT.
Current temperature divisor (currentTemperatureDivisor)	Value in the range 1-4294967295. After reading, the register value is divided by this parameter.

Device on/off state

Parameter name	Value
Enable device power control (enableOnOffDevice)	Enables reading and writing of the device on/off state.
Register or coil address (onOffDeviceRegisterAddress)	Address in the range 0-65535.
On/off function code (onOffDeviceFunctionCode)	Allowed values: 0x01/0x05, 0x03/0x06, 0x03/0x10.
On/off value type (onOffDeviceValueType)	Allowed values: UNSIGNED_NUMBER16 or UNSIGNED_NUMBER32.
Value representing the ON state (onDeviceValue)	Value written and recognized as the ON state.
Value representing the OFF state (offDeviceValue)	Value written and recognized as the OFF state.

The onDeviceValue and offDeviceValue values must be different. For the 0x01/0x05 mode, only the values 0 and 1 make sense.

Input handling

The block has one main input. The following data types are supported:

• cooling command from the command block: switches the device to cooling mode
• heating command from the command block: switches the device to heating mode
• auto command from the command block: switches the device to auto mode
• up command from the command block: increases the blowing force by 1
• down command from the command block: decreases the blowing force by 1
• logical value true: turns the device on
• logical value false: turns the device off
• numeric value: sets the reference temperature

Additional operating rules:

• The cooling, heating, and auto commands from the command block work only when work mode handling is enabled and the corresponding register value has been configured.
• The up and down commands from the command block work only when blowing force handling is enabled and the block knows the current value read from the device.
• up and down never go outside the configured minimum and maximum intensity range.
• A numeric value received at the input is interpreted as the reference temperature. When writing, the block limits it to the referenceTemperatureMin - referenceTemperatureMax range.
• Values that do not match any of the rules above are ignored.

The block does not use tag inputs.

Block outputs

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

The air conditioner state is exposed through the associated virtual device. This device provides:

• reference temperature
• allowed reference temperature range
• work mode and information about which modes are available
• blowing force together with the range of allowed values
• current temperature
• on/off state
• device model

Each of these values can have one of three states:

• valid value
• unknown value, when reading failed or the device returned data outside the expected range
• disabled value, when the given functional area was not enabled in the configuration

Block status description

The status visible below the block does not show the last read temperature or work mode. It is used mainly to indicate configuration problems and RS485 layer problems.

During normal operation, the block remains in the Working state. Errors from individual Modbus reads do not set a separate message below the block. In that situation, the corresponding value in the virtual device changes to the unknown state after the internal retry limit is exceeded.

Errors visible to the user

The block can display the following error messages:

Error code	Error description
Invalid name configuration.	The name parameter has an invalid format.
Invalid device model configuration.	The deviceModel parameter has an invalid format.
Invalid device address configuration.	The deviceAddress parameter is invalid or outside the 1-255 range.
Invalid endianess configuration.	The endianess parameter has an unsupported value.
Invalid refresh interval configuration.	The refreshInterval parameter is invalid or outside the 1-3600000 ms range.
Invalid response timeout configuration.	The responseTimeout parameter is invalid or outside the 10-60000 ms range.
Missing RS485 configuration.	The server parameter does not point to a valid modbus-client block.
Invalid enable reference temperature configuration.	The enableReferenceTemperature parameter is not a valid logical value.
Invalid reference temperature register address configuration.	The referenceTemperatureRegisterAddress parameter is invalid or outside the 0-65535 range.
Invalid reference temperature function code configuration.	The referenceTemperatureFunctionCode parameter has an unsupported value.
Invalid reference temperature value type configuration.	The referenceTemperatureValueType parameter is invalid or incompatible with the selected function code.
Invalid multiplier/divisor configuration.	The referenceTemperatureMultiplierDivisor parameter is invalid or outside the 1-4294967295 range.
Invalid reference temperature minimum value.	The referenceTemperatureMin parameter is invalid or lower than 0°C.
Invalid reference temperature maximum value.	The referenceTemperatureMax parameter is invalid or higher than 80°C.
Invalid reference temperature minimum/maximum values.	The minimum reference temperature is not lower than the maximum.
Invalid enable work mode configuration.	The enableWorkMode parameter is not a valid logical value.
Invalid work mode register address configuration.	The workModeRegisterAddress parameter is invalid or outside the 0-65535 range.
Invalid work mode function code configuration.	The workModeFunctionCode parameter has an unsupported value.
Invalid work mode value type configuration.	The workModeValueType parameter has an unsupported value.
Missing heating/cooling/auto value configuration.	Fewer than two modes among heating, cooling, and auto were configured.
Invalid enable blowing force configuration.	The enableBlowingForce parameter is not a valid logical value.
Invalid reference temperature register address configuration.	This message can also appear for an invalid blowingForceRegisterAddress parameter. Despite its name, it then refers to the blowing force register address.
Invalid blowing force function code configuration.	The blowingForceFunctionCode parameter has an unsupported value.
Invalid blowing force value type configuration.	The blowingForceValueType parameter is invalid or incompatible with the selected function code.
Invalid blowing force minimum intensity configuration.	The blowingForceMinimumIntensity parameter is invalid.
Invalid blowing force maximum intensity configuration.	The blowingForceMaximumIntensity parameter is invalid.
Invalid blowing force minimum/maximum intensity configuration.	The minimum blowing force is not lower than the maximum.
Invalid enable current temperature configuration.	The enableCurrentTemperature parameter is not a valid logical value.
Invalid current temperature register address configuration.	The currentTemperatureRegisterAddress parameter is invalid or outside the 0-65535 range.
Invalid current temperature read function code configuration.	The currentTemperatureReadFunctionCode parameter has an unsupported value.
Invalid current temperature value type configuration.	The currentTemperatureValueType parameter has an unsupported value.
Invalid current temperature divisor configuration.	The currentTemperatureDivisor parameter is invalid or outside the 1-4294967295 range.
Invalid enable on off device configuration.	The enableOnOffDevice parameter is not a valid logical value.
Invalid current temperature register address configuration.	This message can also appear for an invalid onOffDeviceRegisterAddress parameter. Despite its name, it then refers to the register or coil address responsible for turning the device on and off.
Invalid on off device function code configuration.	The onOffDeviceFunctionCode parameter has an unsupported value.
Invalid on off device value type configuration.	The onOffDeviceValueType parameter has an unsupported value.
Invalid on device value configuration.	The onDeviceValue parameter is invalid or incompatible with the selected write method.
Invalid off device value configuration.	The offDeviceValue parameter is invalid or incompatible with the selected write method.
Expected different on/off device value configuration.	onDeviceValue and offDeviceValue have the same value.
RS485 setup incomplete.	The runtime does not yet have a complete RS485 configuration.
RS485 port missing.	No RS485 port is available in the runtime for communication with the device.

Examples

• If the cooling command from the command block is sent to the main input, the block writes the value configured in workModeCoolingValue to the register.
• If the value true is sent to the main input, the block writes the ON state defined by onDeviceValue.
• If the number 31 is sent to the main input and the maximum reference temperature is 28, the block writes the value corresponding to 28 to the device.
• If the current blowing force is 2 and the up command from the command block is sent to the input, the new value is increased to 3, as long as it still fits within the allowed range.
• If current temperature reading is enabled but consecutive reads from the device keep failing, the virtual device shows this value as unknown instead of keeping the last failed read as if it were valid.