[Python] Implement async friendly GetConnectedDevice (project-chip#32760)

* [Python] Implement async friendly GetConnectedDevice

Currently GetConnectedDeviceSync() is blocking e.g. when a new session
needs to be created. This is not asyncio friendly as it blocks the
whole event loop.

Implement a asyncio friendly variant GetConnectedDevice() which is
a co-routine function which can be awaited.

* Drop bracket

* Skip timeout only when passing None

Change semantics slightly to make 0 mean don't wait at all.

* Add API docs

Author: agners

src/controller/python/chip/ChipDeviceCtrl.py

@@ -787,8 +787,16 @@ def GetClusterHandler(self):
 
         return self._Cluster
 
-    def GetConnectedDeviceSync(self, nodeid, allowPASE=True, timeoutMs: int = None):
-        ''' Returns DeviceProxyWrapper upon success.'''
+    def GetConnectedDeviceSync(self, nodeid, allowPASE: bool = True, timeoutMs: int = None):
+        ''' Gets an OperationalDeviceProxy or CommissioneeDeviceProxy for the specified Node.
+
+        nodeId: Target's Node ID
+        allowPASE: Get a device proxy of a device being commissioned.
+        timeoutMs: Timeout for a timed invoke request. Omit or set to 'None' to indicate a non-timed request.
+
+        Returns:
+            - DeviceProxyWrapper on success
+        '''
         self.CheckIsActive()
 
         returnDevice = c_void_p(None)
@@ -824,7 +832,7 @@ def deviceAvailable(self, device, err):
         if returnDevice.value is None:
             with deviceAvailableCV:
                 timeout = None
-                if (timeoutMs):
+                if timeoutMs is not None:
                     timeout = float(timeoutMs) / 1000
 
                 ret = deviceAvailableCV.wait(timeout)
@@ -836,6 +844,64 @@ def deviceAvailable(self, device, err):
 
         return DeviceProxyWrapper(returnDevice, self._dmLib)
 
+    async def GetConnectedDevice(self, nodeid, allowPASE: bool = True, timeoutMs: int = None):
+        ''' Gets an OperationalDeviceProxy or CommissioneeDeviceProxy for the specified Node.
+
+        nodeId: Target's Node ID
+        allowPASE: Get a device proxy of a device being commissioned.
+        timeoutMs: Timeout for a timed invoke request. Omit or set to 'None' to indicate a non-timed request.
+
+        Returns:
+            - DeviceProxyWrapper on success
+        '''
+        self.CheckIsActive()
+
+        if allowPASE:
+            returnDevice = c_void_p(None)
+            res = self._ChipStack.Call(lambda: self._dmLib.pychip_GetDeviceBeingCommissioned(
+                self.devCtrl, nodeid, byref(returnDevice)), timeoutMs)
+            if res.is_success:
+                logging.info('Using PASE connection')
+                return DeviceProxyWrapper(returnDevice)
+
+        eventLoop = asyncio.get_running_loop()
+        future = eventLoop.create_future()
+
+        class DeviceAvailableClosure():
+            def __init__(self, loop, future: asyncio.Future):
+                self._returnDevice = c_void_p(None)
+                self._returnErr = None
+                self._event_loop = loop
+                self._future = future
+
+            def _deviceAvailable(self):
+                if self._returnDevice.value is not None:
+                    self._future.set_result(self._returnDevice)
+                else:
+                    self._future.set_exception(self._returnErr.to_exception())
+
+            def deviceAvailable(self, device, err):
+                self._returnDevice = c_void_p(device)
+                self._returnErr = err
+                self._event_loop.call_soon_threadsafe(self._deviceAvailable)
+                ctypes.pythonapi.Py_DecRef(ctypes.py_object(self))
+
+        closure = DeviceAvailableClosure(eventLoop, future)
+        ctypes.pythonapi.Py_IncRef(ctypes.py_object(closure))
+        self._ChipStack.Call(lambda: self._dmLib.pychip_GetConnectedDeviceByNodeId(
+            self.devCtrl, nodeid, ctypes.py_object(closure), _DeviceAvailableCallback),
+            timeoutMs).raise_on_error()
+
+        # The callback might have been received synchronously (during self._ChipStack.Call()).
+        # In that case the Future has already been set it will return immediately
+        if timeoutMs is not None:
+            timeout = float(timeoutMs) / 1000
+            await asyncio.wait_for(future, timeout=timeout)
+        else:
+            await future
+
+        return DeviceProxyWrapper(future.result(), self._dmLib)
+
     def ComputeRoundTripTimeout(self, nodeid, upperLayerProcessingTimeoutMs: int = 0):
         ''' Returns a computed timeout value based on the round-trip time it takes for the peer at the other end of the session to
             receive a message, process it and send it back. This is computed based on the session type, the type of transport,
@@ -900,7 +966,7 @@ async def TestOnlySendBatchCommands(self, nodeid: int, commands: typing.List[Clu
         eventLoop = asyncio.get_running_loop()
         future = eventLoop.create_future()
 
-        device = self.GetConnectedDeviceSync(nodeid, timeoutMs=interactionTimeoutMs)
+        device = await self.GetConnectedDevice(nodeid, timeoutMs=interactionTimeoutMs)
 
         ClusterCommand.TestOnlySendBatchCommands(
             future, eventLoop, device.deviceProxy, commands,
@@ -921,7 +987,7 @@ async def TestOnlySendCommandTimedRequestFlagWithNoTimedInvoke(self, nodeid: int
         eventLoop = asyncio.get_running_loop()
         future = eventLoop.create_future()
 
-        device = self.GetConnectedDeviceSync(nodeid, timeoutMs=None)
+        device = await self.GetConnectedDevice(nodeid, timeoutMs=None)
         ClusterCommand.TestOnlySendCommandTimedRequestFlagWithNoTimedInvoke(
             future, eventLoop, responseType, device.deviceProxy, ClusterCommand.CommandPath(
                 EndpointId=endpoint,
@@ -953,7 +1019,7 @@ async def SendCommand(self, nodeid: int, endpoint: int, payload: ClusterObjects.
         eventLoop = asyncio.get_running_loop()
         future = eventLoop.create_future()
 
-        device = self.GetConnectedDeviceSync(nodeid, timeoutMs=interactionTimeoutMs)
+        device = await self.GetConnectedDevice(nodeid, timeoutMs=interactionTimeoutMs)
         ClusterCommand.SendCommand(
             future, eventLoop, responseType, device.deviceProxy, ClusterCommand.CommandPath(
                 EndpointId=endpoint,
@@ -994,7 +1060,7 @@ async def SendBatchCommands(self, nodeid: int, commands: typing.List[ClusterComm
         eventLoop = asyncio.get_running_loop()
         future = eventLoop.create_future()
 
-        device = self.GetConnectedDeviceSync(nodeid, timeoutMs=interactionTimeoutMs)
+        device = await self.GetConnectedDevice(nodeid, timeoutMs=interactionTimeoutMs)
 
         ClusterCommand.SendBatchCommands(
             future, eventLoop, device.deviceProxy, commands,
@@ -1044,7 +1110,7 @@ async def WriteAttribute(self, nodeid: int,
         eventLoop = asyncio.get_running_loop()
         future = eventLoop.create_future()
 
-        device = self.GetConnectedDeviceSync(nodeid, timeoutMs=interactionTimeoutMs)
+        device = await self.GetConnectedDevice(nodeid, timeoutMs=interactionTimeoutMs)
 
         attrs = []
         for v in attributes:
@@ -1272,7 +1338,7 @@ async def Read(self, nodeid: int, attributes: typing.List[typing.Union[
         eventLoop = asyncio.get_running_loop()
         future = eventLoop.create_future()
 
-        device = self.GetConnectedDeviceSync(nodeid)
+        device = await self.GetConnectedDevice(nodeid)
         attributePaths = [self._parseAttributePathTuple(
             v) for v in attributes] if attributes else None
         clusterDataVersionFilters = [self._parseDataVersionFilterTuple(