Thermostat - WizBangCrash/esp-homekit-devices GitHub Wiki

A HomeKit Thermostat. It requires a compatible sensor.

Type Device Type
21 Thermostat
25 Thermostat with humidity sensor

The following configuration is available for thermostats:

Section Key Description
Actions "0", "1" etc. The actions performed by the accessory
Digital Inputs "b" GPIOs that invoke specific actions
State & Status Inputs "f[n]" & "g[n]" Inputs that manage accessory state
Initial State "s" State a switch accessory enters on boot
Wildcard Actions "y[n]" Perform an action when an accessory reaches a target value
Sensor GPIO "g" GPIO line sensor is attached to
Sensor Type "n" Type of sensor attached to accessory
Sensor Polling Time "j" How often the temperature sense is read
Temperature Offset "z" Correction offset to apply
Humidity Offset "h" Correction offset to apply
Thermostat Type "w" Type of thermostat connected to accessory
Minimum Temperature "m" Minimum temperature that can be set
Maximum Temperature "x" Maximum temperature that can be set
Deadband Temperature "d" Deadband/Hysteresis of thermostat
Deadband Temperature Force Idle "df" Deadband/Hysteresis of thermostat to exec Force Idle Actions
Deadband Temperature Soft On "ds" Deadband/Hysteresis of thermostat to exec Soft On Actions

Example

{
  "c":{"t":3},
  "a":[{
    "t":25,
    "w":3,
    "p":"HPDRAGAAAGCKAE",
    "s":5,
    "g":14,
    "0":{"i":[{"c":"BcAbBaAbBaBbAbAdArAdCdBdAuHaDcDbDaU"}]},
    "1":{"i":[{"c":"BcAbBaAbBaBbAbAdApAbAbAgBdAuFaBaBaGbDaU"}]},
    "2":{"i":[{"c":"BcAbBaAbBaBbAbAdApAaAdCdBdAuFaAaDcDbDaU"}]},
    "3":{"i":[{"c":"BcAbBaAbBaBbAbAdApAbAdBdBdAuFaBaDbDbDaU"}]},
    "4":{"i":[{"c":"BcAbBaAbBaBbAbAdApAaAcBfBdAuFaAaCbFbDaU"}]},
    "5":{"a":0}
  }]
}

This is an example of a Mitsubishi HVAC IrDA Remote Thermostat and Humidity sensor ("t":25). The type ("w":3) is a heater & cooler thermostat. The thermostat is controlled via a infra-red and the protocol is defined by "p":"HPDRAGAAAGCKAE". A sensor is connected to GPIO 14 ("g":14) and is is the default type 2 ("n":2 not required as the default). Control of the sensor is via actions 0 to 5 and their respective IR strings. The initial state has been set to "last state before restart" ("s":5).

Actions

Key Action Description
"0" All OFF Turns off all components of the thermostat
"1" Thermostat ON, Heating OFF Turn on thermostat but heating is in idle-mode
"2" Thermostat ON, Cooling OFF Turn on thermostat but cooling is in idle-mode
"3" Thermostat ON, Heating ON Thermostat is active and heating
"4" Thermostat ON, Cooling ON Thermostat is active and cooling
"5" Sensor Error Action to perform when there is a sensor error
"6" "f3" triggered Change target temperature by +0.5°C
"7" "f4" triggered Change target temperature by -0.5°C
"8" Thermostat ON, Heating Force OFF Turn on thermostat but heating is in force idle-mode
"9" Thermostat ON, Cooling Force OFF Turn on thermostat but cooling is in force idle-mode
"10" Thermostat ON, Heating Soft ON Thermostat is active and heating in soft mode
"11" Thermostat ON, Cooling Soft ON Thermostat is active and cooling in soft mode

Multiple actions are supported by a thermostat. The Digital Outputs "r": [{}] for each should be configured to attain the desired state.

Sensor GPIO

Sensor GPIO is defined by the "g" key contained within the accessory object.

Key Value Description
"g" GPIO # GPIO line the temperature sensor is connected to

Home Accessory Architect only supports one-wire temperature sensors. This is a mandatory option that specifies the GPIO the sensor is attached to e.g. "g": 14

Sensor Type

Sensor type is defined by the "n" key contained within the accessory object.

A variety of one-wire sensors are available and supported by HAA.

Refer to Sensor Type for details of the sensors that are supported.

Sensor Polling Time

Sensor polling time is defined by the "j" key contained within the accessory object.

Key Value Description
"j" 30 Sensor is polled every 30 seconds (default)
0.1 to 65535 Float specifying the number of seconds between polls

The thermostat temperature is polled on a regular basis to read the latest values. These values are then posted to HomeKit. If this option is not specified then the sensor will be polled once every 30 seconds.

Temperature Offset

Temperature offset is defined by the "z" key contained within the accessory object.

Key Value Description
"z" 0.0 No offset is applied (default)
-∞ < 0.0 > +∞ Offset is added to temperature value read

The accuracy of the temperature sensor varies and may sometimes read consistently higher or lower than the actual temperature. The temperature offset option enables calibration of the sensor by specifying a positive or negative offset to apply to the reading.

The option uses is a floating point value, accurate to 1 decimal place e.g. 1.1

Humidity Offset

Humidity offset is defined by the "h" key contained within the accessory object.

NOTE: This option is available only for device type 25

Key Value Description
"h" 0.0 No offset is applied (default)
-∞ < 0.0 > +∞ Offset is added to humidity value read

The accuracy of the available one-wire sensors varies and may sometimes read consistently higher or lower than the actual humidity. The humidity offset option enables calibration of the sensor by specifying a positive or negative offset to apply to the reading.

The option uses is a floating point value, accurate to 1 decimal place e.g. 1.1

Thermostat Type

Thermostat type is defined by the "w" key contained within the accessory object.

Key Type Description
"w" 1 Heater (default)
2 Cooler
3 Heater and Cooler

This option is used to select the type of thermostat controlled by the device.

Minimum Temperature

Minimum temperature is defined by the "m" key contained within the accessory object.

Key Value Description
"m" 10.00 Set minimum temperature to 10°C (default)
-∞ < 0.00 > +∞ Minimum temperature allowed

This option is used to set the minimum temperature in °C you can set. The value is a floating point variable accurate to 2 decimal places e.g. 10.04.

Maximum Temperature

Maximum temperature is defined by the "x" key contained within the accessory object.

Key Value Description
"x" 38.00 Set maximum temperature to 38°C (default)
-∞ < 0.00 > +∞ Maximum temperature allowed

This option is used to set the maximum temperature in °C you can set. The value is a floating point variable accurate to 2 decimal places e.g. 10.04.

Deadband Temperature

Deadband temperature is defined by the "d" key contained within the accessory object.

Key Value Description
"d" 0.00 Set temperature deadband to 0°C (default)
0.00 > +∞ Temperature deadband allowed

The "d" option is used to set the temperature deadband in °C to adjust how thermostat works. The value is a floating point variable accurate to 2 decimal places e.g. 10.04.

Thermostat Deadband

A thermostat deadband (or hysteresis) is designed to lag the inputs from the environment for the purposes of saving you energy and saving your air conditioner or furnace wear and tear from turning on and off frequently.

The deadband represents a temperature range around the automatic mode set point that is your “comfort zone”. For example, with a 4°C wide deadband ("d": 4.0) and a setpoint of 20°C, the deadband will be 18 - 22°C. This keeps the system from bouncing quickly between heating and cooling when in automatic mode.

When temperatures fall within the deadband, neither heating nor cooling can occur. A larger deadband will have your system run more economically, while a smaller deadband will have your system hold the temperature closer to the setpoint and increase comfort. The deadband does not affect your thermostat’s operation when in HEAT or COOL modes.

Example: If you have an 8ºC deadband and you set your desired temperature to 22ºC in AUTO mode, your heating set point will be 18º and your cooling set point will be 26ºC.

Deadband Temperature Force Idle

Deadband temperature force idle is defined by the "df" key contained within the accessory object.

Key Value Description
"df" 0.00 Set temperature deadband to 0°C (default)
0.00 > +∞ Temperature deadband allowed

Deadband Temperature Soft On

Deadband temperature soft on is defined by the "ds" key contained within the accessory object.

Key Value Description
"ds" 0.00 Set temperature deadband to 0°C (default)
0.00 > +∞ Temperature deadband allowed

Accessory Notifications

The list of notifications "m" supported by a thermostat are as follows:

Value Notification
0.02 Thermostat OFF
0.03 Thermostat ON
0.04 Cooler mode
0.05 Heater mode
0.06 Auto mode
XX.Y0 Set heater temperature to XX.Yº
XX.Y1 Set cooler temperature to XX.Yº

See the general Accessory Notifications section for details of how to configure these notifications.

Digital Inputs

Digital Inputs "b" are supported by this accessory.

See Digital Inputs for details on how to define this mandatory option.

State and Status Inputs

State inputs "f[n]" & Status Inputs "g[n]" are supported by this accessory. The supported list is:

Key Required State
"f0" Thermostat OFF
"f1" Thermostat ON
"f3" Change target temperature by +0.5°C
"f4" Change target temperature by -0.5°C
"f5" Cooler mode ON
"f6" Heater mode ON
"f7" Auto mode ON

NOTE: Fixed states "f5", "f6" & "f7" are only available when thermostat type 3 is selected ("w": 3)

Refer to State Inputs for more detail and examples.

ICMP Ping Inputs

ICMP Ping inputs "p[n]" and "q[n]" are supported by this accessory. Refer to ICMP Ping Inputs for more detail.

Wildcard Actions

Wildcard Actions "y[n]" are supported by this accessory. The supported list is:

Key Action
"y0" Trigger action when accessory reaches a specific temperature
"y1" Trigger action when accessory reaches a specific humidity

Refer to Wildcard Actions for more detail.

Initial State

The Initial State key is supported by this accessory. Refer to Initial State for more details.

Key State Description
"s" 0 OFF (default)
1 Heating
2 Cooling
4 Defined by fixed state inputs
5 Last state before restart
6 Opposite to last state before restart
⚠️ **GitHub.com Fallback** ⚠️