Chapter 7. Data Model Specification
|1-15||Released as revisions of the Dotdot Architecture Model specification|
|16||Initial Release of this specification|
This is part of a package of Data Model specifications that are agnostic to underlying layers (encod ing, message, network, transport, etc.). Each specification below may be independently maintained. This package, as a whole, shall be independently maintained as agnostic and decoupled from lower layers. This package may be referenced by inclusion in vertical protocol stack specifications.
Data Model Defines first order elements and namespace for endpoints, clusters, attributes, data types, etc.
Interaction Model Defines interactions, transactions and actions between nodes.
System Model Defines relationships that are managed between endpoints and clusters.
Cluster Library Reference library of cluster specifications.
Device Library Reference library of device type specifications.
The origin of this section is the Dotdot Architecture Model [Dotdot Architecture] and parts of Chap ter 2 of the Zigbee Cluster Library specification [ZCL] that define the data model.
The purpose of this document is to extend and better define the data model architecture, while not breaking the certifiable cluster specifications in the Zigbee Cluster Library (currently at revision 8). Under the Matter project, new and existing clusters and device types may take advantage of extended architecture elements. Ultimately, the plan is that this architecture is available and main tained for all underlying certifiable protocol stacks.
This document defines first order elements and namespace of the data model and can also be called the meta-model (of the data model). This document is the “read me first” specification in the data model. This data model is ultimately implemented in the application layer of a communication stack.
This specification does not define how data is stored, encoded or what interactions are allowed on the data.
|MS||Manufacturer or Vendor Specific|
|desc||see detailed description section|
The following conventions are used in Data Model specifications.
220.127.116.11. Enumerations and Reserved Values
An undefined value or range of an enumeration, field, or identifier SHALL be considered reserved for future revisions of this standard and SHALL NOT be available for implementation. It is RECOM MENDED that a value stay undefined, rather than defining it as “reserved”.
A value or range of an enumeration, field, or identifier that is available for non-standard imple mentation SHALL be defined as manufacturer specific.
A value or range of an enumeration, field, or identifier that is available for other parts of this stan dard SHALL be defined as such.
A value or range of an enumeration, field, or identifier that is deprecated, and not available for implementation, SHALL be defined as deprecated.
- An undefined bit or bit field SHALL be considered reserved for future revisions of this standard and SHALL not be available for
- It is RECOMMENDED that a bit stay undefined, rather than defining it as “reserved”.
- An implementation of a revision where a bit is reserved SHALL indicate that bit as zero when conveying that bit in an interaction, and ignore that bit when conveyed from another imple mentation.
18.104.22.168. Number Format
In this specification, hexadecimal numbers are prefixed with the designation “0x” and binary num bers are prefixed with the designation “0b”. All other numbers are assumed to be decimal unless indicated otherwise within the associated text.
Binary numbers are specified as successive groups of 4 bits, separated by a space (“ “) character from the most significant bit (next to the 0b prefix and leftmost on the page) to the least significant bit (rightmost on the page), e.g. the binary number 0b0000 1111 represents the decimal number 15.
Where individual bits are indicated (e.g. bit 3) the bit numbers are relative to the least significant bit which is bit 0.
When a digit is specified as having any value in the range of that digit, it is specified with an “x” (this should not be confused with the “x” in the prefix “0x” for hexadecimal notation).
• “0b0000 0xxx” indicates that the lower 3 bits can take any value but the upper 5 bits must each be set to 0.
• “0x0000 0xxx” indicates that the lower 3 nibbles can take any value but the upper 5 nib bles must each be set to 0.
Cluster specifications and device type definitions have tables that define the qualities of elements that make up the cluster or device type. Not all elements have all qualities. For example, a com mand does not have the read quality. Some elements have intrinsic qualities, that are not listed. For example, an event always has the read quality. Qualities SHALL be defined in columns in tables that describe data model elements.
The following columns are common across tables describing attributes, commands, events and structs:
Defines an identifier for the data model element that is unique at its context.
Defines a CamelCase name of the element to be used in specification text, not the protocol. Text usage SHALL always be followed with the element name (e.g. CurrentLevel attribute, Stopped event, or Left field).
Same as Name. Other headers like “Field”, “Bit Field”, and “Command Field”, are deprecated. Use
Defines dependencies on whether an element is optional or mandatory.
Defines how an element is accessed (e.g. read or write) and what privileges are required to access the data.
A short summary of the element with no normative text.
A separate section, describing a table row element, is required to include normative text, such as behavior associated with the element.
Other columns specific to the element:
A data field requires this column for attribute, event or command data.
This is a catchall column for uncategorized qualities.
This defines a default value for data fields.
Cluster command tables have this column.
Cluster command tables have this column.
Event tables have this column.
Enumerations use this column instead of the ID column.
A Conformance column defines optionality and dependency for any data model element or set of elements. This column is valid for attributes, commands, events, enumerations, and fields of com mands, events or structures.
|M||Mandatory||This is part of the base manda tory feature set and is manda tory for current revision.|
|O||Optional||This is a purely optional ele ment with no dependencies, except the M set.|
|P||Provisional||See Provisional below.|
|D||Deprecated||This is a deprecated item that MAY occur in legacy implemen tations, but not in the current revision.|
|X||Disallowed||This is disallowed for the clus ter derivation.|
|AB||Mandatory||This SHALL be supported if AB is true. AB is a boolean expres sion|
|[AB]||Optional||This MAY be supported only if AB is true. Brackets also act as parentheses.|
|EF||Operand||True if EF feature or element is supported.|
|EF==v||Equal||True if EF is equal to the fixed and non-changing value v.|
|EF!=v||UnEqual||True if EF does not equal the non-changing value v.|
|AB | CD||Or||True if either AB or CD is true.|
|AB ^ CD||Xor||True if only one of AB or CD is true, not both.|
|AB & CD||And||True if both AB and CD are true.|
|!AB||Exclusivity||True if AB is false.|
|(AB & CD)||Parentheses||Parentheses can be put around any conformance expression to combine.|
|C1, C2…||List||A conformance that is a list of boolean expressions.|
|C.an||Choice||Exclusive choices between a number of elements with the same conformance|
Optionality with “” SHALL be defined for an entire expression and not for parts of an expression. Individual conformance list entries MAY define optionality with “”, but not the entire list.
For example: The expression “[AA] & BB” is illegal, however, “[AA & BB]” or “AA & BB” is legal. For example: The expression “AA | [BB]” is illegal, however, “[AA | BB]” or “AA, [BB]” is legal.
The tag “O” SHALL define the element as optional for the revision. “O” SHALL only be used by itself, without operators, to mean optional without dependencies, or SHALL be used in a conformance list ending in “, O”, to mean otherwise optional.
The tag “P” defines the element as provisional. “P” may be used in a list, where the intended confor mance or list follows the “P”. If the intended conformance has not been determined, then nothing appears after the “P”.
It is recommended that the intended future conformance be noted, so that when the provisional marking is removed, the intended conformance becomes the current conformance.
For example: “P, M” means provisional, but mandatory, when not provisional in the future.
For example: “P, [AA & BB]” means provisional for now, but optional if AA & BB are true, when not provisional in the future.
For example: “[AA], P” means optional for AA and provisional otherwise, where the future confor mance is unknown at this time.
Each provisional element shall be listed in a higher level specification, that includes the data model, and data model derived specifications that use this notation.
The tag “M” SHALL define the element as mandatory. “M” SHALL only be used by itself, without operators, to mean mandatory without dependencies, or SHALL be used in a conformance list end ing in “, M”, to mean otherwise mandatory.
The tag “X” is used when a derived cluster removes support for some elements. The tag “X” SHALL define the element as disallowed for the revision of the derivation. “X” SHALL only be used by itself, without operators.
The tag “D” SHALL define the element as disallowed for the revision. Previous revisions MAY sup port this element and conformance is defined in such previous revisions. “D” SHALL only be used by itself, without operators.
Exclusivity occurs when the entire expression only excludes.
It is recommended to not use exclusive conformance. Positive conformance is recommended.
For example: Excluding an element with “!Matter” means that it is mandatory otherwise. Better to use positive conformance with (e.g. “Zigbee”). For example: Excluding an element with “[!Matter]”
means that it is optional otherwise. Better to use positive conformance with (e.g. “[Zigbee]”).
A conformance list is evaluated from top to bottom, and left to right, where an expression is mutu ally exclusive to the previous expressions (above and to the left). It is a shorthand that allows defin ing conformance which depends on the previously evaluated true expression.
- “AB, O” means mandatory for AB and optional
- “AB, [CD]” means mandatory for AB, optional if CD is true and AB is false, otherwise not
- “!AB, O” means mandatory if AB is false, otherwise optional (if AB is true).
- “[AB], M” is the equivalent to “!AB, O”, and a clearer way to define the
- “[AA], [BB], [CC]” is the equivalent to “[AA | BB | CC]”.
If a row in a table is repeated for an element with qualities that change based on tags, then evalua tion top to bottom is also supported. For the example below, the MinLevel element is mandatory for LT with the minimum of 1 (not zero), mandatory for AB with the minimum of 0 (zero), otherwise the element is optional with a minimum of 0 (zero).
1 to 100
0 to 100
|LT AB, O|
Above is logically the same and a shorthand for using the choice conformance notation below.
|43||MinLevel||uint8||1 to 100||1||LT.a|
|43||MinLevel||uint8||0 to 100||0||(AB, O).a|
A conformance expression supports conformance tags as operands. A conformance tag for a cluster MAY be the name of a cluster feature (see FeatureMap Attribute). A conformance tag for a cluster MAY be the name of an element in the Name column of the same table. A conformance tag for a device type definition MAY also include a condition of the node.
Expressions SHALL represent a dependency with boolean logic using:
- the NOT operator such as “!AA”
- the OR operator such as “AA | BB”
- the AND operator such as “AA & BB”
- the XOR (exclusive or) operator such as “AA ^ BB”
- the equal operator such as “AA==10”
- the not equal operator such as “AA!=10”
Equality operators require that a value can be resolved for the left operand. If the left operand is not supported, the default is the value. “null” is a valid value for the equality operator.
Simple dependencies MAY also be defined in conformance. If a Max attribute has a dependency on a Min attribute, then the conformance for Max is “Min”. Exclusive logic also applies. For example, if the Absolute attribute is mutually exclusive to the Percentage attribute, and one of the two must be supported, then conformance for Absolute would be “!Percentage”, and conformance for Percent age would be “!Absolute”.
Unless overridden with parentheses, the order of operations is:
- NOT operator “!”
- AND operator “&”, OR operator “|”, XOR operator “^”
- equal “==”, not equal “!=”
If an expression is false, there SHALL be no assumption of general optionality. If the conformance expression evaluates to false but optional, the expression is false.
Some examples of conformance definitions:
- “[AB]” means the element is not allowed, if AB evaluates to
- “[AA & BB]” means optional if AA and BB are both true, but excluded (and not optional) other wise.
- “[!AA & BB]” means only optional if AA is false and BB is
Choice conformance defines requirements for implementing one or some elements at the same level. This set of elements is called the choice set.
C is any logical optional AB expression or optional conformance list, including “O” (optional), but not “M”, “X”, “D”, or “P”. If C is a conformance list, then the list SHALL be surrounded by parenthe ses. A conformance list may also include optional choice expressions among others in the list that do not support a choice.
The choice parameters are a, n, and “+”:
a is a lower case letter identifying 2 or more elements in the choice set, that SHALL be at the same scope (in the same table).
n determines the number in the choice set that SHALL be supported after evaluation of the confor mance C. n is a number between one (1) and the number of elements tagged with an a, minus one. n may be suffixed with a plus sign (“+”), which means the number or more SHALL be supported, oth erwise n is exactly the number that SHALL be supported. If n is omitted, then n is considered to be one.
When this conformance notation is used, each element identifying the set or choices with a, SHALL
have a duplicate n value and duplicate the “+” if used.
Invalid example: It is illegal to use “O.a” for one element and “O.a2” for another. Valid examples:
- “O.a” means exactly one of the “a” elements SHALL be
- “O.a2” means exactly two of the “a” elements SHALL be
- “O.a2+” means at least two of the “a” elements SHALL be
- “O.a+” means at least one of the “a” elements SHALL be
The n value SHALL always be supported.
For choice conformance the element conformance is always optional, such as “O.a+” or “[AB].a+”, where AB is true.
Choice conformance requires the implementation to satisfy the choice parameters (allowed num ber of choices), despite the optional conformance expression.
It is invalid to use mandatory conformance for choice such as “M.a+”, “AB.a+” or “!AB.a+”. This gives the reader the false impression that the element is mandatory.
For example: The following is valid, because the n value of 1 or more is always supported.
If AB is true and CD is false then AbsoluteValue must be supported and optionally PercentValue. If AB is false and CD is true then PercentValue must be supported and optionally AbsoluteValue. If AB is true and CD is true then both must be supported. If AB is false and CD is false then either one or both must be supported.
|43||AbsoluteValue||uint16||0 to 5000||0||AB, O.a1+|
|44||PercentValue||uint8||0 to 100||0||CD, O.a1+|
Different expressions for C are allowed, which may limit the choices, based on conformance, to greater than zero, but less than n. In such cases, consideration is needed to define the choices and conformance so that the n value is satisfied in every valid combination.
For example: The following is invalid if conformance allows AB to be false and CD to be true, because the n value of 2 is not satisfied.
|43||AbsoluteCm||uint16||0 to 5000||0||[AB & CM].a2|
|44||AbsoluteIn||uint16||0 to 2000||0||[AB & IN].a2|
|45||Percent||uint8||0 to 100||0||[CD].a2|
If an element does not have a designated conformance (the column is blank or omitted), then it SHALL inherit conformance from the next highest element in the model hierarchy. For example: A data field in a struct attribute inherits its conformance from the attribute.
The above examples use (all capitalized) cluster feature codes in conformance expressions.
If a feature table has no conformance column then each feature is considered to be optional for that revision and therefore either true (feature supported) or false (feature unsupported).
If a feature table has a Conformance column then these are the allowed conformance:
|M||true||This means the feature is now mandatory, and the confor mance expression is true, and the feature supported (true).|
|O||implementation||This is the default conformance (if blank), which means the fea ture support is indicated by the implementation (true or false).|
|D||false||The conformance expression is false, and the feature is unsup ported (false). A legacy imple mentation may still support the feature with a true value.|
|X||false||This is used in a device type that overrides cluster specifica tion conformance, which means the conformance expression is false, and the feature is unsup ported (false).|
|P||false||This means the conformance expression is false, and the fea ture is provisional and unsup ported.|
|false mandatory expression||false||Conformance expressions are used to define more complex feature dependencies. A list of expressions evaluates to a sin gle expression. Choice options only support optional expres sions.|
|false optional expression||false|
|true mandatory expression||true|
|true optional expression||implementation|
- If the feature indicator (bit) is unsupported, then the feature indicator SHALL be false and the feature SHALL be unsupported (false).
- Otherwise, if the conformance expression evaluates to false, then the feature indicator SHALL be false and the feature SHALL be unsupported (false).
- Otherwise, if the conformance expression evaluates to mandatory, then the feature indicator and feature support SHALL be the value of the conformance
- the feature support (true or false) SHALL be the value or the feature indicator (bit) as imple mented.
- If the conformance expression evaluates to a choice conformance, then the indicators for the choice set SHALL also conform to the choice
An element of the data model is a data construct that supports an instance of data. Listed below are the elements of the data model.
First order elements
fabric, node, endpoint, cluster
Cluster first order elements
command, event, attribute
command field, event field, struct field
device type, data type
elements (above) that are part of an attribute
attribute, field element, or list entry (see Data Field)
When parsing or processing encoded payloads of elements as represented by an encoding layer, such as TLV format, the following general rules apply:
- Unknown elements SHALL be ignored and skipped. This provides forward compatibility with future
- Elements SHALL be present when conveyed according to the element’s
- Elements that are present and conformant SHALL be
A fabric is set of nodes that interact by accessing data model elements as defined in the Interaction Model. A fabric is a security domain that allows a set of nodes to be identified and communicate within the context of the domain. A node is considered to be ‘on’ a fabric, when it can be identified and interact in the context of that fabric. An interaction is considered to occur ‘on’ a fabric, when the interaction occurs in the context of that fabric (see Accessing Fabric). Each interaction occurs either on a single fabric, or without a fabric context (see Accessing Fabric).
A node MAY be identified and interact on one or more fabrics.
How a fabric is established and how a node comes to be on a fabric is not defined here and left to the lower layers.
If an interaction is associated with a particular fabric, that fabric is called the “accessing fabric”.
If the interaction is not associated with a fabric, the accessing fabric does not exist. In this case any comparison of the accessing fabric to any existing fabric SHALL consider them not equal.
Each fabric supported on a node is referenced by fabric-index that is unique on the node. This fab ric-index enables the look-up of the full fabric information from the fabric-index. A fabric-index of 0 (zero) or null SHALL indicate that there is no fabric associated with the context in which the fab ric-index is being used. If fabric-index is used in a context that is exclusively associated with a fab ric, such as fabric-scoped data model elements, then the fabric-index values SHALL NOT include 0 (zero) or null.
The fabric-index corresponding to the accessing fabric is called the “accessing fabric-index”. If the accessing fabric does not exist, the accessing fabric-index SHALL indicate no fabric with a fabric- index of 0.
Most cluster data instances are accessible regardless of the accessing fabric. However, data that is exclusively associated with a particular fabric SHALL be defined as being fabric-scoped. Fabric- scoped data SHALL be defined with the fabric-scoped quality.
The fabric associated with fabric-scoped data is called the “associated fabric”.
Fabric-scoped data allows multiple accessing fabrics to manipulate a list of data items without interfering with each other. See Fabric Filtered List.
Fabric-scoped data SHALL be limited to the following:
- list of fabric-scoped structs
- fabric-sensitive event
A fabric-scoped data instance is always a composite struct-like data instance, with multiple fields.
Fabric-scoped data SHALL always include the FabricIndex field to indicate the associated fabric. The FabricIndex field for fabric-scoped data SHALL NOT be 0 or null.
Any interaction, including cluster commands, SHALL NOT cause modification of fabric-scoped data, directly or indirectly, if the interaction has an accessing fabric different than the associated fabric for the data, except in the case of a cluster command that explicitly defines an exception to this rule.
Data that is fabric-scoped may also be fabric-sensitive, all or in part.
Some data types are fabric-scoped IDs, including, but not limited to, node ID and group ID.
A fabric-scoped ID MAY require the presence of a fabric-index data type field within the same nest ing scope to indicate the fabric associated with the ID in these cases:
- If the fabric-scoped ID is not part of fabric-scoped
- If the fabric-scoped ID is part of fabric-scoped data with an associated fabric that is not the fab ric associated with the
Fabric-scoped IDs SHALL only be indicated in these elements:
Where necessary, specification text SHOULD define the data to which the fabric-index applies.
Data model elements have access qualities. Some elements have intrinsic access or access limita tions. For example: Cluster commands or command fields are not writable.
An Access column defines access to a data model element or set of elements. This column is valid for attributes, commands, events, and nested attribute data fields.
|R[W]||Read Access and optionally Write Access|
|R*W||Deprecated: use R[W]|
|Fabric – separate with space from RW|
|Privileges – separate with space from RW FS|
|V||Read Access or Invoke Access requires View privilege|
|O||Read Access, Write Access, or Invoke Access requires Operate privilege|
|M||Read Access, Write Access, or Invoke Access requires Manage privilege|
|A||Read Access, Write Access, or Invoke Access requires Administer privilege|
|Timed – separate with space from RW FS VOMA|
|T||Write Access or Invoke Access with timed inter action only|
Attributes, commands, and events SHALL define their access, and SHALL include privileges in their access definition. For example: An attribute defines whether it is readable or writable, and what privileges are required to do so.
Attributes, commands, and events that do not define any privileges as access qualities SHALL be deemed to have the following:
- View privilege required for Read access,
- Operate privilege required for Write access,
- Operate privilege required for Invoke access for request
- No privileges defined for response
For example: An event with implicit read access or explicit ‘R’ access defaults to access ‘R V’. An attribute with access ‘RW’ defaults to access ‘RW VO’. A request command with implicit invoke access defaults to privilege ‘O’.
Nested elements MAY define their access, but SHALL NOT include privileges in their access defini tion. Nested elements SHALL inherit their privileges from the next highest element in the model hierarchy. Nested elements that do not define their access SHALL inherit their access from the next highest element in the model hierarchy. For example: A data field in a struct attribute inherits its access qualities from attribute.
Elements SHALL only include the lowest required privilege for a type of access. That means:
- An event SHALL define the single privilege required for Read
- A command SHALL define the single privilege required for Invoke
- A readable attribute SHALL define the single privilege required for Read
- A writable (but not readable) attribute SHALL define the single privilege (that is not View or ProxyView) required for Write
- A readable and writable attribute MAY define a single privilege (that is not View or ProxyView) required for both Read and Write
- A readable and writable attribute MAY define the View or ProxyView privilege as required for Read access and one other privilege (that is not View or ProxyView) as required for Write access.
Read access means that a request for data values associated with an element SHALL be supported. This quality SHALL only be defined for cluster event and attribute data definitions. This quality SHALL NOT be defined for cluster command definitions.
This quality is implicitly defined for cluster events and does not need to be stipulated explicitly.
Write access means that a request to modify attribute data values SHALL be supported. This quality SHALL only be defined for cluster attribute data definitions. This quality SHALL NOT be defined for cluster event and command definitions.
A cluster specification SHALL define the conditions when write access attribute data is not writable, and SHALL define normative or recommended behavior to follow when this occurs.
An implementation that does not support write access for a field with optional write access SHALL have this declared in its product Declaration of Conformity.
Invoke access means that a request to execute a command SHALL be supported. This quality SHALL only be defined for cluster command definitions, by defining an appropriate privilege level for the command. This quality SHALL NOT be defined for cluster event and attribute data definitions.
This defines fabric-scoped data that is scoped to an associated fabric.
This quality acts as an additional constraint over those imposed by the existing Read and Write qualities, namely:
- Fabric-scoped attribute data SHALL NOT be writable unless the accessing fabric is the associ ated fabric of the
- A cluster command SHALL NOT alter fabric-scoped data if the associated fabric is not the accessing fabric.
This further restricts access to data that is sensitive to the associated fabric.
This quality acts as an additional constraint over those imposed by the fabric-scoped quality, namely:
- Fabric-sensitive data SHALL NOT be readable unless the accessing fabric is the associated fabric of the data. See fabric-scoped data.
Data that is fabric-sensitive SHALL always be fabric-scoped.
An element with the View privilege SHALL support Read (if readable) and Invoke (if invocable) access if the source of the request is granted the View privilege.
A command with the View privilege defined SHALL NOT alter data that is part of its function (e.g. settings, configuration), but MAY alter data that is internal or diagnostic in nature (e.g. usage statis tics).
An element with the Operate privilege defined SHALL support Read (if readable), Write (if writable), and Invoke (if invocable) access if the source of the request is granted the Operate privi lege.
An element with the Manage privilege defined SHALL support Read (if readable), Write (if writable), and Invoke (if invocable) access if the source of the request is granted the Manage privi lege.
An element with the Administer privilege defined SHALL support Read (if readable), Write (if writable), and Invoke (if invocable) access if the source of the request is granted the Administer privilege.
This quality requires the use of a timed interaction.
Timed interactions are used to limit the amount of time an action message is valid and can interact with a node. They are used to prevent a timing attack on the system. For example, a malicious attacker could perform an “intercept, interfere, and replay” procedure whereby a legitimate mes sage is intercepted, receipt by the intended destination is jammed, and the attacker sends the mes sage at a later time to cause a malicious action such as unlocking a door at an unintended time. While the practical difficulties of such an attack are high, and the malicious eavesdropper cannot decrypt the action message, the timed interaction provides further mitigation of risk for critical
The timed interaction can be thought of as a 2-phase commit. A precursor action (Timed Request Action) is sent to indicate the valid time window for arrival of some subsequent, primary action. Since the timed request requires a response, an attacker cannot do the store-and-forward timing attack anymore. The lack of an authenticated response from the intended destination will prevent the subsequent primary action from being sent.
A command with this quality SHALL require a timed invoke interaction. A writable attribute with this quality SHALL require a timed write interaction.
An attempted untimed write interaction to a writable attribute with this quality SHALL generate an error response.
An untimed invoke interaction for a request command with this quality SHALL generate an error response.
A Quality column defines other qualities not covered in other columns. Some qualities are limited to a specific set of elements. If an element does not have designated qualities, then it SHALL inherit qualities from the next highest element in the model hierarchy. For example: A data field in a struct attribute inherits its access qualities from attribute.
|X||Nullable||data fields||the data type of the data field is nullable|
|N||Non-Volatile||attribute data||the attribute data value is non-volatile and is persistent across restarts|
|F||Fixed||attribute data||the read only value is a fixed value that never changes, unless the program image changes|
|S||Scene||attribute||the attribute is part of a scene|
|P||Reportable||attribute||if best effort reporting is supported then the attribute supports a reporting configuration|
|C||Changes Omitted||attribute data||fast changing data or data where deltas are meaningless to report, and which will not cause delta changes on subscriptions|
|I||Singleton||device type||the cluster is a single ton on the node for the device type|
|!Q||device type||the quality Q (from those defined above in this table) is disal lowed.|
Data with this quality is read only and has a fixed value that never changes, unless the program image changes.
This quality is supported and described in the Scenes cluster.
The Subscribe interaction supports all attribute data. This quality is supported by other interactions that only require attribute data with this quality to support interval or change reporting.
This quality MAY be given to attribute data that is deemed to have a high rate of change or where changes are not meaningful or too large to convey as part of Subscribe interaction.
Attribute data with this quality SHALL support Read Access, but SHALL NOT have delta changes published as part of a Subscribe interaction.
Data with this quality, that be indicated by more than one cluster, represents a single instance of the data, for the node.
A Node encapsulates an addressable, unique resource on the network that has a set of functions and capabilities that a user recognizes distinctly as a functional whole.
This distinction is usually physical, such as the physical device itself, or a logical instance of a physi cal device.
A node is the highest or outermost first order element in the data model. A node is the outermost unique addressable element of the data model.
A node MAY have multiple node IDs, each ID scoped to a particular fabric. When a node ID is used as the target address of an interaction, the fabric under which the node ID is scoped, is the access ing fabric for the interaction.
The lower layers in a communication stack supporting this data model SHALL support interactions between nodes on a logical inter-network of nodes. Please see the Interaction Model and System Model specifications that describe relationships and interactions between nodes and data model elements on each node.
It is possible for parts of a node to reside on different processors (e.g. separate application and net work processors).
A single physical product may support more than one node.
A node is composed of one or more endpoints. An endpoint is an instance of something that could be a service or virtual device as indicated by a device type.
Each endpoint conforms to one or more device type definitions that define the clusters supported on the endpoint. Clusters are object classes that are instantiated on an endpoint.
The word ‘device’, depending on the context, may be used as shorthand to denote the device type definition as represented by a device type ID, a device type implementation, or an endpoint (device type instance).
There are also many examples in specification text where ‘device’ is used, when it would be better, and more accurate to use ‘node’, ‘physical device’, or ‘product’.
The word ‘device’ may also be used in cluster specifications to describe application software that is supporting an instance of a cluster server or client. In this case, it would be better, and more accu rate to use either ‘client’ or ‘server’.
One must be careful to make sure there is no ambiguity when using the word ‘device’ in specifica
tion text, or better yet, use another word.
Clusters are the functional building block elements of the data model. A cluster specification defines both a client and server side that correspond with each other through interactions. A clus ter may be considered an interface, service, or object class and is the lowest independent functional element in the data model. Each cluster is defined by a cluster specification that defines elements of a cluster including attributes, events, commands, as well as behavior associated with interactions with these elements. Cluster attributes, events, commands and behaviors are mandatory or optional depending on the definition of the cluster. Optional items may have dependencies.
A cluster specification SHALL list one or more Cluster Identifiers. A Cluster Identifier SHALL refer ence a single cluster specification and SHALL define conformance to that specification. A cluster instance SHALL be indicated and discovered by a Cluster Identifier on an endpoint. A Cluster Iden tifier also defines the purpose of the instance.
The server cluster supports attribute data, events and cluster commands. The client cluster initiates interactions, including invocation of cluster commands.
The revision of a cluster is to enforce backward and forward compatibility, but still allow clusters to be enhanced, fixed, or updated, without changing the cluster’s basic function.
A cluster revision SHALL be associated with an approved revision and release of a cluster specifica tion. The revision of an instance of a cluster SHALL be represented by the global, mandatory, and read only ClusterRevision attribute. Please see ClusterRevision attribute.
Changes to a cluster specification SHALL only augment, not modify the primary function of the cluster. Changes to a cluster specification SHALL be represented by incrementing the cluster revi sion. New revisions of a client cluster SHALL interoperate with older revisions of the server cluster and vice versa. Interoperability between corresponding cluster instances MAY require reading the cluster revision.
For example: If a new product client application supporting revision 3 of cluster X wishes to take advantage of the new behavior that is mandated by revision 3, then the application can read the revision of the corresponding server cluster X in each remote endpoint. If a corre sponding cluster X supports revision 3 or greater, then the behavior is supported.
Examples of changes to a cluster that require incrementing the revision:
• Changing the behavior of the cluster
• Changing a read only attribute to become writable
• Adding new attributes (e.g. min and max of an existing attribute value)
• Adding new commands, actions, or behavior
• Adding one or more fields to an existing command
• Adding a new enumerated value to an attribute
• Changing anything that is optional to mandatory
• Changing dependencies of optional items
• Deprecating parts of the cluster specification
• Any non-editorial specification text change
In general, as the number of optional elements in a cluster specification increases, the number of possible combinations increases, which could decrease the interoperability of that cluster.
Each cluster has a mandatory feature set that consists of mandatory elements such as attributes, commands, fields, values, dependencies, behavior, etc.
A cluster specification MAY have optional feature sets, each supported by a set of elements (see Fea tureMap).
There is no requirement that each cluster instance supports the same set of optional elements.
If an application knows the ClusterRevision and FeatureMap supported by a cluster instance, then it knows the exact specification text required to be implemented by that instance.
A cluster data version is a metadata increment-only counter value, maintained for each cluster instance. A cluster data version represents an exact & coherent state of cluster attribute data at present. An application may externally hold a data version (called a held data version) published by a cluster instance which then represents a cluster instance state at some time in the past. An appli cation may use a held data version to optimize future interactions, by indicating the held data ver sion. A cluster data version is surfaced in the Interaction Model when data is requested. It is used to optimize data read transactions by reducing the need to send the same data. Write interactions may also be qualified with a held data version to disallow changes, unless the cluster instance has the same data version (see Interaction Model). A cluster data version is published as information in some interactions (See Interaction Model). An externally held data version may be included as information in some interactions (See Interaction Model).
A cluster data version SHALL increment or be set (wrap) to zero if incrementing would exceed its maximum value. A cluster data version SHALL be maintained for each cluster instance. A cluster data version SHALL be initialized randomly when it is first published. A cluster data version SHALL be incremented if any attribute data changes.
When considering the creation of a new cluster specification, it is recommended to consider reusing and extending an existing cluster specification. These are the mechanisms to consider, in order, to extend a cluster:
- Optional elements: attribute data, commands, events, enumerations,
- Optional feature(s) in the FeatureMap Attribute attribute for a set of elements (see 1)
- Cluster Aliasing to reuse a cluster specification as a whole, but with a different semantic
- Cluster Inheritance
- A new cluster specification
Cluster aliasing allows the reuse of approved and validated specifications and derived documents, such as test plans, scripts, etc.
- More than one Cluster Identifier, each with unique purpose and semantic content, MAY map to a single cluster
|For example: A Concentration Measurement cluster specification may be quite abstract but have many mapped Cluster Identifiers each with a more concrete purpose, such as CO2 or O2 concentration measurement.|
Cluster inheritance allows the reuse of approved and validated specifications and derived docu ments, such as test plans, scripts, etc. This allows a new cluster specification to be defined as extending or reducing the requirements of an existing cluster specification, called the base cluster. This also allows an existing cluster specification to be defined as a derived cluster, by creating a new base cluster that is more generic, allowing potential new clusters to be derived from the new base cluster.
- A derived cluster specification MAY have mandatory requirements that are optional in the base specification.
- A derived cluster specification MAY remove requirements that are optional in the base specifi cation.
- A derived cluster specification MAY remove or make optional a requirement that is mandatory in the base specification, if the resulting specification is deemed useful in its reduced form, and logically a subset of the base
|For example: The Bridged Device Basic Information cluster is derived as a reduced form of the base Basic Information cluster, where many informational attributes are not mandatory, because the information is not available from devices behind the bridge. However, the derived cluster provides the same, but reduced, function as the base cluster.|
- It is RECOMMENDED that an extension or reduction for a derived cluster is one or more fea tures or independent elements, not a modification to custom cluster
- All new features, elements or behavior introduced by the derived cluster SHALL be defined in
the base cluster specification and made optional (in that base cluster specification), to maintain the entire set of requirements and identifier namespace in one place.
- A derived cluster specification SHALL define its own revision (ClusterRevision attribute) that is independent of the base
- A base cluster specification MAY be created from an original base cluster, which then becomes a derived cluster to the newly created base
If an endpoint supports multiple server clusters that derive or map to the same base cluster specifi cation, then each SHALL represent a single implementation and operate as a single entity or instance. This makes it possible to deploy a new device endpoint with both a base and a derived cluster identifier, which SHALL remain backward compatible to legacy devices that support only the original cluster identifier. Cluster identifiers that are mapped to a single base cluster specifica tion, but are defined for distinctly different purposes, MAY exist together on a device endpoint. If there is no base cluster identifier defined, or no base cluster identifier exists on the same endpoint, then each cluster identifier SHALL represent a separate instance.
It is a good practice to explore the possibility of either deriving a cluster from an existing cluster or creating a base cluster to map or derive new and existing cluster identifiers. See New Cluster for other options.
A cluster specification defines status code responses to actions depending on the cluster instance state. A status code is either a global Interaction Model status code, or a cluster specific status code that is unique to the cluster specification. A global status code is either scoped to the entire action, or to a cluster request path. A cluster specific status code scoped to a cluster instance is indicated by a cluster path. When an interaction defines a Status Response response, the responder SHALL return a global Interaction Model status code. When an interaction response needs to communicate a cluster specific status code, the responder SHALL return the path to the cluster instance, the global status code SUCCESS or FAILURE, and the cluster specific status code. Each cluster specific status code SHALL be associated with either SUCCESS or FAILURE, not both. A cluster specific status code SHALL be, by default, associated with FAILURE unless it is defined as associated with SUCCESS. The global SUCCESS status code means the action was executed for the request path; the global FAILURE status code means that it was not executed.
- Cluster-specific status code SHALL be defined using the status
- Cluster-specific status codes MAY have the same numeric values as global status codes. Interac tion model messages SHALL make it clear whether a particular message field is a global status code or a cluster-specific status
- Cluster-specific status codes SHALL communicate more information than just a generic success or failure Global status codes SHALL be used to communicate such conditions.
- A server cluster SHALL NOT return a cluster-specific code from another
A cluster SHALL be defined as either a utility cluster or an application cluster.
22.214.171.124. Utility Cluster
A utility cluster is not part of the primary application operation of an endpoint. It may be used for configuration, discovery, addressing, diagnostics, monitoring device health, software update, etc. It may have a temporary relationship with its cluster counterpart.
|Utility cluster examples scoped to an endpoint: Identify, Descriptor, Binding, Groups, etc. Util ity cluster examples scoped to the node: Basic Information, Diagnostics, etc.|
126.96.36.199. Application Cluster
An application cluster supports the primary operation of the endpoint. An application cluster sup ports one or more persistent application interactions between client and server.
Example application cluster transactions:
• On/Off cluster – client sends command to server
• Temperature Measurement cluster – server reports data to client
An application cluster is not a utility cluster even though it may support utility functions for itself, such as calibration, modes of operation, etc. An application cluster specification SHALL be agnostic about layers and processes outside of its application domain.
Example: A particular temperature measurement cluster may exist on different devices, or in different networks, each with different security & commissioning mechanisms and/or poli cies.
Example: A commissioning cluster’s domain is commissioning, but not temperature measure ment.
A cluster command is a set of data fields, each of a data type that is conveyed between client and server cluster instances to invoke a behavior on the receiver of the command.
Each command SHALL be listed in a table with data quality columns: ID, Name, Direction, Response, Access, Conformance.
The command table SHALL define the direction of the command as either client to server or server to client. The command table SHALL define the access privileges for each request command or omit the privileges for the default (see default access privileges). The command table SHALL NOT define privileges for a response command. The command table SHALL define a possible response to the command, if any. The command table SHALL define conformance for each command.
A command that is not a response (in the Response column) is a request command. Conformance
for a client to server command means the server SHALL recognize and support the client to server command and generate responses as defined. Conformance for a server to client command means the server SHALL send the command as cluster behavior defines, such as in response to a client to server command. Conformance for a command can depend on supported server features. A client SHALL NOT be required to support optional commands or commands depending on an optional feature.
A command description SHALL define when a command is generated. A command description SHALL define the effect upon receipt of a command which may be:
- a response command
- a success status response
- an error status response
- no response
A command definition SHALL clearly define any side-effects on fabric-scoped data, if applicable. A command is identified and indicated with a command ID that SHALL be unique to the cluster*.
Some legacy clusters have reused the same command ID twice to indicate one command from the client and another from the server. Moving forward, command IDs SHALL NOT be reused in that fashion.
A cluster command table SHALL have a Response column with the following values:
|N||no response is returned for this command|
|Y||status only is returned for this command|
|command||name of the response command to this com mand|
A cluster command table SHALL have a Direction column with the following values:
|client ⇒ server||command is conveyed from the client to the server cluster|
|client ⇐ server||command is conveyed from the server to the client cluster|
Each command SHALL be described in its own section with a table defining command fields (if any).
A command MAY indicate zero or more fields that are defined in a table. Each command field is defined as a row in the table with these columns:
|ID||This is the unique field ID of the field|
|Name||This is the unique name of the field|
|Type||This is the data type of the field|
Command field conformance defines the sender requirements to include the field in a well-formed command for the revision of the cluster. A new command field or a newly made-mandatory com mand field in a newly revised cluster specification may be omitted by a legacy sender. The cluster specification shall define clear behavior upon receipt of any possible well-formed command with fields that are not present. The cluster specification shall take into consideration the revision his tory of possible well-formed commands from legacy implementations. To allow deprecation, it is recommended that command fields have a well-defined default value (such as null), and associated default behavior, that is equivalent to omitting the field. Well-defined behavior, for a field that is not present, may be no behavior at all.
A newly revised Noise cluster adds a new mandatory Volume field to the MakeNoise com mand. Legacy receivers will ignore the Volume field, and legacy senders will not include the field.
The Volume field is mandatory for the original cluster and there is a proposal to make it optional. The Volume field null value has the semantic of ignoring the field, so instead of making it optional, the default value is used. This would make the receiver logic simpler.
An attribute is cluster data. Each attribute SHALL be listed in a table with data quality columns: ID, Name, (Data) Type, Constraint, other Quality, Access, Default (value), and Conformance. An attribute SHALL also define its associated semantics and behavior. Attributes reflect queryable/set table state, configuration and capabilities of a device. If no privileges are explicitly defined for an attribute, then default access privileges take effect. Attribute data MAY also have these other quali ties:
|Scene||S||indicates that the data is part of a scene|
|Persistent||N||indicates that the data value is persistent across restarts|
|Fixed||F||indicates that the read only data value will never change|
|Nullable||X||indicates that the data may have a value of null|
Fabric-scoped attribute data SHALL be defined as a fabric-scoped list.
Persistent data retains its value across a restart. A restart is:
- a program restart or reboot
- power cycle reboot
- user-initiated reboot
- reboot initiated from a program image upgrade
A factory reset is not such a restart. A factory reset is a deliberate behavior to reset persistent data back to its original state when the product left the factory.
Cluster attributes that represent configuration data SHALL be persistent data unless otherwise specified.
For example: a writable attribute that persistently changes the behavior (or mode) of the clus ter.
Examples of non-configuration data: device state data, data that is calculated or comes from an external source, such as a sensor value, a time value, etc.
Many clusters define persistent data that is not surfaced as attributes, but is managed by com mands. Commissioning or configuration data that is created to allow the cluster to perform its func tion is persistent data. A group table entry and binding entries are both persistent data across a restart.
When a persistent cluster attribute represents controlled state of the device, the device SHALL restore the attribute value to the value before the restart was initiated, and put the device in the state that is represented by the restored value.
|For example: After an OTA cluster restart, clusters that have visible state attributes, such as|
|the state of a light, or a window shade SHALL be persistent and define these attributes as per sistent.|
Some cluster specifications add a dependency with a persistent configuration attribute A that con tains a value to use to restore persistent state attribute B after a restart. This is perfectly valid but cluster specific.
Cluster state data that is not controlled, such as sensor data, is not considered persistent. The cluster specification may put dependencies and limitations on persistent data.
Below is a list of global elements. These are used for self-description of the server.
|ID||Name||Element||Type||Con straint||Quality||Access||Default||Confor mance|
|0xFFFD||Cluster Revision||attribute||uint16||1 to max||F||R V||M|
|0xFFFC||Fea tureMap||attribute||map32||F||R V||0||M|
|0xFFFB||Attribut eList||attribute||list[attrib- id]||F||R V||M|
|0xFFFA||EventList||attribute||list[event- id]||F||R V||P, M|
|0xFFF9||Accept edCom mandList||attribute||list[com mand-id]||F||R V||M|
|0xFFF8||Generat edCom mandList||attribute||list[com mand-id]||F||R V||M|
|0xFE||FabricIn dex||struct or event field||fabric-idx||1 to 254||R V F||fabric- scoped|
The ClusterRevision attribute indicates the revision of the server cluster specification supported by the cluster instance. An implementation of a cluster specification before the ClusterRevision attribute was added SHALL have an assumed cluster revision of 0 (zero). For a new cluster specifi cation, the initial value for the ClusterRevision attribute SHALL be 1 (not zero).
A history of revision numbers for a cluster specification release is listed in the Revision History sec tion for a cluster specification. Each new revision of a cluster specification SHALL specify a new revision number incremented (by 1) from the last. The highest revision number in a cluster specifi
cation’s Revision History is the revision number for the cluster specification. Therefore, a Cluster Revision attribute value SHALL be the (highest) revision number of the cluster specification that has been implemented.
Each instance of a cluster SHALL support this attribute.
The FeatureMap attribute SHALL indicate whether the server supports zero or more optional clus ter features. A cluster feature is a set of cluster elements that are mandatory or optional for a defined feature of the cluster. If a cluster feature is supported by the cluster instance, then the cor responding bit SHALL be set to 1, otherwise the bit SHALL be set to 0 (zero). All undefined bits in this attribute SHALL be set to 0 (zero).
The set of cluster elements that are designated as mandatory (M) are implicitly part of the manda tory cluster feature set, and do not have a bit in the FeatureMap attribute.
A cluster specification SHALL support this attribute if the cluster supports features. If a cluster specification is revised to support features (and so this attribute), each bit in the FeatureMap attribute SHALL have a defined default value (1 or 0), to conform with the previous revision of the cluster specification, that did not support the FeatureMap attribute. The value of 1 means the fea ture elements were mandatory (M) in the previous revision. The value of 0 (zero) means the ele ments were optional in the previous revision.
Any newly created feature set of a cluster SHALL be dependent on that cluster.
Feature sets are revision controlled as part of a cluster using the ClusterRevision attribute. The clus ter specification is the independent element that is revision controlled. A remote application read ing the FeatureMap Attribute and ClusterRevision Attribute will then know exactly what features are supported in the cluster instance.
Each feature set SHALL be well defined within the cluster specification. Each feature SHALL be mapped to a short capitalized code name for the feature set to be referenced as a conformance tag in the cluster specification text, including the Conformance columns defining the elements of the cluster.
If a cluster defines more than 32 feature sets, then it will be necessary to add another feature bitmap attribute. Any client trying to reference the new feature set will know about the new bitmap, because it knows about the new feature set(s). Legacy products will not know about the new feature set nor the new bitmap.
For a cluster whose definition which does not define a FeatureMap, the server SHALL set this attribute to 0 (zero).
Please see Feature Conformance for details on conformance.
Each instance of a cluster SHALL support this attribute. This attribute SHALL be a list of the attribute IDs of the attributes supported by the cluster instance.
This attribute is a list of client generated commands which are supported by this cluster server instance.
Each instance of a cluster SHALL support this attribute.
This attribute SHALL be a list of the command IDs for client generated commands that are sup ported and processed by the server.
For each client request command in this list that mandates a response from the server, the response command SHALL be indicated in the GeneratedCommandList attribute.
This attribute is a list of server generated commands. A server generated command is a server to client command.
Each instance of a cluster SHALL support this attribute.
This attribute SHALL be a list of the command IDs for server generated commands.
For each command in this list that is a response to a client command request, the request command SHALL be indicated in the AcceptedCommandList attribute.
Each instance of a cluster SHALL support this attribute. This attribute SHALL be a list of the event IDs of the events supported by the cluster instance.
NOTE Support for EventList attribute is provisional.
This field SHALL be present for fabric-scoped data. This field does not have to be defined explicitly in the field table for fabric-scoped data.
This field SHALL NOT be present in a write interaction. For a write interaction, the server SHALL provide the value of the accessing fabric-index as the FabricIndex field value to processing logic, after receipt of the interaction. For a read interaction this field SHALL be included in all reported data that is defined as fabric-scoped.