Section 13 Appliances

Section 13: Appliances

Matter Specification § 13 - Household appliances.

---

Room Air Conditioner

Property	Value
Device Type	api.matter?.deviceTypes.RoomAirConditioner
Description	A room air conditioner that cools, and often heats, with its own power switch.
Matter Specification	§ 13.3

A room air conditioner is a thermostat with an on/off switch. The thermostat holds the mode and setpoints, and the onOff cluster is the unit's power - turning it off keeps the mode and setpoints, so it comes back the way it was.

Auto Mode

Note

Requires Homebridge v2.5.0 or later.

The plain Thermostat device type gets Auto mode as soon as both setpoints are declared. The Room Air Conditioner does not, because every air conditioner declares both setpoints, and Auto brings the deadband rule with it (see below), which could start rejecting setpoints that worked before.

So Auto has to be asked for. Homebridge adds the AutoMode feature when the accessory does either of these:

• starts in Auto (systemMode: 1)
• declares minSetpointDeadBand

Leave both out for an air conditioner without Auto mode. Before v2.5.0, the type was fixed to Heating and Cooling, and an air conditioner that started in Auto failed to register.

Warning

With Auto mode, the deadband applies to the setpoint limits as well as the setpoints. Both of these must hold, in 0.01°C units: maxCoolSetpointLimit - maxHeatSetpointLimit >= deadband and minCoolSetpointLimit - minHeatSetpointLimit >= deadband. minSetpointDeadBand itself is in 0.1°C units, so 20 (2.0°C) means a gap of 200. See HVAC (§9) for the full thermostat reference.

Declaring State

clusters: {
  onOff: {
    onOff: true,
  },
  thermostat: {
    externalMeasuredIndoorTemperature: 2300, // 23.00°C
    controlSequenceOfOperation: 4,           // cooling and heating
    systemMode: 1,                           // 0=off, 1=auto, 3=cool, 4=heat
    occupiedHeatingSetpoint: 2000,           // 20.00°C
    occupiedCoolingSetpoint: 2400,           // 24.00°C
    minHeatSetpointLimit: 1600,              // 16.00°C
    maxHeatSetpointLimit: 2800,              // 28.00°C
    minCoolSetpointLimit: 1800,              // 18.00°C - 2°C above the heat limit
    maxCoolSetpointLimit: 3000,              // 30.00°C - 2°C above the heat limit
    minSetpointDeadBand: 20,                 // 2.0°C
  },
},

Handlers

handlers: {
  onOff: {
    on: async () => {
      await myAirConditionerAPI.turnOn()
    },
    off: async () => {
      await myAirConditionerAPI.turnOff()
    },
  },
  thermostat: {
    systemModeChange: async ({ systemMode }) => {
      // 1 = Auto: the unit picks heating or cooling itself, keeping the room
      // between the two setpoints
      await myAirConditionerAPI.setMode(systemMode)
    },
    occupiedHeatingSetpointChange: async ({ occupiedHeatingSetpoint }) => {
      await myAirConditionerAPI.setHeatingSetpoint(occupiedHeatingSetpoint / 100)
    },
    occupiedCoolingSetpointChange: async ({ occupiedCoolingSetpoint }) => {
      await myAirConditionerAPI.setCoolingSetpoint(occupiedCoolingSetpoint / 100)
    },
    setpointRaiseLower: async ({ mode, amount }) => {
      await myAirConditionerAPI.adjustSetpoint(mode, amount / 10)
    },
  },
}

The example accessory in this plugin is RoomAirConditionerAccessory (option enableRoomAirConditioner).