7.14. Event
An event defines a record of something that occurred in the past. In this regard, an event record can be thought of as a log entry, with an event record stream providing a chronological view of the events on the node.
Unlike attributes, which do not provide any edge-preserving capabilities (i.e. no guarantees that
every attribute change will be conveyed to observers), events permit capturing every single edge or change and conveying it reliably to an observer. This is critical for safety and security applications that rely upon such guarantees for correct behavior.
Each cluster event is listed in a table that defines: ID, Priority, Access, Conformance.
Event records are readable, and do not require the read access quality to be explicitly defined.
7.14.1. Priority
Each event record has an associated priority. This priority describes the usage semantics of the event.
The following table defines possible event priorities:
Priority | Description |
DEBUG | For engineering debugging/troubleshooting |
INFO | Events that either drive customer facing fea tures or provide insights into device functions that are used to drive analytics use-cases |
CRITICAL | Events that impact physical safety of users, or ongoing reliable operation of the node function (or cluster of the node) |
7.14.2. Event Record
An event record is created by the node at the time the event happens. That record SHALL have the following data fields associated with it that are common to all events:
- Event Number
- Timestamp
- Priority
Each generated event record SHALL have an event priority that MAY override the defined priority for that event.
Each event SHALL be described in a section that defines the purpose of the event and data fields of the event (if any). Event fields SHALL be defined in the form of a struct in a table with the following columns: ID, Name, Type, Constraint, Quality, Default, Conformance.
7.14.2.1. Event Number
This is an event number value that is scoped to the node. This number SHALL be monotonically increasing for the life of the node. This monotonicity guarantee SHALL be preserved across restarts.
Between restarts, each event record SHALL be assigned a number that is exactly 1 greater than the last created event record on that Node.
When a node restarts, the event number MAY increase by a larger step than 1. Rationale: Nodes do not need to write every new value of the event number counter to permanent storage each time it is increased (e.g. to prevent flash wear due to many write operations). One example strategy to achieve reduction of non-volatile storage updates is described below:
- Read the counter value at start-up.
- Before processing any message, write counter + N to storage, where N is a carefully chosen number (e.g. 1000). This number N should be chosen carefully in order not to exhaust the life time 64-bit counter
- Process messages normally until the counter has a value one less than the counter in storage. When this happens, store counter + N to storage.
7.14.2.2. Timestamp
Each event record SHALL have a timestamp at the time it was created (and not when it is reported to a client). This timestamp SHALL either be System Time in milliseconds or POSIX Time in millisec onds.
7.14.3. Buffering
Event records SHALL be buffered on the Node, with priority given to events of a higher priority level over a lower priority level. Within a priority level, newer event records SHALL overwrite older event records. The Node SHOULD only overwrite older events if there are newer events cre ated and there is insufficient space to retain both.
7.14.4. Event Filtering
Interactions that report event records MAY be filtered by event ID and/or event number.
7.14.5. Fabric-Sensitive Event
An entire event MAY be defined as having the fabric-sensitive quality; otherwise, it SHALL NOT be associated with a fabric.
A read interaction SHALL NOT filter event records, based on fabric, for event records that are not associated with a fabric.
A read interaction SHALL NOT report fabric-sensitive event records that are associated with a fab ric different than the accessing fabric.
A fabric-sensitive event SHALL include the global FabricIndex field. For a fabric-sensitive event it is not required to define the FabricIndex field in the event field table.
7.15. Device Type
In this architecture model, a device type is the highest semantic element. A device type defines con formance for a set of one or more endpoints. A device type defines a set of requirements for the node or endpoint in the market.
A device type SHALL define the cluster support for an endpoint. A composed device type MAY define one or more other device types as part of the composed device type.
A device type definition MAY define or use predefined conditions from requirements, limitations and/or capabilities of the node. A device type definition MAY define or use predefined conditions on one or more underlying stack standard(s).
A device type MAY define support of a cluster as dependent upon a condition. A device type defini tion MAY specify optional clusters that are recommended as enhancements.
A device type definition MAY refine cluster conformance:
- Support of optional cluster elements or features MAY be changed to mandatory depending on device type
- Support of optional cluster elements or features MAY depend on device type
A device type definition SHALL specify a device type ID, device revision, and a set of one or more mandatory clusters including each cluster’s minimum revision.
A device type definition MAY be generic and allow many similar clusters, where at least one instance SHALL be required.
For example: a simple sensor device. |
If all sensor devices are common in cluster requirements (except the clusters that perform the sens ing), then there is no reason to create a device type for each sensor cluster.
A device type definition MAY be very specific and list particular clusters as mandatory.
For example: a door lock device or thermostat. |
7.15.1. Device Type Revision
A device type revision is an unsigned integer that is associated with an approved revision and release of a device type definition. The initial value for a device type revision SHALL be 1. The ini tial revision (1) of a device type definition SHALL require the latest (at the time of definition the cluster) certifiable revisions of the clusters it mandates. Device type implementations MAY support later revisions of the mandatory clusters as they become certifiable. Any mandatory changes to the device type definition SHALL only augment, not modify, the function of the device. Any changes SHALL increment the version of the device. Newer versions of the device SHALL interoperate with older revisions at the older revision’s level of functionality.
Examples of changes to a device type definition that require incrementing the revision:
• Mandating a higher revision of one or more mandatory clusters • Changing an item from optional to mandatory |
• Deprecating parts of the device type definition |
7.15.2. Device Type Composition
A device type definition MAY be a composed device type and therefore require other device types for its composition. A device type instance MAY be composed of other endpoints that support extra cluster instances. Please see the System Model specification for more details.
7.15.3. Device Type Classification
Each device type definition SHALL specify the endpoint as being either a Utility, or Application. Each device type definition SHALL specify the scope as either endpoint or node. Each Application device type definition SHALL specify the endpoint as being either Simple or Dynamic.
7.15.3.1. Utility Device Type
A Utility device type supports configuration and settings. A utility device type definition SHALL define requirements for utility clusters. A utility device type MAY also represent the physical device or product. There MAY be more than one endpoint supporting a utility device type on a node. Example utility cluster categories: OTA upgrade, diagnostics, basic information. Example utility device type categories: bridge, proxy, power source.
7.15.3.2. Application Device Type
Application devices types are typically the most common endpoints on a node and in the network. An endpoint supporting an application device type is an application endpoint. An Application device type SHALL be scoped to the endpoint. An application endpoint SHALL support clusters the primary application function of the endpoint. Application category examples: HVAC, lighting, home security, etc.
7.15.3.3. Simple Device Type
A Simple device type supports local control that is persistent, independent, and unsupervised. A Simple device type is an Application device type. Simple devices types are typically the most com mon endpoints in the network. Simple device type examples: sensors, actuators, lights, on/off switches, on/off power outlets, etc. Simple endpoints support independent operation without cen tral control or gateways. An endpoint supporting a simple device type is a simple endpoint. Simple endpoints SHALL support relationships through bindings.
7.15.3.4. Dynamic Device Type
A Dynamic device type supports intelligent and supervisory services, such as commissioning, moni toring, trend analysis, scheduling and central management. A dynamic device type is an application device type. An endpoint supporting a dynamic device type is a dynamic endpoint. A dynamic end point is typically found on a central controller where there exists an intelligent supervisory applica tion that manages simple device control applications. Typically, a dynamic endpoint supports client clusters for central control, management, monitoring or supervisory functions. Typically, the prod uct supporting a dynamic endpoint has visibility into the entire network (or part thereof ) of simple
endpoints.
A dynamic endpoint client cluster instance MAY be used to multiplex transactions to or from multi ple simple device server clusters in the network. A dynamic endpoint client cluster MAY initiate interactions to many server clusters in the network. A dynamic endpoint client cluster MAY receive data from many server clusters in the network. Dynamic endpoints MAY support relationships through bindings. A dynamic device endpoint MAY support one or more external agents, outside the node stack, that manage relationships. External agents include, but are not limited to, a cloud application, a smartphone, an in-home display, or a configuration tool.
7.15.3.5. Device Type Scope
A node device type is a utility device type scoped to a node. A node device type definition SHALL support clusters that represent the entire node. An endpoint supporting a node device type is a node endpoint. A node endpoint MAY also represent the physical device or product. There MAY be more than one node endpoint on a node.
Other classes of device types are endpoint scoped device types.
7.15.4. Extra Clusters on an Endpoint
An endpoint MAY support later revisions of a cluster mandated by the device type definition. An endpoint MAY support extra clusters not mandated by the device type definition. An endpoint MAY support optional features or cluster items (attributes, commands, events, etc.), that are not man dated by the device type definition. Extra clusters, features, or cluster items, SHALL only augment, not modify, the function of the device type or clusters.
7.16. Non-Standard
This architecture model provides mechanisms for non-standard or manufacturer specific items such as clusters, commands, events, attributes and attribute data fields. These items MAY be sup ported on a certified product. Such vendor specific items SHALL NOT change the standard behavior of the standard items. The specific function of a vendor specific item cannot be tested as part of cer tification. They can only be tested to verify that they do no harm, and conform to proper behavior with regard to identification, discovery, error processing, etc. A non-standard item SHOULD NOT take the place of a standard item that provides the same function. It is up to the certification authority to make a judgment call that is in keeping with the spirit of these requirements. Imple menters are encouraged to develop and certify standard items, not non-standard items.
7.17. Data Field
A data field is any attribute, field or entry that is not a collection data type, or data that is not sur faced as an attribute, but defined in a cluster specification.
Optional attribute data MAY be referenced as data fields in other attribute specifications within the same cluster specification. Cluster specifications also define data fields that are not surfaced, such as temporary calculated values, or persistent state values. Any defined data value in a cluster speci fication is a data field.
Each cluster data field SHALL be defined with a table including these columns for data qualities:
- Data Type
- Constraint
- Quality
- Access
- Default
- Conformance
A data field SHALL inherit (if possible) the qualities from the cluster first-order element of which it is part, unless overridden. It SHOULD be rare to override inherited qualities.
For example: If an attribute is a struct data type, that is readable and writable, then all fields of the struct are readable and writable. |
New or optional data fields MAY not be recognized by a receiver, such as a legacy receiver. The data field description SHALL define default behavior (such as absence of behavior) when a new or optional data field is not present. It is recommended to define or use a feature when adding new or optional data fields, to better indicate conformance. It is recommended to define a default value, such as a null value, that indicates such default behavior.
7.17.1. Nullable
When a data field value is required to designate an unknown, invalid, or undefined data value, and there is no obvious data value (e.g. zero), that is within the valid range to indicate this, the data field MAY be designated as nullable, so that an implemented instance of data MAY have the value of null.
In this context, these wordings have the same meaning:
- The data field has the value of
- The data field has the null
- The data field is the null
- The data field is
Representation of null for the implementation of the Data Model is a consideration of the underly ing encoding specification. The encoding layer SHALL have the capability to indicate null for any nullable data field. How the encoding layer indicates null is outside the scope of the Data Model specification.
All data fields MAY be defined to be nullable, regardless of data type.
A cluster specification SHALL define whether a data field is nullable. A cluster specification SHALL define the meaning of the null value.
Composite data types that have a length (i.e. octet string and list), and derived types that have those as the base type, SHALL NOT differentiate semantically between the null value and the empty (zero
length) value. In particular a zero-length value SHALL be allowed for nullable values of these types no matter what other length constraints are imposed on the value, and SHALL have the same semantics as the null value.
7.17.2. Optional or Deprecated
An optional or deprecated data field that is not implemented, and therefore does not exist, SHALL NOT be indicated as the null value. How the encoding layer encodes non-existent data is outside the scope of the Data Model specification.
The Conformance column shall define if a data field is optional or deprecated. To manage the data identifier namespace, a deprecated data field SHALL NOT be removed from text that lists its identi fier and default value. The description text of a deprecated data field SHALL be removed for new revisions of specification text.
If the specification text of a cluster depends on the value of an optional or deprecated data field of the same cluster, then the data field SHALL have a well-defined default value that SHALL be used when the data field is not implemented.
7.17.3. Constraint & Value
The tables below describe the nomenclature for describing constraints and default data values. This nomenclature is used in the cluster specifications for data value constraints, defaults, and other definitions.
7.17.3.1. Common Literal Values
These values are commonly used in cluster text and Default columns in cluster data definition tables.
Value | Description |
0 | The numeral zero is used to indicate the zero value for analog data. This is equivalent to the boolean value FALSE. |
1 | This is used for any analog data type to mean that the value is 1. This is equivalent to the boolean value TRUE. |
FALSE | “FALSE”, “false” or “False” is a boolean value and is equivalent to 0 (zero). |
TRUE | “TRUE”, “true” or “True” is a boolean value and is equivalent to 1. |
NaN | Not a Number defined for any floating point val ues. |
null | This indicates the value of null. |
empty | This indicates empty list or string data. |
Value | Description |
min | The minimum possible data value for the data type. |
max | The maximum possible data value for the data type. |
numeric units | Some number in some well-defined units as described in the data type (e.g. 100o C) |
7.17.3.2. Constraint
The Constraint column is valid for any composed device type, attribute or data field of an attribute, event, command or struct. It is RECOMMENDED to always define a constraint for any data field.
Constraint | Description |
desc | Defines the constraint is defined in the descrip tion section |
Composed Device Type Constraints | |
x* | Defines the exact number of endpoints, greater than zero, supporting this device type as a part of the composed device type |
x to y | Defines the allowed number of endpoints, greater than zero, supporting this device type as a part of the composed device |
max y | Defines the maximum number of endpoints, greater than zero, supporting this device type as a part of the composed device |
min x | Defines the minimum number of endpoints, greater than zero, supporting this device type as a part of the composed device |
Numeric Data Type Constraints | |
x | Defines a value that is supported. |
x to y | Defines a supported value range. |
max y | Defines the value range from min to y |
min x | Defines the value range from x to max. |
all | Defines that all values are supported. Same as “min to max”. |
constraint, constraint… | Defines support of a union of two or more value and value range constraints |
Octet String Data Type Constraints | |
x* | Defines the size range in bytes to be exactly x |
Constraint | Description |
x to y | Defines the size range in bytes from x to y |
min x | Defines that the size limit supported is a mini mum of x bytes |
max y | Defines the size limit supported is a maximum of x bytes |
all | Defines no constraint on size of the string. Same as “min to max”. |
constraint, constraint… | Defines support of a union of two or more size range or size limit constraints |
List Data Type Constraints | |
x* | Defines the range of entries to be exactly x |
x to y | Defines the range of entries from x to y |
min x |
defines the limit supported is a minimum of x entries |
max y |
Defines the limit supported is a maximum of x entries |
all | Defines no constraint on the number of entries in the list. Same as “min to max”. |
constraint, constraint… | Defines support of a union of two or more list range or limit constraints |
list_constraint[ entry_constraint ] | Defines list_constraint as a list constraint and entry_constraint as a constraint on the entry data type. See also list entry qualities |
Character String Data Type Constraints | |
char_constraint[ z ] | Defines char_constraint as the string constraint in bytes and z as the maximum number of Uni code codepoints. |
* x, y, or z are literal values of the data type or from the Common Literal Values.
7.17.3.3. List and String Constraint
The minimum number of entries for list or size of a string SHALL be 0 (zero), unless redefined using the above notation.
A comma delimited set of constraints for a list or string defines a union constraint. A union con straint SHALL only have one minimum (min x) constraint and one maximum (max y) constraint. A union constraint SHALL NOT define a range below the minimum constraint or range greater than the maximum constraint, including the defined minimum (min) and maximum (max) for the data type.
A constraint on a list or string data means that the data SHALL always be indicated within that con
straint. A constraint on a writeable list or string data means that the data SHALL support writing within the constraint, and SHALL NOT support writing outside the constraint.
7.17.3.4. Read Only vs Write Access
- Effective Maximum for Character String Data Type
A server SHALL support up to the maximum in char_constraint for a character string data type. The character string data SHALL NOT contain more than z Unicode codepoints.
Example: A string with a constraint of “max 128 [32]” dictates that the server provide for a 128 byte string, but the string may contain up to 32 Unicode codepoints |
7.17.3.6. Nullable in Range
If data is nullable then null SHALL be a valid value.
If the data type is a list or derived from a list, and the list is nullable, then a length of 0 (zero) SHALL be supported, and defined in the constraint column.
If the data type is an octet string, or derived from an octet string (e.g. character string), and the data is nullable, then a length of 0 (zero) SHALL be supported, and defined in the constraint column.
7.17.4. Default Column
A default value defined in the Default column is not meant to be the value used when the server returns to factory fresh settings. Specified conformance for data fields may be optional or change over time. A default value is defined to complete dependencies when the actual data field value is not present.
A data field SHALL have a defined default value when:
- the data field is new, and a default is required for backwards compatibility with legacy instances
- the data field is optional, deprecated, or obsolete and therefore is not always present
- an initial value is needed before the application starts
- the value cannot be determined by the application for the instance
- there is a dependency on the attribute value to formulate other data or affect behavior
If a default value is not defined for a data field, the default value is determined by the following conditions:
- If the data field is nullable then the default value SHALL be null
- Else the default value SHALL be one of the following, depending on type:
- Boolean: false
- Analog: 0 or 0.0, depending on range
- Bitmaps: 0
- Enumeration: MS
- Composite:
- String: empty
- List: empty
- Struct: default is recursively composited from the defaults of its member fields
- Derived types: use the default value of the base type
These are the options for the Default column used for attributes or attribute, command or event data:
Default Column | Description |
x | a literal value x of the data type, or as defined in Common Literal Values |
MS | a manufacturer or implementation specific value |
If the default value of a data field is specified as manufacturer specific, then there SHALL be no defined default value and the application SHALL support a manufacturer specific value that is in the valid range.
7.18. Data Types
Each data field in a cluster specification SHALL have a well-defined data type. Each attribute in a cluster specification SHALL map to a single data type.
The table indicates for each data type whether it defines an analog or discrete value. Values of ana log types MAY be added to or subtracted from other values of the same type and are typically used to measure the value of physical properties that can vary continuously over a range. Values of dis crete data types only have meaning as individual values and SHALL NOT be added or subtracted.
Some data types specify bit-widths for future potential growth in range (analog) or number of val ues (discrete).
Cluster specifications SHALL use the unique data type short name to reduce the text size of the specification.
7.18.1. Base Data Types
Class | Data Type | Short | ID | Size |
Discrete |
Boolean | |||
Boolean | bool | 0x10 | 1 byte | |
Bitmap | ||||
8-bit bitmap | map8 | 0x18 | 1 byte | |
16-bit bitmap | map16 | 0x19 | 2 bytes | |
32-bit bitmap | map32 | 0x1B | 4 bytes | |
64-bit bitmap | map64 | 0x1F | 8 bytes |
Class | Data Type | Short | ID | Size |
Analog |
Unsigned Integer | |||
Unsigned 8-bit integer | uint8 | 0x20 | 1 byte | |
Unsigned 16-bit integer | uint16 | 0x21 | 2 bytes | |
Unsigned 24-bit integer | uint24 | 0x22 | 3 bytes | |
Unsigned 32-bit integer | uint32 | 0x23 | 4 bytes | |
Unsigned 40-bit integer | uint40 | 0x24 | 5 bytes | |
Unsigned 48-bit integer | uint48 | 0x25 | 6 bytes | |
Unsigned 56-bit integer | uint56 | 0x26 | 7 bytes | |
Unsigned 64-bit integer | uint64 | 0x27 | 8 bytes | |
Signed Integer | ||||
Signed 8-bit inte ger | int8 | 0x28 | 1 byte | |
Signed 16-bit inte ger | int16 | 0x29 | 2 bytes | |
Signed 24-bit inte ger | int24 | 0x2A | 3 bytes | |
Signed 32-bit inte ger | int32 | 0x2B | 4 bytes | |
Signed 40-bit inte ger | int40 | 0x2C | 5 bytes | |
Signed 48-bit inte ger | int48 | 0x2D | 6 bytes | |
Signed 56-bit inte ger | int56 | 0x2E | 7 bytes | |
Signed 64-bit inte ger | int64 | 0x2F | 8 bytes | |
Analog |
Floating Point | |||
Single precision | single | 0x39 | 4 bytes | |
Double precision | double | 0x3A | 8 bytes |
Class | Data Type | Short | ID | Size |
Composite |
String | |||
Octet string | octstr | 0x41 | desc | |
Collection | ||||
List | list | 0x48 | desc | |
Struct | struct | 0x4C | desc |
7.18.1.1. Boolean
The Boolean type represents a logical value, either FALSE or TRUE.
- FALSE SHALL be equivalent to the value 0 (zero).
- TRUE SHALL be equivalent to the value 1 (one).
7.18.1.2. Bitmap (8, 16, 32 and 64-bit)
This data type is typically used to represent simple cluster settings or state that are treated as whole.
The Reserved Bit Fields conventions define reserved bitmap data.
- It is RECOMMENDED to define more bits than initially needed to be able to support more values for later
- The Bitmap type MAY be used to support up to 8, 16, 32 or 64 boolean
- Bits MAY be combined to enumerate other
- Bits SHOULD be combined as contiguous bit
- Future revisions MAY require non-contiguous bit
- The conformance for a bit in a bitmap SHALL be mandatory or dependent upon an existing dis coverable element, and therefore SHALL NOT be purely
Allowable Conformance for a bit in a bitmap:
- Mandatory
- Dependent upon a Feature supported in the FeatureMap
- Dependent upon the support of an
A nullable bitmap SHALL NOT permit use of the most significant bit.
7.18.1.3. Unsigned Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)
This type represents an unsigned integer with length of N bits and a usable range of:
- [0..2N-1] if not nullable OR
- [0..2N-2] if nullable.
The following table presents the representable values following the above rules:
Width N (bits) | Minimum value | Maximum value if nullable | Maximum value if not nullable |
8 | 0 (0x00) | 254 (0xFE) | 255 (0xFF) |
16 | 0 (0x0000) | 65534 (0xFFFE) | 65535 (0xFFFF) |
24 | 0 (0x000000) | 16777214 (0xFFFFFE) | 16777215 (0xFFFFFF) |
32 | 0 (0x00000000) | 4294967294 (0xFFFFFFFE) | 4294967295 (0xFFFFFFFF) |
40 | 0 (0x0000000000) | 1099511627774 (0xFFFFFFFFFE) | 1099511627775 (0xFFFFFFFFFF) |
48 | 0 (0x000000000000) | 281474976710654 (0xFFFFFFFFFFFE) | 281474976710655 (0xFFFFFFFFFFFF) |
56 | 0 (0x00000000000000) | 72057594037927934 (0xFFFFFFFFFFFFFE) | 72057594037927935 (0xFFFFFFFFFFFFFF) |
64 | 0 (0x0000000000000000) | 18446744073709551614 (0xFFFFFFFFFFFFFFFE) | 18446744073709551615 (0xFFFFFFFFFFFFFFFF) |
7.18.1.4. Signed Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)
This type represents an signed integer with length of N bits and a usable range of:
- [-(2(N-1))..2(N-1)-1] if not nullable OR
- [-(2(N-1)-1)..2(N-1)-1] if nullable.
Whether to use two’s complement or another representation for the implementation of the Data Model is a consideration of the underlying encoding specification.
The following table presents the representable values in base-10 following the above rules:
Width N (bits) | Minimum value if nullable | Minimum value if not nullable | Maximum value |
8 | -127 | -128 | 127 |
16 | -32767 | -32768 | 32767 |
24 | -8388607 | -8388608 | 8388607 |
32 | -2147483647 | -2147483648 | 2147483647 |
40 | -549755813887 | -549755813888 | 549755813887 |
48 | -140737488355327 | -140737488355328 | 140737488355327 |
56 | -36028797018963967 | -36028797018963968 | 36028797018963967 |
Width N (bits) | Minimum value if nullable | Minimum value if not nullable | Maximum value |
64 | -9223372036854775807 | -9223372036854775808 | 9223372036854775807 |
7.18.1.5. Enumeration (8-bit, 16-bit)
This data type employs scalars to represent context-specific values available from an enumerated set. This data type is nullable.
External standards may be referenced as well as listing the values for the external standard. If the external standard adds values after a specification is adopted, those new values are allowed, but optional. Enumeration values are defined in a table with a Conformance column. When the defini tion of an enumeration is missing a Conformance column, all values SHALL be considered to have mandatory conformance.
All mandatory readable enumeration values SHALL be understood by the client. All mandatory writable enumeration values SHALL be understood by the server.
If a client indicates an enumeration value to the server, that is not supported by the server, because it is optional, deprecated, or a new value unrecognized by a legacy server, then the server SHALL generate a general constraint error, unless the cluster defines alternate behavior, such as:
- convert the value to a mandatory value
- ignore the value
- generate a cluster specific error
With regard to revising a cluster specification:
- It is RECOMMENDED that a client be as strict as possible by indicating only values that a server supports.
- It is RECOMMENDED that the server be as forgiving as possible when processing unsupported values.
Note that indicated enumerations MAY comprise only a strict subset of the required enumerations.
For example: If a server implementation can never enter an enumerated state XYZ, then the value XYZ would never be indicated, therefore the server would not have to support XYZ. |
7.18.1.6. Single-Precision
The single precision number format is based on the IEEE 754-2019 single precision (32-bit) format for binary floating-point arithmetic.
See IEEE 754-2019 for more details on the representable values.
7.18.1.7.
|
Double Precision
The double precision number format is based on the IEEE 754-2019 double precision (64-bit) format for binary floating-point arithmetic.
The format and interpretation of values of this data type follow the same rules as given for the sin gle precision data type, but with wider mantissa and exponent ranges.
See IEEE 754-2019 for more details on the representable values.
7.18.1.8. Octet String
The octet string data type defines a sequence of octets with a finite octet count from 0 to 65534. It is RECOMMENDED to define a constraint on the maximum possible count.
7.18.1.9. List
A list is defined as a collection of entries of the same data type, with a finite count from 0 to 65534. A cluster specification may define further constraints on the maximum possible count. The list entry data type SHALL be any defined data type, except a list data type, or any data type derived from a list.
The quality columns for a list definition are for the list.
The list entries are indicated with an index that is an unsigned integer starting at 0 (zero). The maintained order of entries, by index, is defined in the cluster specification, or undefined. Data that is defined as a list is indicated with “list[X]” where X is the entry type. The data type of the list entry has its own qualities, constraints, and conformance.
|
To define qualities for the list entry data type, make the list entry data type a defined local derived data type, with a table including the columns required to define and constrain the data type.
For example: Derived data types defined here:
SummerStruct defined here:
Used Here: |
ID | Name | Type | Constraint | Quality | … | ||
0 | MonthNames | list[Month NameString] | 12 | N | … | ||
1 | SummerYears | list[Summer Struct] | max 50 | … | |||
|
There is an inline shortcut to define the list entry data type constraints. See List Constraints.
For example: |
It is RECOMMENDED to put a maximum constraint on the list and list entry data types.
It is RECOMMENDED that a list entry data type be a struct, to enable the addition of new fields to the list’s entries in the future.
- The cluster data version SHALL be incremented when the list order or entries
- An entry SHALL NOT be
- The list SHALL support reading and reporting all
- The list SHALL support reporting, updates, and/or deletion of one or more
- If the list is writable, it SHALL support writing or deleting the entire
- If the list is writable, it SHALL support updating one or more individual entries by indicating an index per updated
- If the list is writable, it SHALL support deleting one or more individual entries by indicating an index per deleted
- If the list is writable, it SHALL support adding one or more individual
- A list MAY define an entry that is a struct that is fabric-scoped (see Fabric-Scoped Quality).
Fabric-Scoped List
- A fabric-scoped list SHALL define an entry data type that is a struct, which SHALL also be fab ric-scoped (see Fabric-Scoped Struct).
Each entry in a fabric-scoped list SHALL be fabric-scoped to a particular fabric or no fabric.
A fabric-scoped list supports a fabric-filter that filters the view of the list for read and write interac tions. This filter simplifies client side logic that does not want to read or write fabric data that is not associated with the accessing fabric.
- An interaction upon a list with fabric-filtering SHALL only indicate and access entries where the associated fabric matches the accessing fabric, and all other entries SHALL be
- Fabric-filtered list entries SHALL be in the same order as the full
- Fabric-filtered list entries SHALL be indexed from 0 with no gaps, as if the other entries did not exist.
- For a write interaction, fabric-filtering SHALL be
- When writing to a fabric-scoped list, the write interaction SHALL be on an accessing fabric, oth erwise, the write interaction SHALL fail (see Interaction Model).
- For a read interaction on a list, fabric-filtering MAY be
- For a read interaction on a list, with fabric-filtering disabled, the list SHALL be reported as a full list with all
For example: A fabric-scoped full list with each entry having an associated FabricIndex and Value field:
list = [ { FabricIndex = A, Value = 20 }, { FabricIndex = B, Value = 30 }, { FabricIndex = A, Value = 40 }, { FabricIndex = B, Value = 50 }, { FabricIndex = B, Value = 60 } ]
would be a fabric-filtered list when accessed with fabric B:
list = [ { FabricIndex = B, Value = 30 }, { FabricIndex = B, Value = 50 }, { FabricIndex = B, Value = 60 } ]
Reading a fabric-filtered list entry index 2 accessed with fabric B reports:
list[2] = [ { FabricIndex = B, Value = 60 } ]
Writing fabric-filtered list entry index 1 when accessed with fabric B:
list[1] = [ { FabricIndex = B, Value = 55 } ]
changes the full list to:
list = [ { FabricIndex = A, Value = 20 }, { FabricIndex = B, Value = 30 }, { FabricIndex = A, Value = 40 }, { FabricIndex = B, Value = 55 }, { FabricIndex = B, Value = 60 } ] |
7.18.1.10. Struct
A struct is a sequence of fields of any data type. Individual fields are identified by a field ID of unsigned integer, starting at 0 (zero), for the first field.
- A struct itself SHALL have no constraint
- Each struct field SHALL have its own
- Access, conformance and persistence qualities, when not not explicitly defined, SHALL be inher ited from the instance of the struct
- Struct fields MAY have optional
- A struct SHALL support reading and reporting of all
- A struct SHALL support reporting changes to one or more
- If the struct is writable, it SHALL support writing the entire
- If a field of the struct is writable, the struct SHALL support updating the
- Because of optional struct field conformance, instances of the same struct MAY support multiple ‘flavors’ of the same struct data type, but with a different set of optional
Fabric-Scoped Struct
- A fabric-scoped struct SHALL only be defined and occur as an entry in a fabric-scoped
- A fabric-scoped struct SHALL support the global FabricIndex field of type fabric-index, which indicates the associated fabric of the struct, or indicates that there is no associated
- The table that defines fields of a fabric-scoped struct SHALL NOT list the global FabricIndex field, which is a global field and defined
- The global FabricIndex field of a fabric-scoped struct SHOULD NOT be indicated in a write inter action.
- The global FabricIndex field of a fabric-scoped struct SHALL be ignored in a write
- When a write interaction creates a fabric-scoped struct entry (in a fabric-scoped list), the server SHALL implicitly load the accessing fabric-index into the global FabricIndex field of the
- A fabric-scoped struct MAY be defined with some fields that are fabric-sensitive.
- For interactions on a fabric-scoped struct that report back data, fabric-sensitive struct fields SHALL NOT be indicated when reporting data back to the client, when the struct has an associ ated fabric, and it is not the accessing fabric.
7.18.2. Derived Data Types
These data types are commonly used and derived from the base data types. If a data type is used by more than one cluster specification, then it SHALL be listed here as a derived data type. Such com mon data types can then be reused instead of redefined in each cluster specification.
Class | Data Type | Short | Base Type | ID | Size |
Analog |
Relative | ||||
Percentage units 1% | percent | uint8 | 0x32 | 1 bytes | |
Percentage units 0.01% | percent100ths | uint16 | 0x33 | 2 bytes | |
Time | |||||
Time of day | tod | struct | 0xE0 | 4 bytes | |
Date | date | struct | 0xE1 | 4 bytes | |
Epoch Time in microseconds | epoch-us | uint64 | 0xE3 | 8 bytes | |
Epoch Time in seconds | epoch-s | uint32 | 0xE2 | 4 bytes | |
UTC Time | utc | same as Epoch Time in seconds but Deprecated | |||
POSIX Time in milliseconds | posix-ms | uint64 | 0xF3 | 8 bytes | |
System Time in microseconds | systime-us | uint64 | 0xE4 | 8 bytes | |
System Time in milliseconds | systime-ms | uint64 | 0xF4 | 8 bytes |
Class | Data Type | Short | Base Type | ID | Size |
Discrete |
Enumeration | ||||
8-bit enumera tion | enum8 | uint8 | 0x30 | 1 byte | |
16-bit enumer ation | enum16 | uint16 | 0x31 | 2 bytes | |
Priority | priority | enum8 | 0x34 | 1 byte | |
Status Code | status | enum8 | 0xE7 | 2 bytes | |
Identifier | |||||
Fabric ID | fabric-id | uint64 | 0xD1 | 8 bytes | |
Fabric Index | fabric-idx | uint8 | 0xD2 | 1 byte | |
Node ID | node-id | uint64 | 0xF0 | 8 bytes | |
IEEE Address | EUI64 | same as Node ID but Deprecated | |||
Group ID | group-id | uint16 | 0xF1 | 2 bytes | |
Endpoint Num ber | endpoint-no | uint16 | 0xE5 | 2 bytes | |
Vendor ID | vendor-id | uint16 | 0xD3 | 2 bytes | |
Device Type ID | devtype-id | uint32 | 0xED | 4 bytes | |
Cluster ID | cluster-id | uint32 | 0xE8 | 4 bytes | |
Attribute ID | attrib-id | uint32 | 0xE9 | 4 bytes | |
Field ID | field-id | uint32 | 0xEF | 4 bytes | |
Event ID | event-id | uint32 | 0xEE | 4 bytes | |
Command ID | command-id | uint32 | 0xEC | 4 bytes | |
Action ID | action-id | uint8 | 0xEA | 1 bytes | |
Transaction ID | trans-id | uint32 | 0xEB | 4 bytes | |
Index | |||||
Entry Index | entry-idx | uint16 | 0xF2 | 2 bytes | |
Counter | |||||
Data Version | data-ver | uint32 | 0xD0 | 4 bytes | |
Event Number | event-no | uint64 | 0xE6 | 8 bytes |
Class | Data Type | Short | Base Type | ID | Size |
Composite |
String | ||||
Character String | string | octstr | 0x42 | desc | |
Address | |||||
IP Address | ipadr | octstr | 0xD3 | 4 or 16 bytes | |
IPv4 Address | ipv4adr | octstr | 0xD4 | 4 bytes | |
IPv6 Address | ipv6adr | octstr | 0xD5 | 16 bytes | |
IPv6 Prefix | ipv6pre | octstr | 0xD6 | 1 to 17 bytes | |
Hardware Address | hwadr | octstr | 0xD7 | 6 or 8 bytes |
7.18.2.1. Time of Day
The Time of Day data type SHALL be a struct with these fields: Hours, Minutes, Seconds, and Hun dredths.
The hours field represents hours according to a 24-hour clock. The range is from 0 to 23. The minutes field represents minutes of the current hour. The range is from 0 to 59. The seconds field represents seconds of the current minute. The range is from 0 to 59. The hundredths field repre sents 100ths of the current second. The range is from 0 to 99. A value of null in any subfield indi cates an unused subfield. If all subfields have a value of null, this indicates a null time of day.
7.18.2.2. Date
The Date data type SHALL be a struct with these fields:
The year – 1900 subfield has a range of 0 to 255, representing years from 1900 to 2155. The month field has a range of 1 to 12, representing January to December. The day of month field has a range of 1 to 31. Note that values in the range 29 to 31 may be invalid, depending on the month and year. The day of week field has a range of 1 to 7, representing Monday to Sunday. A value of null in any subfield indicates an unused subfield. If all subfields have a value of null, this indicates a null date.
7.18.2.3. Epoch Time in Microseconds
This type represents an offset, in microseconds, from 0 hours, 0 minutes, 0 seconds, on the 1st of January, 2000 UTC (the Epoch), encoded as an unsigned 64-bit scalar value.
This offset is the sum of two parts: time elapsed, not counting leap-seconds, and a local time offset. The local time offset MAY include a timezone offset and a MAY include a DST offset.
Any use of this type SHALL indicate how the associated local time offset is determined in the spe cific context of that use. This MAY be done, for example, by simply saying the time is a UTC time, in which case the local time offset is 0.
A given Epoch Time value MAY be interpreted in at least two ways:
- The value can be converted to a local clock date/time (year, month, day, hours, minutes, sec onds, microseconds) by treating the local time offset as 0 and finding the UTC (year, month, day, hours, minutes, seconds, microseconds) tuple that corresponds to an elapsed time since the epoch time equal to the given value. The value then represents that tuple, but interpreted in the specific timezone and DST situation associated with the value. This procedure does not require knowing the local time offset of the
- The value can be converted to a UTC time by subtracting the associated local time offset from the Epoch Time value and then treating the resulting value as an elapsed count of microseconds since the epoch
For example, an Epoch Time value of 0x0000_0BF1_B7E1_0000 corresponds to an offset of exactly 152 days. This can be interpreted as “00:00:00 on June 1, 2000” in whatever local time zone is associ ated with the value. That corresponds to the following times in ISO 8601 notation:
- 2000-06-01T00:00Z if the associated local time offset is 0 (i.e. the value is in UTC).
- 2000-05-31T23:00Z if the associated local time offset is +1 hour (e.g. the CET timezone, without daylight savings).
- 2000-06-01T00:00+02 if the associated local time offset is +1
- 2000-06-01T04:00Z if the associated local time offset is -4 hours (e.g. the EDT time zone, which includes daylight savings).
- 2000-06-01T00:00-04 if the associated local time offset is -4
Conversion from NTP timestamps
Timestamps from NTP also do not count leap seconds, but have a different epoch. NTP 128-bit timestamps consist of a 64-bit seconds portion (NTP(s)) and a 64-bit fractional seconds portion (NTP(frac)). NTP(s) at 00:00:00 can be calculated from the Modified Julian Day (MJD) as follows:
NTP(s) = (MJD-15020) * (24*60*60)
where 15020 is the MJD on January 1, 1900 (the NTP epoch)
NTP(s) on January 1, 2000 00:00:00 UTC (MJD = 51544) is 3155673600 (0xBC17C200)
Epoch Time has a microsecond precision, and this precision can be achieved by using the most sig nificant 32 bits of the fractional portion (NTP(frac32)). Conversion between the 128-bit NTP timestamps and a UTC Epoch Time in Microseconds is as follows:
UTC Epoch Time = (NTP(s) – 0xBC17C200)*10^6 + ((NTP(frac32)*10^6) / 2^32) where all numbers are treated as unsigned 64-bit integers and the division is integer division.
7.18.2.4. Epoch Time in Seconds
This type has the same semantics as Epoch Time in Microseconds, except that:
- the value encodes an offset in seconds, rather than microseconds;
- the value is encoded as an unsigned 32-bit scalar, rather than 64-bit.
This type is employed where compactness of representation is important and where the resolution of seconds is still satisfactory.
7.18.2.5. POSIX Time in milliseconds
This type represents an offset, in milliseconds, from the UNIX epoch (1970-01-01 00:00:00 UTC), encoded as an unsigned 64-bit scalar value.
This type is employed for compatibility reasons.
7.18.2.6. System Time in microseconds
System time in microseconds is an unsigned 64-bit value representing the number of microseconds since boot.
7.18.2.7. System Time in milliseconds
System time in milliseconds is an unsigned 64-bit value representing the number of milliseconds since boot.
This type is employed for compatibility reasons.
7.18.2.8. Percentage units 1%
A Percentage is an unsigned 8-bit value representing percent with a resolution of 1%. The range is from 0 (0%) to 100 (100%).
7.18.2.9. Percentage units 0.01%
A Percentage 100ths is an unsigned 16-bit value representing percent with a resolution of 0.01%. The range is from 0 (0.00%) to 10000 (100.00%).
7.18.2.10. Fabric-Index
This is an index that maps to a particular fabric on the node, see Fabric-Index. It is used for:
- the accessing fabric index of an interaction
- the FabricIndex global field in fabric-scoped data
7.18.2.11. Node ID
A 64-bit ID for a node scoped and unique to a particular fabric as indicated by an accompanying fabric-index adjacent instantiation.
7.18.2.12. Group ID
A 16-bit ID for a group scoped to a particular fabric as indicated by an accompanying fabric index adjacent instantiation.
7.18.2.13. Endpoint Number
An unsigned number that indicates an instance of a device type.
7.18.2.14. Vendor ID
A Vendor ID.
Vendor IDs MAY be used as a prefix in a Manufacturer Extensible Identifier format.
7.18.2.15. Device Type ID
An identifier that indicates conformance to a device type.
Device Type IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
7.18.2.16. Cluster ID
An identifier that indicates conformance to a cluster specification.
Cluster IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
7.18.2.17. Attribute ID
An identifier that indicates an attribute defined in a cluster specification.
Attribute IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
7.18.2.18. Field ID
An identifier that indicates a field defined in a struct.
Field IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
7.18.2.19. Event ID
An identifier that indicates an Event defined in a cluster specification.
Event IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
7.18.2.20. Command ID
An identifier that indicates a command defined in a cluster specification.
Command IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
7.18.2.21. Action ID
An identifier that indicates an action as defined in the Interaction Model specification.
7.18.2.22. Transaction ID
An identifier for a transaction as defined in the Interaction Model specification, see Transaction ID.
7.18.2.23. Entry Index
This is an index for a list data type.
7.18.2.24. Status Code
An enumeration value that means a success or error status. A status code is indicated as a response to an action in an interaction (see Interaction Model).
A status code SHALL be one of:
- a common status code from the set defined in the Interaction Model status code table.
- a cluster status code that is scoped to a particular cluster
The following table defines the enumeration ranges for status codes.
Status Code Range | Description |
0x00 | common status code: SUCCESS |
0x01 | common status code: FAILURE |
0x02 to 0x10 | cluster scoped status codes |
0x70 to 0xCF | other common status codes defined in Interac tion Model Status Code Table. |
Status codes in an undefined range, or status codes undefined within a range are reserved and SHALL NOT be indicated.
7.18.2.25. Priority
This is an enumeration of priority used to tag events and possibly other data. The data type does not define any particular ordering among the values. Specific uses of the data type may assign semantics to the values that imply an ordering relationship.
Value | Priority | Description |
0 | DEBUG | Information for engineering debugging/troubleshooting |
Value | Priority | Description |
1 | INFO | Information that either drives customer facing features or pro vides insights into device func tions that are used to drive ana lytics use-cases |
2 | CRITICAL | Information or notification that impacts safety, a critical func tion, or continued operation |
7.18.2.26. Data Version
An unsigned number that indicates a Data Version.
7.18.2.27. Event Number
An unsigned number that indicates an Event instance.
7.18.2.28. Character String
The character string data type is derived from an octet string. The octets SHALL be characters with UTF-8 encoding. An instance of this data type SHALL NOT contain truncated code points.
If at least one of the code points within the string has value 31 (0x1F), which is Unicode INFORMATION SEPARATOR 1 and ASCII Unit Separator, then any client making use of the string SHALL only consider the code points that appear before the first INFORMATION SEPARATOR 1 as being the textual informa tion carried by the string. The remainder of the character string after a first INFORMATION SEPARATOR 1 is reserved for future use by this specification.
Note that the character string type is a bounded sequence of characters whose size bound format is not specified in the data model, but rather a property of the underlying encoding. Therefore, no assumptions are to be made about the presence or absence of a length prefix or null-terminator byte, or other implementation considerations.
It is RECOMMENDED to define constraints on the maximum possible string length.
7.18.2.29. IP Address
Either an IPv4 or an IPv6 address as defined below.
7.18.2.30. IPv4 Address
The IPv4 address data type is derived from an octet string. The octets SHALL correspond to the four octets in network byte order that comprise an IPv4 address represented utilizing quad-dotted nota tion.
Examples of encoding:
- Address 168.2.235 → C0A802EB
- Address 4.200.75 → 0A04C84B
7.18.2.31. IPv6 Address
The IPv6 address data type is derived from an octet string. The octets SHALL correspond to the full 16 octets that comprise an IPv6 address as defined by RFC 4291. The octets SHALL be presented in network byte order.
Examples of encoding:
- Address 2001:DB8:0:0:8:800:200C:417A → 20010DB80000000000080800200C417A
- Address 2001:0DB8:1122:3344:5566:7788:99AA:BBCC → 20010DB8112233445566778899AABBCC
7.18.2.32. IPv6 Prefix
The IPv6 prefix data type is derived from an octet string. The octets SHALL be encoded such that:
- The first octet SHALL encode the prefix length, in bits, in the range of 0 to
- A value of 0 indicates an absent/invalid
- The subsequent octets SHALL encode the contiguous leftmost bits of the prefix, in network byte order, with left justification, such that the first bit of the prefix is in the most significant bit of the first octet. Encoding SHOULD use the least number of bytes to encode the prefix but MAY include unused trailing
Examples of encoding:
- Preferred minimal encoding: Prefix 2001:0DB8:0:CD30::/60 → 9 octets → 3C20010DB80000CD30
- Preferred minimal encoding: Prefix 2001:0DB8:BB00::/40 → 6 octets → 2820010DB8BB
- Allowed non-minimal encoding: Prefix 2001:0DB8:BB00::/40 → 7 octets → 2820010DB8BB00
7.18.2.33. Hardware Address
The Hardware Address data type SHALL be either a 48-bit IEEE MAC Address or a 64-bit IEEE MAC Address (e.g. EUI-64). The order of bytes is Big-Endian or display mode, where the first byte in the string is the left most or highest order byte.
7.19. Manufacturer Specific Extensions
This section covers Manufacturer Specific (MS) extensions and how they are supported by identi fiers, paths, wildcards, discoverability, etc.
7.19.1. Manufacturer Extensible Identifiers
A Manufacturer Extensible Context (MEC) contains a collection of items which MAY be extended by manufacturers. Each item in a MEC has a source which is either Standard, Scoped or a particular Manufacturer Code (MC).
- A Standard source references definitions described in Matter standard
- A Scoped source adopts the same source as that of the cluster that contains its
- An MC-based source references manufacturer-specific
Table 63. MEC Example
Context | Source | Items |
MEC |
Standard |
Item 0 |
Item 1 | ||
Item 2 | ||
Scoped |
Item 0 | |
Item 1 | ||
Item 2 | ||
MC 1 |
Item 0 | |
Item 1 | ||
Item 2 | ||
MC 2 |
Item 0 | |
Item 1 | ||
Item 2 |
A Manufacturer Extensible Identifier (MEI) identifies an item in an MEC and has no meaning beyond the context of that MEC.
7.19.2. Manufacturer Extensible Identifier (MEI)
An MEI has the following format:
Table 64. MEI Format
Field | Prefix | Suffix |
Description |
Encodes a source (standard, scoped or a particu lar MC) |
Encodes an item’s key (in context of MEC + source) |
Width | 16-bit | 16-bit |
Bit Positions | 31..16 | 15..0 |
The MEI permits encoding of ~65K keys in the suffix.
A specific MEI MAY only permit certain combinations of the above.
7.19.2.1. Encoding
The MEI prefix encodes the source Vendor ID and follows the same rules as outlined in Table 1, “Vendor ID Allocations”, with the exception that a Scoped source is encoded using the same prefix as a Standard source. Consequently, a given MEI SHALL NOT permit both Standard and Scoped
source types given the ambiguity in telling them apart. Given the above, the encoding is as follows:
Table 65. MEI Prefix
Prefix | Source |
0x0000 | Standard OR Scoped |
0x0001 – 0xFFF0 | Manufacturer Code as per CSA Manufacturer Code Database |
0xFFF1 – 0xFFF4 | Test Vendor MC |
The MEI suffix encodes a key as follows:
Table 66. MEI Suffix
Suffix | Item |
0x0000 – 0xFFFE | Item 0 to 65534 |
7.19.2.2. Data Model Types
The following data model types SHALL be represented as MEIs:
Table 67. MEI Suffix
Type | Permitted Source Types | Suffix Range |
Device Type ID | Standard or MC | 0x0000 – 0xBFFF |
Cluster ID | Standard or MC |
Standard Cluster: 0x0000 – 0x7FFF |
Manufacturer-Specific Cluster: 0xFC00 – 0xFFFE |
||
Attribute ID (Global) | Standard | 0xF000 – 0xFFFE |
Attribute ID (Non-Global) | Scoped or MC | 0x0000 – 0x4FFF |
Event ID | Scoped or MC | 0x00 – 0xFF |
Command ID | Scoped or MC | 0x00 – 0xFF |
Field ID (Global) | Standard | 0xE0 – 0xFE |
Field ID (Non-Global) | Scoped or MC | 0x00 – 0xDF |
Command ID | Scoped or MC | 0x00 – 0xFF |
For example:
Table 68. MEI Decoding Example
MEI | Description |
0x0000_0000 | Standard/Scoped item 0 |
MEI | Description |
0x0000_0001 | Standard/Scoped item 1 |
0x0000_0002 | Standard/Scoped item 2 |
0x0000_FFFE | Standard/Scoped item 65534 |
0x0001_0000 | MC 1 item 0 |
0x0001_0001 | MC 1 item 1 |
0x0001_0002 | MC 1 item 2 |
0x0001_FFFE | MC 1 item 65534 |
0x0002_0000 | MC 2 item 0 |
0x0002_0001 | MC 2 item 1 |
0x0002_0002 | MC 2 item 2 |
0x0002_FFFE | MC 2 item 65534 |
0xFFFF_0000 | Invalid |
7.19.3. Manufacturer Extensions
A manufacturer extensible context MAY be extended with items from any manufacturer. Such extensions SHALL be identified using an MEI with prefix for that particular manufacturer, and SHALL NOT use a standard/scoped prefix.
There are further constraints:
- MS extensions SHALL only be permitted on standard clusters or another existing MS extension of a standard cluster from another
- An extended cluster MAY instantiate a struct definition defined in the standard
- A struct that has been extended with new fields SHALL have the same definition in all instances of that struct within a given cluster
- A defined element (struct, command, event) SHALL NOT be re-used or instantiable in a different cluster (except in extended clusters)
This is illustrated by the following hypothetical scenario.
Suppose the standard provides cluster ABCD which contains related counters and their recent statis tics. The counter values are available as attributes 1 and 2, which are reset daily. The statistics are grouped into a SummarizedStats struct, available as attributes 3 and 4, and track summary statistics for each counter over a recent period (last month). Each instance of the statistics struct has fields 1, 2, and 3, for minimum, maximum, and mean values for that period.
Suppose manufacturer A extends the standard cluster with additional statistics (red below). A adds lifetime counts as attributes 0x000A_0001 and 0x000A_0002, which are never reset. A also adds quar tiles Q1, Q2, and Q3 to the standard SummarizedStats struct, as fields 0x000A_0001, 0x000A_0002, and 0x000A_0003. These quartiles are available for all existing instances of the standard struct, such as standard attributes 3 and 4.
Suppose manufacturer B, a partner of manufacturer A, extends the standard cluster further (green below). B wishes to add instances of the standard statistics struct, as attributes 0x000B_0001 and 0x000B_0002, to track summary statistics for each counter, over a different recent period (last year
instead of last month). Since manufacturer A had already extended the standard statistics struct, the instantiation of that struct will contain both standard and A’s fields. If B desires to create a new version of that statistics struct without A’s changes, it would have to declare a new definition of that struct with new fields in it.
Suppose manufacturer C, a partner of manufacturers B and A, adds a MS cluster 0x000C_FC01 (blue below) that doesn’t extend an existing standard cluster. This cluster has a sensor available as attribute 0x0000_0001 of type SensorStats, which has fields 0x0000_0001, 0x0000_0002, and 0x0000_0003, for the sensor’s value, precision, and accuracy. Since Attribute and Field IDs are
defined using the ‘Scoped’ source type, the prefix of ‘0000’ implicitly equates to the same source as the cluster it is defined in, i.e Manufacturer C. C also wishes to add an instance of the Summarized Stats struct as attribute 0x000C_0002, to track summary statistics for the sensor over a recent period
(last hour). Since this cluster does not extend any previous cluster, it cannot instantiate any of the extended versions of the SummarizedStats struct as defined previously. Instead, C will have re-define that structure definition within its cluster definition and use it.
Table 69. Hypothetical Standard Cluster
Endpoint | Cluster | Attribute | Attribute Description | Struct Field | Field Description |
0x0001 | 0x0000_ABCD | 0x0000_0001 | Counter 1 current value (reset daily) | – | – |
0x0000_0002 | Counter 2 current value (reset daily) | – | – | ||
0x0000_0003 | Counter 1 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x0000_0004 | Counter 2 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count |
Table 70. Hypothetical Manufacturer A Extension Scenario
Endpoint | Cluster | Attribute | Attribute Description | Struct Field | Field Description |
0x0001 | 0x0000_ABCD | 0x0000_0001 | Counter 1 current value (reset daily) | – | – |
0x0000_0002 | Counter 2 current value (reset daily) | – | – | ||
0x0000_0003 | Counter 1 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x000A_0001 | Q1 count | ||||
0x000A_0002 | Q2 count | ||||
0x000A_0003 | Q3 count | ||||
0x0000_0004 | Counter 2 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x000A_0001 | Q1 count | ||||
0x000A_0002 | Q2 count | ||||
0x000A_0003 | Q3 count |
Table 71. Hypothetical Manufacturer B Extension of A Scenario
Endpoint | Cluster | Attribute | Attribute Description | Struct Field | Field Description |
0x0001 | 0x0000_ABCD | 0x0000_0001 | Counter 1 current value (reset daily) | – | – |
0x0000_0002 | Counter 2 current value (reset daily) | – | – | ||
0x0000_0003 | Counter 1 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x000A_0001 | Q1 count | ||||
0x000A_0002 | Q2 count | ||||
0x000A_0003 | Q3 count | ||||
0x0000_0004 | Counter 2 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x000A_0001 | Q1 count | ||||
0x000A_0002 | Q2 count | ||||
0x000A_0003 | Q3 count | ||||
0x000B_0001 | Counter 1 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x000A_0001 | Q1 count | ||||
0x000A_0002 | Q2 count | ||||
0x000A_0003 | Q3 count | ||||
0x000B_0002 | Counter 2 (period = month) | 0x0000_0001 | Min count | ||
0x0000_0002 | Max count | ||||
0x0000_0003 | Mean count | ||||
0x000A_0001 | Q1 count | ||||
0x000A_0002 | Q2 count | ||||
0x000A_0003 | Q3 count |
Table 72. Hypothetical Manufacturer C Custom Cluster
Endpoint | Cluster | Attribute | Attribute Description | Struct Field | Field Description |
0x0001 | 0x000C_FC01 | 0x0000_0001 | Sensor 1 Stats | 0x0000_0001 | Value |
0x0000_0002 | Precision | ||||
0x0000_0003 | Accuracy | ||||
0x0000_0002 | Counter 1 (period = hour ) | 0x0000_0001 | Min daily count | ||
0x0000_0002 | Max daily count | ||||
0x0000_0003 | Mean daily count |
Note the following potential combinations of path components:
Table 73. Hypothetical Manufacturer Extension Path Examples
Description | |
0x0001/0x0000_ABCD/0x0000_0003/0x0000_0001 |
Cluster ID = Standard, Attribute ID = Scoped, Field ID = Scoped: Counter 1 min value |
0x0001/0x0000_ABCD/0x0000_0003/0x000A_0001 |
Cluster ID = Standard, Attribute ID = Scoped, Field ID = MS(A): Counter 1 Q1 daily count over last month |
0x0001/0x0000_ABCD/0x000B_0001/0x0000_0001 |
Cluster ID = Standard, Attribute ID = MS(B), Field ID = Scoped: Counter 1 Q1 daily count over last year |
0x0001/0x0000_ABCD/0x000B_0001/0x000A_0001 |
Cluster ID = Standard, Attribute ID = MS(B), Field ID = MS(A): Counter 1 Q1 daily count over last year |
0x0001/0x000C_FC01/0x0000_0001/0x0000_0002 |
Cluster ID = MS(C), Attribute ID = Scoped, Field ID = Scoped: Sensor 1 precision |
0x0001/0x000C_FC01/0x0000_0002/0x0000_0003 |
Cluster ID = MS(C), Attribute ID = Scoped, Field ID = Scoped: Counter 1 (period = hour) Mean |
0x0001/0x000C_FC01/0x0000_FFFD | Cluster ID = MS(C), Attribute ID = Standard: Cluster revision |
7.19.4. Discoverability
The Descriptor Cluster reports the device types and clusters on a node’s endpoints, whether they are standard or from a particular manufacturer.
For example, if a node supports cluster 0x000C_ABCD on endpoints 1 and 2, that information is avail able in the Descriptor Cluster.
The Read Interaction provides a means to read the contents of all or part of a cluster.
For example, reading cluster 0x0000_ABCD on endpoint 1 might return mandatory attribute
0x0000_0001, optional attribute 0x0000_0009, and MS attributes 0x000A_0001 and 0x000A_0002.