Chapter 10. Interaction Model Encoding Specification
10.1. Overview
This specification details the encoding of the Interaction Model (IM) in the Matter TLV format.
Specifically, it details the encoding of the application payload for Matter messages that map to the Interaction Model. The details of the message header are described in Section 4.4, “Message Frame Format” and out of scope of this document.
10.2. Messages
10.2.1. IM Protocol Messages
Each Action in the IM specification SHALL be mapped to a message with a unique Protocol Opcode, namespaced under the PROTOCOL_ID_INTERACTION_MODEL Protocol ID.
- Vendor ID = 0x0000 (Matter Common)
- Protocol ID = PROTOCOL_ID_INTERACTION_MODEL
Protocol Opcode | Action | Message |
0x01 | Status Response | StatusResponseMessage |
0x02 | Read Request | ReadRequestMessage |
0x03 | Subscribe Request | SubscribeRequestMessage |
0x04 | Subscribe Response | SubscribeResponseMessage |
0x05 | Report Data | ReportDataMessage |
0x06 | Write Request | WriteRequestMessage |
0x07 | Write Response | WriteResponseMessage |
0x08 | Invoke Request | InvokeRequestMessage |
0x09 | Invoke Response | InvokeResponseMessage |
0x0A | Timed Request | TimedRequestMessage |
10.2.2. Common Action Information Encoding
Every action SHALL encode the fields specified in Section 8.2.5.1, “Common Action Information”. The methods for encoding Common Action Information fields are:
- As a field in the message header
- As a context tagged field in the action payload
For every field appearing in TLV-encoded data described by the schemas of the following sections,
and where a context-specific tag is used, any context-specific tag not listed in a given schema SHALL be reserved for future use and SHALL be silently ignored by clients and servers if seen in a payload.
10.2.2.1. Message Header Encoded Action Information
The following Common Action Information fields are encoded into the message header:
Header Field | Type | Description |
Message Exchange ID | 16-bit integer | Used to convey the Transaction ID |
Source Node ID | 64-bit integer | Node ID of the source that gen erated the transaction |
Destination ID | 64-bit integer | Either a Node ID or Group ID is encoded in here depending on what the IM indicates |
Protocol ID | 32 bits |
The protocol to which this mes sage belongs; all messages in this spec SHALL use the PROTO COL_ID_INTERACTION_MODEL Proto col ID |
Protocol OpCode | 8 bits | The specific message type |
10.2.2.2. Context Tag Encoded Action Information
The following Common Action Information fields are encoded as context tagged fields in the action message payload. All action messages defined in Section 10.6, “Message Definitions” SHALL include these tagged fields:
Common Action Field | Context Tag |
InteractionModelRevision | 0xFF |
10.2.3. Chunking
Chunking is the act of splitting an Action that contains attribute/event data, specifically ReportData and WriteRequest actions, into multiple messages at logical boundaries due to the size limitations imposed by IPv6 for UDP packets (see Section 4.4.4, “Message Size Requirements” for more details).
Since attribute/event data within Actions are already organized into a series of AttributeDataIBs (for attributes) and EventDataIBs for event records, chunking entails maximally packing these information blocks (IBs) into a series of ‘data’ messages.
To ensure in-order delivery of a chunked set of IBs, each data message requires a response before the next data message can be sent. For ReportDataMessage and WriteRequestMessage, a StatusRe sponseMessage and WriteResponseMessage are the respective response messages.
A MoreChunkedMessages flag SHALL be set on every data message except the last to convey to the
receiver possible delivery of more chunked messages within a given Action. This is specified in the WriteRequestMessage and ReportDataMessage.
While most data types can be easily encoded in this scheme to fit within a message, the fact that lists can be of variable, and arbitrary, length can lead to complications. Specific strategies to encode lists that are chunking friendly are provided in Section 10.5.4.3.1, “Lists”.
10.2.4. Transaction Flows
10.2.4.1. Read (Success)
Figure 66. Read message flow
10.2.4.2. Read (Server Error)
Figure 67. Read message with server-side error flow
10.2.4.3. Read (Client Error)
Figure 68. Read message with client-side error flow
10.2.4.4. Write (Success)
Figure 69. Write message flow
10.2.4.5. Write (Server Error)
Figure 70. Write message with server-side error flow
10.2.4.6. Subscribe (Success)
Figure 71. Subscription flow
10.2.4.7. Subscribe (Server Error)
Figure 72. Subscription with server-side error flow
10.2.4.8. Subscribe (Client Error)
Figure 73. Subscription with client-side error flow
10.3. Data Types
The IM specification defines a number of schema data types that are usable in a given cluster schema definition.
This section will outline their encoding onto TLV wire types, and their specific representations.
Class | Schema Data Type | TLV Type |
Analog | uint8, uint16, uint24, uint32, uint40, uint48, uint56, uint64 | Unsigned Integer (width is selected automatically depend ing on data value) |
int8, int16, int24, int32, int40, int48, int56, int64 | Signed Integer (width is selected automatically depend ing on data value) | |
float32 | Floating Point Number, 4-byte value | |
float64 | Floating Point Number, 8-byte value |
Class | Schema Data Type | TLV Type |
Discrete | enum8, enum16 | Unsigned Integer (width is selected automatically depend ing on data value) |
data8, data16, data32, data64 | Unsigned Integer (width is selected automatically depend ing on data value) | |
map8, map16, map32, map64 | Unsigned Integer (width is selected automatically depend ing on data value) | |
boolean | Boolean | |
Composite | string | UTF-8 string (length is selected automatically depending on data value) |
octstr | TLV octet string | |
Collection | list | TLV array |
struct | TLV structure |
10.3.1. Analog – Integer
All signed integer schema types SHALL be encoded using the TLV signed integer type. The specific TLV element type (1-byte, 2-byte, 4-byte and 8-byte signed integer types) SHALL be selected auto matically at runtime depending on the actual value.
In this regard, the actual width of the over-the-wire type can be narrower than the width specified in schema.
E.g. a 32-bit value defined in schema will be encoded to a 1-byte TLV signed integer type if the value doesn’t exceed (-128 to +127).
Similarly, all unsigned integer schema types SHALL be encoded using the TLV unsigned integer type.
10.3.2. Analog – Floating Point
Both single and double precision floating point analog schema types SHALL be encoded using equivalent TLV floating point types as well.
10.3.3. Discrete – Enumeration
Enumerations SHALL be encoded using the TLV unsigned integer type, with the width selected automatically at runtime based on the actual value.
10.3.4. Discrete – Bitmap
Bitmaps SHALL be encoded using the TLV unsigned integer type, with the width selected automati cally at runtime based on the actual value.
10.3.5. Composite – String
While strings are a derived data type, they SHALL be encoded using the TLV UTF-8 string type.
10.3.6. Composite – Octet String
Octet strings SHALL be encoded using TLV Byte Strings.
10.3.7. Collection – Struct
Structure types in schema SHALL be encoded using the TLV structure type.
10.3.8. Collection – List
The entirety of a list SHALL be encoded as a TLV array. A list index SHALL start at 0.
Lists shall have a maximum size of 65535 elements (216-1).
10.3.9. Derived Types
All derived types (with the exception of strings) SHALL be encoded according to their base type.
10.3.10. Field IDs
Field IDs SHALL be encoded as:
- A context tag when the MEI prefix encodes a standard/scoped
- A fully-qualified profile-specific tag when the MEI prefix encodes a manufacturer code. The Vendor ID SHALL be set to the manufacturer code, the profile number set to 0 and the tag num ber set to the MEI
NOTE Support for encoding Field IDs with an MC source is provisional.
10.4. Sample Cluster
This section defines a sample cluster (with attributes, events, and commands) for illustrative pur poses; it SHALL NOT be interpreted as a real cluster.
10.4.1. Disco Ball Cluster
This example cluster controls an imaginary mirrored disco ball, for the express purpose of disco
dancing.
10.4.1.1. Revision History
The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
Revision | Description |
1 | Initial Release |
2 | Deprecated Off enum value in Rotate attribute |
3 | Added pattern list feature |
4 | Added Name attribute |
5 | Added Reverse feature |
6 | Updated columns from Data & Interaction Model specs |
7 | Deprecated Party feature |
10.4.1.2. Classification
Hierarchy | Role | Scope | PICS Code |
Base | Application | Endpoint | DISCO |
- Cluster ID
ID | Name |
0x3456 | Disco Ball |
- Features
This cluster SHALL support the FeatureMap bitmap attribute as defined below.
Bit | Code | Feature | Conformance | Summary |
0 | PTY | Party | D | Deprecated fea ture |
1 | AX | Axis | M | Allows the disco ball rotational axis to change |
2 | WBL | Wobble | M | Allows the disco ball to wobble on its axis as speed (dependent on Axis) |
Bit | Code | Feature | Conformance | Summary |
3 | PAT | Pattern | M | Supports a list of patterns to cycle through automati cally |
4 | STA | Statistics | M | Supports a request to statistics |
5 | REV | Reverse | P, M | Supports a Reverse command and counterclock wise rotation |
Spec Writer Note Describe features each in a separate section (if needed). |
10.4.1.5. Data Types
- RotateEnum
This data type is derived from enum8.
Value | Name | Summary | Conformance |
0 | Off | Deprecated | D* |
1 | Clockwise | Rotation is currently clockwise | M |
2 | CounterClockwise | Rotation is currently counterclockwise | REV |
*Spec Writer Note “D” means deprecated. |
Clockwise Value
This value SHALL indicate that the disco ball is rotating in the clockwise direction
CounterClockwise Value
This value SHALL indicate that the disco ball is rotating in the counterclockwise direction
Spec Writer Note Description sections are optional and should only be present, if additional details are needed for a given enum value |
- PatternStruct
This indicates a pattern of operation for a running disco ball.
Access Quality: Fabric Scoped | |||||||
ID | Name | Type | Constraint | Quality | Default | Access | Confor mance |
0 | Duration | uint16 | all | 0 | RW | M | |
1 | Rotate | Rota teEnum | desc | X* | null* | RW | M |
2 | Speed | uint8 | max 200 | X | null | RW | M |
3 | Axis | uint8 | max 90 | X | null | RW | AX | WBL |
4 | Wobble Speed | uint8 | max 200 | X | null | RW | WBL**, O |
5 | Passcode | string | all | X | null | RWS | M |
*Spec Writer Note Nullable data (“X”) means that in some cases, the data can be null. Null data meaning must be defined (as it is below). **Conformance “WBL, O” means mandatory for WBL feature, otherwise optional. |
Duration Field
This SHALL indicate the time in seconds for the disco ball to perform the pattern.
Rotate Field
This SHALL indicate the rotation direction or null to not change the direction.
Speed Field
This SHALL indicate the speed of the rotation, or null to not change the speed.
Axis Field
This SHALL indicate the angle of the axis of rotation, or null to not change the angle.
WobbleSpeed Field
This SHALL indicate the speed of the axis wobble, or null to not change the speed.
Passcode Field
An optionally specified passcode that if present, needs to always be provided in the Pattern Request
command to successfully invoke this pattern.
10.4.1.6. Status Codes
Listed below are cluster specific status codes only indicated for a particular instance of this cluster.
Status Code | Value | Summary |
0x02* | UNSUPPORTED_PATTERN | The movement pattern is unsupported on the device even though all values are within constraints |
*Spec Writer Note Start at 2, after the global error status values of 0 for SUCCESS and 1 for FAILURE. |
10.4.1.7. Attributes
Spec Writer Note Attributes are supported by the server cluster only. |
ID | Name | Type | Constraint | Quality | Default | Access | Confor mance |
0x0000 | Run | bool | all* | 0 | R V T* | M | |
0x0001 | Rotate | Rota teEnum | desc* | 0 | R V | M | |
0x0002 | Speed | uint8 | 0 to 200* | 0 | R V | M | |
0x0003 | Axis | uint8 | 0 to 90 | 0 | RW VO | AX | WBL | |
0x0004 | Wobble Speed | uint8 | 0 to 200 | 0 | RW VO | WBL | |
0x0005 | Pattern | list[Pat ternStruct] | max 16* | 0 | RW M | PAT | |
0x0006 | Name | string | max 16 | N* | 0 | RW VM | P, O |
*Spec Writer Note Constraint • “all” means all possible values. • “desc” means see attribute description for constraints on attribute. • “X to Y” means a value range from X=minimum to Y=maximum value. • “max X” means range or maximum number of entries for a list or bytes for a string type derived from octstr. |
Quality • “N” indicates the read only, write only or read & write value is non-volatile across restarts. • “F” indicates that the read-only value is static (fixed) and and will not change in the future (like the ClusterRevision attribute). • If there is no “N” or “F” then the value is volatile such that the value of the attribute may change at some point in the future. Access • Access column indicates R=Read Only, RW=Read Write, R*W=Read [Write}, T=Timed Write, View=Read, Operate=Write, Manage=Write, Administer=Write for ACL processing. Conformance Any attribute that is “M” is part of the base mandatory feature set. “O” is purely optional. To support the Axis feature any attribute with “AX” conformance must be supported (see Data Model). To support the Wobble feature any attribute with WBL conformance must be sup ported (see Data Model). “AX | WBL” means either feature mandates this attribute. If neither are true, then the attribute is not allowed. “AX & WBL” would require both features sup ported to mandate. “[PAT]” means optional for Pattern feature. “P, O” means provisional oth erwise optional (after its not provisional). See FeatureMap in Data Model specification. |
- Run Attribute
This SHALL indicate if the disco ball is operating. If the Run attribute is 0, then the Speed, Rotate and WobbleSpeed attributes SHALL be 0.
- Rotate Attribute
This SHALL indicate the direction of rotation either clockwise or counterclockwise.
- Speed Attribute
This SHALL indicate the speed of the disco ball in revolutions per minute.
- Axis Attribute
This SHALL indicate the tilt of the axis of the disco ball, in degrees.
- WobbleSpeed Attribute
This SHALL indicate the speed of the wobble rotation in revolutions per minute.
- Pattern Attribute
This is an ordered list of entries. Entries may be appended or prepended, but not inserted. This list of patterns SHALL be used to operate the disco ball when the Pattern Request command is invoked.
- Name Attribute
This SHALL indicate a display name.
10.4.1.8. Commands
Spec Writer Note Commands are supported by the client & server, but always initiated by the client. |
ID | Name | Direction | Response** | Access | Conformance |
0x00 | Start Request | client ⇒ server | Y | O T* | M |
0x01 | Stop Request | client ⇒ server | Y | O | M |
0x02 | Reverse Request | client ⇒ server | Y | O | REV |
0x03 | Wobble Request | client ⇒ server | Y | O | WBL |
0x04 | Pattern Request | client ⇒ server | Y | M | PAT |
0x05 | Stats Request | client ⇒ server | Stats Response** | O | STA |
0x06 | Stats Response | client ⇐ server | N | O | STA |
*Spec Writer Note Commands are operable (O) with Invoke. Commands are operable with Timed (T) Invoke only. **Spec Writer Note “Stats Request” command has a “Stats Response” command. “Y” means that the command requires just a status in the Invoke Response. “N” means no response required (most response commands do not need a response). |
- Start Request Command
Upon receipt, this SHALL start the disco ball rotating using the data as follows:
ID | Name | Type | Constraint | Quality | Default | Confor mance |
0 | Speed | uint8 | max 200 | MS* | M | |
1 | Rotate | RotateEnum | desc | Clockwise | O |
*Spec Writer Note “ms” means Manufacturer Specific. |
Speed Field
This SHALL indicate the rotation speed.
Rotate Field
This SHALL indicate the rotation direction.
- Pattern Request Command
ID | Name | Type | Constraint | Quality | Default | Confor mance |
0 | Passcode | string | max 6 | empty | M |
Passcode Field
If the passcode field is an empty string, this SHALL start the disco ball rotating using unprotected (i.e patterns that have no passcode) pattern list entries in sequence to control the disco ball. When the final entry in the list is processed the sequence SHALL restart at the first entry.
If the passcode field is not an empty string, only the patterns that correspond to the provided pass code SHALL be invoked.
- Stop Request Command
Upon receipt, this SHALL stop the disco ball rotating, and SHALL set the Run, Speed and Rotate attributes to 0.
- Reverse Request Command
Upon receipt, this SHALL reverse the direction of the disco ball rotation. This command MAY gener ate an error response of UNSUPPORTED_PATTERN.
- Wobble Request Command
Upon receipt, this SHALL wobble the disco ball on its axis at the speed in the WobbleSpeed attribute. This command MAY generate an error response of UNSUPPORTED_PATTERN.
- Stats Request Command
Upon receipt, this SHALL generate a Stats Response command.
- Stats Response Command
This command SHALL be generated in response to a Stats Request command. The data for this com mand SHALL be as follows:
ID | Name | Type | Constraint | Quality | Default | Confor mance |
0 | LastRun | uint32 | all | 0 | M | |
1 | Patterns | uint32 | all | 0 | [PAT] * |
*Spec Writer Note Patterns field is an optional only for the PAT feature. |
Last Run
This SHALL indicate the duration in seconds for the last time the disco ball was run.
Patterns
This SHALL indicate the number of pattern changes from the Pattern attribute attribute within the last run time.
10.4.1.9. Events
Spec Writer Note Events are supported by the server cluster only. |
ID | Name | Priority | Access | Conformance |
0x00 | Started | INFO | V* | M |
0x01 | Stopped | INFO | V | M |
0x02 | PatternChange | INFO | V | [PAT] |
*Spec Writer Note All events are viewable (V). |
- Started Event
This event SHALL be generated, when the Run attribute changes from false to true. There is no data for this event.
- Stopped Event
This event SHALL be generated, when the Run attribute changes from true to false. There is no data for this event.
- Pattern Change Event
This event SHALL be generated when the Rotate, Speed, or WobbleSpeed attributes are written or changed locally as the result of processing the Pattern attribute list.
ID | Name | Type | Constraint | Quality | Default | Confor mance |
0 | PrevPattern | Pattern Struct | X | null | M | |
1 | CurPattern | Pattern Struct | M | |||
2 | NextPattern | Pattern Struct | X | null | M |
PrevPattern Field
This field SHALL be the previous pattern run. If there is no previous pattern, then PrevPattern SHALL be null.
CurPattern Field
This field SHALL be the current pattern being run.
NextPattern Field
This field SHALL be the next in the pattern list. If there is no next pattern, the NextPattern event field SHALL be null.
10.4.2. Super Disco Ball Cluster
This is derived* from the Disco Ball cluster, with overrides for qualities and conformance.
*Spec Writer Note This is an example of a derived cluster, where only stricter conformance overrides, and the Name attribute gets a longer allowed length. If both the Disco Ball and Super Disco Ball server clusters are on the same endpoint, they would represent a singleton instance of a cluster. This allows legacy clients implemented before the Super Disco Ball was specified to still interoperate. Blank column entries define no change to the qualities. |
10.4.2.1. Revision History
The global ClusterRevision attribute value SHALL be the highest revision number in the table below.
Revision | Description |
1 | Initial Release |
10.4.2.2. Classification
Hierarchy | Role | Context | PICS Code |
Disco Ball | Application | Endpoint | SUPDISC |
- Cluster Identifiers
Identifier | Name |
0xBBCC | Super Disco Ball |
- Features
Bit | Feature | Conformance |
0 | Axis | M |
1 | Wobble | M |
2 | Pattern | M |
3 | Statistics | M |
4 | Reverse | M |
- Attributes
ID | Name | Type | Constraint | Quality | Default | Access | Confor mance |
0x0006 | Name | string | max 32 | M |
- Events
ID | Name | Priority | Access | Conformance |
0x02 | PatternChange | M |
10.5. Information Blocks
These are elements that may apply to multiple message types, and are defined in a common way to permit re-use as a definition. Unless stated otherwise, these correspond to their identically named counterparts in the Interaction Model Specification.
10.5.1. Tag Rules
Unless otherwise noted, all context tags SHALL be emitted in the order as defined in the appropri ate specification. This is done to reduce receiver side complexity in having to deal with arbitrary order tags.
10.5.2. AttributePathIB
TLV Type: List | |||||
Tag | Comments | Tag Type | Tag Number | TLV Type | Range |
EnableTagCom pression | Context Tag | 0 | bool | – | |
Node | Context Tag | 1 | Unsigned Int | 64 bits | |
Endpoint | Context Tag | 2 | Unsigned Int | 16 bits | |
Cluster | Context Tag | 3 | Unsigned Int | 32 bits | |
Attribute | Context Tag | 4 | Unsigned Int | 32 bits | |
ListIndex | Context Tag | 5 | Unsigned Int | 16 bits, nul lable |
- The contents of ClusterPathIB in the Interaction Model specification have been expanded here for encoding
- The ClusterPathIB Group field is omitted here (see Node field description).
- Maximum nesting is restricted to referencing a list element in an Consequently, the
NestedPath field is removed and replaced with a single ListIndex field.
10.5.2.1. EnableTagCompression
This tag is used to select between two different interpretations on the receiver when the Node, End point, Cluster, Attribute tags are omitted:
- When false or not present, omission of any of the tags in question (with the exception of Node) indicates wildcard
- When true, indicates the use of a tag compression scheme. In this case the value for any omitted tag SHALL be set to the value for that tag in the last AttributePathIB that had EnableTagCompres sion not present or set to false and was seen in a message that is part of the same interaction
model Action as the current message.
- The AttributePathIB the values end up coming from MAY appear in the same message (but earlier in it) as the current
- The values that come from the previous AttributePathIB MAY still be missing. In that case, with the exception of Node, they indicate wildcard
10.5.2.2. Node
- If the Group field is present in the IM representation, the Group ID is encoded in the DST field in the message header and elided from the encoding
- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server involved in the
10.5.2.3. Endpoint, Cluster
- Each of these tags can be The semantics of such omission depend on the value of
EnableTagCompression.
10.5.2.4. Attribute, ListIndex
- When EnableTagCompression is false or not present, they have the following semantics:
Attribute | ListIndex | Description |
Omitted | Omitted | Selects all attributes within the specified Node, Endpoint, Clus ter |
Present | Omitted | Selects a specific attribute within the specified Node, End point, Cluster. |
Present | Present | Selects a specific list item within a top-level attribute of type list. |
This does not allow expressing all possible paths defined in the interaction model. Only paths that can be expressed MAY be used.
- The ListIndex tag is nullable. The null value SHALL only be used when this AttributePathIB is used in an AttributeDataIB and indicates a list append operation. See Section 10.5.4.3.1, “Lists” for more
10.5.2.5. Examples
Select all attributes on a given cluster and endpoint:
AttributePath = [[ Endpoint = 10, Cluster = Disco Ball ]] |
Select all attributes in all clusters on a given endpoint:
Path = [[ Endpoint = 10 ]] |
Select all attributes in all clusters on the node:
Path = [[ ]] |
Select a specific attribute:
Path = [[ Endpoint = 10, Cluster = Disco Ball, Attribute = Axis ]] |
Select a specific item in a top-level list:
Path = [[ Endpoint = 10, Cluster = Disco Ball, Attribute = Pattern, ListIndex = 4 ]] |
Select all attributes in all clusters on a given endpoint on a proxied node:
Path = [[ Node = 0x18B430003020203, Endpoint = 10 ]] |
Tag Compression Example #1:
Path1 = [[ Node = 0x18B430003020203, Endpoint = 10, Cluster = Disco Ball, Attribute = Pattern, ListIndex = 3 ]] // Start tracking path elements. Path2 = [[ EnableTagCompression = true, ListIndex = 4 ]] // Node, Endpoint, Cluster, Attribute are re-used from Path1 Path3 = [[ EnableTagCompression = true, ListIndex = 5 ]] // Node, Endpoint, Cluster, Attribute are re-used from Path1 Path4 = [[ EnableTagCompression = true, Attribute = Axis ]] // Endpoint, Cluster are re-used from Path1 |
Tag Compression Example #2:
Path1 = [[ Node = 0x18B430003020203, Cluster = Disco Ball, Attribute = Pattern, ListIndex = 3 ]] // Endpoint is wildcard, start tracking path elements. Path2 = [[ EnableTagCompression = true, ListIndex = 4 ]] // Node, Endpoint (including wildcard), Cluster, Attribute are re-used from Path1 Path3 = [[ EnableTagCompression = true, ListIndex = 5 ]] // Node, Endpoint (including wildcard), Cluster, Attribute are re-used from Path1 |
Tag Compression Example #3:
Path1 = [[ Node = 0x18B430003020203, Endpoint = 10, Cluster = Disco Ball, Attribute = Pattern, ListIndex = 3 ]] // Start tracking path elements. Path2 = [[ EnableTagCompression = true, ListIndex = 4 ]] // Node, Endpoint, Cluster, Attribute are re-used from Path1 Path3 = [[ EnableTagCompression = true, ListIndex = 5 ]] // Node, Endpoint, Cluster, Attribute are re-used from Path1 Path4 = [[ Node = 0x18B430003020203, Endpoint = 20, Cluster = Disco Ball, Attribute = Axis ]] // Reset tracker variables Path5 = [[ EnableTagCompression = true, Attribute = Pattern, ListIndex = 5]] // Node, Endpoint, Cluster are re-used from Path4. |
10.5.3. DataVersionFilterIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Path | Context Tag | 0 | ClusterPathIB | – | |
DataVersion | Context Tag | 1 | Unsigned Int | 32 bits |
10.5.4. AttributeDataIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
DataVersion | Context Tag | 0 | Unsigned Int | 32 bits | |
Path | Context Tag | 1 | Attribut ePathIB | – | |
Data | Context Tag | 2 | Variable (see below) | – |
- The Change field in the Interaction Model specification is not encoded Instead, it is encoded through the use of special values in the Path and Data fields (see Lists below.
10.5.4.1. DataVersion
This tag can be omitted if the value of EnableTagCompression in the Path field is true. In this case, the value for the omitted tag SHALL be set to the value for that tag (if present) in the last Attribute DataIB that had tag compression disabled (i.e EnableTagCompression not present or set to false) and was seen in a message that is part of the same interaction model Action as the current message. If
this tag was not present and tag compression was disabled, it SHALL be interpreted as though a data version was not specified in that, or subsequent AttributeDataIBs.
10.5.4.2. Path
In addition to the rules specified for AttributePathIB, the Attribute and ‘Cluster’ fields within that element SHALL always be present.
10.5.4.3. Data
Upon path expansion of the value in Path, the hierarchy and structure of the encoded data for each concrete Path SHALL be based on the schema description of the specified attribute within the speci
fied cluster. The TLV encoding of each element in the data SHALL follow the rules of encoding as provided in Data Types.
- Lists
The various values in the Change enumeration are realized as follows:
Change Type | Realization |
REPLACE | Path SHALL refer to a list with ListIndex omitted and Data SHALL contain new values that will replace the existing contents of the list. |
ADD |
Path SHALL refer to a list with ListIndex contain ing a value of null and Data containing the new value of the list item that will be added to the list. |
DELETE | Path SHALL contain a non-null value for ListIn dex and Data SHALL contain null. |
MODIFY | Path SHALL contain a non-null value for ListIn dex and Data SHALL contain the new value for the existing list item. |
- A single AttributeDataIB containing a path to the list itself and Data that contains all items in the list encoded as a TLV This option SHOULD be selected if it is possible to encode the entirety of the list in a single AttributeDataIB that fits in a single message.
- A series of AttributeDataIBs, with the first containing a path to the list itself and Data that is an empty array, which signals clearing the list, and subsequent AttributeDataIBs each containing a path to each list item, in order, and Data that contains the value of the list item. This option SHOULD be selected when it is not possible to encode the entirety of the list in a single Attribut eDataIB that fits in a single
|
- Examples 5.4.4.1. Simple Types Update a top-level attribute:
10.5.4.5. Collection Types (List)
Modify a list item:
AttributeDataIB = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = 1]], Data = { Duration = 900, Rotate = Clockwise, // On the wire enum value (1) is used Speed = 12, |
Axis = 0, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “1234” } } |
Add an item to a list:
AttributeDataIB = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = null]], Data = { Duration = 100, Rotate = Counterclockwise, // On the wire enum value (2) is used Speed = 12, Axis = 90, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “9876” } } |
Delete an item in a list:
AttributeDataIB = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = 0]], Data = null, } |
Replace a list (Single IB):
AttributeDataIB = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern]], Data = [[ { Duration = 900, Rotate = Clockwise, // On the wire enum value (1) is used Speed = 12, Axis = 0, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “1234” } { Duration = 100, Rotate = Counterclockwise, // On the wire enum value (2) is used |
Speed = 12, Axis = 90, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “9876” }, ]] } |
Replace a list (Multiple IBs):
AttributeDataIB1 = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern ]], Data = [ ] } AttributeDataIB2 = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = 0]], Data = { Duration = 900, Rotate = Clockwise, // On the wire enum value (1) is used Speed = 12, Axis = 0, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “1234” } } AttributeDataIB3 = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Pattern, ListIndex = 1]], Data = { Duration = 100, Rotate = Counterclockwise, // On the wire enum value (2) is used Speed = 12, Axis = 90, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “9876” } } |
10.5.5. AttributeReportIB
TLV Type: Anonymous Struct | |||||
Element | Comments | Tag Type | Tag Number | TLV Type | Range |
TLV Type: Anonymous Struct | |||||
AttributeSta tus | Context Tag | 0 | AttributeSta tusIB | – | |
AttributeData | Context Tag | 1 | Attribute DataIB | – |
10.5.6. EventFilterIB
TLV Type: Anonymous Struct | |||||
Element | Comments | Tag Type | Tag Number | TLV Type | Range |
Node | Context Tag | 0 | Unsigned Int | 64 bits | |
EventMin | Context Tag | 1 | Unsigned Int | 64 bits |
- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server involved in the
10.5.7. ClusterPathIB
TLV Type: List | |||||
Element | Comments | Tag Type | Tag Number | TLV Type | Range |
Node | Context Tag | 0 | Unsigned Int | 64 bits | |
Endpoint | Context Tag | 1 | Unsigned Int | 16 bits | |
Cluster | Context Tag | 2 | Unsigned Int | 32 bits |
- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server involved in the
- If the Group field is present, the Group ID is encoded in the DST field in the message header and elided from the encoding
10.5.8. EventPathIB
TLV Type: List | |||||
Element | Comments | Tag Type | Tag Number | TLV Type | Range |
Node | Context Tag | 0 | Unsigned Int | 64 bits | |
Endpoint | Context Tag | 1 | Unsigned Int | 16 bits | |
Cluster | Context Tag | 2 | Unsigned Int | 32 bits | |
Event | Context Tag | 3 | Unsigned Int | 32 bits | |
‘IsUrgent’ | Context Tag | 4 | Boolean | – |
- The contents of ClusterPathIB have been expanded here to increase encoding
- The Node tag MAY be omitted if the target node of the path matches the NodeID of the server
involved in the interaction.
- Omission of the Endpoint, Cluster and Event tags SHALL have different interpretations depend ing on where the EventPathIB is used. See Section 10.6.2.2, “EventRequests”, Section 10.6.4.1, “EventRequests”, and Section 10.6.3.1, “EventReports” for the different
10.5.8.1. Examples
Select a particular event type:
Path = [[ Endpoint = 10, Cluster = Disco Ball, Event = Pattern Change ]] |
Select all events on a given cluster (used in Read/Subscribe requests):
Path = [[ Endpoint = 10, Cluster = Disco Ball ]] |
Select all events on a given cluster with urgency (used in Read/Subscribe requests):
Path = [[ Endpoint = 10, Cluster = Disco Ball, IsUrgent = true ]] |
10.5.9. EventDataIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Path | Context Tag | 0 | EventPathIB | – | |
EventNumber | Context Tag | 1 | Unsigned Int | 64 bits | |
Priority | Context Tag | 2 | Unsigned Int | 8 bits | |
one-of { | |||||
→ EpochTimestamp |
Context Tag | 3 | Signed Int | 64 bits | |
→ System Timestamp | Context Tag | 4 | Unsigned Int | 64 bits | |
→ DeltaE pochTimestamp | Optional | Context Tag | 5 | Unsigned Int | 64 bits |
→ DeltaSystem Timestamp | Optional | Context Tag | 6 | Unsigned Int | 64 bits |
} | |||||
Data | Context Tag | 7 | Variable (see below) | – |
10.5.9.1. DeltaEpochTimestamp
This tag is present when delta encoding the UTC timestamp relative to a prior event in a given
stream of events.
When this tag is present, all other timestamp tags SHALL be omitted. This SHALL have the same units as EpochTimestamp.
10.5.9.2. DeltaSystemTimestamp
This tag is present when delta encoding the System timestamp relative to a prior event in a given stream of events.
When this tag is present, all other timestamp tags SHALL be omitted. This SHALL have the same units as SystemTimestamp.
10.5.9.3. Data
This contains the cluster-specific payload of the Event.
The entirety of the Event is represented as a TLV Structure type.
The TLV encoding of each field in the event SHALL follow the rules of encoding as provided in Data Types.
10.5.9.4. Examples
Single event:
EventDataElement = { Path = [[ Endpoint = 10, Cluster = Disco Ball, EventID = Started ]], EventNumber = 1001, Priority = INFO, EpochTimestamp = 102340234293, Data = { // Started event contains no data } } |
10.5.10. EventReportIB
TLV Type: Anonymous Struct | |||||
Element | Comments | Tag Type | Tag Number | TLV Type | Range |
EventStatus | Context Tag | 0 | EventStatusIB | – | |
EventData | Context Tag | 1 | EventDataIB | – |
10.5.11. CommandPathIB
TLV Type: List | |||||
Element | Comments | Tag Type | Tag Number | TLV Type | Range |
Endpoint | Context Tag | 0 | Unsigned Int | 16 bits | |
Cluster | Context Tag | 1 | Unsigned Int | 32 bits | |
Command | Context Tag | 2 | Unsigned Int | 32 bits |
- The contents of ClusterPathIB have been expanded into the CommandPathIB here to increase encoding
- Wildcarding is achieved by omission of the respective
- The Node field in the IM representation is the NodeID of the server involved in the interaction. This is omitted in the encoding here since it is retrievable from the message layer for the mes sage containing this
- The Group field in the IM representation is encoded in the DST field in the message
10.5.11.1. Examples
Select a particular command:
Path = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stop Request ]] |
Select a particular command (addressed to a group):
Path = [[ Cluster = Disco Ball, Command = Stop Request ]] |
10.5.12. CommandDataIB
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
CommandPath | Context Tag | 0 | Command PathIB | – | |
CommandFields | Context Tag | 1 | variable | – |
10.5.12.1. CommandFields
This field SHALL contain the full set of arguments as specified in the description of the command request/response. The arguments SHALL follow the rules of encoding as provided in Data Types.
The entirety of the arguments SHALL be encapsulated in a TLV structure, with each argument encoded appropriately using its field id as the context tag number.
If there are no arguments in the Request or Response, this tag MAY be omitted entirely.
10.5.12.2. Examples
Request + Response:
RequestCommandElement = { CommandPath = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stats Request ]], CommandData = {} // Empty CommandData MAY be encoded as an empty container } ResponseCommandElement = { CommandPath = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stats Response ]], CommandData = { LastRun = 100, Patterns = 1 } } |
Empty request:
RequestCommandElement = { CommandPath = [[ Endpoint = 10, Cluster = Disco Ball, Command = Stop Request ]] // Empty CommandData MAY also be omitted entirely } // No cluster specific response is returned; a status is passed via Invoke Response at the Interaction layer |
10.5.13. InvokeResponseIB
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Command | Context Tag | 0 | Command DataIB | – | |
Status | Context Tag | 1 | CommandSta tusIB | – |
10.5.14. CommandStatusIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
CommandPath | Context Tag | 0 | Command PathIB | – | |
Status | Context Tag | 1 | StatusIB | – |
10.5.15. EventStatusIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Path | Context Tag | 0 | EventPathIB | – | |
Status | Context Tag | 1 | StatusIB | – |
10.5.16. AttributeStatusIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Path | Context Tag | 0 | Attribut ePathIB | – | |
Status | Context Tag | 1 | StatusIB | – |
10.5.17. StatusIB
TLV Type: Structure | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Status | Context Tag | 0 | Unsigned Int | 8 bits | |
ClusterStatus | Context Tag | 1 | Unsigned Int | 8 bits |
10.6. Message Definitions
This section contains message definitions that correspond to their equivalent actions in the Interac tion Model Specification. Unless specifically indicated, all fields in the ensuing definitions SHALL match their equivalents in the appropriate Actions defined in the Interaction Model Specification.
10.6.1. StatusResponseMessage
StatusResponseMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Status | Context Tag | 0 | Unsigned Int | 8-bits |
10.6.2. ReadRequestMessage
ReadRequestMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
ReadRequestMessage | |||||
Attribut eRequests | Optional | Context Tag | 0 | Array of Attribut ePathIB | – |
EventRequests | Optional | Context Tag | 1 | Array of Event PathIB | – |
EventFilters | Optional | Context Tag | 2 | Array of Event FilterIB | – |
FabricFiltered | Context Tag | 3 | boolean | – | |
DataVersion Filters | Optional | Context Tag | 4 | Array of DataVersionFil terIB | – |
10.6.2.1. AttributeRequests
- If not present SHALL be treated as an empty
10.6.2.2. EventRequests
- If not present SHALL be treated as an empty
- Omission of any of the Endpoint, Cluster, Event tags indicates wildcard semantics.
10.6.2.3. EventFilters
- If not present SHALL be treated as an empty
- MAY be ignored (i.e. not decoded) if EventRequests is
10.6.2.4. DataVersionFilters
- If not present SHALL be treated as an empty
- MAY be ignored (i.e. not decoded) if AttributeRequests is
10.6.3. ReportDataMessage
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
SubscriptionID | Optional | Context Tag | 0 | Unsigned Inte ger | 32 bits |
AttributeRe ports | Optional | Context Tag | 1 | Array of AttributeRe portIB | |
EventReports | Optional | Context Tag | 2 | Array of Even tReportIB |
TLV Type: Structure (Anonymous) | |||||
MoreChun kedMessages | Can be omitted if false. | Context Tag | 3 | Boolean | – |
SuppressRe sponse | Omit if ‘false’ | Context Tag | 4 | Boolean | – |
- Multiple ReportDataMessages MAY be sent if a Report Data action does not fit into a single mes sage.
- For each ReportDataMessage received, a successful StatusResponse message SHALL be sent back to the sender unless SuppressResponse is true.
- SuppressResponse SHALL NOT be set to true when either AttributeReports or EventReports are non-empty
10.6.3.1. EventReports
A list of EventReportIB encoded as a TLV array that have certain compression schemes applied to them to reduce redundant data.
For each EventReportIB in the list:
- The Path tag SHALL utilize the same tag compression scheme as that utilized by the tags in AttributePathIB. Specifically:
- The tag compression scheme SHALL only apply to the Node, Endpoint, Cluster and Event tags within the EventPathIB
- The first element within the list SHALL specify all the necessary tags and hence serve as the anchor on which subsequent items MAY rely for
- The EventNumber MAY be omitted if it is exactly one greater than the EventNumber of the pre vious
- The ‘Delta’ tags SHALL be used to encode timestamps as deltas from the prior event to improve compression of large
10.6.3.1.1. Examples
Event list (highlighting compressions):
EventReports = [ { Path = [[ Endpoint = 10, Cluster = Disco Ball, EventID = Started ]], ImportanceLevel = INFO, Number = 1001, UTCTimestamp = 102340234293, Data = { }, }, { Path = [[ EventID = PatternChange]], // same endpoint and cluster but different |
event type DeltaUTCTimestamp = 1000, Data = { PrevPattern = null, CurPattern = { Duration = 900, Rotate = Clockwise, // On the wire enum value (1) is used Speed = 12, Axis = 0, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “1234” }, NextPattern = { Duration = 100, Rotate = Counterclockwise, // On the wire enum value (2) is used Speed = 12, Axis = 90, // WobbleSpeed omitted; this cluster instance does not support Wobble Passcode = “9876” } } } { Path = [[ ]], // same path as the previous path DeltaUTCTimestamp = 900000000, Data = { PrevPattern = { Duration = 900, Rotate = Clockwise, Speed = 12, Axis = 0, Passcode = “1234” }, CurPattern = { Duration = 100, Rotate = Counterclockwise, Speed = 12, Axis = 90, Passcode = “9876” }, NextPattern = null } } ] |
10.6.3.2. MoreChunkedMessages
This flag is set to ‘true’ when there are more chunked messages in a transaction.
10.6.4. SubscribeRequestMessage
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
KeepSubscrip tions | Context Tag | 0 | Boolean | ||
MinInter valFloor | Context Tag | 1 | Unsigned Int | 16 bits | |
MaxInterval Ceiling | Context Tag | 2 | Unsigned Int | 16 bits | |
Attribut eRequests | Optional | Context Tag | 3 | Array of Attribut ePathIB | – |
EventRequests | Optional | Context Tag | 4 | Array of Event PathIB | – |
EventFilters | Optional. Only present if EventRequests is present. | Context Tag | 5 | Array of Event FilterIB | – |
FabricFiltered | Context Tag | 7 | boolean | – | |
DataVersion Filters | Optional. Only present if Attribut eRequests is present. | Context Tag | 8 | Array of DataVersionFil terIB | – |
10.6.4.1. EventRequests
- Omission of any of Endpoint, Cluster, Event tags indicates wildcard semantics.
10.6.5. SubscribeResponseMessage
This is sent after all Reports have been sent back to the client. The sole purpose of this is to convey the final set of parameters for the subscription back to the client.
SubscribeResponseMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
SubscriptionID | Context Tag | 0 | Unsigned Int | 32 bits | |
MaxInterval | Context Tag | 2 | Unsigned Int | 16 bits |
10.6.6. WriteRequestMessage
WriteRequestMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
SuppressRe sponse | Omit if ‘false’ | Context Tag | 0 | Boolean | – |
TimedRequest | Context Tag | 1 | Boolean | – | |
WriteRequests | Context Tag | 2 | Array of Attribute DataIB | ||
MoreChun kedMessages | Can be omitted if false | Context Tag | 3 | Boolean | – |
10.6.6.1. MoreChunkedMessages
- Like reports, multiple WriteRequestMessages MAY be sent in a single transaction if the set of AttributeDataIBs have to be sent across multiple All but the last message SHALL have
the MoreChunkedMessages flag set to true to indicate this situation. Before sending the next
WriteRequestMessage, the sender SHALL await the WriteResponseMessage associated with the
previous WriteRequestMessage.
- SuppressResponse SHALL NOT be set to true if MoreChunkedMessages is
- A Write Request action that is part of a Timed Write Interaction SHALL NOT be
10.6.7. WriteResponseMessage
WriteResponseMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
WriteResponses | Context Tag | 0 | Array of AttributeSta tusIB | – |
10.6.8. TimedRequestMessage
TimedRequestMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
Timeout | Context Tag | 0 | Unsigned Int | 16 bits |
10.6.9. InvokeRequestMessage
InvokeRequestMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
SuppressRe sponse | Context Tag | 0 | Boolean | – | |
TimedRequest | Context Tag | 1 | Boolean | – | |
InvokeRequests | Context Tag | 2 | Array of Com mandDataIB | – |
10.6.10. InvokeResponseMessage
InvokeResponseMessage | |||||
TLV Type: Structure (Anonymous) | |||||
Element | Comments | Tag Type | Tag Number | Type | Range |
SuppressRe sponse | Context Tag | 0 | Boolean | – | |
InvokeRe sponses | Context Tag | 1 | Array of Invok eResponseIB | – |