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 (2¹⁶-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

 

•  

AttributeDataIB = { DataVersion = 1, Path = [[ Endpoint = 10, Cluster = Disco Ball, FieldID = Axis ]], Data = 90 }

• 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	–