0
# Device Controller
1

2
Core device controller functionality for Matter fabric management, device commissioning, and communication. The ChipDeviceController class provides the primary interface for interacting with Matter devices.
3

4
## Capabilities
5

6
### Device Controller Initialization
7

8
Creates and configures a device controller instance for managing Matter devices within a fabric.
9

10
```python { .api }
11
class ChipDeviceController:
12
    def __init__(
13
        self,
14
        opCredsContext: ctypes.c_void_p,
15
        fabricId: int,
16
        nodeId: int,
17
        adminVendorId: int,
18
        catTags: list = [],
19
        paaTrustStorePath: str = "",
20
        useTestCommissioner: bool = False,
21
        fabricAdmin: FabricAdmin = None,
22
        name: str = "",
23
        keypair: P256Keypair = None
24
    ):
25
        """
26
        Initialize a CHIP Device Controller.
27

28
        Parameters:
29
        - opCredsContext: Operational credentials context
30
        - fabricId: Fabric ID for this controller
31
        - nodeId: Node ID for this controller
32
        - adminVendorId: Administrator vendor ID
33
        - catTags: List of CASE Authenticated Tags
34
        - paaTrustStorePath: Path to PAA trust store certificates
35
        - useTestCommissioner: Whether to use test commissioner credentials
36
        - fabricAdmin: Fabric administrator instance
37
        - name: Name for this controller
38
        - keypair: Optional P256 keypair for this controller
39
        """
40
```
41

42
### Device Commissioning
43

44
Commission new Matter devices into the fabric using network-based or code-based methods.
45

46
```python { .api }
47
async def CommissionOnNetwork(
48
    self,
49
    nodeId: int,
50
    setupPinCode: int,
51
    filterType: int = None,
52
    filter: str = None,
53
    discoveryTimeoutMsec: int = 30000
54
) -> bool:
55
    """
56
    Commission a device over the network.
57

58
    Parameters:
59
    - nodeId: Target node ID for the device
60
    - setupPinCode: Device setup PIN code
61
    - filterType: Discovery filter type (0=None, 1=Short Discriminator, 2=Long Discriminator, 3=Vendor ID, 4=Device Type)
62
    - filter: Filter value based on filterType
63
    - discoveryTimeoutMsec: Discovery timeout in milliseconds
64

65
    Returns:
66
    True if commissioning started successfully
67
    """
68

69
async def CommissionWithCode(
70
    self,
71
    setupPayload: str,
72
    nodeId: int,
73
    discoveryType: int = 0
74
) -> bool:
75
    """
76
    Commission a device using setup payload (QR code or manual code).
77

78
    Parameters:
79
    - setupPayload: Setup payload string from QR code or manual entry
80
    - nodeId: Target node ID for the device
81
    - discoveryType: Discovery method (0=Network Only, 1=BLE Only, 2=On Network, 3=BLE WiFi, 4=BLE Thread)
82

83
    Returns:
84
    True if commissioning started successfully
85
    """
86
```
87

88
### Device Connection Management
89

90
Manage connections to commissioned devices and retrieve device proxy objects.
91

92
```python { .api }
93
def GetConnectedDevice(
94
    self,
95
    nodeId: int,
96
    allowPASE: bool = False,
97
    timeoutMs: int = None
98
):
99
    """
100
    Get a connected device proxy for the specified node.
101

102
    Parameters:
103
    - nodeId: Node ID of the target device
104
    - allowPASE: Allow PASE (password-authenticated session establishment) connections
105
    - timeoutMs: Connection timeout in milliseconds
106

107
    Returns:
108
    Device proxy object for interacting with the device
109
    """
110

111
def IsConnected(self, nodeId: int) -> bool:
112
    """
113
    Check if a device is currently connected.
114

115
    Parameters:
116
    - nodeId: Node ID to check
117

118
    Returns:
119
    True if device is connected
120
    """
121
```
122

123
### Attribute Operations
124

125
Read, write, and subscribe to device attributes using the Matter interaction model.
126

127
```python { .api }
128
async def ReadAttribute(
129
    self,
130
    nodeid: int,
131
    attributes: list,
132
    fabricFiltered: bool = True,
133
    returnRawTLV: bool = False,
134
    suppressResponse: bool = False,
135
    reportInterval: tuple = None,
136
    keepSubscriptions: bool = False,
137
    autoResubscribe: bool = True
138
):
139
    """
140
    Read attributes from a device.
141

142
    Parameters:
143
    - nodeid: Target device node ID
144
    - attributes: List of (endpoint, attribute) tuples or AttributePath objects
145
    - fabricFiltered: Filter attributes by current fabric
146
    - returnRawTLV: Return raw TLV data instead of decoded values
147
    - suppressResponse: Suppress response for write operations
148
    - reportInterval: Tuple of (min_interval, max_interval) for subscriptions
149
    - keepSubscriptions: Keep existing subscriptions when creating new ones
150
    - autoResubscribe: Automatically resubscribe on connection loss
151

152
    Returns:
153
    Dictionary of attribute values keyed by (endpoint, cluster, attribute)
154
    """
155

156
async def WriteAttribute(
157
    self,
158
    nodeid: int,
159
    attributes: list,
160
    timedRequestTimeoutMs: int = None,
161
    interactionTimeoutMs: int = None,
162
    suppressResponse: bool = False
163
):
164
    """
165
    Write attributes to a device.
166

167
    Parameters:
168
    - nodeid: Target device node ID
169
    - attributes: List of (endpoint, attribute, value) tuples
170
    - timedRequestTimeoutMs: Timeout for timed requests
171
    - interactionTimeoutMs: Overall interaction timeout
172
    - suppressResponse: Suppress write response
173

174
    Returns:
175
    Write response status
176
    """
177

178
async def ReadAttribute(
179
    self,
180
    nodeid: int,
181
    attributes: list,
182
    reportInterval: tuple = None,
183
    keepSubscriptions: bool = False,
184
    autoResubscribe: bool = True,
185
    fabricFiltered: bool = True,
186
    **kwargs
187
):
188
    """
189
    Read attributes from a device. When reportInterval is provided, creates a subscription instead of a one-time read.
190

191
    Parameters:
192
    - nodeid: Target device node ID
193
    - attributes: List of (endpoint, attribute) tuples or AttributePath objects
194
    - reportInterval: Tuple of (min_interval, max_interval) in seconds. When provided, creates subscription.
195
    - keepSubscriptions: Keep existing subscriptions when creating new ones
196
    - autoResubscribe: Automatically resubscribe on connection loss
197
    - fabricFiltered: Filter attributes by current fabric
198

199
    Returns:
200
    Dictionary of attribute values for one-time read, or SubscriptionTransaction object for subscriptions
201
    """
202
```
203

204
### Command Operations
205

206
Send cluster commands to devices and handle responses.
207

208
```python { .api }
209
async def SendCommand(
210
    self,
211
    nodeid: int,
212
    endpoint: int,
213
    command,
214
    timedRequestTimeoutMs: int = None,
215
    interactionTimeoutMs: int = None,
216
    busyWaitMs: int = None,
217
    suppressResponse: bool = False,
218
    remotePassiveTimeout: int = None,
219
    suppressTimedRequestMessage: bool = False,
220
    responseCallback=None
221
):
222
    """
223
    Send a cluster command to a device.
224

225
    Parameters:
226
    - nodeid: Target device node ID
227
    - endpoint: Target endpoint ID
228
    - command: Cluster command object
229
    - timedRequestTimeoutMs: Timeout for timed requests
230
    - interactionTimeoutMs: Overall interaction timeout
231
    - busyWaitMs: Busy wait timeout
232
    - suppressResponse: Suppress command response
233
    - remotePassiveTimeout: Remote passive timeout
234
    - suppressTimedRequestMessage: Suppress timed request message
235
    - responseCallback: Callback for command response
236

237
    Returns:
238
    Command response or None if suppressResponse=True
239
    """
240

241
def SendGroupCommand(
242
    self,
243
    groupid: int,
244
    command,
245
    busyWaitMs: int = None
246
):
247
    """
248
    Send a command to a group of devices.
249

250
    Parameters:
251
    - groupid: Target group ID
252
    - command: Cluster command object
253
    - busyWaitMs: Busy wait timeout
254

255
    Returns:
256
    Command response
257
    """
258
```
259

260
### Device Management
261

262
Additional device management operations including fabric and group management.
263

264
```python { .api }
265
def RemoveDevice(self, nodeid: int):
266
    """
267
    Remove a device from the fabric.
268

269
    Parameters:
270
    - nodeid: Node ID of device to remove
271
    """
272

273
def SetWiFiCredentials(self, ssid: str, credentials: str):
274
    """
275
    Set WiFi credentials for device commissioning.
276

277
    Parameters:
278
    - ssid: WiFi network SSID
279
    - credentials: WiFi password
280
    """
281

282
def SetThreadOperationalDataset(self, threadOperationalDataset: bytes):
283
    """
284
    Set Thread operational dataset for device commissioning.
285

286
    Parameters:
287
    - threadOperationalDataset: Thread network dataset
288
    """
289

290
def Shutdown(self):
291
    """
292
    Clean shutdown of the device controller.
293
    Closes all connections and releases resources.
294
    """
295
```
296

297
## Usage Examples
298

299
### Basic Device Control
300

301
```python
302
import chip.ChipDeviceCtrl
303
from chip.ChipDeviceCtrl import ChipDeviceController
304
from chip.FabricAdmin import FabricAdmin
305
import chip.clusters as Clusters
306
import asyncio
307

308
async def main():
309
    # Initialize fabric admin and controller
310
    fabricAdmin = FabricAdmin()
311
    controller = fabricAdmin.NewController(
312
        nodeId=12345,
313
        paaTrustStorePath=None,
314
        useTestCommissioner=False
315
    )
316

317
    # Commission a device
318
    await controller.CommissionOnNetwork(
319
        nodeId=1,
320
        setupPinCode=20202021,
321
        discoveryTimeoutMsec=30000
322
    )
323

324
    # Read device basic information
325
    basic_info = await controller.ReadAttribute(
326
        nodeid=1,
327
        attributes=[(0, Clusters.BasicInformation.Attributes.VendorName),
328
                   (0, Clusters.BasicInformation.Attributes.ProductName)]
329
    )
330
    
331
    # Control an OnOff device
332
    await controller.SendCommand(
333
        nodeid=1,
334
        endpoint=1,
335
        Clusters.OnOff.Commands.On()
336
    )
337

338
    # Clean shutdown
339
    controller.Shutdown()
340

341
# Run the async function
342
asyncio.run(main())
343
```
344

345
### Subscription Handling
346

347
```python
348
# Subscribe to attribute changes using ReadAttribute with reportInterval
349
subscription = await controller.ReadAttribute(
350
    nodeid=1,
351
    attributes=[(1, Clusters.OnOff.Attributes.OnOff),
352
               (1, Clusters.LevelControl.Attributes.CurrentLevel)],
353
    reportInterval=(1, 10)  # Report changes every 1-10 seconds
354
)
355

356
# Set up callbacks to handle subscription updates
357
def attribute_update_callback(path, transaction):
358
    print(f"Attribute updated: {path}")
359

360
subscription.SetAttributeUpdateCallback(attribute_update_callback)
361
```