Interaction Model

The Matter spec defines the Interaction Model explain how a controller, such as the hub, should interact with various cluster elements on the device, and to provide an abstraction that is separate from other layers such as security, and message format/encoding. An Interaction between two nodes is made up one or more Transactions, which is made up of Actions. Actions are then translated into one or more messages in the layers below the Interaction Model.

The lua objects defined in the interaction_model module break down the Interaction Model as defined in the spec into a Request/Response model where an InteractionRequest and InteractionResponse are analagous to the Actions that make up an Interaction. This was done to work with the Matter communication socket used for device communication, which is completely asynchronous. For Read, Write, and Invoke interactions, the hub guarantees that a response (possibly with an error status) will be received in the driver for every Read, Write, and Invoke request that is sent.

Drivers hook into the Matter device interaction model by building InteractionRequests that contain one or more InteractionInfoBlocks; when an InteractionResponse is received as a result of a request, the driver handles the InteractionResponseInfoBlocks contained within the response by dispatching the info blocks to matter handler funtions.

InteractionInfoBlocks exist on both requests and responses. They contain the attribute/event/command paths along with any TLV data associated with the cluster path for the request or response. The TLV data is a string of bytes that is serialized and deserialized into the core matter data types as well as cluster library defined types and stored in the table field InteractionInfoBlock.data. TLV deserialization is done automatically when raw responses are received from the matter socket and serialization occurs when sending on the matter socket. InteractionResponseInfoBlocks contain an InteractionInfoBlock as well as a status associated with the response.

Subscribe Interaction

The subscription interaction is unique in the spec-defined Interaction model and as such is also unique in the interaction model exposed by the Matter Lua standard libraries. The hub maintains a single subscription for each device on its Matter fabric. The SUBSCRIBE InteractionRequest.RequestType is used to update the subscription with a list of attribute and event paths. The hub will restart subscriptions if they terminate, update the subscription event/attribute paths with each subsequent subscribe request, and guarantees that the most recent subscription request sent from the driver will have its attributes and events included in the current subscription. There are no subscription InteractionResponses from the hub that will be received in the driver.

class st.matter.interaction_model.InteractionRequest.RequestType
READ: number

0

SUBSCRIBE: number

1

WRITE: number

2

INVOKE: number

3

class st.matter.interaction_model.InteractionRequest

Interaction Request sent on a matter socket to initiate an device interaction with a matter device.

type: number

Interaction Request type

info_blocks: table

list<InteractionInfoBlock> info_blocks for the given Interaction Request.

timed: boolean or nil

This is a timed interaction if true

static from_parts(cls, type, info_blocks, timed)

Constructor for InteractionRequests

Parameters

  • cls (table) – InteractionRequest reference from __call

  • type (number) – Matter Request type

  • info_blocks (table) – list<InteractionInfoBlock> info_blocks for the given Interaction Request.

  • timed (boolean or nil) – Specifies that a write/invoke interaction is a timed interaction

Returns

constructed InteractionRequest instance

Return type

InteractionRequest

pretty_print()
Return type

str

static merge(cls, other)

Merge the info blocks of a different interaction request into

the info blocks of this request, so they can be sent on the channel together.

Note this does not take into account wildcard clusters. If one IB path contains a wildcard and therefore encompasses another IB path both paths will be merged.

Parameters

  • cls (InteractionRequest) – request to merge into

  • other (InteractionRequest) – request getting merged

Returns

string|nil

Return type

err

with_info_block(ib)

Append the InteractionInfoBlock to the request

Parameters

ib (InteractionInfoBlock) – to append to the requests info_blocks field

serialize()

Serialize the InteractionRequest into the raw table that goes on the matter socket

Return type

table

class st.matter.interaction_model.InteractionInfoBlock
endpoint_id: number

device endpoint id

cluster_id: number

cluster path

attribute_id: number or nil

attribute path

event_id: number or nil

event path

command_id: number or nil

command path

tlv: str or nil

data associated with the interaction path

static from_parts(cls, endpoint_id, cluster_id, attribute_id, event_id, command_id, tlv)

Constructor for InteractionInfoBlock objects.

Parameters

  • cls (table) – UNUSED InteractionInfoBlock reference from __call

  • endpoint_id (number) – device endpoint id

  • cluster_id (number) – cluster path

  • attribute_id (number or nil) – attribute path

  • event_id (number or nil) – event path

  • command_id (number or nil) – command path

  • tlv (str or nil) – data associated with the interaction path

Returns

constructed path

Return type

InteractionInfoBlock

static equals(cls, other)

Checks if two interaction info blocks are equal to each other

Parameters

  • cls (InteractionInfoBlock) –

  • other (InteractionInfoBlock) –

Return type

boolean

pretty_print()
Return type

str

serialize()
class st.matter.interaction_model.InteractionResponse.ResponseType
REPORT_DATA: number

0

COMMAND_RESPONSE: number

1

WRITE_RESPONSE: number

2

SUBSCRIBE_RESPONSE: number

3, not used currently as the hub manages the subscription interaction completely

class st.matter.interaction_model.InteractionResponse

Interaction Response received on a matter socket as a result of initiating a device interaction.

type: number

Matter interaction type

info_blocks: table

InteractionInfoBlock interaction info_blocks for the given interaction

status: number

InteractionRequest.status enum value

static from_parts(cls, type, info_blocks)

Constructor for InteractionResponse objects

Parameters

  • cls (table) – InteractionResponse reference from __call

  • type (number) – Matter interaction type

  • info_blocks (list[InteractionInfoBlock]) – interaction info_blocks for the given interaction

Returns

constructed interaction req instance

Return type

InteractionResponse

static deserialize(socket_message)

Deserialize raw matter socket message into InteractionResponse

Parameters

socket_message (table) –

Return type

InteractionResponse

pretty_print()
Return type

str

class st.matter.interaction_model.InteractionResponseInfoBlock
info_block: table

data/path associated with the response block

status: number

Interaction status associated with the path

cluster_status: number or nil

Optional cluster status associated with the interaction path.

static from_parts(cls, info_block, status, cluster_status, event_number)

Constructor for InteractionResponseInfoBlock objects.

Parameters

  • cls (table) – UNUSED InteractionResponseInfoBlock reference from __call

  • info_block (InteractionInfoBlock) – Single info block of data in the response

  • status (str) – Interaction status associated with the path

  • cluster_status (number or nil) – Optional cluster status associated with the interaction path.

  • event_number (number or nil) – The event number if this block holds event data.

Returns

constructed path

Return type

InteractionResponseInfoBlock

static deserialize(socket_response_block)

Deserialize raw matter socket response info block into InteractionResponseInfoBlock

Parameters

socket_response_block (table) –

Return type

InteractionResponseInfoBlock

pretty_print()
Return type

str