Matter - Air Conditioner: Mode Management

pierre-gilles · July 20, 2026, 12:17pm

Thanks to the new supported_options recently developed, I was able to develop this feature!

To test, I propose a Docker image:

ghcr.io/gladysassistant/gladys-preview:cursor-matter-ac-mode-management-fb55

The PR:

github.com/gladysassistant/gladys

Matter: Add air conditioner mode management (Thermostat SystemMode) (#2690)

GladysAssistant:master ← GladysAssistant:cursor/matter-ac-mode-management-fb55

ouvert 09:57AM - 20 Jul 26 UTC

Pierre-Gilles

+613 -64

## Description Adds air conditioner operating mode management to the Matter int…egration, as requested on the community forum: https://community.gladysassistant.com/t/matter-climatiseur-gestion-des-modes/10225 Air conditioners exposed over Matter (e.g. Daikin units bridged through Matterbridge) expose their operating mode through the `Thermostat` cluster `SystemMode` attribute. Until now, Gladys only handled the local temperature and the heating/cooling setpoints, so the mode selector visible in Apple Home was missing in Gladys. ### Server (`server/services/matter`) - New `utils/thermostatMatterMapping.js`: bidirectional mapping between Matter `SystemMode` (Off/Auto/Cool/Heat/EmergencyHeat/Precooling/FanOnly/Dry/Sleep) and Gladys `AC_MODE` (Auto/Cooling/Heating/Drying/Fan), plus `getAcModeSupportedOptions` which builds the feature `supported_options` from the Thermostat cluster capabilities (Auto only when the cluster has the `AutoMode` feature, Heat only with the `Heating` feature; Dry/FanOnly have no Matter capability flag and are always exposed on cooling devices). - `convertToGladysDevice`: devices whose Thermostat cluster supports the `cooling` feature now expose an `air-conditioning/mode` feature (`:mode` external id suffix) with its `supported_options` (persisted via the mechanism introduced in #2567), and `min`/`max` derived from them. - `matter.listenToStateChange`: subscribes to `SystemMode` attribute changes and emits the mapped Gladys AC mode (values without a Gladys equivalent, such as `Off`, are ignored — on/off is handled by the `OnOff` cluster). - `matter.readInitialDeviceStates`: reads the initial `SystemMode` value on startup. - `matter.setValue`: writes the `SystemMode` attribute when the user changes the mode from Gladys. - README compatibility table updated. ### Server (core fix) - `utils/normalizeSupportedOptions.js`: strip the DB metadata fields (`device_feature_id`, `created_at`, `updated_at`) from `supported_options` payloads. Devices fetched from the API include the full `DeviceFeatureSupportedOption` rows, so re-saving a device from an integration page failed validation with `"[0].device_feature_id" is not allowed` (found while testing this PR end-to-end). ### Front - `AirConditioningModeDeviceFeature` now renders the mode buttons dynamically from the feature `supported_options` (sorted by `sort_order`, labels translated per mode with the stored label as fallback). Features without `supported_options` (e.g. existing MELCloud devices) keep the previous behavior: Auto/Cool/Heat, plus Dry/Fan when the feature `max` covers them. - New `drying`/`fan` translations added to `en`, `fr`, and `de`. ## Tests - New unit tests for `thermostatMatterMapping` (all mappings, unknown-value branches, and supported options per capability combination). - Updated/extended tests for `convertToGladysDevice`, `listenToStateChange`, `readInitialDeviceStates`, `setValue`, `matter.init` and `normalizeSupportedOptions` (metadata stripping round-trip). - `npm run coverage` on the server passes (4337 tests), with 100% line coverage on every touched file. Front `prettier-check`, `eslint`, `compare-translations`, `build` and the full Cypress suite pass. ## End-to-end validation Tested against **two real Matter nodes** built with matter.js and commissioned into Gladys through the Matter integration UI/API: - a Room Air Conditioner with Thermostat `Heating + Cooling + AutoMode` → Mode feature with 5 supported options (Auto, Cool, Heat, Dry, Fan); - a second one with `Heating + Cooling` only (no AutoMode) → Mode feature with 4 supported options (no Auto). The options are persisted in `t_device_feature_supported_option`: ``` matter-1-1-513-mode|0|Auto|0 matter-2-1-513-mode|1|Cool|0 matter-1-1-513-mode|1|Cool|1 matter-2-1-513-mode|2|Heat|1 matter-1-1-513-mode|2|Heat|2 matter-2-1-513-mode|3|Dry|2 matter-1-1-513-mode|3|Dry|3 matter-2-1-513-mode|4|Fan|3 matter-1-1-513-mode|4|Fan|4 ``` The dashboard widget follows them — the first device shows 5 buttons, the second only 4 (no Auto), and clicking a mode writes the correct Matter `SystemMode` to each device: [matter_ac_supported_options_demo.mp4](https://cursor.com/agents/bc-6057d516-266d-490e-8877-6dc49a82fb55/artifacts?path=%2Fopt%2Fcursor%2Fartifacts%2Fmatter_ac_supported_options_demo.mp4) ``` [VIRTUAL-AC] systemMode changed to 1 (Auto) [VIRTUAL-AC] systemMode changed to 8 (Dry) [VIRTUAL-AC-NOAUTO] systemMode changed to 3 (Cool) [VIRTUAL-AC-NOAUTO] systemMode changed to 7 (FanOnly) ``` [Paired Matter AC device card with Mode feature](https://cursor.com/agents/bc-6057d516-266d-490e-8877-6dc49a82fb55/artifacts?path=%2Fopt%2Fcursor%2Fartifacts%2Fmatter_device_card_with_mode_feature.webp) <sub>To show artifacts inline, <a href="https://cursor.com/dashboard/cloud-agents#my-pull-requests">enable</a> in settings.</sub> <div><a href="https://cursor.com/agents/bc-6057d516-266d-490e-8877-6dc49a82fb55"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-6057d516-266d-490e-8877-6dc49a82fb55"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> ## Summary by CodeRabbit * **New Features** * Added Matter thermostat HVAC operating mode control (Auto/Cooling/Heating/Drying/Fan) with mode availability derived from the device’s supported options and kept in sync. * Unified AC mode selection so all mode buttons update through the same flow. * **Documentation** * Updated Matter thermostat documentation to describe HVAC system modes. * **Bug Fixes** * Improved supported-option saving by stripping database metadata from option objects. * Skip unknown/unmapped thermostat system modes and ignore unsupported app mode values to prevent incorrect updates. * **Localization** * Added/extended English, French, and German labels for the new drying and fan modes.

Topic		Replies	Views
Matter : Intégration lave vaisselle Demande de fonctionnalités intégration	2	54	May 18, 2026
[Matter] Ajouter la gestion des ventilateurs Demande de fonctionnalités matter	3	104	June 15, 2026
Matter : Investigation ventilateur Dyson Matterbridge Développement	12	67	June 22, 2026
Gladys Assistant 4.64 : Compatibilités Matter Actualités	10	154	October 10, 2025
[Matterbridge] Plugin Dyson - manque configuration? Configuration matter	22	246	September 15, 2025

Matter - Air Conditioner: Mode Management

Related topics