[Feature]Add operational state cluster xml and code gen (#26736)

* Add operational state cluster xml to data-model * Zap generated for operational state cluster * Restyled by prettier-json * Fix Android and Java test build * Fix operational state cluster's xml match the spec * Fix Java codegen bits missing * Zap generated for operational state cluster * Zap generated for operational state cluster * Fix Java header generation for attributes with nullable list type. * Fix OperationalStateStruct's field OperationalStateLabel missing Constraint * Zap generated for operational state cluster --------- Co-authored-by: Restyled.io <[email protected]> Co-authored-by: Boris Zbarsky <[email protected]>
project-chip · May 27, 2023 · bd43948 · bd43948
1 parent f223899
commit bd43948
Show file tree

Hide file tree

Showing 60 changed files with 9,599 additions and 401 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -164,6 +164,7 @@ jobs:
                       src/app/zap-templates/zcl/data-model/chip/occupancy-sensing-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/onoff-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/operational-credentials-cluster.xml \
+                      src/app/zap-templates/zcl/data-model/chip/operational-state-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/pressure-measurement-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/power-source-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/power-source-configuration-cluster.xml \

diff --git a/scripts/rules.matterlint b/scripts/rules.matterlint
@@ -47,6 +47,7 @@ load "../src/app/zap-templates/zcl/data-model/chip/network-commissioning-cluster
 load "../src/app/zap-templates/zcl/data-model/chip/occupancy-sensing-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/onoff-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/operational-credentials-cluster.xml";
+load "../src/app/zap-templates/zcl/data-model/chip/operational-state-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/power-source-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/power-source-configuration-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/pressure-measurement-cluster.xml";

diff --git a/src/app/zap-templates/zcl/data-model/all.xml b/src/app/zap-templates/zcl/data-model/all.xml
@@ -46,6 +46,7 @@
    <xi:include href="chip/occupancy-sensing-cluster.xml" />
    <xi:include href="chip/onoff-cluster.xml" />
    <xi:include href="chip/operational-credentials-cluster.xml" />
+   <xi:include href="chip/operational-state-cluster.xml" />
    <xi:include href="chip/pressure-measurement-cluster.xml" />
    <xi:include href="chip/power-source-cluster.xml" />
    <xi:include href="chip/power-source-configuration-cluster.xml" />

diff --git a/src/app/zap-templates/zcl/data-model/chip/operational-state-cluster.xml b/src/app/zap-templates/zcl/data-model/chip/operational-state-cluster.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0"?>
+<!--
+Copyright (c) 2023 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="CHIP"/>
+
+  <enum name="OperationalStateEnum" type="ENUM8">
+    <cluster code="0x0060"/>
+    <item name="Stopped" value="0x00"/>
+    <item name="Running" value="0x01"/>
+    <item name="Paused"  value="0x02"/>
+    <item name="Error"   value="0x03"/>
+  </enum>
+
+  <enum name="ErrorStateEnum" type="ENUM8">
+    <cluster code="0x0060"/>
+    <item name="NoError"                    value="0x00"/>
+    <item name="UnableToStartOrResume"      value="0x01"/>
+    <item name="UnableToCompleteOperation"  value="0x02"/>
+    <item name="CommandInvalidInState"      value="0x03"/>
+  </enum>
+
+  <struct name="OperationalStateStruct">
+    <cluster code="0x0060"/>
+    <item name="OperationalStateID"    type="OperationalStateEnum" optional="false"/>
+    <item name="OperationalStateLabel" type="CHAR_STRING" optional="false" length="64"/>
+  </struct>
+
+  <struct name="ErrorStateStruct">
+    <cluster code="0x0060"/>
+    <item name="ErrorStateID" type="ErrorStateEnum" optional="false" />
+    <item name="ErrorStateLabel" type="CHAR_STRING" optional="false" isNullable="true" length="64"/>
+    <item name="ErrorStateDetails" type="CHAR_STRING" optional="true" length="64"/>
+  </struct>
+
+  <cluster>
+    <domain>General</domain>
+    <name>Operational State</name>
+    <code>0x0060</code>
+    <define>OPERATIONAL_STATE_CLUSTER</define>
+    <client init="false" tick="false">true</client>
+    <server init="false" tick="false">true</server>
+    <description>This cluster supports remotely monitoring and, where supported, changing the operational state of any device where a state machine is a part of the operation.</description>
+
+    <globalAttribute side="server" code="0xFFFD" value="1" />
+
+    <attribute side="server" code="0x0000" define="PHASE_LIST"              type="ARRAY" entryType="CHAR_STRING"                                     writable="false" isNullable="true"  optional="false">PhaseList</attribute>
+    <attribute side="server" code="0x0001" define="CURRENT_PHASE"           type="INT8U"                                    min="0x00" max="0x1F"    writable="false" isNullable="true"  optional="false">CurrentPhase</attribute>
+    <attribute side="server" code="0x0002" define="COUNTDOWN_TIME"          type="elapsed_s"                                min="0x00" max="2529200" writable="false" isNullable="true"  optional="true">CountdownTime</attribute>
+    <attribute side="server" code="0x0003" define="OPERATIONAL_STATE_LIST"  type="ARRAY" entryType="OperationalStateStruct"                          writable="false"                    optional="false">OperationalStateList</attribute>
+    <attribute side="server" code="0x0004" define="OPERATIONAL_STATE"       type="OperationalStateStruct"                                            writable="false"                    optional="false">OperationalState</attribute>
+    <attribute side="server" code="0x0005" define="OPERATIONAL_ERROR"       type="ErrorStateStruct"                                                   writable="false"                    optional="false">OperationalError</attribute>
+
+    <command source="client" code="0x00" name="Pause" response="OperationalCommandResponse" optional="true">
+      <description>Upon receipt, the device SHALL pause its operation if it is possible based on the current function of the server.</description>
+    </command>
+
+    <command source="client" code="0x01" name="Stop" response="OperationalCommandResponse" optional="true">
+      <description>Upon receipt, the device SHALL stop its operation if it is at a position where it is safe to do so and/or permitted.</description>
+    </command>
+
+    <command source="client" code="0x02" name="Start" response="OperationalCommandResponse" optional="true">
+      <description>Upon receipt, the device SHALL start its operation if it is safe to do so and the device is in an operational state from which it can be started.</description>
+    </command>
+
+    <command source="client" code="0x03" name="Resume" response="OperationalCommandResponse" optional="true">
+      <description>Upon receipt, the device SHALL resume its operation from the point it was at when it received the Pause command, or from the point when it was paused by means outside of this cluster (for example by manual button press).</description>
+    </command>
+
+    <command source="server" code="0x04" name="OperationalCommandResponse" optional="true">
+      <description>This command SHALL be generated in response to any of the Start, Stop, Pause, or Resume commands.</description>
+      <arg name="CommandResponseState" type="ErrorStateStruct"/>
+    </command>
+
+    <event side="server" code="0x00" priority="critical" name="OperationalError" optional="false">
+      <description>OperationalError</description>
+      <field id="0" name="ErrorState" type="ErrorStateStruct" />
+    </event>
+
+     <event side="server" code="0x01" priority="info" name="OperationCompletion" optional="true">
+      <description>OperationCompletion</description>
+      <field id="0" name="CompletionErrorCode"  type="ErrorStateEnum" />
+      <field id="1" name="TotalOperationalTime" type="elapsed_s" isNullable="true" optional="true"/>
+      <field id="2" name="PausedTime"           type="elapsed_s" isNullable="true" optional="true"/>
+    </event>
+
+  </cluster>
+</configurator>
diff --git a/src/app/zap-templates/zcl/zcl-with-test-extensions.json b/src/app/zap-templates/zcl/zcl-with-test-extensions.json
@@ -64,6 +64,7 @@
         "onoff-cluster.xml",
         "onoff-switch-configuration-cluster.xml",
         "operational-credentials-cluster.xml",
+        "operational-state-cluster.xml",
         "pressure-measurement-cluster.xml",
         "power-source-cluster.xml",
         "power-source-configuration-cluster.xml",
@@ -290,7 +291,8 @@
             "UTCTime",
             "LocalTime"
         ],
-        "Temperature Control": ["SupportedTemperatureLevels"]
+        "Temperature Control": ["SupportedTemperatureLevels"],
+        "Operational State": ["OperationalState", "OperationalError"]
     },
     "defaultReportingPolicy": "mandatory",
     "ZCLDataTypes": ["ARRAY", "BITMAP", "ENUM", "NUMBER", "STRING", "STRUCT"],

diff --git a/src/app/zap-templates/zcl/zcl.json b/src/app/zap-templates/zcl/zcl.json
@@ -62,6 +62,7 @@
         "onoff-cluster.xml",
         "onoff-switch-configuration-cluster.xml",
         "operational-credentials-cluster.xml",
+        "operational-state-cluster.xml",
         "pressure-measurement-cluster.xml",
         "power-source-cluster.xml",
         "power-source-configuration-cluster.xml",
@@ -288,7 +289,8 @@
             "UTCTime",
             "LocalTime"
         ],
-        "Temperature Control": ["SupportedTemperatureLevels"]
+        "Temperature Control": ["SupportedTemperatureLevels"],
+        "Operational State": ["OperationalState", "OperationalError"]
     },
     "defaultReportingPolicy": "mandatory",
     "ZCLDataTypes": ["ARRAY", "BITMAP", "ENUM", "NUMBER", "STRING", "STRUCT"],

diff --git a/src/app/zap_cluster_list.json b/src/app/zap_cluster_list.json
@@ -81,6 +81,7 @@
         "ON_OFF_CLUSTER": [],
         "ON_OFF_SWITCH_CONFIGURATION_CLUSTER": [],
         "OPERATIONAL_CREDENTIALS_CLUSTER": [],
+        "OPERATIONAL_STATE_CLUSTER": [],
         "OTA_BOOTLOAD_CLUSTER": [],
         "OTA_SOFTWARE_UPDATE_PROVIDER_CLUSTER": [],
         "OTA_SOFTWARE_UPDATE_REQUESTOR_CLUSTER": [],

diff --git a/src/controller/data_model/BUILD.gn b/src/controller/data_model/BUILD.gn
@@ -156,6 +156,8 @@ if (current_os == "android" || build_java_matter_controller) {
       "jni/OtaSoftwareUpdateRequestorClient-ReadImpl.cpp",
       "jni/OzoneFilterMonitoringClient-InvokeSubscribeImpl.cpp",
       "jni/OzoneFilterMonitoringClient-ReadImpl.cpp",
+      "jni/OperationalStateClient-InvokeSubscribeImpl.cpp",
+      "jni/OperationalStateClient-ReadImpl.cpp",
       "jni/PowerSourceClient-InvokeSubscribeImpl.cpp",
       "jni/PowerSourceClient-ReadImpl.cpp",
       "jni/PowerSourceConfigurationClient-InvokeSubscribeImpl.cpp",

diff --git a/src/controller/data_model/controller-clusters.matter b/src/controller/data_model/controller-clusters.matter
@@ -2978,6 +2978,70 @@ client cluster SmokeCoAlarm = 92 {
   command SelfTestRequest(): DefaultSuccess = 0;
 }
 
+/** This cluster supports remotely monitoring and, where supported, changing the operational state of any device where a state machine is a part of the operation. */
+client cluster OperationalState = 96 {
+  enum ErrorStateEnum : ENUM8 {
+    kNoError = 0;
+    kUnableToStartOrResume = 1;
+    kUnableToCompleteOperation = 2;
+    kCommandInvalidInState = 3;
+  }
+
+  enum OperationalStateEnum : ENUM8 {
+    kStopped = 0;
+    kRunning = 1;
+    kPaused = 2;
+    kError = 3;
+  }
+
+  struct ErrorStateStruct {
+    ErrorStateEnum errorStateID = 0;
+    nullable char_string<64> errorStateLabel = 1;
+    optional char_string<64> errorStateDetails = 2;
+  }
+
+  struct OperationalStateStruct {
+    OperationalStateEnum operationalStateID = 0;
+    char_string<64> operationalStateLabel = 1;
+  }
+
+  critical event OperationalError = 0 {
+    ErrorStateStruct errorState = 0;
+  }
+
+  info event OperationCompletion = 1 {
+    ErrorStateEnum completionErrorCode = 0;
+    optional nullable elapsed_s totalOperationalTime = 1;
+    optional nullable elapsed_s pausedTime = 2;
+  }
+
+  readonly attribute nullable CHAR_STRING phaseList[] = 0;
+  readonly attribute nullable int8u currentPhase = 1;
+  readonly attribute optional nullable elapsed_s countdownTime = 2;
+  readonly attribute OperationalStateStruct operationalStateList[] = 3;
+  readonly attribute OperationalStateStruct operationalState = 4;
+  readonly attribute ErrorStateStruct operationalError = 5;
+  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;
+
+  response struct OperationalCommandResponse = 4 {
+    ErrorStateStruct commandResponseState = 0;
+  }
+
+  /** Upon receipt, the device SHALL pause its operation if it is possible based on the current function of the server. */
+  command Pause(): OperationalCommandResponse = 0;
+  /** Upon receipt, the device SHALL stop its operation if it is at a position where it is safe to do so and/or permitted. */
+  command Stop(): OperationalCommandResponse = 1;
+  /** Upon receipt, the device SHALL start its operation if it is safe to do so and the device is in an operational state from which it can be started. */
+  command Start(): OperationalCommandResponse = 2;
+  /** Upon receipt, the device SHALL resume its operation from the point it was at when it received the Pause command, or from the point when it was paused by means outside of this cluster (for example by manual button press). */
+  command Resume(): OperationalCommandResponse = 3;
+}
+
 /** Attributes and commands for monitoring HEPA filters in a device */
 client cluster HepaFilterMonitoring = 113 {
   enum ChangeIndicationEnum : ENUM8 {