TimeFormatLocalization Cluster

Cluster ID: 0x002C  |  Endpoint: Endpoint 0 (Root)  |  Role: Server (configured via Write attribute, no commands)

TimeFormatLocalization controls the time and date display format preferences on the device. It is not responsible for obtaining or synchronizing time itself (that is the job of TimeSynchronization Cluster), but rather determines how the device displays time on screens, panels, etc. — 12-hour or 24-hour format, Gregorian or other calendars.

This Cluster is very compact — at minimum only 1 attribute (HourFormat), with 2 additional calendar-related attributes when CALFMT Feature is supported. No commands; all configuration is done through direct attribute writes.

When to Use

A user gets a smart device with a screen (thermostat, smart panel, door lock with display), finds the time displayed in 12-hour format, and wants to change to 24-hour? Just write HourFormat. Need to display a lunar calendar date on the device screen? First confirm the device supports CALFMT Feature, then write ActiveCalendarType.

Feature Bitmap

TimeFormatLocalization declares calendar format support through FeatureMap (0xFFFC):

Bit 0
CALFMT（CalendarFormat） Calendar format — enables ActiveCalendarType and SupportedCalendarTypes attributes for switching between Gregorian, Chinese lunar, and other calendar systems
Feature Impact on Attributes

HourFormat is mandatory, regardless of Features. Only when the device declares the CALFMT Feature are ActiveCalendarType and SupportedCalendarTypes available. Simple devices (e.g. outlets with only a clock display) typically don't support CALFMT and have only the HourFormat attribute.

Attribute Overview

TimeFormatLocalization has up to 3 attributes, 2 of which depend on CALFMT Feature. Click an attribute ID to jump to its detailed description.

ID Name Type Access Feature Description
0x00 HourFormat enum8 Read/Write - Time display format (12/24-hour)
0x01 ActiveCalendarType enum8 Read/Write CALFMT Currently used calendar type
0x02 SupportedCalendarTypes list<enum8> Read-only CALFMT List of all calendar types supported by the device

HourFormat (Time Display Format)

Controls whether the device displays time in 12-hour or 24-hour format. This is TimeFormatLocalization's only mandatory attribute; all devices supporting this Cluster must implement it. Read/write; switch by directly writing the attribute.

HourFormatEnum Enum Values

0
12hr 12-hour format with AM/PM (e.g. 2:30 PM)
1
24hr 24-hour format (e.g. 14:30)
0xFF
UseActiveLocale Automatically determined by current locale setting (follows LocalizationConfiguration Cluster's ActiveLocale)
UseActiveLocale Behavior

When HourFormat is set to 0xFF (UseActiveLocale), the device will follow the ActiveLocale attribute in the LocalizationConfiguration Cluster to automatically select the time format. For example, en-US automatically uses 12-hour format, zh-CN automatically uses 24-hour format. This is the most hassle-free choice, letting the device follow language settings automatically.

Write attribute example (switch to 12-hour format):

// App → Device: Switch time display to 12-hour format
{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x002C",
      "attributeId": "0x00"        // HourFormat
    },
    "data": 0                      // 12hr
  }]
}

↑ Back to Attributes

ActiveCalendarType (Current Calendar Type)

Controls which calendar system the device uses to display dates. Read/write, but only values in the SupportedCalendarTypes list can be written. Requires device support for the CALFMT Feature; otherwise this attribute does not exist.

CalendarTypeEnum Enum Values

0
Buddhist Buddhist calendar (used in Thailand, Sri Lanka, etc.)
1
Chinese Chinese lunar calendar (with solar terms and zodiac)
2
Coptic Coptic calendar (used by the Coptic Church in Egypt)
3
Ethiopian Ethiopian calendar
4
Gregorian Gregorian calendar (global standard, most common)
5
Hebrew Hebrew calendar (Jewish calendar)
6
Indian Indian National Calendar
7
Islamic Islamic calendar (Hijri)
8
Japanese Japanese calendar (era names such as Reiwa, Heisei)
9
Korean Korean Dangun calendar
10
Persian Persian calendar (Iranian calendar)
11
Taiwanese Taiwanese Minguo calendar
0xFF
UseActiveLocale Automatically determined by current locale setting
Check Supported List Before Writing

Not all devices support all 12 calendar types. Before writing to ActiveCalendarType, you must first read SupportedCalendarTypes to confirm the target calendar is in the list. Writing an unsupported value will be rejected by the device (returns CONSTRAINT_ERROR).

Write attribute example (switch to Chinese lunar calendar):

// App → Device: Switch calendar to Chinese Lunar
{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x002C",
      "attributeId": "0x01"        // ActiveCalendarType
    },
    "data": 1                      // Chinese (Chinese Lunar)
  }]
}

↑ Back to Attributes

SupportedCalendarTypes (Supported Calendar List)

Read-only attribute returning a list of all calendar types the device supports. Each element in the list is a CalendarTypeEnum value. Apps should use this list to build the calendar selection UI — only showing options the device actually supports. Requires device support for the CALFMT Feature.

Developer Advice

After reading SupportedCalendarTypes, use it to dynamically generate the calendar options list on the settings page. Most devices will only support Gregorian and one or two locally common calendars; don't hardcode all 12. If the list has only one item, consider hiding the calendar switching entry.

↑ Back to Attributes

Example Data

Reading TimeFormatLocalization attributes from a smart thermostat supporting CALFMT Feature:

{
  // --- Time Format ---
  "0x00": 1,              // HourFormat = 24hr (24-hour format)

  // --- Calendar Format (requires CALFMT Feature) ---
  "0x01": 4,              // ActiveCalendarType = Gregorian
  "0x02": [4, 0, 1]       // SupportedCalendarTypes = [Gregorian, Buddhist, Chinese]
}

Common Scenarios

Scenario 1: Thermostat Time Format Settings

A user has installed a new smart thermostat, and the screen shows 12-hour format (e.g. 2:30 PM). The user prefers 24-hour format and wants to switch via the App.

  1. Read HourFormat to confirm current value is 0 (12hr)
  2. App settings page shows three options: 12-hour, 24-hour, follow system language
  3. User selects 24-hour format, App writes HourFormat = 1 (24hr)
  4. Device screen immediately changes from "2:30 PM" to "14:30"
  5. If the device supports CALFMT, the same settings page can also show calendar switching options
Scenario 2: Calendar Localization for Multi-region Smart Panels

A smart home panel for the global market, with the main screen displaying date and time. Users in different regions need different calendar formats — Chinese users want the lunar calendar, Middle Eastern users want the Islamic calendar.

  1. Read FeatureMap to confirm the device supports CALFMT (Bit 0 = 1)
  2. Read SupportedCalendarTypes, assume it returns [4, 1, 7] (Gregorian, Chinese Lunar, Islamic)
  3. App settings page dynamically generates options from the list with localized names: "Gregorian", "Chinese Lunar", "Islamic"
  4. Chinese user selects lunar calendar, App writes ActiveCalendarType = 1 (Chinese)
  5. Panel screen date area changes from "2024-09-22" to also display the corresponding lunar date
  6. Can also be set to UseActiveLocale (0xFF), letting the panel automatically choose the appropriate calendar based on language settings