[Matter] Add air quality management

pierre-gilles · June 23, 2025, 12:42pm

Description

Add support for « AirQuality » sensors in the Matter integration:

cursor-bot · August 17, 2026, 12:08pm

Hi everyone!

This topic is now under development.

A PR has been opened to add support for the AirQuality Matter cluster:

github.com/GladysAssistant/Gladys

Matter: add support for the AirQuality cluster (#2891)

master ← claude/matter-air-quality

ouvert 04:57PM - 15 Aug 26 UTC

Pierre-Gilles

+390 -16

Implements feature request: https://community.gladysassistant.com/t/matter-ajout…er-la-gestion-de-la-qualite-de-lair/9620 > **Note:** this PR was opened by an automated Claude Code run. It needs human review and testing on a real Matter device (no physical AirQuality sensor was available to validate the mapping end to end). ### Description The Matter `AirQuality` cluster (id 91 / `0x005B`) exposes a single `airQuality` attribute, an enum holding the overall air quality verdict the device computes itself: `Unknown(0)`, `Good(1)`, `Fair(2)`, `Moderate(3)`, `Poor(4)`, `VeryPoor(5)`, `ExtremelyPoor(6)`. The Matter integration already handled the individual concentration clusters (PM2.5, PM10, CO2, VOC, NO2, formaldehyde) but not this overall verdict. **Taxonomy choice — a new type, not a new category.** `docs/specs/device-feature-categories.md` lists `voc-matter-index-sensor` / `no2-matter-index-sensor` as legacy exceptions that must not be used as precedents for new protocol-named categories, and rule 5 says not to create a category when a new type on an existing one is enough. So this adds a `level` type to the existing `airquality-sensor` category, next to the numeric `aqi` type: - `DEVICE_FEATURE_TYPES.AIRQUALITY_SENSOR.LEVEL = 'level'`, values from the new `AIR_QUALITY_LEVEL` constant; - the value scale is Matter's, which is also how Zigbee air quality sensors report an overall level (rule 3: align with the standard by default); - inline scope comments on both the new constant and the two types state the boundary: `aqi` holds the numeric index, `level` the qualitative verdict, an integration maps whichever form its device natively reports and never both, and the raw concentrations behind the verdict keep going to their own per-pollutant categories; - units declared in `DEVICE_FEATURE_UNITS_BY_CATEGORY_AND_TYPE` (`aqi` → AQI, `level` → none). **Per-device value set through `supported_options` (rule 6).** Only `Unknown`, `Good` and `Poor` are always part of the Matter enum — `Fair`, `Moderate`, `VeryPoor` and `ExtremelyPoor` are each behind an optional cluster feature. The new `airQualityMatterMapping.js` builds the feature's `supported_options` from the cluster's supported features, exactly like `getAcModeSupportedOptions` does for the air conditioning mode, and `min`/`max` follow that list. Server changes: - `server/services/matter/utils/convertToGladysDevice.js`: discovery of the `AirQuality` cluster as a read-only `airquality-sensor/level` feature; - `server/services/matter/lib/matter.listenToStateChange.js`: subscription to the `airQuality` attribute; - `server/services/matter/lib/matter.readInitialDeviceStates.js`: initial read so the feature has a value right after pairing; - `server/services/matter/utils/airQualityMatterMapping.js` (new): supported-options mapping; - `server/services/matter/README.md`: `AirQuality` row moved to handled, counters and percentage updated (27 / 132 = 20.5%). Front changes (full plumbing per rule 8): - type label and the seven value labels in `en`, `fr` and `de`; - icon in `front/src/utils/consts.js`; - dashboard badge: `BadgeNumberDeviceValue` now allows a type-specific color method, so the level does not get read on the numeric-index scale (where it would stay green forever). The level uses the same palette as the AQI index, and an out-of-enum value falls back on the shared "unknown" label instead of an empty badge; - MQTT device page: default `min`/`max`/`read_only` and catalog preview value/label for the new type. Scene triggers and the history grouping needed no change: `getDeviceFeatureValueOptions` picks up the numeric value labels automatically, and `airquality-sensor` is already in the climate history group. ## Forum Forum: https://community.gladysassistant.com/t/matter-ajouter-la-gestion-de-la-qualite-de-lair/9620 ### Checklist - [x] Tests pass: `cd server && npm run coverage` (Codecov requires 100% coverage on changed lines) and Cypress (`npm run cypress:run`) if the UI changed - Ran the Matter suites (`test/services/matter/**`, 270 passing) plus `test/utils`, `test/lib/device`, `test/services/mqtt` and `test/services/homekit` (1043 passing). `nyc` reports **100% line coverage** on every touched server file (`convertToGladysDevice.js`, `matter.listenToStateChange.js`, `matter.readInitialDeviceStates.js`, `airQualityMatterMapping.js`), including the fallback branch where the cluster declares no optional level feature. The full `npm run coverage` and Cypress were **not** run in this environment — CI will cover them. - [x] Linter and prettier pass on both front and server (`npm run eslint`, `npm run prettier`) - `npm run eslint` and `prettier --check` pass on `server/` and `front/` (0 errors; only pre-existing warnings), and `npm run compare-translations` passes for en/fr/de. - [x] No undocumented breaking change - Adding a type to an existing category is additive; no existing feature, selector or value changes. --- _Generated by [Claude Code](https://claude.ai/code/session_013yxguVaLdJ8ZKmw5x3HePT)_ ## Summary by CodeRabbit * **New Features** * Added Matter and MQTT support for air-quality level readings, including initial values and live updates. * Added qualitative air-quality levels from “Unknown” to “Extremely poor.” * Added localized English, French, and German labels. * Added color-coded badges and a dedicated air-quality level icon. * Air-quality levels now appear as read-only sensor information with supported ranges based on device capabilities. * **Documentation** * Updated Matter compatibility coverage to include air-quality support.

Don’t hesitate to follow the PR, test as soon as possible, and share your feedback here.

Topic		Replies	Views
[Matter] Ajouter la gestion du monitoring de filtre charbon actif Demande de fonctionnalités matter , in-progress	8	145	August 17, 2026
Ajout de ColorTemperature et XY dans intégration matter pour les ampoules Demande de fonctionnalités feature-core , in-progress	1	34	August 17, 2026
Matter : Intégration lave vaisselle Demande de fonctionnalités feature-integration , in-progress	3	81	August 17, 2026
Matter: Intégration capteur de CO2 Demandes livrées matter	2	63	July 30, 2026
[Matter] Ajouter la gestion du Formaldehyde Demandes livrées matter	25	255	October 9, 2025

[Matter] Add air quality management

Related topics