0
# Home Assistant CHIP Clusters
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: home-assistant-chip-clusters
7
- **Language**: Python
8
- **Installation**: `pip install home-assistant-chip-clusters`
9

10
## Core Imports
11

12
```python
13
import chip.ChipDeviceCtrl
14
from chip.ChipDeviceCtrl import ChipDeviceController
15
```
16

17
Common for cluster operations:
18

19
```python
20
import chip.clusters
21
from chip.clusters import OnOff, LevelControl, ColorControl
22
```
23

24
## Basic Usage
25

26
```python
27
import chip.ChipDeviceCtrl
28
from chip.ChipDeviceCtrl import ChipDeviceController
29
from chip.FabricAdmin import FabricAdmin
30
import chip.clusters as Clusters
31
import asyncio
32

33
async def main():
34
    # Initialize fabric admin (required for controller)
35
    fabricAdmin = FabricAdmin()
36
    
37
    # Initialize the device controller
38
    controller = fabricAdmin.NewController(
39
        nodeId=12345,
40
        paaTrustStorePath=None,
41
        useTestCommissioner=False
42
    )
43

44
    # Commission a device
45
    await controller.CommissionOnNetwork(
46
        nodeId=1, 
47
        setupPinCode=20202021,
48
        filterType=None,
49
        filter=None
50
    )
51

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

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

61
    # Send a command (e.g., turn on)
62
    await controller.SendCommand(
63
        nodeid=1,
64
        endpoint=0,
65
        Clusters.OnOff.Commands.On()
66
    )
67

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

75
    # Clean shutdown
76
    controller.Shutdown()
77

78
# Run the async function
79
asyncio.run(main())
80
```
81

82
## Architecture
83

84
The Matter/CHIP Python library follows a layered architecture:
85

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

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

96
## Capabilities
97

98
### Device Control and Management
99

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

102
```python { .api }
103
class ChipDeviceController:
104
    def __init__(self, opCredsContext: ctypes.c_void_p, fabricId: int, nodeId: int, adminVendorId: int, **kwargs): ...
105
    async def CommissionOnNetwork(self, nodeId: int, setupPinCode: int, **kwargs): ...
106
    async def CommissionWithCode(self, setupPayload: str, nodeId: int, **kwargs): ...
107
    def GetConnectedDevice(self, nodeId: int, allowPASE: bool = False): ...
108
    async def ReadAttribute(self, nodeid: int, attributes: list, reportInterval: tuple = None, **kwargs): ...
109
    async def WriteAttribute(self, nodeid: int, attributes: list, **kwargs): ...
110
    async def SendCommand(self, nodeid: int, endpoint: int, command, **kwargs): ...
111
    def Shutdown(self): ...
112
```
113

114
[Device Controller](./device-controller.md)
115

116
### Matter Clusters
117

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

120
```python { .api }
121
class OnOff:
122
    class Attributes:
123
        OnOff: int
124
    class Commands:
125
        class On: ...
126
        class Off: ...
127
        class Toggle: ...
128

129
class LevelControl:
130
    class Attributes:
131
        CurrentLevel: int
132
        MinLevel: int
133
        MaxLevel: int
134
    class Commands:
135
        class MoveToLevel: ...
136
        class Move: ...
137
        class Step: ...
138

139
class ColorControl:
140
    class Attributes:
141
        CurrentHue: int
142
        CurrentSaturation: int
143
        ColorTemperatureMireds: int
144
    class Commands:
145
        class MoveToHue: ...
146
        class MoveToSaturation: ...
147
        class MoveToColorTemperature: ...
148
```
149

150
[Matter Clusters](./clusters.md)
151

152
### BLE and Device Discovery
153

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

156
```python { .api }
157
class BleManager:
158
    def __init__(self): ...
159
    def scan(self, timeout: int = 10): ...
160
    def connect(self, identifier: str): ...
161
    def disconnect(self): ...
162

163
class DiscoveryManager:
164
    def __init__(self): ...
165
    def discover_commissionable_nodes(self, timeout: int = 30): ...
166
    def discover_operational_devices(self): ...
167
```
168

169
[BLE and Discovery](./ble-discovery.md)
170

171
### Stack Management
172

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

175
```python { .api }
176
class ChipStack:
177
    def __init__(self, persistentStoragePath: str = None, **kwargs): ...
178
    def Call(self, f): ...
179
    def CallAsync(self, f): ...
180
    def Shutdown(self): ...
181

182
class DeviceProxyWrapper:
183
    def __init__(self, device): ...
184
    def GetDevice(self): ...
185
```
186

187
[Stack Management](./stack-management.md)
188

189
### Persistent Storage
190

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

193
```python { .api }
194
class PersistentStorage:
195
    def __init__(self, path: str): ...
196
    def set(self, key: str, value: bytes): ...
197
    def get(self, key: str) -> bytes: ...
198
    def delete(self, key: str): ...
199
    def clear(self): ...
200
```
201

202
[Storage](./storage.md)
203

204
### Cryptographic Operations
205

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

208
```python { .api }
209
class CertificateAuthority:
210
    def __init__(self): ...
211
    def generate_noc_chain(self, csr: bytes, fabric_id: int, node_id: int): ...
212
    def get_root_cert(self) -> bytes: ...
213

214
class FabricAdmin:
215
    def __init__(self, fabricId: int): ...
216
    def generate_controller_noc_chain(self, node_id: int, cat_tags: list = None): ...
217
```
218

219
[Crypto and Credentials](./crypto-credentials.md)
220

221
### Protocol Data Handling
222

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

225
```python { .api }
226
class TLVWriter:
227
    def __init__(self): ...
228
    def put(self, tag: int, value): ...
229
    def finalize(self) -> bytes: ...
230

231
class TLVReader:
232
    def __init__(self, data: bytes): ...
233
    def get(self, tag: int): ...
234
    def get_all(self) -> dict: ...
235
```
236

237
[TLV Data Handling](./tlv-data.md)
238

239
## Common Types
240

241
```python { .api }
242
# Device and node identifiers
243
NodeId = int
244
FabricId = int
245
EndpointId = int
246
ClusterId = int
247
AttributeId = int
248
CommandId = int
249

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

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

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

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

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