BDX transfer support for Python tests

src/controller/python/BUILD.gn

@@ -63,6 +63,11 @@ shared_library("ChipDeviceCtrl") {
       "ChipDeviceController-StorageDelegate.cpp",
       "ChipDeviceController-StorageDelegate.h",
       "OpCredsBinding.cpp",
+      "chip/bdx/bdx-transfer.cpp",
+      "chip/bdx/bdx-transfer.h",
+      "chip/bdx/bdx.cpp",
+      "chip/bdx/test-bdx-transfer-server.cpp",
+      "chip/bdx/test-bdx-transfer-server.h",
       "chip/clusters/attribute.cpp",
       "chip/clusters/command.cpp",
       "chip/commissioning/PlaceholderOperationalCredentialsIssuer.h",
@@ -166,6 +171,9 @@ chip_python_wheel_action("chip-core") {
         "chip/ChipStack.py",
         "chip/FabricAdmin.py",
         "chip/__init__.py",
+        "chip/bdx/Bdx.py",
+        "chip/bdx/BdxTransfer.py",
+        "chip/bdx/__init__.py",
         "chip/ble/__init__.py",
         "chip/ble/commissioning/__init__.py",
         "chip/ble/get_adapters.py",
@@ -235,6 +243,7 @@ chip_python_wheel_action("chip-core") {
 
   py_packages = [
     "chip",
+    "chip.bdx",
     "chip.ble",
     "chip.ble.commissioning",
     "chip.configuration",

src/controller/python/chip/ChipDeviceCtrl.py

@@ -48,6 +48,7 @@
 from . import FabricAdmin
 from . import clusters as Clusters
 from . import discovery
+from .bdx import Bdx
 from .clusters import Attribute as ClusterAttribute
 from .clusters import ClusterObjects as ClusterObjects
 from .clusters import Command as ClusterCommand
@@ -1343,6 +1344,36 @@ def WriteGroupAttribute(
         # An empty list is the expected return for sending group write attribute.
         return []
 
+    def TestOnlyPrepareToReceiveBdxData(self) -> asyncio.Future:
+        '''
+        Sets up the system to expect a node to initiate a BDX transfer. The transfer will send data here.
+
+        Returns:
+            - a future that will yield a BdxTransfer with the init message from the transfer.
+        '''
+        self.CheckIsActive()
+
+        eventLoop = asyncio.get_running_loop()
+        future = eventLoop.create_future()
+
+        Bdx.PrepareToReceiveBdxData(future).raise_on_error()
+        return future
+
+    def TestOnlyPrepareToSendBdxData(self, data: bytes) -> asyncio.Future:
+        '''
+        Sets up the system to expect a node to initiate a BDX transfer. The transfer will send data to the node.
+
+        Returns:
+            - a future that will yield a BdxTransfer with the init message from the transfer.
+        '''
+        self.CheckIsActive()
+
+        eventLoop = asyncio.get_running_loop()
+        future = eventLoop.create_future()
+
+        Bdx.PrepareToSendBdxData(future, data).raise_on_error()
+        return future
+
     def _parseAttributePathTuple(self, pathTuple: typing.Union[
         None,  # Empty tuple, all wildcard
         typing.Tuple[int],  # Endpoint

src/controller/python/chip/ChipStack.py

@@ -36,6 +36,7 @@
 import chip.native
 from chip.native import PyChipError
 
+from .bdx import Bdx
 from .clusters import Attribute as ClusterAttribute
 from .clusters import Command as ClusterCommand
 from .exceptions import ChipStackError, ChipStackException, DeviceError
@@ -175,6 +176,7 @@ def HandleChipThreadRun(callback):
         im.InitIMDelegate()
         ClusterAttribute.Init()
         ClusterCommand.Init()
+        Bdx.Init()
 
         builtins.chipStack = self
 

src/controller/python/chip/bdx/Bdx.py

@@ -0,0 +1,184 @@
+#
+#    Copyright (c) 2024 Project CHIP Authors
+#    All rights reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+
+import asyncio
+import builtins
+import ctypes
+from asyncio.futures import Future
+from ctypes import CFUNCTYPE, POINTER, c_char_p, c_size_t, c_uint8, c_uint16, c_uint64, c_void_p, py_object
+
+import chip
+from chip.native import PyChipError
+
+from . import BdxTransfer
+
+c_uint8_p = POINTER(c_uint8)
+
+
+_OnTransferObtainedCallbackFunct = CFUNCTYPE(
+    None, py_object, c_void_p, c_uint8, c_uint16, c_uint64, c_uint64, c_uint8_p, c_uint16, c_uint8_p, c_size_t)
+_OnFailedToObtainTransferCallbackFunct = CFUNCTYPE(None, py_object, PyChipError)
+_OnDataReceivedCallbackFunct = CFUNCTYPE(None, py_object, c_uint8_p, c_size_t)
+_OnTransferCompletedCallbackFunct = CFUNCTYPE(None, py_object, PyChipError)
+
+
+class AsyncTransferObtainedTransaction:
+    def __init__(self, future, event_loop, data=None):
+        self._future = future
+        self._data = data
+        self._event_loop = event_loop
+
+    def _handleTransfer(self, bdxTransfer, initMessage: BdxTransfer.InitMessage):
+        transfer = BdxTransfer.BdxTransfer(bdx_transfer=bdxTransfer, init_message=initMessage, data=self._data)
+        self._future.set_result(transfer)
+
+    def handleTransfer(self, bdxTransfer, initMessage: BdxTransfer.InitMessage):
+        self._event_loop.call_soon_threadsafe(self._handleTransfer, bdxTransfer, initMessage)
+
+    def _handleError(self, result: PyChipError):
+        self._future.set_exception(result.to_exception())
+
+    def handleError(self, result: PyChipError):
+        self._event_loop.call_soon_threadsafe(self._handleError, result)
+
+
+class AsyncTransferCompletedTransaction:
+    def __init__(self, future, event_loop):
+        self._future = future
+        self._event_loop = event_loop
+
+    def _handleResult(self, result: PyChipError):
+        if result.is_success:
+            self._future.set_result(result)
+        else:
+            self._future.set_exception(result.to_exception())
+
+    def handleResult(self, result: PyChipError):
+        self._event_loop.call_soon_threadsafe(self._handleResult, result)
+
+
+@_OnTransferObtainedCallbackFunct
+def _OnTransferObtainedCallback(transaction: AsyncTransferObtainedTransaction, bdxTransfer, transferControlFlags: int,
+                                maxBlockSize: int, startOffset: int, length: int, fileDesignator, fileDesignatorLength: int,
+                                metadata, metadataLength: int):
+    fileDesignatorData = ctypes.string_at(fileDesignator, fileDesignatorLength)
+    metadataData = ctypes.string_at(metadata, metadataLength)
+
+    initMessage = BdxTransfer.InitMessage(
+        transferControlFlags,
+        maxBlockSize,
+        startOffset,
+        length,
+        fileDesignatorData[:],
+        metadataData[:],
+    )
+
+    transaction.handleTransfer(bdxTransfer, initMessage)
+
+
+@_OnFailedToObtainTransferCallbackFunct
+def _OnFailedToObtainTransferCallback(transaction: AsyncTransferObtainedTransaction, result: PyChipError):
+    transaction.handleError(result)
+
+
+@_OnDataReceivedCallbackFunct
+def _OnDataReceivedCallback(context, dataBuffer: c_uint8_p, bufferLength: int):
+    data = ctypes.string_at(dataBuffer, bufferLength)
+    context(data)
+
+
+@_OnTransferCompletedCallbackFunct
+def _OnTransferCompletedCallback(transaction: AsyncTransferCompletedTransaction, result: PyChipError):
+    transaction.handleResult(result)
+
+
+def PrepareToReceiveBdxData(future: Future) -> PyChipError:
+    handle = chip.native.GetLibraryHandle()
+    transaction = AsyncTransferObtainedTransaction(future=future, event_loop=asyncio.get_running_loop())
+
+    ctypes.pythonapi.Py_IncRef(ctypes.py_object(transaction))
+    res = builtins.chipStack.Call(
+        lambda: handle.pychip_Bdx_ExpectBdxTransfer(ctypes.py_object(transaction))
+    )
+    if not res.is_success:
+        ctypes.pythonapi.Py_DecRef(ctypes.py_object(transaction))
+    return res
+
+
+def PrepareToSendBdxData(future: Future, data: bytes) -> PyChipError:
+    handle = chip.native.GetLibraryHandle()
+    transaction = AsyncTransferObtainedTransaction(future=future, event_loop=asyncio.get_running_loop(), data=data)
+
+    ctypes.pythonapi.Py_IncRef(ctypes.py_object(transaction))
+    res = builtins.chipStack.Call(
+        lambda: handle.pychip_Bdx_ExpectBdxTransfer(ctypes.py_object(transaction))
+    )
+    if not res.is_success:
+        ctypes.pythonapi.Py_DecRef(ctypes.py_object(transaction))
+    return res
+
+
+def AcceptSendTransfer(transfer: c_void_p, dataReceivedClosure, transferComplete: Future):
+    handle = chip.native.GetLibraryHandle()
+    complete_transaction = AsyncTransferCompletedTransaction(future=transferComplete, event_loop=asyncio.get_running_loop())
+    ctypes.pythonapi.Py_IncRef(ctypes.py_object(dataReceivedClosure))
+    ctypes.pythonapi.Py_IncRef(ctypes.py_object(complete_transaction))
+    res = builtins.chipStack.Call(
+        lambda: handle.pychip_Bdx_AcceptSendTransfer(transfer, dataReceivedClosure, complete_transaction)
+    )
+    if not res.is_success:
+        ctypes.pythonapi.Py_DecRef(ctypes.py_object(dataReceivedClosure))
+        ctypes.pythonapi.Py_DecRef(ctypes.py_object(complete_transaction))
+    return res
+
+
+def AcceptReceiveTransfer(transfer: c_void_p, data: bytes, transferComplete: Future):
+    handle = chip.native.GetLibraryHandle()
+    return builtins.chipStack.Call(
+        lambda: handle.pychip_Bdx_AcceptReceiveTransfer(transfer, c_char_p(data), len(data), transferComplete)
+    )
+
+
+async def RejectTransfer(transfer: c_void_p):
+    handle = chip.native.GetLibraryHandle()
+    return await builtins.chipStack.CallAsyncWithResult(
+        lambda: handle.pychip_Bdx_RejectTransfer(transfer)
+    )
+
+
+def Init():
+    handle = chip.native.GetLibraryHandle()
+    # Uses one of the type decorators as an indicator for everything being initialized.
+    if not handle.pychip_Bdx_ExpectBdxTransfer.argtypes:
+        setter = chip.native.NativeLibraryHandleMethodArguments(handle)
+
+        setter.Set('pychip_Bdx_ExpectBdxTransfer',
+                   PyChipError, [py_object])
+        setter.Set('pychip_Bdx_StopExpectingBdxTransfer',
+                   PyChipError, [py_object])
+        setter.Set('pychip_Bdx_AcceptSendTransfer',
+                   PyChipError, [c_void_p, py_object, py_object])
+        setter.Set('pychip_Bdx_AcceptReceiveTransfer',
+                   PyChipError, [c_void_p, c_uint8_p, c_size_t])
+        setter.Set('pychip_Bdx_RejectTransfer',
+                   PyChipError, [c_void_p])
+        setter.Set('pychip_Bdx_InitCallbacks', None, [
+                   _OnTransferObtainedCallbackFunct, _OnFailedToObtainTransferCallbackFunct, _OnDataReceivedCallbackFunct,
+                   _OnTransferCompletedCallbackFunct])
+
+    handle.pychip_Bdx_InitCallbacks(
+        _OnTransferObtainedCallback, _OnFailedToObtainTransferCallback, _OnDataReceivedCallback, _OnTransferCompletedCallback)

src/controller/python/chip/bdx/BdxTransfer.py

@@ -0,0 +1,59 @@
+#
+#    Copyright (c) 2024 Project CHIP Authors
+#    All rights reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+
+import asyncio
+from ctypes import c_void_p
+from dataclasses import dataclass
+
+from . import Bdx
+
+
+@dataclass
+class InitMessage:
+    TransferControlFlags: int
+    MaxBlockSize: int
+    StartOffset: int
+    Length: int
+    FileDesignator: bytes
+    Metadata: bytes
+
+
+class BdxTransfer:
+    def __init__(self, bdx_transfer: c_void_p, init_message: InitMessage, data: bytes = None):
+        self.init_message = init_message
+        self._bdx_transfer = bdx_transfer
+        self._data = bytearray(data) if data else None
+
+    async def accept(self):
+        eventLoop = asyncio.get_running_loop()
+        future = eventLoop.create_future()
+
+        if self._data is not None:
+            res = Bdx.AcceptReceiveTransfer(self._bdx_transfer, self._data, future)
+            res.raise_on_error()
+            return await future
+        else:
+            self._data = bytearray()
+            res = Bdx.AcceptSendTransfer(self._bdx_transfer, lambda data: self._data.extend(data), future)
+            res.raise_on_error()
+            await future
+            return self._data[:]
+
+    async def reject(self):
+        res = await Bdx.RejectTransfer(self._bdx_transfer)
+        res.raise_on_error()
+        return res

src/controller/python/chip/bdx/__init__.py

@@ -0,0 +1,27 @@
+#
+#    Copyright (c) 2024 Project CHIP Authors
+#    All rights reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+
+#
+#    @file
+#      Provides Python APIs for CHIP.
+#
+
+"""Provides Python APIs for CHIP."""
+
+from . import Bdx, BdxTransfer
+
+__all__ = [Bdx, BdxTransfer]