hvac_ac | Documentation for developers
Skip to main content


Last updated on August 26, 2022

An air conditioner is a device capable of changing temperature and other characteristics of the air in the room.

Available device functions

The device may have all the following functions or just some of them. For example, if an air conditioner cannot regulate the humidity in a room, there is no need to include the hvac_humidity_set function in the description of its model.

A device complies with three mandatory functions: online, on_off, hvac_temp_set. All air conditioners must have this functions.

humidityCurrent humidity
hvac_air_flow_directionAir flow direction
hvac_air_flow_powerFan speed
hvac_humidity_setDesired air humidity
hvac_ionizationIonization mode
hvac_night_modeNight mode
hvac_temp_set✔︎Desired air temperature
hvac_work_modeAir conditioner operation mode
on_off✔︎Turning the device on and off remotely
online✔︎Device availability: offline or online
temperatureCurrent temperature

Air conditioner model description example

The model shall be described in accordance with the model structure. The example describes an air conditioner equipped with all functions except for the ionization mode.

Besides, allowed values for the hvac_air_flow_power function (fan speed) of the model are changed: the quiet mode is not supported by the model and therefore deleted.

"id": "QWERTY124",
"manufacturer": "Xiaqara",
"model": "SM1123456789",
"hw_version": "3.1",
"sw_version": "5.6",
"description": "Xiaqara smart air conditioner",
"category": "hvac_ac",
"features": [
"allowed_values": {
"hvac_air_flow_power": {
"type": "ENUM",
"enum_values": {
"values": [

User's air conditioner description example

The device shall be describe in accordance with the device structure. The example contains no air conditioner model description as we believe that models are described independently and the model ID will be enough (in this case, QWERTY124).

"id": "ABCD_004",
"name": "My air conditioner",
"default_name": "Smart air conditioner",
"nicknames": ["Controlled air conditioner", "Manageable air conditioner"],
"home": "My home",
"room": "Living room",
"groups": ["Climate", "Cooling"],
"model_id": "QWERTY124",
"hw_version": "3.1",
"sw_version": "5.6"