matter

Documentation

Overview

Package matter provides a high-level Go API for controlling Matter smart home devices. It wraps the internal controller, commissioning, discovery, and interaction model packages into a single, easy-to-use Client.

Basic usage:

client, err := matter.NewClient(matter.DefaultConfig())
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Commission a new device.
err = client.Commission(ctx, matter.CommissionParams{
    SetupCode: "MT:Y3.13OTB00KA0648G00",
    NodeID:    1,
})

// Connect and toggle a light.
session, err := client.ConnectCASE(ctx, "192.168.1.42:5540", 1)
_, err = session.Invoke(ctx, 1, 0x0006, 0x02, nil) // on-off toggle

Index

• type AttributeInfo
• type Client
  • func NewClient(cfg Config) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Commission(ctx context.Context, params CommissionParams) error
  • func (c *Client) CommissionByIP(ctx context.Context, addr string, passcode uint32, nodeID uint64) error
  • func (c *Client) ConnectCASE(ctx context.Context, addr string, nodeID uint64) (*Session, error)
  • func (c *Client) ConnectPASE(ctx context.Context, addr string, passcode uint32) (*Session, error)
• type ClusterInfo
  • func AllClusters() []ClusterInfo
  • func LookupCluster(name string) (*ClusterInfo, bool)
  • func LookupClusterByID(id uint32) (*ClusterInfo, bool)
• type CommandInfo
• type CommissionParams
• type Config
  • func DefaultConfig() Config
• type Device
  • func FindCommissionable(ctx context.Context, timeout time.Duration) ([]*Device, error)
  • func FindOperational(ctx context.Context, timeout time.Duration) ([]*Device, error)
• type Session
  • func (s *Session) Invoke(ctx context.Context, endpoint uint16, clusterID, commandID uint32, request any) ([]byte, error)
  • func (s *Session) ReadAttribute(ctx context.Context, endpoint uint16, clusterID, attributeID uint32) ([]byte, error)
  • func (s *Session) WriteAttribute(ctx context.Context, endpoint uint16, clusterID, attributeID uint32, ...) error
• type SetupPayload
  • func ParseSetupCode(code string) (*SetupPayload, error)

Types

type AttributeInfo

type AttributeInfo = clusters.AttributeInfo

AttributeInfo describes a single attribute within a cluster.

type Client

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

Client is the main entry point for interacting with Matter devices. It manages the underlying transport, session establishment, and interaction model operations.

func NewClient

func NewClient(cfg Config) (*Client, error)

NewClient creates a new Matter client with the given configuration.

func (*Client) Close

func (c *Client) Close() error

Close shuts down the client, releasing all resources.

func (*Client) Commission

func (c *Client) Commission(ctx context.Context, params CommissionParams) error

Commission commissions a new device using its setup code. The device must be in commissioning mode and discoverable via mDNS.

func (*Client) CommissionByIP

func (c *Client) CommissionByIP(ctx context.Context, addr string, passcode uint32, nodeID uint64) error

CommissionByIP commissions a device at a known IP address, bypassing mDNS discovery. This is useful for devices on different subnets or when mDNS is unreliable.

func (*Client) ConnectCASE

func (c *Client) ConnectCASE(ctx context.Context, addr string, nodeID uint64) (*Session, error)

ConnectCASE establishes an authenticated CASE session with a commissioned device identified by its node ID.

func (*Client) ConnectPASE

func (c *Client) ConnectPASE(ctx context.Context, addr string, passcode uint32) (*Session, error)

ConnectPASE establishes an unauthenticated PASE session with a device. This is typically only needed for low-level operations; Commission handles PASE automatically.

type ClusterInfo

type ClusterInfo = clusters.ClusterInfo

ClusterInfo describes a registered Matter cluster.

func AllClusters

func AllClusters() []ClusterInfo

AllClusters returns all registered cluster definitions.

func LookupCluster

func LookupCluster(name string) (*ClusterInfo, bool)

LookupCluster returns the cluster definition by name (case-insensitive).

func LookupClusterByID

func LookupClusterByID(id uint32) (*ClusterInfo, bool)

LookupClusterByID returns the cluster definition by numeric ID.

type CommandInfo

type CommandInfo = clusters.CommandInfo

CommandInfo describes a single command within a cluster.

type CommissionParams

type CommissionParams struct {
	// SetupCode is the device setup code (QR code "MT:..." or manual pairing code).
	SetupCode string
	// NodeID is the operational node ID to assign to the device.
	NodeID uint64
	// WiFiSSID and WiFiPassword provide WiFi credentials for network commissioning.
	WiFiSSID     string
	WiFiPassword string
	// ThreadDataset provides Thread network credentials for network commissioning.
	ThreadDataset []byte
}

CommissionParams holds parameters for commissioning a device.

type Config

type Config struct {
	// StorePath is the filesystem path for persistent storage.
	// If empty, an in-memory store is used.
	StorePath string
	// FabricID is the fabric identity to use. Defaults to 1.
	FabricID uint64
	// BindAddr is the local UDP address to bind to. Defaults to ":0".
	BindAddr string
}

Config holds configuration for creating a Client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults. It uses in-memory storage, fabric ID 1, and binds to a random port.

type Device

type Device = discovery.Device

Device represents a discovered Matter device on the network.

func FindCommissionable

func FindCommissionable(ctx context.Context, timeout time.Duration) ([]*Device, error)

FindCommissionable scans the local network for commissionable Matter devices. The timeout controls how long the mDNS browse runs.

func FindOperational

func FindOperational(ctx context.Context, timeout time.Duration) ([]*Device, error)

FindOperational scans the local network for operational Matter devices.

type Session

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

Session represents an active session with a Matter device.

func (*Session) Invoke

func (s *Session) Invoke(ctx context.Context, endpoint uint16, clusterID, commandID uint32, request any) ([]byte, error)

Invoke sends a command to a device and returns the response fields (if any). The request parameter should be a TLV-marshalable struct, or nil for commands that take no arguments.

func (*Session) ReadAttribute

func (s *Session) ReadAttribute(ctx context.Context, endpoint uint16, clusterID, attributeID uint32) ([]byte, error)

ReadAttribute reads a single attribute from a device over an established session. It returns the raw TLV-encoded attribute value.

func (*Session) WriteAttribute

func (s *Session) WriteAttribute(ctx context.Context, endpoint uint16, clusterID, attributeID uint32, value []byte) error

WriteAttribute writes a TLV-encoded value to a single attribute.

type SetupPayload

type SetupPayload = commissioning.SetupPayload

SetupPayload contains the information parsed from a Matter setup code.

func ParseSetupCode

func ParseSetupCode(code string) (*SetupPayload, error)

ParseSetupCode parses a Matter QR code (starting with "MT:") or a manual pairing code (numeric string) and returns the decoded SetupPayload.