Climate Entity

A climate entity controls heating, ventilation and air conditioning (HVAC) devices. This can range from simple fans to personal air conditioning units to integrated building devices.

Features

Attributes

Entity attributes are controlled by features. Multiple features can act on the same attribute.

See entity options for temperature unit and ranges.

States

The climate entity provides the following entity state values and represents the currently set HVAC mode of the device:

Note: the current mode may not be the active state of the device. E.g. if the mode is set to AUTO the climate unit may be heating, cooling, idle, etc. at a specific point in time.

See common entity states.

Device Classes

None.

Options

🚧 Planned feature.

All temperature values are given in the temperature unit of the entity, as defined by the temperature_unit option: the current_temperature and target_temperature attributes, the max_temperature, min_temperature and target_temperature_step options, and the temperature parameter of the target_temperature command.

The range and step options also define the input range of the temperature command parameter in a command editor, e.g. in the web-configurator.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests within msg_data.cmd_id.

• The command request must be acknowledged with a result response message.
• Once the value has been set or confirmed by the physical device, an entity_change event message with the new value(s) must be sent.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the climate device changes. Either after anentity_command or if the climate device has been updated externally through a user or another system. This keeps the remote in sync with the real state of the entity without the need of constant polling.

The following attributes are supported:

At least one attribute must be specified in the entity_change message. If the entity state and a climate attribute changed at the same time, they may both be included in the same message. It’s also valid to always send every attribute.

Command examples

on

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "on"
  }
}

off

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "off"
  }
}

hvac_mode

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "hvac_mode",
    "params": {
      "hvac_mode": "COOL"
    }
  }
}

Combined with target temperature

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "hvac_mode",
    "params": {
      "hvac_mode": "COOL",
      "temperature": 23
    }
  }
}

target_temperature

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "target_temperature",
    "params": {
      "temperature": 23
    }
  }
}

Event examples

State change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "attributes": {
      "hvac_mode": "HEAT",
      "current_temperature": 19.5,
      "target_temperature": 21.0
    }
  }
}