HeaterCooler
A HomeKit HeaterCooler service. It requires a compatible sensor.
| Type | Service Type |
|---|---|
| 21 | HeaterCooler |
| 25 | HeaterCooler with humidity sensor |
The following configuration is available:
| Section | Key | Description |
|---|---|---|
| Actions | "0", "1" etc. | The actions performed by the service |
| Digital Inputs | "b" | GPIOs that invoke specific actions |
| State & Status Inputs | "f[n]" & "g[n]" | Inputs that manage service state |
| Service Notifications | "m" | Notifications to send to another service |
| ICMP Ping Inputs | "q[n]" & "p[n]" | Ping inputs that manage service state |
| Wildcard Actions | "y[n]" | Perform an action when an service reaches a target value |
| Initial State | "s" | State an service enters on boot |
| Sensor GPIO | "g" | GPIO line sensor is attached to |
| Sensor Type | "n" | Type of sensor attached to service |
| Sensor Polling Time | "j" | How often the temperature sense is read |
| Temperature Offset | "z" | Correction offset to apply |
| Humidity Offset | "k" | Correction offset to apply |
| HeaterCooler Type | "w" | Type of HeaterCooler connected to service |
| Minimum Temperature | "m" | Minimum temperature that can be set |
| Maximum Temperature | "x" | Maximum temperature that can be set |
| Deadband Temperature | "d" | Deadband/Hysteresis of HeaterCooler |
| Deadband Temperature Force Idle | "df" | Deadband/Hysteresis of HeaterCooler to exec Force Idle Actions |
| Deadband Temperature Soft On | "ds" | Deadband/Hysteresis of HeaterCooler to exec Soft On Actions |
| Delay time to process | "dl" | Time in seconds to wait for process HeaterCooler logic |
{
"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 HeaterCooler and
Humidity sensor ("t":25).
The type ("w":3) is a heater & cooler.
The HeaterCooler 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).
| Key | Action | Description |
|---|---|---|
| "0" | All OFF | Turns off all components of the HeaterCooler |
| "1" | HeaterCooler ON, Heating OFF | Turn on HeaterCooler but heating is in idle-mode |
| "2" | HeaterCooler ON, Cooling OFF | Turn on HeaterCooler but cooling is in idle-mode |
| "3" | HeaterCooler ON, Heating ON | HeaterCooler is active and heating |
| "4" | HeaterCooler ON, Cooling ON | HeaterCooler 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" | HeaterCooler ON, Heating Force OFF | Turn on HeaterCooler but heating is in force idle-mode |
| "9" | HeaterCooler ON, Cooling Force OFF | Turn on HeaterCooler but cooling is in force idle-mode |
| "10" | HeaterCooler ON, Heating Soft ON | HeaterCooler is active and heating in soft mode |
| "11" | HeaterCooler ON, Cooling Soft ON | HeaterCooler is active and cooling in soft mode |
Multiple actions are supported by a HeaterCooler. The Digital Outputs
"r": [{}] for each should be configured to attain the desired state.
Sensor GPIO is defined by the "g" key contained within the service 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 is defined by the "n" key contained within the service 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 is defined by the "j" key contained within the
service 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 HeaterCooler 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 is defined by the "z" key contained within the service
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 is defined by the "k" key contained within the service
object.
NOTE: This option is available only for device type 25
| Key | Value | Description |
|---|---|---|
| "k" | 0 | No offset is applied (default) |
| -∞ < 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 an integer point value.
HeaterCooler type is defined by the "w" key contained within the service object.
| Key | Type | Description |
|---|---|---|
| "w" | 1 | Heater (default) |
| 2 | Cooler | |
| 3 | Heater and Cooler |
This option is used to select the type of HeaterCooler controlled by the device.
Minimum temperature is defined by the "m" key contained within the
service 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 is defined by the "x" key contained within the
service 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 is defined by the "d" key contained within the
service 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
HeaterCooler works. The value is a floating point variable accurate to 2 decimal
places e.g. 10.04.
A HeaterCooler 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 HeaterCooler'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 is defined by the "df" key contained within the
service object.
| Key | Value | Description |
|---|---|---|
| "df" | 0.00 | Set temperature deadband to 0°C (default) |
| 0.00 > +∞ | Temperature deadband allowed |
Deadband temperature soft on is defined by the "ds" key contained within the
service object.
| Key | Value | Description |
|---|---|---|
| "ds" | 0.00 | Set temperature deadband to 0°C (default) |
| 0.00 > +∞ | Temperature deadband allowed |
Time to wait until HeaterCooler data in processed. It is used to avoid conflicts when many HomeKit orders are sent at same time.
| Key | Value | Description |
|---|---|---|
| "dl" | 3.0 | Set delay time to 4 seconds (default) |
| 0.15 > +∞ | Delay time allowed in seconds |
The list of notifications "m" supported by this service are as follows:
| Value | Notification |
|---|---|
| 0.02 | HeaterCooler OFF |
| 0.03 | HeaterCooler 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 Service Notifications section for details of how to configure these notifications.
Digital Inputs "b" are supported by this service.
See Digital Inputs for details on how to define this mandatory option.
State inputs "f[n]" & Status Inputs "g[n]" are supported by this service.
The supported list is:
| Key | Required State |
|---|---|
| "f0" | HeaterCooler OFF
|
| "f1" | HeaterCooler 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 HeaterCooler
type 3 is selected ("w": 3)
Refer to State Inputs for more detail and examples.
ICMP Ping inputs "p[n]" and "q[n]" are supported by this service.
Refer to ICMP Ping Inputs for
more detail.
Wildcard Actions "y[n]" are supported by this service.
The supported list is:
| Key | Action |
|---|---|
| "y0" | Trigger action when service reaches a specific temperature |
| "y1" | Trigger action when service reaches a specific humidity |
| "y2" | Trigger action when heater target temperature reaches a specific value |
| "y3" | Trigger action when cooler target temperature reaches a specific value |
Refer to Wildcard Actions for more detail.
The Initial State key is supported by this service. 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 |