Skip to content

Commit 67cc8a8

Browse files
committed
[Python] Make Commissioning APIs more pythonic and consistent
This commit makes the commissioning APIs more pythonic and consistent by not returning PyChipError but simply raising ChipStackError exceptions on errors instead. The return value instead returns the effectively assigned node ID as defined by the NOC. If the SDK ends up generating that NOC, it will use the thing passed to PairDevice, so those will match with what is provided when calling the commissioning API.
1 parent c955d03 commit 67cc8a8

File tree

1 file changed

+44
-19
lines changed

1 file changed

+44
-19
lines changed

src/controller/python/chip/ChipDeviceCtrl.py

+44-19
Original file line numberDiff line numberDiff line change
@@ -230,11 +230,14 @@ class CommissionableNode(discovery.CommissionableNode):
230230
def SetDeviceController(self, devCtrl: 'ChipDeviceController'):
231231
self._devCtrl = devCtrl
232232

233-
def Commission(self, nodeId: int, setupPinCode: int) -> PyChipError:
233+
def Commission(self, nodeId: int, setupPinCode: int) -> int:
234234
''' Commission the device using the device controller discovered this device.
235235
236236
nodeId: The nodeId commissioned to the device
237237
setupPinCode: The setup pin code of the device
238+
239+
Returns:
240+
- Effective Node ID of the device (as defined by the assigned NOC)
238241
'''
239242
return self._devCtrl.CommissionOnNetwork(
240243
nodeId, setupPinCode, filterType=discovery.FilterType.INSTANCE_NAME, filter=self.instanceName)
@@ -360,7 +363,10 @@ def HandleCommissioningComplete(nodeId: int, err: PyChipError):
360363
logging.exception("HandleCommissioningComplete called unexpectedly")
361364
return
362365

363-
self._commissioning_complete_future.set_result(err)
366+
if err.is_success:
367+
self._commissioning_complete_future.set_result(nodeId)
368+
else:
369+
self._commissioning_complete_future.set_exception(err.to_exception())
364370

365371
def HandleFabricCheck(nodeId):
366372
self.fabricCheckNodeId = nodeId
@@ -408,7 +414,7 @@ def HandlePASEEstablishmentComplete(err: PyChipError):
408414
# During Commissioning, HandlePASEEstablishmentComplete will also be called.
409415
# Only complete the future if PASE session establishment failed.
410416
if not err.is_success:
411-
self._commissioning_complete_future.set_result(err)
417+
self._commissioning_complete_future.set_exception(err.to_exception())
412418
return
413419

414420
if self._pase_establishment_complete_future is None:
@@ -533,7 +539,12 @@ def IsConnected(self):
533539
self.devCtrl)
534540
)
535541

536-
def ConnectBLE(self, discriminator: int, setupPinCode: int, nodeid: int, isShortDiscriminator: bool = False) -> PyChipError:
542+
def ConnectBLE(self, discriminator: int, setupPinCode: int, nodeid: int, isShortDiscriminator: bool = False) -> int:
543+
"""Connect to a BLE device using the given discriminator and setup pin code.
544+
545+
Returns:
546+
- Effective Node ID of the device (as defined by the assigned NOC)
547+
"""
537548
self.CheckIsActive()
538549

539550
self._commissioning_complete_future = concurrent.futures.Future()
@@ -545,11 +556,7 @@ def ConnectBLE(self, discriminator: int, setupPinCode: int, nodeid: int, isShort
545556
self.devCtrl, discriminator, isShortDiscriminator, setupPinCode, nodeid)
546557
).raise_on_error()
547558

548-
# TODO: Change return None. Only returning on success is not useful.
549-
# but that is what the previous implementation did.
550-
res = self._commissioning_complete_future.result()
551-
res.raise_on_error()
552-
return res
559+
return self._commissioning_complete_future.result()
553560
finally:
554561
self._commissioning_complete_future = None
555562

@@ -1853,17 +1860,19 @@ def caIndex(self) -> int:
18531860
def fabricAdmin(self) -> FabricAdmin:
18541861
return self._fabricAdmin
18551862

1856-
def Commission(self, nodeid) -> PyChipError:
1863+
def Commission(self, nodeid) -> int:
18571864
'''
18581865
Start the auto-commissioning process on a node after establishing a PASE connection.
18591866
This function is intended to be used in conjunction with `EstablishPASESessionBLE` or
18601867
`EstablishPASESessionIP`. It can be called either before or after the DevicePairingDelegate
18611868
receives the OnPairingComplete call. Commissioners that want to perform simple
1862-
auto-commissioning should use the supplied "PairDevice" functions above, which will
1869+
auto-commissioning should use the supplied "CommissionWithCode" function, which will
18631870
establish the PASE connection and commission automatically.
18641871
1865-
Return:
1866-
bool: True if successful, False otherwise.
1872+
Raises a ChipStackError on failure.
1873+
1874+
Returns:
1875+
- Effective Node ID of the device (as defined by the assigned NOC)
18671876
'''
18681877
self.CheckIsActive()
18691878

@@ -1879,13 +1888,13 @@ def Commission(self, nodeid) -> PyChipError:
18791888
finally:
18801889
self._commissioning_complete_future = None
18811890

1882-
def CommissionThread(self, discriminator, setupPinCode, nodeId, threadOperationalDataset: bytes, isShortDiscriminator: bool = False) -> PyChipError:
1891+
def CommissionThread(self, discriminator, setupPinCode, nodeId, threadOperationalDataset: bytes, isShortDiscriminator: bool = False) -> int:
18831892
''' Commissions a Thread device over BLE
18841893
'''
18851894
self.SetThreadOperationalDataset(threadOperationalDataset)
18861895
return self.ConnectBLE(discriminator, setupPinCode, nodeId, isShortDiscriminator)
18871896

1888-
def CommissionWiFi(self, discriminator, setupPinCode, nodeId, ssid: str, credentials: str, isShortDiscriminator: bool = False) -> PyChipError:
1897+
def CommissionWiFi(self, discriminator, setupPinCode, nodeId, ssid: str, credentials: str, isShortDiscriminator: bool = False) -> int:
18891898
''' Commissions a Wi-Fi device over BLE.
18901899
'''
18911900
self.SetWiFiCredentials(ssid, credentials)
@@ -1988,7 +1997,7 @@ def GetFabricCheckResult(self) -> int:
19881997
return self.fabricCheckNodeId
19891998

19901999
def CommissionOnNetwork(self, nodeId: int, setupPinCode: int,
1991-
filterType: DiscoveryFilterType = DiscoveryFilterType.NONE, filter: typing.Any = None, discoveryTimeoutMsec: int = 30000) -> PyChipError:
2000+
filterType: DiscoveryFilterType = DiscoveryFilterType.NONE, filter: typing.Any = None, discoveryTimeoutMsec: int = 30000) -> int:
19922001
'''
19932002
Does the routine for OnNetworkCommissioning, with a filter for mDNS discovery.
19942003
Supported filters are:
@@ -2004,6 +2013,11 @@ def CommissionOnNetwork(self, nodeId: int, setupPinCode: int,
20042013
DiscoveryFilterType.COMPRESSED_FABRIC_ID
20052014
20062015
The filter can be an integer, a string or None depending on the actual type of selected filter.
2016+
2017+
Raises a ChipStackError on failure.
2018+
2019+
Returns:
2020+
- Effective Node ID of the device (as defined by the assigned NOC)
20072021
'''
20082022
self.CheckIsActive()
20092023

@@ -2023,9 +2037,14 @@ def CommissionOnNetwork(self, nodeId: int, setupPinCode: int,
20232037
finally:
20242038
self._commissioning_complete_future = None
20252039

2026-
def CommissionWithCode(self, setupPayload: str, nodeid: int, discoveryType: DiscoveryType = DiscoveryType.DISCOVERY_ALL) -> PyChipError:
2040+
def CommissionWithCode(self, setupPayload: str, nodeid: int, discoveryType: DiscoveryType = DiscoveryType.DISCOVERY_ALL) -> int:
20272041
''' Commission with the given nodeid from the setupPayload.
20282042
setupPayload may be a QR or manual code.
2043+
2044+
Raises a ChipStackError on failure.
2045+
2046+
Returns:
2047+
- Effective Node ID of the device (as defined by the assigned NOC)
20292048
'''
20302049
self.CheckIsActive()
20312050

@@ -2042,8 +2061,14 @@ def CommissionWithCode(self, setupPayload: str, nodeid: int, discoveryType: Disc
20422061
finally:
20432062
self._commissioning_complete_future = None
20442063

2045-
def CommissionIP(self, ipaddr: str, setupPinCode: int, nodeid: int) -> PyChipError:
2046-
""" DEPRECATED, DO NOT USE! Use `CommissionOnNetwork` or `CommissionWithCode` """
2064+
def CommissionIP(self, ipaddr: str, setupPinCode: int, nodeid: int) -> int:
2065+
""" DEPRECATED, DO NOT USE! Use `CommissionOnNetwork` or `CommissionWithCode`
2066+
2067+
Raises a ChipStackError on failure.
2068+
2069+
Returns:
2070+
- Effective Node ID of the device (as defined by the assigned NOC)
2071+
"""
20472072
self.CheckIsActive()
20482073

20492074
self._commissioning_complete_future = concurrent.futures.Future()

0 commit comments

Comments
 (0)