Unit Localization Cluster

Cluster ID: 0x002D  |  Endpoint: Endpoint 0 (Root Node)

Unit Localization stores the user's temperature unit display preference. After receiving this setting, the device displays temperature in the user's preferred unit on its local screen, panel, etc. This is one of the simplest Clusters in Matter — only 1 attribute, no commands, configured directly via Write operations.

When to Use

The thermostat panel shows Fahrenheit, but the user prefers Celsius? Just write TemperatureUnit = Celsius to switch. This Cluster only affects the display unit; it does not change the device's internal temperature data (internal storage and transmission always use standard units).

Feature Map

Unit Localization defines one Feature — TEMP. Only after the device declares support for this Feature will it expose the TemperatureUnit attribute.

Bit Code Name Description
0 TEMP Temperature Unit Supports temperature unit configuration. Exposes TemperatureUnit attribute when enabled
Relationship Between Feature and Attribute

If the TEMP bit is 0 in the device's Feature Map, the TemperatureUnit attribute will not be exposed, and reading it returns UNSUPPORTED_ATTRIBUTE. For devices that need to display temperature such as thermostats and temperature sensors, TEMP is typically enabled.

Attribute Overview

Unit Localization has only one attribute, depending on the TEMP Feature.

ID Name Type Access Required Feature Description
0x00 TemperatureUnit enum8 Read/Write TEMP Temperature display unit preference

TemperatureUnit (Temperature Display Unit)

The user's preferred temperature display unit. After writing this attribute, the device displays temperature values in the specified unit on its local interface (screen, panel, LED, etc.). This attribute does not affect temperature data reported by the device via Matter protocol — protocol-transmitted temperatures are always in units of 0.01°C.

TempUnitEnum Enum Values

0
Fahrenheit Fahrenheit (°F) — used in the US and a few other regions
1
Celsius Celsius (°C) — used in most of the world
2
Kelvin Kelvin (K) — used in scientific/industrial applications

↑ Back to Attributes

Commands

Unit Localization does not define any commands. All configuration is done through direct attribute writes. This is a common pattern in Matter — for purely configurational Clusters, directly reading/writing attributes is simpler than defining dedicated commands.

How to Configure

Want to switch temperature units? Just send a Write request to the TemperatureUnit attribute. No Timed Interaction required, no security restrictions.

Write request example (switch to Celsius):

{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x002D",
      "attributeId": "0x00"        // TemperatureUnit
    },
    "attributeValue": 1            // Celsius
  }]
}

Read request example (query current settings):

{
  "attributeRequests": [{
    "endpointId": 0,
    "clusterId": "0x002D",
    "attributeId": "0x00"          // TemperatureUnit
  }]
}

Example Data

Reading Unit Localization Cluster attributes on a thermostat device's Endpoint 0:

{
  // --- Attributes ---
  "0x0": 0          // TemperatureUnit = Fahrenheit
}

Real-world Scenarios

Scenario 1: US User — Keep Fahrenheit

Scenario Description

A US user purchases a Matter thermostat. The thermostat defaults to TemperatureUnit = Fahrenheit out of the box, displaying 72°F on the panel. The user is accustomed to Fahrenheit, no changes needed.

After commissioning, the App reads the attribute, finds TemperatureUnit = 0 (Fahrenheit), and syncs the App interface to display temperature in °F. The user sees consistent units on both the App and device panel, requiring no additional action.

Scenario 2: Metric User — Switch to Celsius

Scenario Description

A Chinese user purchases the same thermostat (factory default Fahrenheit). The panel shows 72°F, which the user doesn't understand. The user selects "Celsius" in the App settings, and the App writes TemperatureUnit = 1 (Celsius) to the device.

After successful write, the thermostat panel immediately switches to display 22°C. The App interface also syncs to display in °C. Note: Raw data reported by the device via Matter protocol (e.g. Thermostat Cluster's LocalTemperature) is always an integer in units of 0.01°C, unaffected by TemperatureUnit. This attribute only controls the device's local display and the App's display preference.

Developer Advice

The "Temperature Unit Settings" feature in Apps is typically implemented as follows:

  1. After commissioning, automatically determine the preferred unit based on the phone's locale settings (Locale such as en_US uses Fahrenheit, others use Celsius)
  2. Write TemperatureUnit to device Endpoint 0
  3. App-side temperature display uses the same unit for consistency
  4. Provide a manual switch entry in settings, allowing users to change at any time