Add support for optional commands and events

Author: AryaHassanli

scripts/py_matter_idl/matter/idl/data_model_xml/handlers/handlers.py

@@ -274,6 +274,9 @@ def GetNextProcessor(self, name: str, attrs: AttributesImpl):
             field = AttributesToField(attrs)
             self._event.fields.append(field)
             return FieldHandler(self.context, field)
+        if name == "optionalConform":
+            self._event.qualities |= EventQuality.OPTIONAL
+            return BaseHandler(self.context, handled=HandledDepth.ENTIRE_TREE)
         if name == "mandatoryConform":
             # assume handled (we do not record conformance in IDL)
             return BaseHandler(self.context, handled=HandledDepth.ENTIRE_TREE)
@@ -500,7 +503,11 @@ def EndProcessing(self):
             self._cluster.commands.append(self._command)
 
     def GetNextProcessor(self, name: str, attrs: AttributesImpl):
-        if name in {"mandatoryConform", "optionalConform", "disallowConform"}:
+        if name == "optionalConform":
+            if self._command:
+                self._command.qualities |= CommandQuality.OPTIONAL
+            return BaseHandler(self.context, handled=HandledDepth.ENTIRE_TREE)
+        if name in {"mandatoryConform", "disallowConform"}:
             # Unclear how commands may be optional or mandatory
             return BaseHandler(self.context, handled=HandledDepth.ENTIRE_TREE)
         if name == "access":

scripts/py_matter_idl/matter/idl/generators/idl/__init__.py

@@ -57,6 +57,8 @@ def human_text_string(value: Union[StructTag, StructQuality, EventPriority, Even
         result = ""
         if EventQuality.FABRIC_SENSITIVE in value:
             result += "fabric_sensitive "
+        if EventQuality.OPTIONAL in value:
+            result += "optional "
         return result.strip()
     elif type(value) is AccessPrivilege:
         if value == AccessPrivilege.VIEW:
@@ -84,6 +86,8 @@ def human_text_string(value: Union[StructTag, StructQuality, EventPriority, Even
             result += "fabric "
         if CommandQuality.TIMED_INVOKE in value:
             result += "timed "
+        if CommandQuality.OPTIONAL in value:
+            result += "optional "
         return result
     elif type(value) is ApiMaturity:
         if value == ApiMaturity.STABLE:

scripts/py_matter_idl/matter/idl/matter_grammar.lark

@@ -28,10 +28,13 @@ event_access: "access" "(" ("read" ":" access_privilege)? ")"
 
 event_with_access: "event" event_access? id
 
-event: event_qualities event_priority event_with_access "=" positive_integer "{" (struct_field ";")* "}"
+event: prefix_qualities event_priority event_with_access "=" positive_integer "{" (struct_field ";")* "}"
 
-event_quality: "fabric_sensitive" -> event_fabric_sensitive
-event_qualities: event_quality*
+prefix_quality: "fabric_sensitive" -> prefix_fabric_sensitive
+              | "fabric"i           -> prefix_fabric_scoped
+              | "timed"i            -> prefix_timed
+              | "optional"i         -> prefix_optional
+prefix_qualities: prefix_quality* -> prefix_qualities
 
 ?event_priority: "critical"i -> critical_priority
                | "info"i     -> info_priority
@@ -55,15 +58,11 @@ request_struct: "request"i struct
 // Response structures must have a response id
 response_struct: "response"i "struct"i id "=" positive_integer "{" (struct_field ";") * "}"
 
-command_quality: "timed"i -> timed_command
-                 | "fabric"i -> fabric_scoped_command
-command_qualities: command_quality*
-
 command_access: "access"i "(" ("invoke"i ":" access_privilege)? ")"
 
 command_with_access: "command"i command_access? id
 
-command: command_qualities command_with_access "(" id? ")" ":" id "=" positive_integer ";"
+command: prefix_qualities command_with_access "(" id? ")" ":" id "=" positive_integer ";"
 
 cluster_revision: "revision"i positive_integer ";"
 

scripts/py_matter_idl/matter/idl/matter_idl_parser.py

@@ -38,6 +38,8 @@ def UnionOfAllFlags(flags_list):
     return functools.reduce(lambda a, b: a | b, flags_list)
 
 
+
+
 class PrefixCppDocComment:
     def __init__(self, token):
         self.start_pos = token.start_pos
@@ -284,20 +286,20 @@ def info_priority(self, _):
     def debug_priority(self, _):
         return EventPriority.DEBUG
 
-    def event_fabric_sensitive(self, _):
-        return EventQuality.FABRIC_SENSITIVE
+    def prefix_fabric_sensitive(self, _):
+        return "fabric_sensitive"
 
-    def event_qualities(selt, qualities):
-        return UnionOfAllFlags(qualities) or EventQuality.NONE
+    def prefix_fabric_scoped(self, _):
+        return "fabric"
 
-    def timed_command(self, _):
-        return CommandQuality.TIMED_INVOKE
+    def prefix_timed(self, _):
+        return "timed"
 
-    def fabric_scoped_command(self, _):
-        return CommandQuality.FABRIC_SCOPED
+    def prefix_optional(self, _):
+        return "optional"
 
-    def command_qualities(self, attrs):
-        return UnionOfAllFlags(attrs) or CommandQuality.NONE
+    def prefix_qualities(self, qualities):
+        return set(qualities)
 
     @v_args(meta=True)
     def struct_field(self, meta, args):
@@ -336,11 +338,20 @@ def command(self, meta, *tuple_args):
         if len(args) != 5:
             args.insert(2, None)
 
+        qualities_set = args[0] or set()
+        qualities = CommandQuality.NONE
+        if "fabric" in qualities_set:
+            qualities |= CommandQuality.FABRIC_SCOPED
+        if "timed" in qualities_set:
+            qualities |= CommandQuality.TIMED_INVOKE
+        if "optional" in qualities_set:
+            qualities |= CommandQuality.OPTIONAL
+
         meta = None if self.skip_meta else ParseMetaData(meta)
 
         return Command(
             parse_meta=meta,
-            qualities=args[0],
+            qualities=qualities,
             input_param=args[2], output_param=args[3], code=args[4],
             **args[1],
         )
@@ -366,8 +377,15 @@ def cluster_revision(self, revision):
 
     @v_args(meta=True)
     def event(self, meta, args):
+        qualities_set = args[0] or set()
+        qualities = EventQuality.NONE
+        if "fabric_sensitive" in qualities_set:
+            qualities |= EventQuality.FABRIC_SENSITIVE
+        if "optional" in qualities_set:
+            qualities |= EventQuality.OPTIONAL
+
         meta = None if self.skip_meta else ParseMetaData(meta)
-        return Event(qualities=args[0], priority=args[1], code=args[3], fields=args[4:], parse_meta=meta, **args[2])
+        return Event(qualities=qualities, priority=args[1], code=args[3], fields=args[4:], parse_meta=meta, **args[2])
 
     def view_privilege(self, args):
         return AccessPrivilege.VIEW

scripts/py_matter_idl/matter/idl/matter_idl_types.py

@@ -62,6 +62,7 @@ class CommandQuality(enum.Flag):
     NONE = 0
     TIMED_INVOKE = enum.auto()
     FABRIC_SCOPED = enum.auto()
+    OPTIONAL = enum.auto()
 
 
 class AttributeQuality(enum.Flag):
@@ -87,6 +88,7 @@ class EventPriority(enum.Enum):
 class EventQuality(enum.Flag):
     NONE = 0
     FABRIC_SENSITIVE = enum.auto()
+    OPTIONAL = enum.auto()
 
 
 class StructTag(enum.Enum):
@@ -171,6 +173,14 @@ def is_subscribable(self) -> bool:
     def requires_timed_write(self) -> bool:
         return AttributeQuality.TIMED_WRITE in self.qualities
 
+    @property
+    def is_optional(self) -> bool:
+        return self.definition.is_optional
+
+    @property
+    def is_nullable(self) -> bool:
+        return self.definition.is_nullable
+
 
 @dataclass
 class Struct:
@@ -206,6 +216,10 @@ class Event:
     def is_fabric_sensitive(self) -> bool:
         return EventQuality.FABRIC_SENSITIVE in self.qualities
 
+    @property
+    def is_optional(self) -> bool:
+        return EventQuality.OPTIONAL in self.qualities
+
 
 @dataclass
 class ConstantEntry:
@@ -266,6 +280,10 @@ class Command:
     def is_timed_invoke(self) -> bool:
         return CommandQuality.TIMED_INVOKE in self.qualities
 
+    @property
+    def is_optional(self) -> bool:
+        return CommandQuality.OPTIONAL in self.qualities
+
 
 @dataclass
 class Cluster:

scripts/py_matter_idl/matter/idl/test_matter_idl_parser.py

@@ -1181,6 +1181,60 @@ def test_handle_commands(self):
 
         self.assertIdlEqual(actual, expected)
 
+    def test_optional_nullable_support(self):
+        actual = parseText("""
+            server cluster MyCluster = 0x123 {
+                attribute optional int8u optAttr = 1;
+                attribute nullable int8u nullAttr = 2;
+                attribute optional nullable int8u optNullAttr = 3;
+
+                optional info event OptionalEvent = 1 {}
+                optional critical event OptionalCriticalEvent = 2 {}
+
+                optional command OptionalCommand(): DefaultSuccess = 10;
+                optional timed command OptionalTimedCommand(): DefaultSuccess = 11;
+            }
+        """)
+
+        expected = Idl(clusters=[
+            Cluster(name="MyCluster",
+                    code=0x123,
+                    attributes=[
+                        Attribute(qualities=AttributeQuality.READABLE | AttributeQuality.WRITABLE, definition=Field(
+                            data_type=DataType(name="int8u"), code=1, name="optAttr", qualities=FieldQuality.OPTIONAL)),
+                        Attribute(qualities=AttributeQuality.READABLE | AttributeQuality.WRITABLE, definition=Field(
+                            data_type=DataType(name="int8u"), code=2, name="nullAttr", qualities=FieldQuality.NULLABLE)),
+                        Attribute(qualities=AttributeQuality.READABLE | AttributeQuality.WRITABLE, definition=Field(
+                            data_type=DataType(name="int8u"), code=3, name="optNullAttr", qualities=FieldQuality.OPTIONAL | FieldQuality.NULLABLE)),
+                    ],
+                    events=[
+                        Event(priority=EventPriority.INFO, name="OptionalEvent", code=1, fields=[], qualities=EventQuality.OPTIONAL),
+                        Event(priority=EventPriority.CRITICAL, name="OptionalCriticalEvent", code=2, fields=[], qualities=EventQuality.OPTIONAL),
+                    ],
+                    commands=[
+                        Command(name="OptionalCommand", code=10, input_param=None, output_param="DefaultSuccess", qualities=CommandQuality.OPTIONAL),
+                        Command(name="OptionalTimedCommand", code=11, input_param=None, output_param="DefaultSuccess", qualities=CommandQuality.TIMED_INVOKE | CommandQuality.OPTIONAL),
+                    ]
+                    )])
+
+        self.assertIdlEqual(actual, expected)
+
+        # Also verify properties
+        self.assertTrue(actual.clusters[0].attributes[0].is_optional)
+        self.assertFalse(actual.clusters[0].attributes[0].is_nullable)
+
+        self.assertFalse(actual.clusters[0].attributes[1].is_optional)
+        self.assertTrue(actual.clusters[0].attributes[1].is_nullable)
+
+        self.assertTrue(actual.clusters[0].attributes[2].is_optional)
+        self.assertTrue(actual.clusters[0].attributes[2].is_nullable)
+
+        self.assertTrue(actual.clusters[0].events[0].is_optional)
+        self.assertTrue(actual.clusters[0].events[1].is_optional)
+
+        self.assertTrue(actual.clusters[0].commands[0].is_optional)
+        self.assertTrue(actual.clusters[0].commands[1].is_optional)
+
 
 if __name__ == '__main__':
     unittest.main()

scripts/py_matter_idl/matter/idl/test_zapxml.py

@@ -25,7 +25,7 @@
     sys.path.append(str(Path(__file__).resolve().parent / ".." / ".."))
     from matter.idl.zapxml import ParseSource, ParseXmls
 
-from matter.idl.matter_idl_types import (AccessPrivilege, Attribute, AttributeQuality, Bitmap, Cluster, Command, ConstantEntry,
+from matter.idl.matter_idl_types import (AccessPrivilege, Attribute, AttributeQuality, Bitmap, Cluster, Command, CommandQuality, ConstantEntry,
                                          DataType, Enum, Event, EventPriority, EventQuality, Field, FieldQuality, Idl, Struct,
                                          StructQuality, StructTag)
 
@@ -153,7 +153,8 @@ def testCluster(self):
                                      Command(name='GetSomeData', code=33,
                                              input_param='GetSomeDataRequest', output_param='GetSomeDataResponse',
                                              description='This is just a test: client to server',
-                                             invokeacl=AccessPrivilege.ADMINISTER)
+                                             invokeacl=AccessPrivilege.ADMINISTER,
+                                             qualities=CommandQuality.OPTIONAL)
                                  ])
                          ]))
 

scripts/py_matter_idl/matter/idl/zapxml/handlers/handlers.py

@@ -88,6 +88,9 @@ def __init__(self, context: Context, cluster: Cluster, attrs):
         if attrs.get('isFabricSensitive', "false").lower() == 'true':
             self._event.qualities |= EventQuality.FABRIC_SENSITIVE
 
+        if attrs.get('optional', "false").lower() == 'true':
+            self._event.qualities |= EventQuality.OPTIONAL
+
     def GetNextProcessor(self, name: str, attrs):
         if name.lower() == 'field':
             data_type = DataType(name=attrs['type'])
@@ -428,6 +431,9 @@ def __init__(self, context: Context, cluster: Cluster, attrs):
             if attrs.get('mustUseTimedInvoke', 'false') == 'true':
                 self._command.qualities |= CommandQuality.TIMED_INVOKE
 
+            if attrs.get('optional', 'false').lower() == 'true':
+                self._command.qualities |= CommandQuality.OPTIONAL
+
         else:
             self._struct.tag = StructTag.RESPONSE
             self._struct.code = ParseInt(attrs['code'])