Air Quality Cluster

Cluster ID: 0x005B  |  Endpoint: Application endpoint (typically Endpoint 1 or the endpoint corresponding to the air quality sensor)

The Air Quality Cluster provides a comprehensive air quality index as an enum value that reflects the overall air condition of the current environment. This is a minimal read-only cluster — it has only 1 attribute, no commands, and no Feature Map.

Purpose and Companion Clusters

Air Quality provides an overall rating level and does not include specific pollutant concentration data. In practice, it typically appears alongside concentration measurement clusters such as PM2.5 Concentration Measurement (0x042A), CO2 Concentration Measurement (0x040D), and TVOC Concentration Measurement (0x042E). Those clusters provide precise values, while Air Quality provides an at-a-glance level assessment.

Attribute Overview

The Air Quality Cluster has only one attribute.

ID Name Type Access Description
0x00 AirQuality AirQualityEnum Read-only Current overall air quality level

AirQuality (Air Quality Level)

A read-only attribute indicating the device's current overall air quality level. Values range from 0 (Unknown) to 6 (ExtremelyPoor), covering 7 levels in total. The device computes and reports this value based on its built-in sensor readings; the specific calculation algorithm is determined by the device manufacturer.

Unknown Does Not Mean Offline

Unknown (0) means the device currently cannot determine the air quality level (e.g., the sensor is warming up, calibrating, or lacks sufficient data). It does not mean the device is offline or malfunctioning. Apps should display this as "Detecting" or "No data yet," not as an error state.

AirQualityEnum Enum Values

0
Unknown Unknown — sensor is warming up or has insufficient data
1
Good Good — air quality is satisfactory with no health risk
2
Fair Fair — acceptable; sensitive individuals may experience minor effects
3
Moderate Moderate — sensitive individuals may experience health effects
4
Poor Poor — everyone may begin to experience health effects
5
VeryPoor Very Poor — health alert; everyone may experience more serious effects
6
ExtremelyPoor Extremely Poor — health emergency; protective measures should be taken immediately

↑ Back to Attributes

Commands

The Air Quality Cluster is purely read-only and has no commands. Apps can only obtain air quality data by reading attributes or subscribing to reports — they cannot send control commands to the device.

Example Data

Reading the Air Quality Cluster attributes from an air quality sensor:

{
  // --- Attributes ---
  "0x0": 1           // AirQuality = Good (air quality is good)
}

Subscribing to air quality changes (recommended approach):

{
  "subscribeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x005B",
      "attributeId": "0x00"       // AirQuality
    },
    "minInterval": 10,            // Minimum reporting interval: 10 seconds
    "maxInterval": 60             // Maximum reporting interval: 60 seconds
  }]
}
Why Subscribe Instead of Poll

Air quality is a continuously changing metric. Rather than reading periodically, use Subscribe to have the device proactively report when values change. Setting appropriate minInterval and maxInterval values balances real-time responsiveness with power consumption.

Scenario 1: Air Purifier Automation

The air quality sensor and purifier work together: the purifier automatically turns on when the sensor detects worsening air quality, and turns off when conditions improve.

Implementation Approach
  1. Subscribe to the air quality sensor's AirQuality attribute changes
  2. Upon receiving a report, take action based on the level:
    • Moderate (3) or above: send the On/Off Cluster On command to turn on the purifier
    • Good (1): send the Off command to turn off the purifier
    • Fair (2): maintain the current state to avoid frequent switching
  3. You can also use the Level Control Cluster to adjust purifier fan speed — Poor (4) for high speed, Moderate (3) for low speed

This logic can be implemented on the app side, or pushed to a Hub/Bridge via Matter automation rules, which allows it to run without the app being online.

Scenario 2: Dashboard Display

Visualize air quality levels in a smart home app, typically presented alongside concentration measurement data.

Display Recommendations
  1. Use colors to differentiate levels (following common AQI color schemes):
    • Good → Green
    • Fair → Yellow
    • Moderate → Orange
    • Poor → Red
    • VeryPoor → Purple
    • ExtremelyPoor → Maroon
  2. Display Unknown in gray with the text "Detecting" to avoid users mistaking it for an error
  3. Below the level card, show specific concentration data (from companion clusters):
    • PM2.5 Concentration (0x042A)
    • CO2 Concentration (0x040D)
    • TVOC Concentration (0x042E)
  4. Include a historical trend chart so users can see how air quality changes over time