페이지 선택
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Search in pages

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:

  1. Read the counter value at start-up.
  2. 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
  3. 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.

ID Name Type Constraint Quality
0 Year int16 -1000 to 3000  
1 Summer­ Months list[Month­ Number] max 12 N

 

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.

Name Type Constraint Quality
Month­ NameString string 3 F
MonthNumber uint8 1 to 12  

 

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  
 

 

ID Name Type Constraint Quality
0 MonthNames list[string] 12[3] N … .

 

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:

 

  1. 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
  2. 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.

 

 

 

Adsense

 

 WiFi IoT Module

 

www.mxchip.com

 

 

 Bluetooth Module

www.feasycom.com

 

 

 5G/LTE/CAT-M1/NB-IoT

 

www.simcom.com

 

Viewed Page List