Thermostat User Interface Configuration Cluster

Cluster ID: 0x0204 | Endpoint: Same Endpoint as Thermostat (0x0201), typically on Endpoint 1

ThermostatUserInterfaceConfiguration is used to configure the display and operation behavior of the thermostat's physical panel — whether the panel shows temperature in Celsius or Fahrenheit, whether keys are locked, and whether schedule programming is visible. This is a configuration-only Cluster with only 3 attributes and no commands, all configured through Write operations.

Relationship with Thermostat Cluster

Thermostat (0x0201) handles core thermostat logic — temperature reading, setpoints, operating modes, command control. ThermostatUserInterfaceConfiguration (0x0204) only manages the user interface — what the panel displays and what the user can operate. Both coexist on the same Endpoint, each with its own responsibilities.

Difference from Unit Localization

Unit Localization (0x002D) is on Endpoint 0 and controls device-wide temperature display preferences. TemperatureDisplayMode here controls the thermostat's own panel temperature display. Both can be set independently, but it is recommended to keep them consistent to avoid confusing users.

Attributes

ThermostatUserInterfaceConfiguration has 3 attributes, all read/write. Click an attribute ID in the summary table below to jump to its detailed description.

ID	Name	Type	Access	Description
`0x00`	TemperatureDisplayMode	enum8	Read/Write	Panel temperature display unit (Celsius / Fahrenheit)
`0x01`	KeypadLockout	enum8	Read/Write	Panel keypad lock level (No lock / Level 1-5)
`0x02`	ScheduleProgrammingVisibility	enum8	Read/Write	Whether schedule programming is visible on the panel

TemperatureDisplayMode (Temperature Display Mode)

Controls the temperature display unit on the thermostat's physical panel. After writing, the temperature numbers on the panel immediately display in the new unit. This attribute does not affect temperature values reported by the Thermostat Cluster via the Matter protocol — temperatures transmitted over the protocol are always in 0.01°C units.

TemperatureDisplayModeEnum Enum Values

Celsius Celsius (°C) — default value, used in most regions worldwide

Fahrenheit Fahrenheit (°F) — used in the United States and other regions

↑ Back to Attributes

KeypadLockout (Keypad Lockout)

Controls the keypad lock level on the thermostat panel. When locked, users cannot modify specific settings via physical keys and can only make changes remotely through the Matter protocol (App / automation). This is very useful in commercial and public venues — preventing unauthorized temperature adjustments.

Lock Level Description

The Matter specification defines 5 lock levels, but which specific functions each level locks is determined by the manufacturer. The specification only requires that higher levels lock more functions. Level 5 locks all local operations. The function restriction descriptions below are typical implementation references; actual behavior depends on the device manufacturer's documentation.

KeypadLockoutEnum Enum Values

NoLockout No lockout — all panel keys available (default)

LockoutLevel1 Level 1 lockout — typically locks schedule programming

LockoutLevel2 Level 2 lockout — typically also locks mode switching (heat/cool/auto)

LockoutLevel3 Level 3 lockout — typically also locks fan speed adjustment

LockoutLevel4 Level 4 lockout — typically also locks temperature setpoint adjustment

LockoutLevel5 Level 5 lockout — locks all local operations, panel is view-only

Lockout ≠ Disable

Keypad lockout only prevents modifying settings through the physical panel and does not affect remote operations via the Matter protocol. Even with KeypadLockout = Level5, App and automation rules can still adjust temperature and switch modes normally. This is the core purpose of this attribute — centralizing control authority to the remote management side.

↑ Back to Attributes

ScheduleProgrammingVisibility (Schedule Programming Visibility)

Controls whether the schedule programming feature entry is displayed on the thermostat panel. When hidden, users cannot see schedule-related menus or buttons on the panel and can only manage schedules through the App.

ScheduleProgrammingVisibilityEnum Enum Values

ScheduleProgrammingPermitted Schedule visible — users can view and edit schedules on the panel (default)

ScheduleProgrammingDenied Schedule hidden — schedule function not displayed on panel, can only be managed through the App

↑ Back to Attributes

Commands

ThermostatUserInterfaceConfiguration does not define any commands. All configuration is done through direct attribute writes. This is a common pattern in Matter — for configuration-only Clusters, direct attribute read/write is simpler than defining dedicated commands.

How to Configure

Want to switch temperature display units? Simply send a Write request to the TemperatureDisplayMode attribute. Want to lock the panel? Just write to KeypadLockout. No Timed Interaction needed.

Write request example — switch to Fahrenheit display:

{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x0204",
      "attributeId": "0x00"           // TemperatureDisplayMode
    },
    "attributeValue": 1               // Fahrenheit
  }]
}

Write request example — set keypad Level 1 lockout:

{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x0204",
      "attributeId": "0x01"           // KeypadLockout
    },
    "attributeValue": 1               // LockoutLevel1
  }]
}

Example Data

Reading ThermostatUserInterfaceConfiguration attributes on Endpoint 1 of a thermostat:

{
  // --- Display Configuration ---
  "0x00": 0,             // TemperatureDisplayMode = Celsius
  "0x01": 0,             // KeypadLockout = NoLockout
  "0x02": 0              // ScheduleProgrammingVisibility = ScheduleProgrammingPermitted (schedule visible)
}

Attribute Count

This Cluster has no Feature Map controlling attribute visibility — all 3 attributes are always exposed. If reading an attribute returns UNSUPPORTED_ATTRIBUTE, it means the device has not implemented that optional attribute (ScheduleProgrammingVisibility is optional in the Matter specification).

Real-world Scenarios

Scenario 1: Hotel Room Thermostat — Lock Panel to Prevent Tampering

Expand scenario

A hotel uses Matter thermostats to manage guest room HVAC. To prevent guests from freely modifying AC modes and schedules, the property management system configures each thermostat as follows:

Write KeypadLockout = 4 (LockoutLevel4) — guests can only view temperature, cannot adjust temperature or switch modes via the panel
Write ScheduleProgrammingVisibility = 1 (ScheduleProgrammingDenied) — hide schedule function
Write TemperatureDisplayMode = 0 (Celsius) — uniform Celsius display

Guests can only see the current temperature on the panel. All temperature adjustments are done through the room App, which can limit the adjustment range (e.g., only allowing 20~26°C), preventing guests from setting extreme temperatures. During housekeeping, the property management system remotely sets all units to energy-saving temperatures.

Scenario 2: Export to Different Regions — Auto-configure Display Units During Commissioning

Expand scenario

A Matter thermostat for the global market, factory-default displaying Celsius. After commissioning, the App automatically configures temperature display based on the user's phone locale:

Read phone Locale: if it is en_US (United States) or en_LR (Liberia), etc., temperature preference is Fahrenheit
Write TemperatureDisplayMode = 1 (Fahrenheit) to Endpoint 1
Also write TemperatureUnit = 0 (Fahrenheit) to Unit Localization (0x002D) on Endpoint 0, keeping device-wide display consistent
The App interface also synchronizes to display temperature in °F

This way, when users receive the device, both the panel and App show familiar temperature units without manual switching. If users want to change later, they select another unit in App settings, and the App updates both Cluster attributes simultaneously.