or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ble-discovery.mdclusters.mdcrypto-credentials.mddevice-controller.mdindex.mdstack-management.mdstorage.mdtlv-data.md
tile.json

tessl/pypi-home-assistant-chip-clusters

Python APIs and tools for Matter (Project CHIP) protocol implementation, specifically the chip clusters functionality used by Home Assistant for Matter device control and communication

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/home-assistant-chip-clusters@2024.11.x

To install, run

npx @tessl/cli install tessl/pypi-home-assistant-chip-clusters@2024.11.0

index.mddocs/

Home Assistant CHIP Clusters

A comprehensive Python library providing APIs and tools for Matter (Project CHIP) protocol implementation. This package enables Home Assistant and other applications to control and communicate with Matter-compatible smart home devices through cluster-based interactions, device commissioning, and protocol operations.

Package Information

  • Package Name: home-assistant-chip-clusters
  • Language: Python
  • Installation: pip install home-assistant-chip-clusters

Core Imports

import chip.ChipDeviceCtrl
from chip.ChipDeviceCtrl import ChipDeviceController

Common for cluster operations:

import chip.clusters
from chip.clusters import OnOff, LevelControl, ColorControl

Basic Usage

import chip.ChipDeviceCtrl
from chip.ChipDeviceCtrl import ChipDeviceController
from chip.FabricAdmin import FabricAdmin
import chip.clusters as Clusters
import asyncio

async def main():
    # Initialize fabric admin (required for controller)
    fabricAdmin = FabricAdmin()
    
    # Initialize the device controller
    controller = fabricAdmin.NewController(
        nodeId=12345,
        paaTrustStorePath=None,
        useTestCommissioner=False
    )

    # Commission a device
    await controller.CommissionOnNetwork(
        nodeId=1, 
        setupPinCode=20202021,
        filterType=None,
        filter=None
    )

    # Get connected device
    device = controller.GetConnectedDevice(nodeId=1, allowPASE=False)

    # Read an attribute (e.g., OnOff state)
    onoff_state = await controller.ReadAttribute(
        nodeid=1,
        attributes=[(0, Clusters.OnOff.Attributes.OnOff)]
    )

    # Send a command (e.g., turn on)
    await controller.SendCommand(
        nodeid=1,
        endpoint=0,
        Clusters.OnOff.Commands.On()
    )

    # Subscribe to attribute changes (using ReadAttribute with reportInterval)
    subscription = await controller.ReadAttribute(
        nodeid=1,
        attributes=[(0, Clusters.OnOff.Attributes.OnOff)],
        reportInterval=(1, 10)  # Min 1s, Max 10s intervals
    )

    # Clean shutdown
    controller.Shutdown()

# Run the async function
asyncio.run(main())

Architecture

The Matter/CHIP Python library follows a layered architecture:

  • ChipStack: Core Matter stack initialization and thread management
  • ChipDeviceController: Main device controller for fabric management and device communication
  • Clusters: Matter cluster implementations (170+ cluster types) for device interaction
  • BLE/Discovery: Device discovery and Bluetooth Low Energy connectivity
  • Storage: Persistent storage for device credentials and configuration
  • TLV: Tag-Length-Value encoding/decoding for Matter protocol data
  • Crypto/Credentials: Security and certificate management

This design enables comprehensive Matter ecosystem support, from device discovery and commissioning to ongoing cluster-based device control and monitoring.

Capabilities

Device Control and Management

Core device controller functionality for Matter fabric management, device commissioning, and communication. Provides the primary interface for interacting with Matter devices.

class ChipDeviceController:
    def __init__(self, opCredsContext: ctypes.c_void_p, fabricId: int, nodeId: int, adminVendorId: int, **kwargs): ...
    async def CommissionOnNetwork(self, nodeId: int, setupPinCode: int, **kwargs): ...
    async def CommissionWithCode(self, setupPayload: str, nodeId: int, **kwargs): ...
    def GetConnectedDevice(self, nodeId: int, allowPASE: bool = False): ...
    async def ReadAttribute(self, nodeid: int, attributes: list, reportInterval: tuple = None, **kwargs): ...
    async def WriteAttribute(self, nodeid: int, attributes: list, **kwargs): ...
    async def SendCommand(self, nodeid: int, endpoint: int, command, **kwargs): ...
    def Shutdown(self): ...

Device Controller

Matter Clusters

Complete implementation of Matter clusters (170+ cluster types) providing standardized device interaction patterns for smart home devices including lighting, sensors, HVAC, security, and more.

class OnOff:
    class Attributes:
        OnOff: int
    class Commands:
        class On: ...
        class Off: ...
        class Toggle: ...

class LevelControl:
    class Attributes:
        CurrentLevel: int
        MinLevel: int
        MaxLevel: int
    class Commands:
        class MoveToLevel: ...
        class Move: ...
        class Step: ...

class ColorControl:
    class Attributes:
        CurrentHue: int
        CurrentSaturation: int
        ColorTemperatureMireds: int
    class Commands:
        class MoveToHue: ...
        class MoveToSaturation: ...
        class MoveToColorTemperature: ...

Matter Clusters

BLE and Device Discovery

Bluetooth Low Energy connectivity and device discovery functionality for finding and connecting to Matter devices during commissioning and setup.

class BleManager:
    def __init__(self): ...
    def scan(self, timeout: int = 10): ...
    def connect(self, identifier: str): ...
    def disconnect(self): ...

class DiscoveryManager:
    def __init__(self): ...
    def discover_commissionable_nodes(self, timeout: int = 30): ...
    def discover_operational_devices(self): ...

BLE and Discovery

Stack Management

Core Matter stack initialization, configuration, and lifecycle management providing the foundation for all Matter protocol operations.

class ChipStack:
    def __init__(self, persistentStoragePath: str = None, **kwargs): ...
    def Call(self, f): ...
    def CallAsync(self, f): ...
    def Shutdown(self): ...

class DeviceProxyWrapper:
    def __init__(self, device): ...
    def GetDevice(self): ...

Stack Management

Persistent Storage

Storage interfaces for device credentials, fabric information, and configuration persistence across application restarts.

class PersistentStorage:
    def __init__(self, path: str): ...
    def set(self, key: str, value: bytes): ...
    def get(self, key: str) -> bytes: ...
    def delete(self, key: str): ...
    def clear(self): ...

Storage

Cryptographic Operations

Security and cryptographic functionality including certificate management, fabric credentials, and secure communication setup.

class CertificateAuthority:
    def __init__(self): ...
    def generate_noc_chain(self, csr: bytes, fabric_id: int, node_id: int): ...
    def get_root_cert(self) -> bytes: ...

class FabricAdmin:
    def __init__(self, fabricId: int): ...
    def generate_controller_noc_chain(self, node_id: int, cat_tags: list = None): ...

Crypto and Credentials

Protocol Data Handling

TLV (Tag-Length-Value) encoding and decoding for Matter protocol data structures, enabling low-level protocol operations and custom data handling.

class TLVWriter:
    def __init__(self): ...
    def put(self, tag: int, value): ...
    def finalize(self) -> bytes: ...

class TLVReader:
    def __init__(self, data: bytes): ...
    def get(self, tag: int): ...
    def get_all(self) -> dict: ...

TLV Data Handling

Common Types

# Device and node identifiers
NodeId = int
FabricId = int
EndpointId = int
ClusterId = int
AttributeId = int
CommandId = int

# Status and error codes
class ChipStackException(Exception):
    def __init__(self, err: int, msg: str = None): ...

# Attribute and command structures
class AttributePath:
    def __init__(self, EndpointId: int = None, ClusterId: int = None, AttributeId: int = None): ...

class CommandPath:
    def __init__(self, EndpointId: int, ClusterId: int, CommandId: int): ...

# Subscription and event handling
class SubscriptionParameters:
    def __init__(self, min_interval: int, max_interval: int): ...

class EventPathType:
    def __init__(self, EndpointId: int = None, ClusterId: int = None, EventId: int = None): ...