Read Transactions

Read Transaction

One of the first use cases when interacting with Nodes in Matter is the reading of an Attribute from another Node, such as a temperature value from a sensor. In such Interactions, the first Action that must be performed is the Read Request Action.

Sequence of operations of a Read Transaction
Figure 1: Read Transaction

Read Request Action

Direction: Initiator -> Target

In this Action the Initiator queries a Target providing:

  • Attribute Requests: a list of zero or more of the Target's Attributes. This list is composed of zero or more Paths to the Target's requested Attributes.
  • Event Requests: list of zero or more Paths to the Target's requested Events.

After the Read Request Action is received by the Target it will assemble a Report Data Action with the requested information.

Report Data Action

Direction: Target -> Initiator

In this Action the Target responds with:

  • Attribute Reports: a list of zero or more of the reported Attributes requested in the Read Action Request.
  • Event Reports: a list of zero or more reported Events.
  • Suppress Response: a flag that determines whether the status response to this action should be suppressed.
  • Subscription ID: if this report is part of a subscribing transaction, it must include an integer used to identify the subscription transaction.

Status Response Action

Direction: either Target -> Initiator or Initiator -> Target

Once the Initiator receives the requested data, by default it must generate a Status Response Action. This action is sent from the Initiator, acknowledging the receipt of the reported data. If the flag Suppress Status Response is set, the Initiator must not send the Status Response Action.

Once the Status Response Action is sent by the Initiator, or a Report Data Action is received by the Initiator with the Suppress Response flag enabled, the read/report query is finished.

The Status Response Action simply contains a status field that will either acknowledge operation success or present a failure code.

Read Restrictions

The Read Request Action and Report Data Action are Unicast-only. Moreover, the Paths of these requests may not target a Group of Nodes.

The Status Response Action is Unicast-only and can't be generated as a response to a groupcast.

Subscription Transaction

Sequence of operations of a Subscription Transaction
Figure 2: Subscription Transaction

Subscribe Request Action

Direction: Initiator -> Target

In addition to a singular Read Request Action, an Initiator may also subscribe to periodic updates of an Attribute or Event. Thus the same Report Data Action can be generated as a result of periodic data updates that follow a Subscription Transaction.

A Subscription Interaction creates a relationship between two Nodes, in which the Target periodically generates Report Data Actions to the Initiator. The Initiator is the Subscriber and the Target is the Publisher.

A Subscribe Request Action contains:

  • Min Interval Floor: the minimum interval between reports.
  • Max Interval Ceiling: the maximum interval between reports.
  • Attribute Reports: a list of zero or more of the reported Attributes requested in the Read Action Request.
  • Event Reports: a list of zero or more reported Events.

After the Subscribe Request, the Target responds to the Initiator with a Report Data Action containing the first batch of reported data: the Primed Published Data.

The Initiator then acknowledges the Report Data Action with a Status Response Action sent to the Target. Once the Target receives a Status Response Action reporting no errors, it sends a Subscribe Response Action.

The Target will subsequently send Report Data Action periodically at the negotiated interval and the Initiator will respond to those Actions until the subscription is lost or cancelled.

Subscribe Response Action

Direction: Target -> Initiator

This is the last Action on the Subscription Transaction and concludes the process. It includes:

  • Subscription ID: a integer that identifies the subscription.
  • Min Interval: the final, determined minimum interval between reports.
  • Max Interval: the final, determined maximum interval between reports.

Subscribe Restrictions

  • The Subscribe Request Action and the Subscribe Response Action are Unicast-only actions.
  • All Report Data Actions in a Subscription Interaction must have the same Subscription ID.
  • If the Subscriber does not receive a Report Data Action within the maximum negotiated interval between Actions, the subscription will be terminated.
  • As a consequence of the previous rule, the Publisher may terminate a Subscription Interaction by simply stopping sending periodic Report Data Actions.
  • The Subscriber may terminate the Subscription Interaction by responding to a Report Data Action with an INACTIVE_SUBSCRIPTION status code.
Previous
Concepts
Next
Write Transactions