ha-hiq

Supported devices

This integration enables basic support for HIQ-Controllers (Cybro 2/3 PLC with HIQ software running on it from Robotina D.o.o or Cybrotech).

Functionality

This integration is a local polling integration that connects to a running CybroScgiServer from Cybrotech. To use this integration you need to have a running scgi server. Please use one of the 3 methods to run the scgi server. Without a running scgi server it is not possible to use this integration!

• Homeassistant Addon CybroScgiServer (Recommended)

  

• Own Docker container on own Docker host.

  

• Native manual install from source.

If you had a running CybroScgiServer (from one of the 3 possibilities from above), you can continue and add this integration to Home Assistant from the HACS-store.

Supported entities

During creation of the device it scans for supported device types and creates it in home assistant. If the general_error of the HIQ expansion unit is set, the device will be ignored (Default behaviour of hiq software).

Currently supported are:

• light
• cover
• climate
• binary_sensor
• sensor
• number
• select
• switch
• button

---

light

Supported HIQ expansion units:

• LC-10-IQ (light on / off supported)
• LC-8-IQ (light on / off supported)
• LD-D10-IQ (light on / off, brightness and RGB supported)
• LD-D8-IQ (light on / off and brightness supported)
• LD-P4-IQ (light on / off, brightness and RGB supported)
• LD-V4-IQ (light on / off, brightness and RGB supported)
• Virtual LC (light on / off supported)

---

cover

Blinds in the HIQ controller are called cover devices in HA.

Supported HIQ expansion units:

• BC-5-IQ
• Virtual BC

Possible commands for the blinds are:

• open cover
• close cover
• stop cover
• set position

---

climate

TH (thermostat) devices in the HIQ controller are called climate devices in HA.

Supported HIQ expansion units:

• TH-X-IQ

Possible commands for the thermostats are:

• Turn heating / cooling on / off
• Set setpoint temperature
• Set presets eco (idle) / comfort (on) / boost (fan max)

---

binary_sensor

To have a basic diagnostic, there are some binary_sensor Entities exposed.

For the controller:

Entity name	Description	Enabled
cXXXX.general_error	Logical or of IEX general errors, indicates that at least one module has an error.	yes
cXXXX.retentive_fail	Indicates that retentive memory failed.	yes
cXXXX.scan_overrun	Too long scan execution caused scan overrun error.	yes

For every IEX expansion unit:

Entity name	Description	Enabled
cXXXX.YYYY_general_error	Combined system error (timeout or program error), module is not operational.	yes

For TH (thermostat) expansion unit:

Entity name	Description	Controller var	Enabled
cXXXX.thYY thermostat window	Indicate state of window switch input.	cXXXX.thYY_ix00	if configured
cXXXX.thYY thermostat output	Radiator output.	cXXXX.thYY_output	yes

XXXX is the NAD of the controller, and YYYY is the IEX module prefix

---

sensor

To have a basic diagnostic, there are some sensor Entities exposed.

It is also possible to add custom sensors from variables in the HIQ controller. To add custom sensors, navigate to HIQ integration and click on configure.

For the controller:

Entity name	Description	Enabled
cXXXX.scan_time	Last scan execution time [ms].	no
cXXXX.scan_time_max	Maximal scan execution time encountered since program started [ms].	no
cXXXX.scan_frequency	Actual number of scans per second.	no
cXXXX.cybro_power_supply	Measured power supply voltage [V]. Measuring range is 0..40V.	no
cXXXX.cybro_uptime	Number of operating hours since power-on [h].	no
cXXXX.operating_hours	Total number of operating hours [h].	no
cXXXX.sys.ip_port	IP address and UDP port of the controller.	no

For every IEX expansion unit:

Entity name	Description	Enabled
cXXXX.YYYY_iex_power_supply	Measured power supply voltage [V]. Measuring range is 0..40V.	no

power meter:

In presence of a power meter, it will add the following Entities:

Entity name	Description	Enabled
cXXXX.power_meter_power	Measured power consumption [W].	yes
cXXXX.power_meter_energy	Energy consumption total [kWh].	yes
cXXXX.power_meter_voltage	Measured AC voltage [V].	no

temperatures:

In presence of expansion units with temperature / humidity sensors, it will add the following Entities:

Entity name	Description	Enabled
cXXXX.YYYY_temperature	Measured temperature [°C].	if module has no general_error
cXXXX.YYYY_humidity	Measured relative humidity (0..100%rh).	if module has no general_error

For every TH (thermostat) expansion unit:

Entity name	Description	Controller var	Enabled
cXXXX.thYY thermostat temperature	Measured temperature (internal, external or remote).	cXXXX.thYY_temperature	yes
cXXXX.thYY thermostat temperature 1	Measured external temperature.	cXXXX.thYY_temperature_1	yes
cXXXX.thYY thermostat humidity	Measured relative humidity.	cXXXX.thYY_humidity	yes

For hvac (internal):

Entity name	Description	Controller var	Enabled
cXXXX.thYY HVAC outdoor temperature	Measured outdoor temperature.	cXXXX.outdoor_temperature	if zz_enable is set
cXXXX.thYY HVAC wall temperature	Measured temperature within building construction.	cXXXX.wall_temperature	if zz_enable is set
cXXXX.thYY HVAC water temperature	Measured temperature of heating/cooling medium.	cXXXX.water_temperature	if zz_enable is set
cXXXX.thYY HVAC auxilary temperature	Measured temperature of auxilary sensor.	cXXXX.auxilary_temperature	if zz_enable is set

XXXX is the NAD of the controller, and YYYY is the IEX module prefix (eg: lc00, bc02..)

---

number

To set some parameters in the controller, there are some number Entities exposed.

For every TH (thermostat) expansion unit:

Entity name	Description	Controller var
cXXXX.thYY thermostat setpoint idle	Secondary setpoint, used when thermostat is off. Zero means output is off.	cXXXX.thYY_setpoint_idle
cXXXX.thYY thermostat setpoint idle cooling	Secondary setpoint for cooling, used when thermostat is off. Zero means output is off.	cXXXX.thYY_setpoint_idle_c
cXXXX.thYY thermostat setpoint idle heating	Secondary heating setpoint, used when thermostat is off. Zero means output is off.	cXXXX.thYY_setpoint_idle_h
cXXXX.thYY thermostat setpoint offset	Setpoint correction, used to affect regulated temperature without changing setpoint.	cXXXX.thYY_setpoint_offset
cXXXX.thYY thermostat setpoint offset cooling	Setpoint correction for cooling, used to affect regulated temperature without changing setpoint.	cXXXX.thYY_setpoint_offset_c
cXXXX.thYY thermostat setpoint offset heating	Setpoint correction for heating, used to affect regulated temperature without changing setpoint.	cXXXX.thYY_setpoint_offset_h
cXXXX.thYY thermostat hystheresis	Hysteresis for on/off regulation. Defined as distance between on and off points.	cXXXX.thYY_setpoint_hystheresis
cXXXX.thYY thermostat hystheresis cooling	Hysteresis for on/off regulation in cooling mode. Defined as distance between on and off points.	cXXXX.thYY_setpoint_hystheresis_c
cXXXX.thYY thermostat hystheresis heating	Hysteresis for on/off regulation in heating mode. Defined as distance between on and off points.	cXXXX.thYY_setpoint_hystheresis_h
cXXXX.thYY thermostat activation time max function	Activation period for max function [s].	cXXXX.thYY_max_time
cXXXX.thYY thermostat activation time max function cooling	Activation period for max function in cooling [s].	cXXXX.thYY_max_time_c
cXXXX.thYY thermostat activation time max function heating	Activation period for max function in heating [s].	cXXXX.thYY_max_time_h
cXXXX.thYY thermostat max temp external	External sensor max temperature setpoint.	cXXXX.thYY_max_temp

By default all of the number entities are disabled.

Note: Not all entities are supported by stock HIQ firmware! Some of them are additions to HIQ functionality.

---

select

To set some parameters in the controller, there are some select Entities exposed.

For every TH (thermostat) expansion unit:

Entity name	Description	Controller var
cXXXX.thYY thermostat temperature source	Source of measured temperature: 0-internal sensor, 1-external sensor, 2-remote from another device.	cXXXX.thYY_temperature_source
cXXXX.thYY thermostat display mode	Select what to display when thermostat is off: 0-nothing, 1- ---, 2-temperature.	cXXXX.thYY_display_mode

For hvac (internal):

Entity name	Description	Controller var
cXXXX HVAC mode	Hvac mode: 0-off, 1-heating, 2-cooling.	cXXXX.hvac_mode
cXXXX HVAC thermostat config display mode	What to display when thermostat is off: 0-nothing, 1-dashes, 2-temperature.	cXXXX.hvac_display_mode
cXXXX HVAC thermostat config temperature source	Select temperature source: 0-internal, 1-external, 2-remote from controller.	cXXXX.hvac_temperature_source

By default all of the select entities are disabled.

Note: Not all entities are supported by stock HIQ firmware! Some of them are additions to HIQ functionality.

---

switch

To set some parameters in the controller, there are some switch Entities exposed.

For every TH (thermostat) expansion unit:

Entity name	Description	Controller var
cXXXX.thYY thermostat window switch enable	Select how window switch input is handled: 0-ignore input, 1-use input to disable thermostat.	cXXXX.thYY_window_enable
cXXXX.thYY thermostat demand enable	Enable thermostat to control energy source: 0-off, 1-on.	cXXXX.thYY_demand_enable

For hvac (internal):

Entity name	Description	Controller var
cXXXX HVAC outdoor temperature enable	Enable outdoor temperature measurement: 0-off, 1-on.	cXXXX.outdoor_temperature_enable
cXXXX HVAC wall temperature enable	Enable wall temperature measurement: 0-off, 1-on.	cXXXX.wall_temperature_enable
cXXXX HVAC water temperature enable	Enable water temperature measurement: 0-off, 1-on.	cXXXX.water_temperature_enable
cXXXX HVAC auxilary temperature enable	Enable auxilary temperature measurement: 0-off, 1-on.	cXXXX.auxilary_temperature_enable
cXXXX HVAC automatic setpoint limits enable	Automatically set when operation mode is changed between heating and cooling.	cXXXX.auto_limits_enable
cXXXX HVAC thermostat fan option speed auto 1	Enable fan speed auto 1.	cXXXX.hvac_fan_option_b01
cXXXX HVAC thermostat fan option speed auto 2	Enable fan speed auto 2.	cXXXX.hvac_fan_option_b02
cXXXX HVAC thermostat fan option speed auto 3	Enable fan speed auto 3.	cXXXX.hvac_fan_option_b03
cXXXX HVAC thermostat fan option speed max	Enable fan speed max.	cXXXX.hvac_fan_option_b04

By default all of the switch entities are disabled.

Note: Not all entities are supported by stock HIQ firmware! Some of them are additions to HIQ functionality.

---

button

To save / read parameters in the expansion units, there are some button Entities exposed.

For every TH (thermostat) expansion unit:

Entity name	Description	Controller var
cXXXX HVAC thYY config request	Set to update configuration parameters. It will reset automatically after sending.	cXXXX.thYY_config1_req
cXXXX HVAC thYY config read back request	Request to read options back from thermostat.	cXXXX.thYY_options_back_req

By default all of the button entities are disabled.

Note: Not all entities are supported by stock HIQ firmware! Some of them are additions to HIQ functionality.

---

Common Attributes

Attribute	Example Values (comma separated)
description	the description text from the PLC tag

Devices

A device is created for each HIQ-controller (diagnostics) and for every light, blind, thermostat and HVAC.

---

Services

To forward some smartphone events directly to the HIQ-controller some services are exposed.

Service	Description
Presence signal	Set the smartphone presence signal
Charge on event	Set the smartphone charge on (connect charger) event
Charge off event	Set the smartphone charge off (disconnect charger) event
Home event	Set the smartphone home event
Precede event	Set the smartphone Precede event (used in advance for triggering some actions before the alarm occurs)
Write tag	Write a custom tag with a custom value in the controller (any accessible tag is allowed)

{% if not installed %}

Installation

HACS

1. Install HACS
2. Go to HACS "Integrations >" section
3. In the lower right click "+ Explore & Download repositories"
4. Search for "HIQ" and add it
5. Restart Home Assistant
6. In the Home Assistant (HA) UI go to "Configuration"
7. Click "Integrations"
8. Click "+ Add Integration"
9. Search for "HIQ"

Manual

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called hiq.
4. Download all the files from the custom_components/hiq/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant
7. In the Home Assistant (HA) UI go to "Configuration"
8. Click "Integrations"
9. Click "+ Add Integration"
10. Search for "HIQ"

{% endif %}

Configuration (Important! Please Read)

Config is done in the HA integrations UI.

Disable new entities

If you prefer new entities to be disabled by default:

1. In the Home Assistant (HA) UI go to "Configuration"
2. Click "Integrations"
3. Click the three dots in the bottom right corner for the HIQ integration
4. Click "System options"
5. Disable "Enable newly added entities"

Tested Devices

• HC-HIQ v3.0.3 Software running on a Cybro-3 controller with FW: 3.2.3, cybroscgiserver v3.1.3 running in a docker container

Contributions are welcome!

If you want to contribute to this please read the Contribution guidelines

Credits

Code template was mainly taken from @amosyuen's ha-tplink-deco integration

---