--- title: "RelaySimpleThermostat device" canonical: "https://docs.cuesystem.com/space/CVCDD/448004134/RelaySimpleThermostat%20device" format: markdown --- > Macro (toc) --- # Overview This device is used for relay control. It is connected to a *Relay *(*GeneralIO*, *DigitalIO*) connector of CUE unit. # Properties | | | | | | | --- | --- | --- | --- | --- | | Property Name | Data Type | Allowed Values | Default Value | Description | | ControlMode | Long | Open = 0 Close = 1 AutoScan = 2 ManualScan = 3 | 2 = AutoScan | Control mode | | SetpointTemperature | Double | Any | 21.0 | Setpoint (desired) temperature | | LowTemperatureRelayState | Boolean | Close Open | Close | State of the relay, if the real temperature is lower then the setpoint temperature | | TemperatureAutoScanPeriod | Time | Any | 0:2:0.0 | Period of time, in which the temperature is measured and the relay action is performed in the AutoScan mode | | TemperatureHysteresis | Double | Any | 0.5 | Temperature hysteresis for the regulation loop (see picture below) | | TemperatureSensorFailure RelayState | Boolean | Close Open | Open | State of the relay, if the temperature sensor does not work. | # Regulation ![image](media://0dbe3b85-a14f-4daa-80ac-bb35a620e090) In this picture you can see, how the relay state is changed when the real temperature changes in the time. States of the relay on the pictures are valid for the default value of LowTemperatureRelayState (Close). When you will change the property LowTemperatureRelayState to value Open, states of the relay will be opposite. # Control Modes The driver has the following control modes: - **Open **- in this control mode the output relay is permanently in the open state. There is no active regulation. - **Close **- in this control mode the output relay is permanently in the close state. There is no active regulation. - **AutoScan **– in this control mode the temperature is measured and the state of the relay is evaluated automatically with TemperatureAutoScanPeriod. This action is performed at the beginning of each period. This mode is useful for independent regulation of the heating source. The scan period starts when control mode is set to AutoScan (in case that this is the default state it begins when program starts) or if SetpointTemperature is changed. - **ManualScan **- in this mode the state of the relay is evaluated each time the Scan() function is called. This mode is useful if you need to synchronize the regulation actions for more heating sources. In this case it is necessary to create an event scheduler with required period in your application. Then you need to place the Scan() function for all required RelaySimpleThermostat devices to the event raised by this scheduler. # Global Functions ## SetSetpointTemperature This functions sets desired temperature in regulation loop to *newtemperature*. #### Syntax ```visualbasic SetSetpointTemperature (newtemperature As Double) ``` ## GetSetpointTemperature This functions returns current desired temperature. #### Syntax ```visualbasic GetSetpointTemperature () As Double ``` ## IsRelayClosed This functions returns true, if output relay is closed, otherwise it returns false. #### Syntax ```visualbasic IsRelayClosed () As Boolean ``` ## GetLastRealTemperature This functions returns last measured real temperature. This measuring is performed periodically in AutoScan mode or when function Scan () is called in other control modes. #### Syntax ```visualbasic GetLastRealTemperature () As Double ``` ## IsTemperatureMeasurementValid This functions returns true, if last temperature measurement was valid, otherwise it returns false. #### Syntax ```visualbasic IsTemperatureMeasurementValid () As Boolean ``` ## SetControlMode This function sets control mode to newcontrolmode. You can use named constants for newcontrolmode parameter (CONTROL_MODE_OPEN = 0, CONTROL_MODE_CLOSE = 1, CONTROL_MODE_AUTOSCAN = 2, CONTROL_MODE_MANUALSCAN = 3). The function returns True on success or False if an error occurs (parameter is out of limits). #### Syntax ```visualbasic SetControlMode (newcontrolmode As Long) As Boolean ``` #### Example ```visualbasic HVAC1.SetControlMode(HVAC1.CONTROL_MODE_AUTOSCAN) ``` ## GetControlMode This function returns current control mode. If control mode is AUTOSCAN, then it returns value 2. If control mode is MANUALSCAN, then it returns value 3, othewise it returns current state of relay (OPEN = 0, CLOSE = 1). If control mode is AUTOSCAN or MANUALSCAN, use function *IsRelayClosed *to get real relay state. #### Syntax ```visualbasic GetControlMode () As Long ``` ## Scan This function starts temperature measuring. In control mode Manual Scan it also evaluates output relay state. This function does not work in AutoScan control mode and it returns false when it is called in this mode. Function returns true in case of success or false if temperature measurement error occurs if other control mode is used. #### Syntax ```visualbasic Scan () As Boolean ``` # Global Events ## OnGetRealTemperatureRequest This event is generated by the driver and it joins the driver with the temperature sensor. It is important to correct link this event in your CVC program and to pass the real temperature from the temperature sensor to the *newrealtemperature *parameter. Return value of the function is true, if temperature measurement was valid, or false in case of temperature sensor failure. #### Syntax ```visualbasic OnGetRealTemperatureRequest As Function (ByRef newrealtemperature As Double) As Boolean ``` #### Example ```visualbasic Function HVAC1_OnGetRealTemperatureRequest (ByRef newrealtemperature As Double) As Boolean Link HVAC1.OnGetRealTemperatureRequest newrealtemperature := sensorCUE_W1.GetTemperatureCelsius() Return Value True End Function ``` If your temperature sensor has diagnostic functions, you can use this result in value returned by this function (if sensor works well, use *Return Value True*, in case of failure of the sensor, use *Return Value False)*. ## OnTemperatureChange This event is generated when the driver read real temperature from the temperature sensor or if the Setpoint Temperature is changed. You can use parameters *realtemperature *and *setpointtemperature *to display their values on the touch panel. #### Syntax ```visualbasic OnTemperatureChange As Process (realtemperature As Double, setpointtemperature As Double) ``` #### Example ```visualbasic Process HVAC1_OnTemperatureChange (realtemperature As Double, setpointtemperature As Double) Link HVAC1. OnTemperatureChange PageTemperature.ThermometerReal.SetValueCelsius(realtemperature) PageTemperature.ThermometerSetpoint.SetValueCelsius(setpointtemperature) End Process ``` ## OnRelayChange This event is generated when the driver sets a new state of the control relay. You can use parameter *relayisclosed *to display the relay state on the touch panel. #### Syntax ```visualbasic OnRelayChange As Process (relayisclosed As Boolean) ```