interaction

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 24, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package interaction implements the Matter Interaction Model (IM), providing Read, Write, Invoke, and Subscribe operations over Matter exchanges. It encodes and decodes IM messages using TLV and communicates through the protocol.Exchange abstraction.

Index

Constants

View Source 
const (
	OpcodeStatusResponse    byte = 0x01
	OpcodeReadRequest       byte = 0x02
	OpcodeSubscribeRequest  byte = 0x03
	OpcodeSubscribeResponse byte = 0x04
	OpcodeReportData        byte = 0x05
	OpcodeWriteRequest      byte = 0x06
	OpcodeWriteResponse     byte = 0x07
	OpcodeInvokeRequest     byte = 0x08
	OpcodeInvokeResponse    byte = 0x09
	OpcodeTimedRequest      byte = 0x0A
)

IM opcodes as defined in the Matter specification (Chapter 8).

View Source 
const ProtocolID uint16 = 0x0001

ProtocolID is the Matter protocol identifier for the Interaction Model.

Variables

This section is empty.

Functions

func IsStatus 

func IsStatus(err error, code StatusCode) bool

IsStatus returns true if err (or any error in its chain) is a StatusError with the given code. It uses errors.As so it works with wrapped errors too.

func WithInvokeTimeout 

func WithInvokeTimeout(ctx context.Context, d time.Duration) context.Context

WithInvokeTimeout returns a child context that overrides the default invoke response timeout used by Client.Invoke / Client.InvokeTimed. This is useful for commands whose response is expected to take longer than the default 30 s (e.g. NetworkCommissioning.ConnectNetwork on Thread devices).

Types

type AttributeData 

type AttributeData struct {
	DataVersion uint32        `tlv:"0,uint"`
	Path        AttributePath `tlv:"1,liststruct"`
	Data        []byte        `tlv:"2,rawtlv"`
}

AttributeData carries the actual data for a successfully read attribute.

type AttributePath 

type AttributePath struct {
	EnableTagCompression *bool   `tlv:"0,bool"`
	NodeID               *uint64 `tlv:"1,uint"`
	EndpointID           *uint16 `tlv:"2,uint"`
	ClusterID            *uint32 `tlv:"3,uint"`
	AttributeID          *uint32 `tlv:"4,uint"`
	ListIndex            *uint16 `tlv:"5,uint"`
}

AttributePath identifies an attribute on a Matter node. Nil pointer fields act as wildcards, matching all values for that path component.

func NewAttributePath 

func NewAttributePath(endpoint uint16, cluster uint32, attribute uint32) AttributePath

NewAttributePath creates an AttributePath targeting a specific endpoint, cluster, and attribute.

func (AttributePath) String 

func (p AttributePath) String() string

String returns a human-readable representation of the attribute path.

type AttributeReport 

type AttributeReport struct {
	Status *AttributeStatus `tlv:"0,struct"`
	Data   *AttributeData   `tlv:"1,struct"`
}

AttributeReport contains either an error status or attribute data for a single attribute path in a ReportData message.

type AttributeStatus 

type AttributeStatus struct {
	Path   AttributePath `tlv:"0,liststruct"`
	Status StatusIB      `tlv:"1,struct"`
}

AttributeStatus pairs an attribute path with an error status, indicating that the read for that path failed.

type AttributeWrite 

type AttributeWrite struct {
	DataVersion *uint32       `tlv:"0,uint"`
	Path        AttributePath `tlv:"1,liststruct"`
	Data        []byte        `tlv:"2,rawtlv"`
}

AttributeWrite specifies a single attribute value to write, including the target path and the raw TLV-encoded data. Data must contain a single anonymous-tagged TLV element (as produced by tlv.Writer.PutUnsignedInt/PutBool/etc. with AnonymousTag()). The marshaller re-encodes it at context tag 2 inline — NOT wrapped in an octet string — which is what the Matter IM spec requires for AttributeDataIB.Data.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides high-level Interaction Model operations. It uses an ExchangeManager to create exchanges and communicate with Matter peers.

func NewClient 

func NewClient(em *protocol.ExchangeManager) *Client

NewClient creates a new IM client backed by the given ExchangeManager.

func (*Client) Invoke 

func (c *Client) Invoke(ctx context.Context, session *protocol.Session, path CommandPath, fields []byte) (*InvokeResponseIB, error)

Invoke sends an InvokeRequest with a single command and returns the response. The fields parameter contains the raw TLV-encoded command fields, or nil if the command takes no arguments.

func (*Client) InvokeTimed 

func (c *Client) InvokeTimed(ctx context.Context, session *protocol.Session, path CommandPath, fields []byte, timeoutMs uint16) (*InvokeResponseIB, error)

InvokeTimed sends a Timed Invoke: first sends a TimedRequest with the given timeout (in milliseconds), waits for the StatusResponse(Success), then sends the InvokeRequest with TimedRequest=true.

func (*Client) Read 

func (c *Client) Read(ctx context.Context, session *protocol.Session, paths ...AttributePath) ([]AttributeReport, error)

Read sends a ReadRequest for the given attribute paths and collects the full ReportData response(s). It handles chunked responses (MoreChunkedMessages) automatically by sending StatusResponse(Success) acknowledgments.

func (*Client) Subscribe 

func (c *Client) Subscribe(ctx context.Context, session *protocol.Session, paths []AttributePath, minInterval, maxInterval uint16) (*Subscription, error)

Subscribe sends a SubscribeRequest and returns a Subscription that delivers periodic attribute reports. The subscription runs in the background and delivers reports through the Subscription.Reports channel.

func (*Client) Write 

func (c *Client) Write(ctx context.Context, session *protocol.Session, writes ...AttributeWrite) ([]AttributeStatus, error)

Write sends a WriteRequest with the given attribute writes and returns the per-attribute write status results.

type CommandDataIB 

type CommandDataIB struct {
	Path   CommandPath `tlv:"0,liststruct"`
	Fields []byte      `tlv:"1,rawstruct"`
}

CommandDataIB carries a single command invocation or response, pairing a command path with optional raw TLV-encoded fields.

type CommandPath 

type CommandPath struct {
	EndpointID uint16 `tlv:"0,uint"`
	ClusterID  uint32 `tlv:"1,uint"`
	CommandID  uint32 `tlv:"2,uint"`
}

CommandPath identifies a command on a specific endpoint and cluster. All fields are required (no wildcards).

func NewCommandPath 

func NewCommandPath(endpoint uint16, cluster uint32, command uint32) CommandPath

NewCommandPath creates a CommandPath with the given endpoint, cluster, and command IDs.

func (CommandPath) String 

func (p CommandPath) String() string

String returns a human-readable representation of the command path.

type CommandStatusIB 

type CommandStatusIB struct {
	Path   CommandPath `tlv:"0,liststruct"`
	Status StatusIB    `tlv:"1,struct"`
}

CommandStatusIB pairs a command path with a status, used when a command invocation fails or succeeds with no response data.

type EventPath 

type EventPath struct {
	NodeID     *uint64 `tlv:"1,uint"`
	EndpointID *uint16 `tlv:"2,uint"`
	ClusterID  *uint32 `tlv:"3,uint"`
	EventID    *uint32 `tlv:"4,uint"`
	IsUrgent   *bool   `tlv:"5,bool"`
}

EventPath identifies an event on a Matter node. Nil pointer fields act as wildcards.

func (EventPath) String 

func (p EventPath) String() string

String returns a human-readable representation of the event path.

type InvokeRequest 

type InvokeRequest struct {
	SuppressResponse bool            `tlv:"0,bool"`
	TimedRequest     bool            `tlv:"1,bool"`
	InvokeRequests   []CommandDataIB `tlv:"2,array"`
}

InvokeRequest is the TLV structure for an Invoke Request message (opcode 0x08). It carries one or more command invocations to execute on the peer.

type InvokeResponse 

type InvokeResponse struct {
	SuppressResponse bool               `tlv:"0,bool"`
	InvokeResponses  []InvokeResponseIB `tlv:"1,array"`
}

InvokeResponse is the TLV structure for an Invoke Response message (opcode 0x09). It contains per-command response data and/or status results.

type InvokeResponseIB 

type InvokeResponseIB struct {
	Command *CommandDataIB   `tlv:"0,struct"`
	Status  *CommandStatusIB `tlv:"1,struct"`
}

InvokeResponseIB carries either response data or a status for a single invoked command. Exactly one of Command or Status is set.

type ReadRequest 

type ReadRequest struct {
	AttributeRequests []AttributePath `tlv:"0,listarray"`
	EventRequests     []EventPath     `tlv:"1,listarray"`
	FabricFiltered    bool            `tlv:"3,bool"`
}

ReadRequest is the TLV structure for a Read Request message (opcode 0x02). It specifies which attributes and/or events to read from the peer.

type ReportData 

type ReportData struct {
	SubscriptionID      *uint32           `tlv:"0,uint"`
	AttributeReports    []AttributeReport `tlv:"1,array"`
	MoreChunkedMessages *bool             `tlv:"3,bool"`
	SuppressResponse    *bool             `tlv:"4,bool"`
}

ReportData is the TLV structure for a Report Data message (opcode 0x05). It carries attribute reports in response to a Read or Subscribe request.

type StatusCode 

type StatusCode uint8

StatusCode represents an Interaction Model status code from the Matter specification. 

const (
	// StatusSuccess indicates the operation completed successfully.
	StatusSuccess StatusCode = 0x00
	// StatusFailure indicates a generic failure.
	StatusFailure StatusCode = 0x01
	// StatusInvalidSubscription indicates an invalid or unknown subscription ID.
	StatusInvalidSubscription StatusCode = 0x7D
	// StatusUnsupportedAccess indicates the access level is insufficient.
	StatusUnsupportedAccess StatusCode = 0x7E
	// StatusUnsupportedEndpoint indicates the endpoint is not supported.
	StatusUnsupportedEndpoint StatusCode = 0x7F
	// StatusInvalidAction indicates the action is not valid in the current state.
	StatusInvalidAction StatusCode = 0x80
	// StatusUnsupportedCommand indicates the command is not supported.
	StatusUnsupportedCommand StatusCode = 0x81
	// StatusInvalidCommand indicates the command is malformed or has invalid fields.
	StatusInvalidCommand StatusCode = 0x85
	// StatusUnsupportedAttribute indicates the attribute is not supported.
	StatusUnsupportedAttribute StatusCode = 0x86
	// StatusConstraintError indicates a value constraint violation.
	StatusConstraintError StatusCode = 0x87
	// StatusUnsupportedWrite indicates the attribute does not support writing.
	StatusUnsupportedWrite StatusCode = 0x88
	// StatusResourceExhausted indicates resources are exhausted.
	StatusResourceExhausted StatusCode = 0x89
	// StatusNotFound indicates the requested resource was not found.
	StatusNotFound StatusCode = 0x8B
	// StatusUnreportableAttribute indicates the attribute cannot be reported.
	StatusUnreportableAttribute StatusCode = 0x8C
	// StatusInvalidDataType indicates a data type mismatch.
	StatusInvalidDataType StatusCode = 0x8D
	// StatusUnsupportedRead indicates the attribute does not support reading.
	StatusUnsupportedRead StatusCode = 0x8F
	// StatusDataVersionMismatch indicates a data version filter mismatch.
	StatusDataVersionMismatch StatusCode = 0x92
	// StatusTimeout indicates the operation timed out.
	StatusTimeout StatusCode = 0x94
	// StatusBusy indicates the node is busy and cannot process the request.
	StatusBusy StatusCode = 0x9C
	// StatusPathsExhausted indicates too many paths in the request.
	StatusPathsExhausted StatusCode = 0xC8
	// StatusTimedRequestMismatch indicates a timed request mismatch.
	StatusTimedRequestMismatch StatusCode = 0xC9
	// StatusFailsafeRequired indicates a failsafe must be armed first.
	StatusFailsafeRequired StatusCode = 0xCA
	// StatusInvalidInState indicates the operation is invalid in the current state.
	StatusInvalidInState StatusCode = 0xCB
	// StatusNoCommandResponse indicates no response was provided for a command.
	StatusNoCommandResponse StatusCode = 0xCC
)

func (StatusCode) String 

func (s StatusCode) String() string

String returns a human-readable name for the status code.

type StatusError 

type StatusError struct {
	// GeneralCode is the IM-level status code.
	GeneralCode StatusCode
	// ClusterCode is the optional cluster-specific status code.
	ClusterCode *uint8
}

StatusError wraps an IM status code into a Go error. It is returned when the peer responds with a non-success status.

func (*StatusError) Error 

func (e *StatusError) Error() string

Error returns a human-readable description of the status error.

type StatusIB 

type StatusIB struct {
	Status        uint8  `tlv:"0,uint"`
	ClusterStatus *uint8 `tlv:"1,uint"`
}

StatusIB represents the Status Information Block as defined in the Matter spec. It contains a general status code and an optional cluster-specific status.

type StatusResponseMessage 

type StatusResponseMessage struct {
	Status uint8 `tlv:"0,uint"`
}

StatusResponseMessage is the TLV payload of a StatusResponse message (opcode 0x01). Note: the Status field is a plain uint8 status code, NOT a nested StatusIB struct.

type SubscribeRequest 

type SubscribeRequest struct {
	KeepSubscriptions  bool            `tlv:"0,bool"`
	MinIntervalFloor   uint16          `tlv:"1,uint"`
	MaxIntervalCeiling uint16          `tlv:"2,uint"`
	AttributeRequests  []AttributePath `tlv:"3,listarray"`
	EventRequests      []EventPath     `tlv:"4,listarray"`
	FabricFiltered     bool            `tlv:"7,bool"`
}

SubscribeRequest is the TLV structure for a Subscribe Request message (opcode 0x03). It requests periodic attribute and/or event reports from the peer.

type SubscribeResponse 

type SubscribeResponse struct {
	SubscriptionID uint32 `tlv:"0,uint"`
	MaxInterval    uint16 `tlv:"2,uint"`
}

SubscribeResponse is the TLV structure for a Subscribe Response message (opcode 0x04). It confirms subscription establishment and provides the negotiated parameters.

type Subscription 

type Subscription struct {
	// ID is the subscription identifier assigned by the peer.
	ID uint32
	// Reports delivers attribute report batches from the peer.
	Reports <-chan []AttributeReport
	// Errors delivers errors that occur during the subscription.
	Errors <-chan error
	// contains filtered or unexported fields
}

Subscription represents an active subscription to attribute or event changes. Reports are delivered through the Reports channel and errors through the Errors channel. Call Cancel to terminate the subscription.

func (*Subscription) Cancel 

func (s *Subscription) Cancel()

Cancel terminates the subscription and closes its channels.

type TimedRequestMessage 

type TimedRequestMessage struct {
	Timeout uint16 `tlv:"0,uint"`
}

TimedRequestMessage is the TLV payload of a TimedRequest (opcode 0x0A).

type WriteRequest 

type WriteRequest struct {
	SuppressResponse    bool             `tlv:"0,bool"`
	TimedRequest        bool             `tlv:"1,bool"`
	WriteRequests       []AttributeWrite `tlv:"2,array"`
	MoreChunkedMessages *bool            `tlv:"3,bool"`
}

WriteRequest is the TLV structure for a Write Request message (opcode 0x06). It carries one or more attribute writes to be applied on the peer. SuppressResponse and TimedRequest are non-pointer bools so they are always encoded on the wire (as false) — the CHIP SDK WriteHandler requires both fields to be present and returns INVALID_ACTION if either is absent. WriteRequests uses "array" (TLV ARRAY outer + STRUCT inner) to match what matter.js and chip-tool send: TlvArray(TlvObject(...)) → Array of Structs. CHIP SDK AttributeDataIB::Parser::Init accepts both STRUCT and LIST inner elements, but interop devices may only be tested with STRUCT encoding.

type WriteResponse 

type WriteResponse struct {
	WriteResponses []AttributeStatus `tlv:"0,array"`
}

WriteResponse is the TLV structure for a Write Response message (opcode 0x07). It contains per-attribute write status results.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.