Hysteresis controllers — also called bang-bang controllers — are the right choice whenever your actuator can only be fully on or fully off. This includes relays, smart plugs, solenoid valves, and contactors. Unlike a PID controller, which produces a continuous output that varies between 0% and 100%, a hysteresis controller outputs a simple true/false signal: the device is either running or it is not.
LoopString includes two hysteresis controller parts: the generic Hysteresis (Bang-Bang) Controller for everyday on/off applications, and the HVAC Hysteresis Controller for air conditioners, heat pumps, refrigeration units, and any other equipment where compressor short-cycling can cause hardware damage.
Controller Selection Decision Tree
Before adding a controller to your project, answer these questions in order:
1. Can your actuator vary its output continuously?
If your actuator accepts a PWM signal, 0–10 V analog input, or a 4–20 mA signal, it can follow a variable output. Choose a PID Controller. Examples: variable-speed fan, chiller with analog control, servo valve.
If your actuator is binary — it is either on or off — continue to question 2. Examples: relay, smart plug, solenoid valve, contactor.
2. Are you controlling a compressor-based system?
If yes — air conditioner, heat pump, mini-split, refrigeration unit, chiller with a compressor — choose the HVAC Hysteresis Controller. Compressors must not be started and stopped rapidly; the minimum run time and minimum off time settings prevent this.
If no — a simple heater, heat mat, reptile lamp, fan, solenoid irrigation valve, or relay-controlled device — choose the Hysteresis (Bang-Bang) Controller.
Quick reference:
- Variable-speed fan or chiller → PID Controller
- PWM heater element → PID Controller
- Relay-controlled heater, heat mat, or lamp → Hysteresis (Bang-Bang) Controller
- Simple on/off fan → Hysteresis (Bang-Bang) Controller
- AC unit via Kasa smart plug → HVAC Hysteresis Controller
- Heat pump or mini-split → HVAC Hysteresis Controller
- Refrigeration or chest freezer → HVAC Hysteresis Controller
How Hysteresis Control Works
A hysteresis controller holds a target setpoint and a deadband — a tolerance zone on either side of that setpoint. The controller watches the sensor reading and switches the actuator based on which boundary is crossed.
In heating mode:
- The actuator turns ON when the sensor reading drops below the setpoint minus the lower deadband.
- The actuator turns OFF when the sensor reading rises above the setpoint plus the upper deadband.
In cooling mode (or when thinking of the output as "reduce the measured value"):
- The actuator turns ON when the reading rises above the setpoint plus the upper deadband.
- The actuator turns OFF when the reading drops below the setpoint minus the lower deadband.
The deadband is intentional. Without it, the controller would switch on and off constantly every time the sensor reading fluctuated by even a fraction of a degree — a condition called rapid cycling or chattering. The deadband creates a stable zone where the actuator does nothing, letting the reading drift slightly while keeping energy use and wear reasonable.
Oscillation within the deadband is completely normal. If your fermentation chamber cycles between 19.5 °C and 20.5 °C when your setpoint is 20 °C with a 0.5 °C deadband on each side, the controller is working correctly.
Hysteresis (Bang-Bang) Controller
This is the general-purpose version. Use it for fermentation temperature control, terrariums, reptile enclosures, incubators, simple HVAC fans, irrigation solenoids, and any other application where the actuator is a plain relay or smart plug and no compressor is involved.
Configuration Options
Setpoint The target value you want the controlled parameter to reach and hold. For temperature control this is in degrees; for humidity control this is in percent. Default is 20.
Deadband High How far above the setpoint the reading must go before the actuator turns off (in heating mode) or turns on (in cooling mode). Smaller values mean tighter control but more frequent switching. Default is 0.5. Minimum is 0.1.
Deadband Low How far below the setpoint the reading must drop before the actuator turns on (in heating mode) or turns off (in cooling mode). Can be set independently from Deadband High. Default is 0.5. Minimum is 0.1.
The total deadband width is Deadband Low plus Deadband High. With defaults of 0.5 each, the deadband spans 1.0 unit total — meaning the reading can drift 1 full degree (or percent, or whatever your sensor measures) before the actuator changes state.
Wiring in the Configurator
This is a software-only part — no physical pins. In the flow editor:
- Add a Hysteresis (Bang-Bang) Controller part to your room.
- Wire the output of your sensor part (for example, a DS18B20 temperature sensor) to the input of the controller.
- Wire the output of the controller to an actuator part (for example, a Kasa Smart Plug or GPIO relay node).
- Set the Setpoint and Deadband values to match your application.
- Deploy the flow to your Pi.
HVAC Hysteresis Controller
The HVAC variant adds two critical protections that prevent compressor damage in air conditioners, heat pumps, mini-splits, and refrigeration units.
Minimum Run Time — Once the compressor starts, it must run for at least this long before it can be turned off, even if the setpoint is already satisfied. This ensures the refrigerant cycle completes fully and the system reaches thermal equilibrium. Stopping too early traps high-pressure refrigerant that causes liquid slugging when the compressor restarts. Default is 5 minutes (300,000 ms).
Anti-Short-Cycle Protection — After the compressor stops, the controller will not restart it until the minimum run time has elapsed. This gives the compressor time to equalize pressure before the next start. Without this, rapid on/off cycles can overheat the compressor motor, trip thermal cutouts, and eventually burn out the windings.
This is the part that should be used whenever you connect a Kasa smart plug (or any other smart outlet) to an air conditioner or heat pump. If you use the generic Hysteresis Controller or a PID Controller with a binary actuator for this application, the AC unit may short-cycle and sustain compressor damage.
Configuration Options
Setpoint The target temperature or humidity value. Default is 22.
Upper Deadband How far above the setpoint the reading must rise before the system turns off (cooling mode) or on (heating mode). Default is 1.0. Minimum is 0.1.
Lower Deadband How far below the setpoint the reading must drop before the system turns on (cooling mode) or off (heating mode). Default is 1.0. Minimum is 0.1.
Minimum Run Time Minimum duration the compressor stays on after starting. Expressed in milliseconds in the flow, but the Configurator accepts human-readable values like 5 minutes. Default is 300,000 ms (5 minutes). For residential AC units 3–5 minutes is typical; for commercial refrigeration 5–10 minutes is common.
Wiring in the Configurator
- Add an HVAC Hysteresis Controller part to your room.
- Wire the temperature or humidity sensor output to the controller input.
- Wire the controller output to a Kasa Smart Plug actuator (or another binary actuator controlling your AC unit or heat pump).
- Set the Setpoint and Deadband values. For an AC unit maintaining 22 °C, a deadband of 1.0 on each side gives a 2 °C operating range (the AC runs until the room reaches 21 °C, then stays off until it reaches 23 °C).
- Set the Minimum Run Time. Start with 5 minutes and adjust only if your equipment manufacturer specifies a different value.
- Deploy.
Use Cases
AC Unit via Kasa Smart Plug
A mushroom grow room uses a window AC unit plugged into a Kasa KP115 smart plug. The room needs to hold 18 °C for fruiting.
Parts used: BME680 temperature sensor, HVAC Hysteresis Controller, Kasa KP115 Smart Plug actuator.
Configuration: Setpoint 18 °C, Upper Deadband 1.0, Lower Deadband 1.0, Minimum Run Time 5 minutes.
Behavior: The AC turns on when the room exceeds 19 °C. Once running, it stays on for at least 5 minutes even if the room quickly cools back to 18 °C. The AC turns off when the room drops below 17 °C. It will not restart for 5 minutes after stopping.
Why not PID? The Kasa plug is binary — it has no variable output. A PID controller computing, say, 42% output has no meaning to a relay. The PID would effectively act as a bang-bang controller but without compressor protection, producing rapid cycling that damages the unit.
Fermentation Heat Mat
A homebrewing setup ferments lager at 10 °C using a heat mat wrapped around a carboy.
Parts used: DS18B20 1-Wire temperature sensor, Hysteresis (Bang-Bang) Controller, GPIO relay.
Configuration: Setpoint 10 °C, Deadband High 0.3, Deadband Low 0.3.
Behavior: The heat mat turns on when the fermenter drops below 9.7 °C and off when it rises above 10.3 °C. The 0.6 °C total swing is tight enough for lager fermentation while still avoiding excessive relay cycling.
Why not the HVAC controller? A heat mat is resistive — it has no compressor and no refrigerant. There is no hardware risk from short-cycling. The simpler generic controller is appropriate.
Troubleshooting
The actuator is cycling on and off very rapidly
This means the deadband is too narrow for the thermal mass and response time of your system. If the sensor is reading 20.0, 20.1, 19.9, 20.0 several times per minute, a deadband of 0.1 will switch the actuator with every fluctuation.
Increase both the Deadband High and Deadband Low values. A starting point for most applications is 0.5 for each. For large spaces or high-mass systems (fermenters, aquariums), 1.0 or more may be appropriate. Rapid cycling causes unnecessary relay wear, smart-plug switching events, and compressor damage.
The HVAC controller is not responding to the sensor
Check that the sensor output signal type matches the controller's expected input. The HVAC Hysteresis Controller expects a numeric value on its input. If your sensor outputs a value-unit object (some sensors do), you may need to add a function node or signal adapter between the sensor and controller output to extract just the numeric value.
Also verify the flow was deployed after any wiring changes. The Configurator flow editor shows the intended wiring, but changes only take effect after you press Deploy and the Pi confirms the new flow is running.
The controller output appears stuck — the actuator never turns on or off
If the actuator appears permanently on or permanently off, check whether the controller is in the locked-out state due to Minimum Run Time. During the lockout window the controller will not switch the actuator even if the deadband thresholds are crossed. This is intentional behavior.
If the lockout window has passed and the actuator still does not respond, confirm the wiring between the controller output and the actuator input in the flow editor. A missing wire connection means the actuator never receives the boolean signal the controller is producing.
The temperature is consistently above or below the setpoint
The hysteresis controller does not have an integral term — it does not "learn" from persistent error the way a PID does. If your actuator is undersized for the load (for example, a small heat mat trying to hold temperature in a very cold environment), the controlled value may settle at a point consistently on one side of the deadband.
Solutions: increase actuator capacity, reduce thermal losses from the enclosure, or reconsider whether a variable-output actuator with a PID controller would be more effective.
Known Issues and Limitations
No integral correction — A hysteresis controller cannot compensate for steady-state offset caused by a mismatched load. If the heater cannot keep up with heat loss, the temperature will sit below the setpoint. This is a fundamental property of bang-bang control, not a bug.
Sensor noise can cause unnecessary switching — If your sensor has high-frequency noise, small deadband values may cause the controller to switch even when the actual temperature is stable. Adding a small moving-average filter node upstream of the controller in the flow editor can smooth out noisy readings.
Minimum Run Time is Pi-side only — The minimum run time logic runs on the Raspberry Pi inside Node-RED. If the Pi restarts, the minimum run time timer resets. On restart, the compressor protection window starts fresh, which means a compressor that was recently stopped could restart immediately after a Pi reboot. If uptime is critical, consider adding a startup delay inject node before the controller input.
The HVAC controller does not detect compressor mode — The controller does not know whether the connected AC unit is in heating or cooling mode, or whether it has its own internal thermostat. Set the controller's Setpoint and Deadband to complement the AC unit's internal settings, not to fight them.
Related Documentation
For applications where your actuator supports variable output, see PID Controllers and Setpoints.