Add XML and generated files of the Energy Calendar cluster

.github/workflows/tests.yaml

@@ -206,6 +206,7 @@ jobs:
                       src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/electrical-energy-measurement-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/electrical-power-measurement-cluster.xml \
+                      src/app/zap-templates/zcl/data-model/chip/energy-calendar-cluster.xml \
                     "
             - name: Build Apps
               run: |

docs/zap_clusters.md

@@ -82,6 +82,7 @@ Generally regenerate using one of:
 |        151 |       0x97 | Messages                                                |
 |        152 |       0x98 | DeviceEnergyManagement                                  |
 |        153 |       0x99 | EnergyEvse                                              |
+|        154 |       0x9A | EnergyCalendar                                          |
 |        155 |       0x9B | EnergyPreference                                        |
 |        156 |       0x9C | PowerTopology                                           |
 |        157 |       0x9D | EnergyEvseMode                                          |

scripts/rules.matterlint

@@ -117,6 +117,7 @@ load "../src/app/zap-templates/zcl/data-model/chip/resource-monitoring-cluster.x
 load "../src/app/zap-templates/zcl/data-model/chip/sample-mei-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/electrical-energy-measurement-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/electrical-power-measurement-cluster.xml";
+load "../src/app/zap-templates/zcl/data-model/chip/energy-calendar-cluster.xml";
 
 all endpoints {
     // These attributes follow a different code path and do not have to be

src/app/zap-templates/zcl/data-model/chip/energy-calendar-cluster.xml

@@ -0,0 +1,116 @@
+<?xml version="1.0"?>
+<!--
+Copyright (c) 2024 Project CHIP Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<configurator>
+  <domain name="Energy Management"/>
+  <bitmap name="AuxiliaryLoadBitmap" type="bitmap8">
+    <cluster code="0x009A"/>
+    <field name="AuxiliarySwitch1" mask="0x01"/>
+    <field name="AuxiliarySwitch2" mask="0x02"/>
+    <field name="AuxiliarySwitch3" mask="0x04"/>
+    <field name="AuxiliarySwitch4" mask="0x08"/>
+    <field name="AuxiliarySwitch5" mask="0x10"/>
+    <field name="AuxiliarySwitch6" mask="0x20"/>
+    <field name="AuxiliarySwitch7" mask="0x40"/>
+    <field name="AuxiliarySwitch8" mask="0x80"/>
+  </bitmap>
+
+  <bitmap name="TransitionDayOfWeekBitmap" type="bitmap8">
+    <cluster code="0x009A"/>
+    <field name="Sunday" mask="0x01"/>
+    <field name="Monday" mask="0x02"/>
+    <field name="Tuesday" mask="0x04"/>
+    <field name="Wednesday" mask="0x08"/>
+    <field name="Thursday" mask="0x10"/>
+    <field name="Friday" mask="0x20"/>
+    <field name="Saturday" mask="0x40"/>
+  </bitmap>
+
+  <enum name="PeakPeriodSeverityEnum" type="enum8">
+    <cluster code="0x009A"/>
+    <item name="Unused" value="0x00"/>
+    <item name="Low" value="0x01"/>
+    <item name="Medium" value="0x02"/>
+    <item name="High" value="0x03"/>
+  </enum>
+
+  <struct name="CalendarPeriodStruct" apiMaturity="provisional">
+    <cluster code="0x009A"/>
+    <item fieldId="0" name="StartDate" type="epoch_s" isNullable="true"/>
+    <item fieldId="1" name="Days" array="true" type="DayStruct" length="7" minLength="1"/>
+  </struct>
+
+  <struct name="DayStruct" apiMaturity="provisional">
+    <cluster code="0x009A"/>
+    <item fieldId="0" name="Date" type="epoch_s" optional="true"/>
+    <item fieldId="1" name="DaysOfWeek" type="TransitionDayOfWeekBitmap" optional="true" min="0x00" max="0x7F"/>
+    <item fieldId="2" name="Transitions" array="true" type="TransitionStruct" length="48" minLength="1"/>
+    <item fieldId="3" name="CalendarID" type="int32u" optional="true"/>
+  </struct>
+
+  <struct name="PeakPeriodStruct" apiMaturity="provisional">
+    <cluster code="0x009A"/>
+    <item fieldId="0" name="Severity" type="PeakPeriodSeverityEnum" min="0x00" max="0x03"/>
+    <item fieldId="1" name="PeakPeriod" type="int16u" default="0"/>
+    <item fieldId="2" name="StartTime" type="epoch_s" isNullable="true"/>
+    <item fieldId="3" name="EndTime" type="epoch_s" isNullable="true"/>
+  </struct>
+
+  <struct name="TransitionStruct" apiMaturity="provisional">
+    <cluster code="0x009A"/>
+    <item fieldId="0" name="TransitionTime" type="int16u" max="1499"/>
+    <item fieldId="1" name="PriceTier" type="int32u" optional="true"/>
+    <item fieldId="2" name="FriendlyCredit" type="boolean" optional="true"/>
+    <item fieldId="3" name="AuxiliaryLoad" type="AuxiliaryLoadBitmap" optional="true" min="0x00" max="0xFF"/>
+  </struct>
+
+  <cluster>
+    <domain>Energy Management</domain>
+    <name>Energy Calendar</name>
+    <code>0x009A</code>
+    <define>ENERGY_CALENDAR_CLUSTER</define>
+    <description>The Energy Calendar Cluster provides a mechanism for communicating schedules associated with various forms of energy consumption</description>
+    <client init="false" tick="false">true</client>
+    <features>
+      <feature bit="0" code="PTIER" name="PricingTier" summary="Supports information about pricing tiers">
+        <optionalConform choice="a" more="true" min="1"/>
+      </feature>
+      <feature bit="1" code="FCRED" name="FriendlyCredit" summary="Supports information about when friendly credit periods begin and end">
+        <optionalConform choice="a" more="true" min="1"/>
+      </feature>
+      <feature bit="2" code="AUXLD" name="AuxiliaryLoad" summary="Supports information about when auxiliary loads should be enabled or disabled">
+        <optionalConform choice="a" more="true" min="1"/>
+      </feature>
+      <feature bit="3" code="PEAKP" name="PeakPeriod" summary="Supports information about peak periods">
+        <optionalConform/>
+      </feature>
+    </features>
+    <server init="false" tick="false">true</server>
+    <globalAttribute code="0xFFFD" side="either" value="3"/>
+    <attribute code="0x0000" side="server" define="CALENDAR_ID" type="int32u" isNullable="true">CalendarID</attribute>
+    <attribute code="0x0001" side="server" define="NAME" type="char_string" isNullable="true" length="12">Name</attribute>
+    <attribute code="0x0002" side="server" define="PROVIDER_ID" type="int32u" isNullable="true">ProviderID</attribute>
+    <attribute code="0x0003" side="server" define="EVENT_ID" type="int32u" isNullable="true">EventID</attribute>
+    <attribute code="0x0004" side="server" define="START_DATE" type="epoch_s" isNullable="true">StartDate</attribute>
+    <attribute code="0x0005" side="server" define="CALENDAR_PERIODS" type="array" entryType="CalendarPeriodStruct" isNullable="true" length="4" minLength="1">CalendarPeriods</attribute>
+    <attribute code="0x0006" side="server" define="SPECIAL_DAYS" type="array" entryType="DayStruct" isNullable="true" length="50">SpecialDays</attribute>
+    <attribute code="0x0007" side="server" define="CURRENT_DAY" type="DayStruct" isNullable="true">CurrentDay</attribute>
+    <attribute code="0x0008" side="server" define="NEXT_DAY" type="DayStruct" isNullable="true">NextDay</attribute>
+    <attribute code="0x0009" side="server" define="CURRENT_TRANSITION" type="TransitionStruct" isNullable="true">CurrentTransition</attribute>
+    <attribute code="0x000A" side="server" define="CURRENT_PEAK_PERIOD" type="PeakPeriodStruct" isNullable="true" optional="true">CurrentPeakPeriod</attribute>
+    <attribute code="0x000B" side="server" define="NEXT_PEAK_PERIOD" type="PeakPeriodStruct" isNullable="true" optional="true">NextPeakPeriod</attribute>
+  </cluster>
+</configurator>

src/app/zap-templates/zcl/zcl-with-test-extensions.json

@@ -47,6 +47,7 @@
         "microwave-oven-control-cluster.xml",
         "door-lock-cluster.xml",
         "ecosystem-information-cluster.xml",
+        "energy-calendar-cluster.xml",
         "energy-preference-cluster.xml",
         "electrical-energy-measurement-cluster.xml",
         "electrical-power-measurement-cluster.xml",
@@ -659,6 +660,16 @@
             "NeutralCurrent",
             "FeatureMap"
         ],
+        "Energy Calendar": [
+            "CalendarPeriods",
+            "SpecialDays",
+            "CurrentDay",
+            "NextDay",
+            "CurrentTransition",
+            "CurrentPeakPeriod",
+            "NextPeakPeriod",
+            "FeatureMap"
+        ],
         "Power Topology": ["FeatureMap"],
         "Valve Configuration and Control": ["RemainingDuration"],
         "Boolean State Configuration": ["CurrentSensitivityLevel"],

src/app/zap-templates/zcl/zcl.json

@@ -43,6 +43,7 @@
         "ecosystem-information-cluster.xml",
         "electrical-energy-measurement-cluster.xml",
         "electrical-power-measurement-cluster.xml",
+        "energy-calendar-cluster.xml",
         "energy-evse-cluster.xml",
         "energy-evse-mode-cluster.xml",
         "energy-preference-cluster.xml",
@@ -653,6 +654,16 @@
             "NeutralCurrent",
             "FeatureMap"
         ],
+        "Energy Calendar": [
+            "CalendarPeriods",
+            "SpecialDays",
+            "CurrentDay",
+            "NextDay",
+            "CurrentTransition",
+            "CurrentPeakPeriod",
+            "NextPeakPeriod",
+            "FeatureMap"
+        ],
         "Power Topology": ["FeatureMap"],
         "Valve Configuration and Control": ["RemainingDuration"],
         "Boolean State Configuration": ["CurrentSensitivityLevel"],

src/app/zap_cluster_list.json

@@ -33,6 +33,7 @@
         "DIAGNOSTIC_LOGS_CLUSTER": [],
         "DISHWASHER_ALARM_CLUSTER": [],
         "DISHWASHER_MODE_CLUSTER": [],
+        "ENERGY_CALENDAR_CLUSTER": [],
         "MICROWAVE_OVEN_MODE_CLUSTER": [],
         "DOOR_LOCK_CLUSTER": [],
         "ECOSYSTEM_INFORMATION_CLUSTER": [],
@@ -178,6 +179,7 @@
         "DIAGNOSTIC_LOGS_CLUSTER": ["diagnostic-logs-server"],
         "DISHWASHER_ALARM_CLUSTER": ["dishwasher-alarm-server"],
         "DISHWASHER_MODE_CLUSTER": ["mode-base-server"],
+        "ENERGY_CALENDAR_CLUSTER": ["energy-calendar-server"],
         "MICROWAVE_OVEN_MODE_CLUSTER": ["mode-base-server"],
         "DOOR_LOCK_CLUSTER": ["door-lock-server"],
         "ECOSYSTEM_INFORMATION_CLUSTER": ["ecosystem-information-server"],

src/controller/data_model/controller-clusters.matter

@@ -5437,6 +5437,91 @@ cluster EnergyEvse = 153 {
   timed command ClearTargets(): DefaultSuccess = 7;
 }
 
+/** The Energy Calendar Cluster provides a mechanism for communicating schedules associated with various forms of energy consumption */
+cluster EnergyCalendar = 154 {
+  revision 3;
+
+  enum PeakPeriodSeverityEnum : enum8 {
+    kUnused = 0;
+    kLow = 1;
+    kMedium = 2;
+    kHigh = 3;
+  }
+
+  bitmap AuxiliaryLoadBitmap : bitmap8 {
+    kAuxiliarySwitch1 = 0x1;
+    kAuxiliarySwitch2 = 0x2;
+    kAuxiliarySwitch3 = 0x4;
+    kAuxiliarySwitch4 = 0x8;
+    kAuxiliarySwitch5 = 0x10;
+    kAuxiliarySwitch6 = 0x20;
+    kAuxiliarySwitch7 = 0x40;
+    kAuxiliarySwitch8 = 0x80;
+  }
+
+  bitmap Feature : bitmap32 {
+    kPricingTier = 0x1;
+    kFriendlyCredit = 0x2;
+    kAuxiliaryLoad = 0x4;
+    kPeakPeriod = 0x8;
+  }
+
+  bitmap TransitionDayOfWeekBitmap : bitmap8 {
+    kSunday = 0x1;
+    kMonday = 0x2;
+    kTuesday = 0x4;
+    kWednesday = 0x8;
+    kThursday = 0x10;
+    kFriday = 0x20;
+    kSaturday = 0x40;
+  }
+
+  struct TransitionStruct {
+    int16u transitionTime = 0;
+    optional int32u priceTier = 1;
+    optional boolean friendlyCredit = 2;
+    optional AuxiliaryLoadBitmap auxiliaryLoad = 3;
+  }
+
+  struct DayStruct {
+    optional epoch_s date = 0;
+    optional TransitionDayOfWeekBitmap daysOfWeek = 1;
+    TransitionStruct transitions[] = 2;
+    optional int32u calendarID = 3;
+  }
+
+  struct CalendarPeriodStruct {
+    nullable epoch_s startDate = 0;
+    DayStruct days[] = 1;
+  }
+
+  struct PeakPeriodStruct {
+    PeakPeriodSeverityEnum severity = 0;
+    int16u peakPeriod = 1;
+    nullable epoch_s startTime = 2;
+    nullable epoch_s endTime = 3;
+  }
+
+  readonly attribute nullable int32u calendarID = 0;
+  readonly attribute nullable char_string<12> name = 1;
+  readonly attribute nullable int32u providerID = 2;
+  readonly attribute nullable int32u eventID = 3;
+  readonly attribute nullable epoch_s startDate = 4;
+  readonly attribute nullable CalendarPeriodStruct calendarPeriods[] = 5;
+  readonly attribute nullable DayStruct specialDays[] = 6;
+  readonly attribute nullable DayStruct currentDay = 7;
+  readonly attribute nullable DayStruct nextDay = 8;
+  readonly attribute nullable TransitionStruct currentTransition = 9;
+  readonly attribute optional nullable PeakPeriodStruct currentPeakPeriod = 10;
+  readonly attribute optional nullable PeakPeriodStruct nextPeakPeriod = 11;
+  readonly attribute command_id generatedCommandList[] = 65528;
+  readonly attribute command_id acceptedCommandList[] = 65529;
+  readonly attribute event_id eventList[] = 65530;
+  readonly attribute attrib_id attributeList[] = 65531;
+  readonly attribute bitmap32 featureMap = 65532;
+  readonly attribute int16u clusterRevision = 65533;
+}
+
 /** This cluster provides an interface to specify preferences for how devices should consume energy. */
 provisional cluster EnergyPreference = 155 {
   revision 1;