US Heat Pump with gas aux

N0YKG · March 16, 2025, 2:12pm

I have one of the original HestaPI units, but never put it in place because I have a US style heat pump with propane auxiliary heat, and I could never find out how to configure the HestaPI to support that. It has a line to start the compressor, a line for the reversing valve, a fan line, and a line to turn on the gas heat.
Ideally, I want to have the device use the heat pump for heating unless one of the following is true:

External temperature (as fetched from some external source e.g. NOAA) is below 10F
Delta between setpoint and internal temperature is greater than 10F (e.g. during a transition from nighttime to daytime heat settings)
When forced by an override (for use during power failures where the backup generator has enough power for the fans but not the compressor).

Bonus points would be for having an addition mode where the auxiliary heat is disabled, and ONLY the heat pump may be used (for when the propane delivery is late and I’m running out).

I’ve done some searching and I don’t see any other posts that cover this use case.

hestia_hacker · March 16, 2025, 4:12pm

I think this is doable with some customization.

There is a 2nd stage heating built in, which is similar to what it sounds like you are looking for. It will use the main heart (your heat pump) unless it can’t keep up, then it’ll also turn on the auxillary heat (gas). The way it’s currently implemented in the HestiaPi is that if the heat has been on for a while and it’s still not up to the set point, it’ll turn on the seconds stage until it gets to where it should be.

The main issue is that most thermostats, including the HestiaPi, expect turning the heat on to be a single relay. I’m not quite sure I followed how your system works with the reversing valve, but it seems pretty clear that’s not the case with your system.

As I see it, there are two options:

Change to code that turns on the heat, the second stage, and the cooling, or
Build some hardware so a single relay will control the heat pump, another relay will control the gas heater, and a third one will control the cooling

Pure software solution

It sounds like your system is controlled by 4 relays, which matches what the HestiaPi has. If I understood correctly, it should look like this:

Normal heating
- heat pump: on
- reversing valve: off
- fan: on
- gas heater: off
Second stage heating
- heat pump: on?
- reversing valve: off
- fan: on
- gas heater: on
Cooling
- heat pump: on
- reversing valve: on
- fan: on
- gas heater: off
Fan
- heat pump: off
- reversing valve: off
- fan: on
- gas heater: off
Off
- heat pump: off
- reversing valve: off
- fan: off
- gas heater: off

If that’s correct then this is totally doable. And if I have the reversing valve backwards, let me know, that’s easy enough to fix.

Hardware solution

This option is interesting because it would not only make your HVAC compatible with the stock HestiaPi, buy it would also make it compatible with and standard thermostat.

Basically it would have 3 inputs (heating, 2nd stage, cooling) and then would control each of the components. The fan would just connect directly.

It would take some thought, but it should be a pretty simple circuit in the end. Just a bunch of relays and some kind of power supply (possibly powered by the HVAC lines, depending on if you have a common wire or not).

Second stage logic

Whether going the software or hardware route, the logic to control when the second stage kicks in will need some work. I like what you have in mind and it should be fairly straight forward to implement.

However I’d suggest we focus on the control parts first. It’s getting to be spring, so second stage heating shouldn’t be urgent at this time of year. Plus you can always adjust your set point to kind of get what you want until you’ve implemented what you actually want.

Once the basics are covered, then we can do the improved logic for when to turn on the second stage.

Questions

Are you more interested in the software solution or the hardware option? I can help with either.

Do you know how to read or write Javascript code? I ask because most of the control logic is written in JS.

Comments

I’m also personally interested in more advanced logic for multi-stage heating (and cooling). I have a ground source heat pump that has 3 stage heating and 2 stage cooling.

It also is not controlled by relays, but rather some propritary ModBus over RS485 junk. So before I can use more advanced multi-stage heating/cooling, I need to find a way interface with the HVAC unit (there’s an existing project to help with this). I also want to upgrade to Debian 12, and have the option to run OpenHAB on another machine (rather than ruining on the thermostat itself).

So in other words, there’s a lot vying for my time on this project alone. But, fear not, I make supporting others a priority.

N0YKG · March 16, 2025, 5:12pm

My system is already compatible with the US standard, so I have no reason to change it.
The truth table for a standard US system like this is:
State | Compressor | Reversing | Fan | Aux
Cool | ON | off | ON | off
Fan | off | off | ON | off
Heat | ON | ON | ON | off
Gas heat | off | off | ON | ON
IDLE | off | off | off | off

Then basically:
doThermostat()
{
if SetpointLo - Internal > swing
CallForHeat();
else if Internal - SetpointHi > swing
CallForCool();
else if Mode = Fan
HwState(Fan);
else HwState(Idle);
}

CallForHeat()
{
if (ouside < -10C)
HwState(Gas Heat);
else if (Emergency)
HwState(Gas Heat);
else if (Low Fuel)
HwState(Heat);
else if (SetPointLo - internal > 10C)
HwState(Gas Heat);
else
HwState(Heat);
}
CallForCool()
{
if (Emergency)
return;
HwState(Cool);
}

Mostly, I just need to know where any changes need to go. Is this all controlled by some form of config file (e.g. XML), or is this all code.
As for languages: I’m fluent in C++20, Javascript, Perl, Python, Shell Scripting, TCL, C# - I just need to know what to change.

hestia_hacker · March 16, 2025, 5:40pm

Awesome. The code is technically stored in /var/lib/openhab2/jsondb/automation_rules.json but you’ll probably want to update it via the OpenHAB PaperUI (under Configuration → Rules, IIRC).

You’ll find rules like “HeatingCtrl received command” which has the code when the heat should be turned on:

github.com/HestiaPi/hestia-touch-openhab

var/lib/openhab2/jsondb/automation_rules.json

ONE


      
              "description": "Control the fan"
            }
          },
          "05a775d5-554d-4bf9-9012-166e6a217d6d": {
            "class": "org.openhab.core.automation.dto.RuleDTO",
            "value": {
              "triggers": [
                {
                  "id": "1",
                  "label": "HeatingCtrl received command",
                  "description": "This triggers the rule if an item receives a command.",
                  "configuration": {
                    "itemName": "HeatingCtrl"
                  },
                  "type": "core.ItemCommandTrigger"
                }
              ],
              "conditions": [
                {
                  "inputs": {},
                  "id": "3",

And cooling:

github.com/HestiaPi/hestia-touch-openhab

var/lib/openhab2/jsondb/automation_rules.json

ONE


      
              "description": "Determines if the humidifier/dehumidifier should turn on"
            }
          },
          "79e9a0ba-b377-4324-ac31-e187674a13f1": {
            "class": "org.openhab.core.automation.dto.RuleDTO",
            "value": {
              "triggers": [
                {
                  "id": "1",
                  "label": "CoolingCtrl",
                  "description": "This triggers the rule if an item receives a command.",
                  "configuration": {
                    "itemName": "CoolingCtrl"
                  },
                  "type": "core.ItemCommandTrigger"
                }
              ],
              "conditions": [
                {
                  "inputs": {},
                  "id": "2",

And the logic for when to trigger the heating or cooling:

github.com/HestiaPi/hestia-touch-openhab

var/lib/openhab2/jsondb/automation_rules.json

ONE


      
                "type": "application/javascript",
                "script": "var OPENHAB_CONF \u003d Java.type(\u0027java.lang.System\u0027).getenv(\u0027OPENHAB_CONF\u0027);\nload(OPENHAB_CONF + \u0027/automation/lib/hestia/utils.js\u0027);\n\nvar logName\u003d\"heatcool\";\n\nvar minSP \u003d items[\"MinTempSetpoint\"].class;\nvar maxSP \u003d items[\"MaxTempSetpoint\"].class;\nvar hyst \u003d items[\"Comfort_Value\"].class;\nvar temp \u003d items[\"MyTempProxy\"].class;\nvar comfMode \u003d items[\"Comfort_Mode\"].class;\n\nvar ok \u003d (minSP !\u003d UnDefType.class \u0026\u0026\n          hyst !\u003d UnDefType.class \u0026\u0026\n          temp !\u003d UnDefType.class \u0026\u0026\n          comfMode !\u003d UnDefType.class);\nif(items[\"SystemType\"] \u003d\u003d \"US\") ok \u003d (ok \u0026\u0026 maxSP !\u003d UnDefType.class);\n\nif(!ok){\n  if(items[\"SystemType\"] \u003d\u003d \"US\"){\n    logError(logName, \"Cannot determine heating/cooling: MinTempSetpoint \u003d \" + items[\"MinTempSetpoint\"] + \" MaxTempSetpoint \u003d \" + items[\"MaxTempSetpoint\"] + \" MyTempProxy \u003d \" + items[\"MyTempProxy\"] + \" Comfort_Value \u003d \" + items[\"Comfort_Value\"]);\n  }\n  else {\n    logError(logName, \"Cannot determine heating: MinTempSetpoint \u003d \" + items[\"MinTempSetpoint\"] + \" MyTempProxy \u003d \" + items[\"MyTempProxy\"] + \" Comfort_Value \u003d \" + items[\"Comfort_Value\"]);\n  }\n}\n\n(ok);"
              },
              "type": "script.ScriptCondition"
            }
          ],
          "actions": [
            {
              "inputs": {},
              "id": "3",
              "label": "Determines whether to turn on/off the heater/ac based on temp and setpoint.",
              "description": "Sends command to Heating/CoolingCtrl to change device\u0027s state.",
              "configuration": {
                "type": "application/javascript",
                "script": "var OPENHAB_CONF \u003d Java.type(\u0027java.lang.System\u0027).getenv(\u0027OPENHAB_CONF\u0027);\nload(OPENHAB_CONF + \u0027/automation/lib/hestia/utils.js\u0027);\nload(OPENHAB_CONF + \u0027/automation/lib/hestia/defaults.js\u0027);\n\nvar mode \u003d event.itemName.replace(\"Check\", \"\");\nvar temp \u003d items[\"MyTempProxy\"].floatValue();\n\nvar minDelta \u003d items[\"MinTempSetpoint\"].floatValue() - temp; // positive means below setpoint, heating\nvar maxDelta \u003d temp - items[\"MaxTempSetpoint\"].floatValue(); // positive means above setpoint\nvar delta \u003d (mode \u003d\u003d \"Heating\") ? minDelta : maxDelta;\n\nvar comfHyst \u003d DEFAULTS.get(items[\"TempUnit\"]+\"_COMFORT_DEF\");\nvar ecoHyst \u003d items[\"Comfort_Value\"].floatValue();\nvar hysteresis \u003d (items[\"Comfort_Mode\"] \u003d\u003d \"COMFORT\") ? comfHyst : ecoHyst;\n\nvar turnOn \u003d (items[mode+\"Mode\"] \u003d\u003d \"Boost\" || delta \u003e\u003d hysteresis);\nvar turnOff \u003d delta \u003c\u003d 0;\n\nif(turnOn) {\n  logInfo(\"heatingcooling\", \"TURN ON \" + mode + \": heating delta is \" + minDelta + \" cooling delta is \" + maxDelta + \" hysteresis is \" + hysteresis);\n  events.sendCommand(mode+\"Ctrl\", \"ON\");\n}\nelse if(turnOff){\n  logInfo(\"heatingcooling\", \"TURN OFF \" + mode + \": heating delta is \" + minDelta + \" cooling delta is \" + maxDelta + \" hysteresis is \" + hysteresis);\n  events.sendCommand(mode+\"Ctrl\", \"OFF\");\n}\nelse {\n  logInfo(\"heatingcooling\", \"Nothing to do: mode \u003d \" + mode + \" temp \u003d  \" + temp + \" hysteresis \u003d \" + hysteresis + \" min delta \u003d \" + minDelta + \" max delta \u003d \" + maxDelta);\n}\n\nsleep(10); // keep the rule from running again too soon"
              },
              "type": "script.ScriptAction"
            }
          ],
          "configuration": {},
          "configDescriptions": [],

I find the text file easier to navigate to figure out which rules I should look into and then I use the PaperUI to actually look at and modify the code. I’d highly recommend making a backup before and after you make changes.

If you want to contribute your changes back, it’d be very cool to have a third mode (US-Heat-Pump) to add to the existing US and EU modes. Then if you ever have to re-flash the card you won’t have to re-apply all your changes. Just switch from US to US-Heat-Pump and you’ll be good to go.