第1篇：了解Matter物模型翻译器

1. Matter物模型简介

Matter物模型的介绍可以参考: Matter Core Specification的第7章

Matter物模型直观展示，可以看下图1-1， Matter Dimmable Light的实例。
在Matter协议中，所有的设备都看做一个节点（node）。这个节点可以包含多个端点（Endpoint）。图1-1 左侧Endpoint 0 是记录节点的基本信息，比如设备名，厂商名，固件版本号，硬件版本等等。 Endpoint 1 是记录设备可使用的功能集的端点，并且有设备类型Matter Dimmable Light。

每个Endpoint里带有很多功能集。比如这里的Light有开关功能。在Matter中功能集被定义为一个个的Cluster, 比如OnOff Cluster是表示开关功能集。
Cluster有分Server和Client 角色。在这里，只需要把提供服务的一方定义为Server, 比如Matter Dimmable Light。使用服务的一方定义为Client，比如手机App，需要控制Light。
一个OnOff Cluster里面有有很多属性，如图1-2所示。比如OnOff属性。参考: Matter Application Specification 第1.5章节的介绍

每个Cluster可带有相关命令(Command), Client和Server之间的交互可以通过命令来完成。如图1-3所示，手机App可以通过On 命令打开Light, 或者通过Off命令关闭Light。
以此类推，可以通过Matter工程提供的zap工具配置其他的功能集，配置好后保存名为*.zap格式的物模型配置文件。

2. 物模型翻译成编程语言

物模型配置好后，还需要翻译成编程语言才能编程固件，大致过程如下：

*.zap格式的物模型配置文件是一个json格式的 文件, 截取其中的片段。

 {
          "name": "On/Off",
          "code": 6,
          "mfgCode": null,
          "define": "ON_OFF_CLUSTER",
          "side": "server",
          "enabled": 1,
          "attributes": [
            {
              "name": "OnOff",
              "code": 0,
              "mfgCode": null,
              "side": "server",
              "type": "boolean",
              "included": 1,
              "storageOption": "NVM",
              "singleton": 0,
              "bounded": 0,
              "defaultValue": "0x00",
              "reportable": 1,
              "minInterval": 0,
              "maxInterval": 65344,
              "reportableChange": 0
            }
          ]
        }

这个配置文件最终需要翻译成电脑可以读懂编程语言，比如C++/Java/Object C/Python等。
在翻译成代码之前，需要转译为一种*.matter后缀的中间格式。截取其中的片段

/** Attributes and commands for switching devices between 'On' and 'Off' states. */
server cluster OnOff = 6 {

  enum OnOffStartUpOnOff : ENUM8 {
    kOff = 0;
    kOn = 1;
    kTogglePreviousOnOff = 2;
  }

  bitmap Feature : BITMAP32 {
    kLighting = 0x1;
    kDeadFront = 0x2;
  }

  bitmap OnOffControl : BITMAP8 {
    kAcceptOnlyWhenOn = 0x1;
  }
  readonly attribute boolean onOff = 0;
  readonly attribute boolean globalSceneControl = 16384;
  readonly attribute attrib_id attributeList[] = 65531;
  readonly attribute bitmap32 featureMap = 65532;
  readonly attribute int16u clusterRevision = 65533;

  command Off(): DefaultSuccess = 0;
  command On(): DefaultSuccess = 1;
  command Toggle(): DefaultSuccess = 2;
  command OffWithEffect(OffWithEffectRequest): DefaultSuccess = 64;
  command OnWithRecallGlobalScene(): DefaultSuccess = 65;
  command OnWithTimedOff(OnWithTimedOffRequest): DefaultSuccess = 66;
}

这个表示方法大家可能很熟悉，像C++语言的类，也就是通过这种相当接近编程语言的中间格式，进一步再转换为各种编程语言。
为了有更直观的印象，先展示最终的转换结果，看通过*.matter文件最终需要生成怎样的编程语言文件。
比如生成C++语言 的五个文件如下表1-1，其他语言原理亦然。

文件列表
CHIPClusters.h
MClusterCommandHandler.cpp
access.h
endpoint_config.h
gen_config.h

截取 endpoint_config.h文件的片段，这个文件定义名为GENERATED_ATTRIBUTES 的宏， 这个宏记录节点（node）中所有Cluster的所有的属性。这个宏是C++数组里的元素，这样C++代码通过解析这个宏就可以知道设备物模型有什么属性了。

#define GENERATED_ATTRIBUTES                                                                                                       \
    {                                                                                                                              \
                                                                                                                                   \
        /* Endpoint: 0, Cluster: Groups (server) */                                                                                \
        { ZAP_EMPTY_DEFAULT(), 0x00000000, 1, ZAP_TYPE(BITMAP8), 0 },        /* NameSupport */                                     \
            { ZAP_SIMPLE_DEFAULT(0), 0x0000FFFC, 4, ZAP_TYPE(BITMAP32), 0 }, /* FeatureMap */                                      \
            { ZAP_SIMPLE_DEFAULT(4), 0x0000FFFD, 2, ZAP_TYPE(INT16U), 0 },   /* ClusterRevision */                                 \
                                                                                                                                   \
            /* Endpoint: 0, Cluster: Descriptor (server) */                                                                        \
            { ZAP_EMPTY_DEFAULT(), 0x00000000, 0, ZAP_TYPE(ARRAY), ZAP_ATTRIBUTE_MASK(EXTERNAL_STORAGE) },  /* DeviceTypeList */   \
            { ZAP_EMPTY_DEFAULT(), 0x00000001, 0, ZAP_TYPE(ARRAY), ZAP_ATTRIBUTE_MASK(EXTERNAL_STORAGE) },  /* ServerList */       \
            { ZAP_EMPTY_DEFAULT(), 0x00000002, 0, ZAP_TYPE(ARRAY), ZAP_ATTRIBUTE_MASK(EXTERNAL_STORAGE) },  /* ClientList */       \
            { ZAP_EMPTY_DEFAULT(), 0x00000003, 0, ZAP_TYPE(ARRAY), ZAP_ATTRIBUTE_MASK(EXTERNAL_STORAGE) },  /* PartsList */        \
            { ZAP_SIMPLE_DEFAULT(0), 0x0000FFFC, 4, ZAP_TYPE(BITMAP32), 0 },                                /* FeatureMap */       \
            { ZAP_EMPTY_DEFAULT(), 0x0000FFFD, 2, ZAP_TYPE(INT16U), ZAP_ATTRIBUTE_MASK(EXTERNAL_STORAGE) }, /* ClusterRevision */  \

3. 思考题

本节先留几个思考题供读者思考，下一篇文章继续为你揭秘《第2篇：Matter物模型翻译器原理》。

1. 物模型*.zap格式文件转换为*.matter格式文件好处在哪？
2. 物模型*.zap格式文件如何转换为*.matter格式的文件？
3. *matter格式的中间文件是怎么转换成电脑编译器可以识别的代码的？