Messages Cluster XML

.github/workflows/tests.yaml

@@ -143,6 +143,7 @@ jobs:
                       src/app/zap-templates/zcl/data-model/chip/low-power-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/media-input-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/media-playback-cluster.xml \
+                      src/app/zap-templates/zcl/data-model/chip/messages-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/mode-select-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/network-commissioning-cluster.xml \

docs/clusters.md

@@ -79,6 +79,7 @@ Generally regenerate using one of:
 |        129 |       0x81 | ValveConfigurationAndControl                            |
 |        145 |       0x91 | ElectricalEnergyMeasurement                             |
 |        150 |       0x96 | DemandResponseLoadControl                               |
+|        151 |       0x97 | Messages                                                |
 |        152 |       0x98 | DeviceEnergyManagement                                  |
 |        153 |       0x99 | EnergyEvse                                              |
 |        155 |       0x9B | EnergyPreference                                        |

scripts/rules.matterlint

@@ -54,6 +54,7 @@ load "../src/app/zap-templates/zcl/data-model/chip/low-power-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/matter-devices.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/media-input-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/media-playback-cluster.xml";
+load "../src/app/zap-templates/zcl/data-model/chip/messages-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/mode-select-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/network-commissioning-cluster.xml";

src/app/clusters/messages-server/messages-server.cpp

@@ -0,0 +1,40 @@
+#include "messages-server.h"
+
+#include <app-common/zap-generated/attributes/Accessors.h>
+#include <app-common/zap-generated/cluster-objects.h>
+#include <app-common/zap-generated/ids/Attributes.h>
+#include <app-common/zap-generated/ids/Clusters.h>
+#include <app-common/zap-generated/ids/Commands.h>
+#include <app/CommandHandler.h>
+#include <app/ConcreteCommandPath.h>
+
+#include <app/util/af.h>
+#include <app/util/common.h>
+#include <app/util/error-mapping.h>
+#include <array>
+#include <lib/support/CodeUtils.h>
+#include <platform/CHIPDeviceLayer.h>
+
+using namespace chip;
+using namespace chip::app;
+using namespace chip::app::Clusters::Messages;
+using chip::Protocols::InteractionModel::Status;
+
+bool emberAfMessagesClusterPresentMessagesRequestCallback(
+    chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
+    const chip::app::Clusters::Messages::Commands::PresentMessagesRequest::DecodableType & commandData)
+{
+    return true;
+}
+/**
+ * @brief Messages Cluster CancelMessagesRequest Command callback (from client)
+ */
+
+bool emberAfMessagesClusterCancelMessagesRequestCallback(
+    chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
+    const chip::app::Clusters::Messages::Commands::CancelMessagesRequest::DecodableType & commandData)
+{
+    return true;
+}
+
+void MatterMessagesPluginServerInitCallback() {}

src/app/clusters/messages-server/messages-server.h

@@ -0,0 +1,29 @@
+/**
+ *
+ *    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.
+ */
+
+#pragma once
+
+#include <app-common/zap-generated/cluster-enums.h>
+#include <app/util/basic-types.h>
+
+namespace chip {
+namespace app {
+namespace Clusters {
+namespace Messaging {} // namespace Messaging
+} // namespace Clusters
+} // namespace app
+} // namespace chip

src/app/zap-templates/zcl/data-model/all.xml

@@ -55,6 +55,7 @@
    <xi:include href="chip/low-power-cluster.xml" />
    <xi:include href="chip/media-input-cluster.xml" />
    <xi:include href="chip/media-playback-cluster.xml" />
+   <xi:include href="chip/messages-cluster.xml" />   
    <xi:include href="chip/mode-base-cluster.xml" />
    <xi:include href="chip/mode-select-cluster.xml" />
    <xi:include href="chip/network-commissioning-cluster.xml" />

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

@@ -0,0 +1,111 @@
+<?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="General"/>
+
+  <bitmap name="Feature" type="bitmap32">
+    <cluster code="0x0097"/>
+    <field name="ReceivedConfirmation" mask="0x1"/>
+    <field name="ConfirmationResponse" mask="0x2"/>
+    <field name="ConfirmationReply" mask="0x4"/>
+    <field name="ProtectedMessages" mask="0x8"/>
+  </bitmap>
+
+  <bitmap name="MessageControlBitmap" type="bitmap8">
+    <cluster code="0x0097"/>
+    <field name="ConfirmationRequired" mask="0x1"/>
+    <field name="ResponseRequired" mask="0x2"/>
+    <field name="ReplyMessage" mask="0x4"/>
+    <field name="MessageConfirmed" mask="0x8"/>
+    <field name="MessageProtected" mask="0x10"/>
+  </bitmap>
+
+  <enum name="FutureMessagePreferenceEnum" type="enum8">
+    <cluster code="0x0097"/>
+    <item value="0x00" name="Allowed"/>
+    <item value="0x01" name="Increased" />
+    <item value="0x02" name="Reduced"/>
+    <item value="0x03" name="Disallowed"/>
+    <item value="0x04" name="Banned"/>
+  </enum>
+
+  <enum name="MessagePriorityEnum" type="enum8">
+    <cluster code="0x0097"/>
+    <item value="0x00" name="Low"/>
+    <item value="0x01" name="Medium" />
+    <item value="0x02" name="High"/>
+    <item value="0x03" name="Critical"/>
+  </enum>
+
+
+  <struct name="MessageStruct"> <!-- TODO: enable isFabricScoped="true", as of Jan 2024 it breaks at compile time as command argument PresentMessagesRequest#Messages-->
+    <cluster code="0x0097"/>
+    <item fieldId="0" name="MessageID" type="octet_string" length="16" optional="false"/>
+    <item fieldId="1" name="Priority" type="MessagePriorityEnum" optional="false"/>
+    <item fieldId="2" name="MessageControl" type="MessageControlBitmap" default="0" optional="false"/>
+    <item fieldId="3" name="StartTime" type="epoch_s" default="0" optional="false" isNullable="true"/>
+    <item fieldId="4" name="Duration" type="int16u" default="0" optional="false" isNullable="true"/>
+    <item fieldId="5" name="MessageText" type="char_string" length="256" optional="false"/>
+    <item fieldId="6" name="Responses" type="MessageResponseOptionStruct" array="true" length="4" optional="true"/>
+  </struct>
+
+  <struct name="MessageResponseOptionStruct">
+    <cluster code="0x0097"/>
+    <item fieldId="0" name="MessageResponseID" type="int32u" optional="true"/>
+    <item fieldId="1" name="Label" type="char_string" length="32" optional="true"/>
+  </struct>
+
+  <cluster>
+    <name>Messages</name>
+    <domain>General</domain>
+    <description>This cluster provides an interface for passing messages to be presented by a device.</description>
+    <code>0x0097</code>
+    <define>MESSAGES_CLUSTER</define>
+    <client tick="false" init="false">true</client>
+    <server tick="false" init="false">true</server>
+    <globalAttribute side="either" code="0xFFFD" value="3"/><!-- Revision   -->
+    <attribute side="server" code="0x0000" define="LIST_MESSAGES" type="array" entryType="MessageStruct" length="8" writable="false" optional="false">Messages</attribute>
+    <attribute side="server" code="0x0001" define="MESSAGES_CLUSTER_ACTIVE_MESSAGES_IDS" type="ARRAY" entryType="octet_string" max="8" writable="false" optional="false">ActiveMessageIDs</attribute>
+    <command source="client" code="0x00" name="PresentMessagesRequest" isFabricScoped="true" optional="false">
+      <description>
+        Command for requesting messages be presented
+      </description>
+      <arg name="Messages" type="MessageStruct" array="true" optional="false"/>
+    </command>
+    <command source="client" code="0x01" name="CancelMessagesRequest" isFabricScoped="true" optional="false">
+      <description>
+        Command for cancelling message present requests
+      </description>
+      <arg name="MessageIDs" type="octet_string" array="true" optional="false"/>
+    </command>
+    <event side="server" code="0x00" name="MessageQueued" priority="info" optional="false">
+      <description>This event SHALL be generated when the message is confirmed by the user, or when the expiration date of the message is reached.</description>
+      <field id="0" name="MessageID" type="octet_string" max="16"/>
+    </event>
+    <event side="server" code="0x01" name="MessagePresented" priority="info" optional="false">
+      <description>This event SHALL be generated when the message is presented to the user.</description>
+      <field id="0" name="MessageID" type="octet_string" max="16"/>
+    </event>
+    <event side="server" code="0x02" name="MessageComplete" priority="info" optional="false">
+      <description>This event SHALL be generated when the message is confirmed by the user, or when the expiration date of the message is reached.</description>
+      <field id="0" name="MessageID" type="octet_string" optional="false"/>
+      <field id="1" name="ResponseID" type="int32u" isNullable="true" optional="true"/>
+      <field id="2" name="Reply" type="char_string" length="256" isNullable="true" optional="true"/>
+      <field id="3" name="FutureMessagesPreference" type="FutureMessagePreferenceEnum" isNullable="true" optional="false"/>
+    </event>
+  </cluster>
+</configurator>

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

@@ -73,6 +73,7 @@
         "low-power-cluster.xml",
         "media-input-cluster.xml",
         "media-playback-cluster.xml",
+        "messages-cluster.xml",
         "mode-base-cluster.xml",
         "mode-select-cluster.xml",
         "mode-select-extensions.xml",

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

@@ -71,6 +71,7 @@
         "low-power-cluster.xml",
         "media-input-cluster.xml",
         "media-playback-cluster.xml",
+        "messages-cluster.xml",
         "mode-base-cluster.xml",
         "mode-select-cluster.xml",
         "network-commissioning-cluster.xml",

src/app/zap_cluster_list.json

@@ -64,6 +64,7 @@
         "MEDIA_INPUT_CLUSTER": [],
         "MEDIA_PLAYBACK_CLUSTER": [],
         "MICROWAVE_OVEN_CONTROL_CLUSTER": [],
+        "MESSAGES_CLUSTER": [],
         "MODE_SELECT_CLUSTER": [],
         "NETWORK_COMMISSIONING_CLUSTER": [],
         "SAMPLE_MEI_CLUSTER": [],
@@ -213,6 +214,7 @@
         "MEDIA_INPUT_CLUSTER": ["media-input-server"],
         "MEDIA_PLAYBACK_CLUSTER": ["media-playback-server"],
         "MICROWAVE_OVEN_CONTROL_CLUSTER": ["microwave-oven-control-server"],
+        "MESSAGES_CLUSTER": ["messages-server"],
         "MODE_SELECT_CLUSTER": ["mode-select-server"],
         "NETWORK_COMMISSIONING_CLUSTER": ["network-commissioning"],
         "NITROGEN_DIOXIDE_CONCENTRATION_MEASUREMENT_CLUSTER": [

src/controller/data_model/controller-clusters.matter

@@ -4372,6 +4372,93 @@ provisional cluster DemandResponseLoadControl = 150 {
   command ClearLoadControlEventsRequest(): DefaultSuccess = 4;
 }
 
+/** This cluster provides an interface for passing messages to be presented by a device. */
+cluster Messages = 151 {
+  revision 3;
+
+  enum FutureMessagePreferenceEnum : enum8 {
+    kAllowed = 0;
+    kIncreased = 1;
+    kReduced = 2;
+    kDisallowed = 3;
+    kBanned = 4;
+  }
+
+  enum MessagePriorityEnum : enum8 {
+    kLow = 0;
+    kMedium = 1;
+    kHigh = 2;
+    kCritical = 3;
+  }
+
+  bitmap Feature : bitmap32 {
+    kReceivedConfirmation = 0x1;
+    kConfirmationResponse = 0x2;
+    kConfirmationReply = 0x4;
+    kProtectedMessages = 0x8;
+  }
+
+  bitmap MessageControlBitmap : bitmap8 {
+    kConfirmationRequired = 0x1;
+    kResponseRequired = 0x2;
+    kReplyMessage = 0x4;
+    kMessageConfirmed = 0x8;
+    kMessageProtected = 0x10;
+  }
+
+  struct MessageResponseOptionStruct {
+    optional int32u messageResponseID = 0;
+    optional char_string<32> label = 1;
+  }
+
+  struct MessageStruct {
+    octet_string<16> messageID = 0;
+    MessagePriorityEnum priority = 1;
+    MessageControlBitmap messageControl = 2;
+    nullable epoch_s startTime = 3;
+    nullable int16u duration = 4;
+    char_string<256> messageText = 5;
+    optional MessageResponseOptionStruct responses[] = 6;
+  }
+
+  info event MessageQueued = 0 {
+    octet_string messageID = 0;
+  }
+
+  info event MessagePresented = 1 {
+    octet_string messageID = 0;
+  }
+
+  info event MessageComplete = 2 {
+    octet_string messageID = 0;
+    optional nullable int32u responseID = 1;
+    optional nullable char_string reply = 2;
+    nullable FutureMessagePreferenceEnum futureMessagesPreference = 3;
+  }
+
+  readonly attribute MessageStruct messages[] = 0;
+  readonly attribute octet_string activeMessageIDs[] = 1;
+  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;
+
+  request struct PresentMessagesRequestRequest {
+    MessageStruct messages[] = 0;
+  }
+
+  request struct CancelMessagesRequestRequest {
+    octet_string messageIDs[] = 0;
+  }
+
+  /** Command for requesting messages be presented */
+  fabric command PresentMessagesRequest(PresentMessagesRequestRequest): DefaultSuccess = 0;
+  /** Command for cancelling message present requests */
+  fabric command CancelMessagesRequest(CancelMessagesRequestRequest): DefaultSuccess = 1;
+}
+
 /** This cluster allows a client to manage the power draw of a device. An example of such a client could be an Energy Management System (EMS) which controls an Energy Smart Appliance (ESA). */
 provisional cluster DeviceEnergyManagement = 152 {
   revision 3;