HVAC Configurations
What This Page Covers
This page explains how actuator outputs are configured for each operation mode of a virtual thermostat. It covers cooldown protection, hysteresis bands, output inversion, multi-stage setups and the binding model that connects physical HVAC equipment to the thermostat's control logic.
Actuator Configuration Model
Each operation mode (Heating, Cooling, Humidification, Dehumidification, Ventilation) on a thermostat carries its own actuator configuration. This configuration governs how the thermostat drives the bound physical outputs — relays, motorized valves, fan controllers — for that mode.
The configuration is stored on the operation mode endpoint and applies uniformly to all actuators bound to that mode.
Configuration Parameters
| Parameter | Type | Purpose |
|---|---|---|
cooldown | Integer (ms) | Minimum time between actuator state changes |
hysteresis | Float (°C / %RH) | Tolerance band around the setpoint |
separation | Integer | Separation value between heating and cooling setpoints |
invert | Boolean | Inverts the output signal |
initiallyDisabled | Boolean | Whether the actuator starts in a disabled state |
Cooldown
The cooldown parameter defines the minimum interval (in milliseconds) between consecutive actuator state changes. It protects HVAC equipment from rapid on/off cycling, which can damage compressors, shorten relay life and cause voltage spikes.
How it works:
- The thermostat turns an actuator on or off.
- A cooldown timer starts.
- Until the timer expires, the thermostat will not change the actuator state again — even if the measured value crosses the setpoint threshold.
- Once the cooldown period elapses, normal regulation resumes.
Typical values:
| Equipment Type | Recommended Cooldown |
|---|---|
| Compressor-based cooling | 180000–300000 ms (3–5 minutes) |
| Gas boiler | 120000–180000 ms (2–3 minutes) |
| Electric heater / relay | 30000–60000 ms (30–60 seconds) |
| Motorized valve | 10000–30000 ms (10–30 seconds) |
Shorter cooldowns allow tighter regulation but increase equipment wear. Longer cooldowns protect equipment at the cost of allowing the measured value to drift further from the setpoint between cycles.
Hysteresis
The hysteresis parameter defines a tolerance band around the setpoint to prevent oscillation. Without hysteresis, the actuator would toggle rapidly as the measured value fluctuates near the setpoint.
Heating example (setpoint = 21.0°C, hysteresis = 0.5°C):
ON threshold: 20.5°C (setpoint - hysteresis)
OFF threshold: 21.0°C (setpoint)
Temperature
21.5 ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
21.0 ─ ─ ─ ─ ─ ─ ─ ─ OFF ─ ─ ─ ─ ─ ─ ← setpoint
20.5 ─ ─ ON ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ← setpoint - hysteresis
20.0 ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
- Heating turns on when the temperature drops below
setpoint - hysteresis. - Heating turns off when the temperature reaches the setpoint.
Cooling example (setpoint = 24.0°C, hysteresis = 0.5°C):
- Cooling turns on when the temperature rises above
setpoint + hysteresis. - Cooling turns off when the temperature drops to the setpoint.
The same logic applies to humidity-based modes using %RH values.
Choosing a hysteresis value:
| Situation | Recommended Hysteresis |
|---|---|
| Underfloor heating (slow response) | 0.5–1.0°C |
| Radiator heating (moderate response) | 0.3–0.5°C |
| Forced-air systems (fast response) | 0.2–0.3°C |
| Humidity control | 2–5 %RH |
Larger hysteresis values reduce cycling frequency but allow wider temperature swings. Smaller values maintain tighter control but increase actuator switching.
Separation
The separation parameter defines the minimum gap between heating and cooling setpoints when both modes are configured on the same thermostat. This prevents the thermostat from simultaneously activating heating and cooling equipment when their setpoints are too close together.
For example, with a separation value of 2 and a heating setpoint of 21°C, the cooling setpoint cannot be set below 23°C.
Output Inversion
The invert parameter reverses the meaning of the actuator's on/off signal. This accommodates equipment that uses normally-open vs. normally-closed valve logic.
Default inversion by mode:
| Mode | Default invert Value | Reason |
|---|---|---|
| Heating | false | ON = heat is being delivered |
| Cooling | true | ON = cooling is active (inverted signal for NC valves) |
| Humidification | false | ON = humidification active |
| Dehumidification | true | ON = dehumidification active (inverted for NC valves) |
| Ventilation | false | ON = ventilation active |
When invert = true, the thermostat sends an OFF command when it wants the equipment to activate, and an ON command when it wants the equipment to stop. This is the standard behaviour for normally-closed valves that open when de-energized.
Initially Disabled
When initiallyDisabled is set to true, the operation mode starts in a disabled state after thermostat creation or system restart. The mode must be explicitly enabled before it will regulate. This is useful for seasonal equipment (e.g. cooling that should not activate until manually enabled in summer).
Binding Actuators to Operation Modes
Actuator endpoints are bound to a thermostat's operation mode using the output binding API. Because the thermostat operates on the normalized device model, any actuator endpoint can be bound regardless of its underlying protocol — Z-Wave relays, Zigbee valves, KNX outputs and wired contacts all appear as uniform endpoints. Each operation mode maintains its own list of bound actuators.
Binding Model
Thermostat
└── Operation Mode (e.g. HEATING)
├── Output: Relay endpoint (boiler circuit)
├── Output: Valve endpoint (radiator zone 1)
└── Output: Valve endpoint (radiator zone 2)
When the thermostat determines that the mode should be active, all bound actuators for that mode receive the appropriate command simultaneously.
Multi-Mode Configuration
A single thermostat can have multiple operation modes configured concurrently. The master control determines which mode is currently active.
Example — heating and cooling on one thermostat:
Thermostat "Living Room Climate"
├── HEATING mode
│ ├── Cooldown: 120000 ms
│ ├── Hysteresis: 0.5°C
│ ├── Invert: false
│ └── Outputs: underfloor heating valve, radiator valve
│
└── COOLING mode
├── Cooldown: 300000 ms
├── Hysteresis: 0.5°C
├── Invert: true
└── Outputs: AC compressor relay, fan relay
The master control switches between modes manually or via schedule. Only one mode is active at a time — heating and cooling do not run simultaneously.
Control Loop Summary
The thermostat control loop uses the configuration parameters together:
- Read the current sensor value (temperature or humidity).
- Compare against the active setpoint, applying the hysteresis band.
- Decide whether actuators should be on or off.
- Check if the cooldown period has elapsed since the last state change.
- Apply the inversion setting and send the command to all bound actuators.
- Repeat continuously on the edge runtime.
This loop runs locally on the Zipabox, ensuring climate regulation continues even when cloud connectivity is unavailable.
Where to Continue
| Goal | Page |
|---|---|
| Understand the thermostat model and operation modes | Overview |
| Configure time-based schedules and profiles | Scheduling |
| Learn how physical devices are normalized for binding | Device Normalization |