Request for Custom UI Support for Multiple Clusters Under a Single Logical Device

[Chintanp038]

Dear Google Home Team,

I hope you are doing well.

We are currently developing a Matter-certified device that includes multiple functional clusters (such as Humidity, Fan Control, and additional sensor/control features). All of these need to be presented to the user as a single logical device within Google Home.

During testing, we observed that Google Home creates multiple tiles or does not correctly group these clusters under one device, which results in a confusing user experience.

We would like to request clarification and possible support for the following:

Custom UI support for a single logical device that contains multiple endpoints/clusters.

The recommended method to group multiple functional clusters under one visible device card in the Google Home application.

Whether Google Home currently supports custom Matter UI layouts or combined interfaces for multi-function devices.

Any guidelines, API references, or best practices for designing composite Matter devices that appear as one device in Google Home.

Our goal is to provide a clean and user-friendly interface where all controls are shown in one place rather than as separate devices.

We appreciate your guidance and support.
Please let us know if you require additional details about our device structure or Matter implementation.

[arm_dpe · Accepted solution]

Google Home's UI and functionality for a Matter device are determined by the Device Type implemented on a specific Endpoint (as defined in the Matter Device Library), not by a collection of isolated clusters.

The most effective way to present your multi-function device as a single logical device (one tile/card) in the Google Home app is by placing all primary functional clusters (like Humidity, Fan Control, and other sensor/control features) on the same Matter Endpoint.

• Matter Device Data Model: In Matter, a Node represents the physical device, and it contains one or more Endpoints. An Endpoint is a grouping of Clusters that represents a single logical unit of functionality.
• Google Home Interpretation: Google Home typically maps a single, logical device card in the app to an Endpoint that implements a primary Matter Device Type (e.g., a "Thermostat" or an "Air Quality Sensor"). If you use separate endpoints for each function (e.g., Endpoint 1 for Humidity Sensor, Endpoint 2 for Fan Control), Google Home is likely treating each endpoint as a distinct, separate device, resulting in multiple tiles.
• Solution: For a device that users perceive as a single product (like an advanced air controller), you should define a single primary endpoint (e.g., Endpoint 1) that includes all relevant application clusters (e.g., Fan Control Cluster, Relative Humidity Measurement Cluster, etc.) to consolidate the control interface into one card.

Custom UI Support

• Google Home does not currently support custom Matter UI layouts or custom combined interfaces for third-party devices. The UI, including the main device card, detail view, and controls, is automatically generated by the Google Home app based on the Matter Device Type and the Clusters/Traits it detects on the primary endpoint.
• The system uses the detected Matter Clusters (which map to Google Home Traits) to dynamically build the user interface controls. For example, if the primary endpoint includes the Fan Control Cluster (which maps to the FanSpeed Trait in Google Home), the fan control interface will be automatically included in the device's detail view.

Grouping and Consolidation

• Leverage the Device Type and Cluster Mapping: Your primary goal should be to select the most appropriate Matter Device Type for your main logical function (e.g., an Air Purifier or a more generic device type if available), and ensure that all required and optional functional clusters are exposed on the same endpoint as that Device Type.
• This forces the Google Home app to interpret all those functions as belonging to a single logical entity, displaying them within the single device card and its detail view.

Best Practices for Composite Devices

1. Select the Primary Endpoint: Identify the Matter Endpoint that represents the main purpose of your device. This endpoint should contain the primary Device Type (e.g., AirPurifierDeviceType).
2. Consolidate Clusters: Implement all functional clusters—Humidity Measurement, Fan Control, etc.—on this single primary endpoint.
• Example: Endpoint 1 should have:
• Device Type: AirPurifierDeviceType (or similar)
• Cluster: Fan Control Cluster (for fan speed)
• Cluster: Relative Humidity Measurement Cluster (for sensing)
• Cluster: Temperature Measurement Cluster (if applicable)
3. Endpoint 0: Remember that Matter requires Endpoint 0 to be reserved for utility clusters like the Descriptor Cluster, which provides visibility into all other endpoints.
4. Refer to the Google Home Developer Documentation: Continuously check the official Google Home Developers documentation for supported Matter Device Types and the corresponding Matter Clusters and Google Home Traits. Ensuring your implementation correctly aligns with these mappings is the key to achieving the desired single-card presentation.

By ensuring your device's data model exposes all user-facing functions on a single logical endpoint, you maximize the chances of Google Home correctly consolidating them into the clean, single-card interface you're aiming for.