brp-lib 4.0.0__py3-none-any.whl

brp_lib/__init__.py

@@ -0,0 +1,44 @@
+import sys
+import importlib.resources
+from pathlib import Path
+from typing import Optional, Union
+
+from .protocols import BrpStack, UsbHid, RS232, SecureChannel
+from .dll_wrapper import c_brp_lib
+from . import err, protocols
+
+__all__ = [
+    "c_brp_lib",
+    "BrpStack",
+    "UsbHid",
+    "RS232",
+    "SecureChannel",
+    "protocols",
+    "get_brp_lib_path",
+    "set_brp_lib_path",
+]
+
+def get_brp_lib_path() -> Optional[Path]:
+    return c_brp_lib.dll_path
+
+
+def set_brp_lib_path(path: Union[Path, str]) -> None:
+    c_brp_lib.dll_path = Path(path)
+
+
+def _autodetect_brp_lib() -> None:
+    arch = 64 if sys.maxsize > 2 ** 32 else 32
+    platform = sys.platform.replace("win32", "win")
+    extension = {
+        "win": "dll"
+    }.get(platform, "unknown")
+    dll_name = f"brp_lib.{platform}{arch}.{extension}"
+
+    root_resource = importlib.resources.files("brp_lib")
+    dll_resource = root_resource / dll_name
+    dll_path = Path(str(dll_resource))
+    if dll_path.exists():
+        set_brp_lib_path(dll_path)
+
+
+_autodetect_brp_lib()

brp_lib/dll_wrapper.py

@@ -0,0 +1,253 @@
+import ctypes
+import typing
+import functools
+from contextlib import suppress
+from pathlib import Path
+from typing import Any, Protocol, TypeVar, Callable, Optional
+from typing_extensions import Annotated, ParamSpec, Never
+
+from .err import BrpError
+
+
+buf = ctypes.POINTER(ctypes.c_char)
+time = ctypes.c_ulong
+errcode = ctypes.c_uint
+layer_id = ctypes.c_int
+socket = ctypes.c_int
+
+
+class protocol_t(ctypes.Structure):
+    pass
+
+
+protocol = ctypes.POINTER(protocol_t)
+
+
+class frame_t(ctypes.Structure):
+    _fields_ = [
+        ("ptr", buf),  # type is brp_buf, but in python
+        # buf is defined in the scope of
+        # this class definition...
+        ("act_size", ctypes.c_size_t),
+        ("total_size", ctypes.c_size_t),
+    ]  # last read/write of frame failed
+
+
+frame = ctypes.POINTER(frame_t)
+
+
+class frame_reader_t(ctypes.Structure):
+    _fields_ = [("frame", frame), ("ptr", buf), ("err", ctypes.c_bool)]
+
+
+frame_reader = ctypes.POINTER(frame_reader_t)
+
+
+class mempool_object_t(ctypes.Structure):
+    pass
+
+
+mempool = ctypes.POINTER(mempool_object_t)
+
+mempool_object_t._fields_ = [
+    ("prev", ctypes.POINTER(mempool_object_t)),
+    ("next", ctypes.POINTER(mempool_object_t)),
+    ("buf", ctypes.c_char_p),
+]
+
+
+class ioiter_t(ctypes.Structure):
+    pass
+
+
+ioiter = ctypes.POINTER(ioiter_t)
+ioiter_p = ctypes.POINTER(ioiter)
+
+
+cb_generic_t = ctypes.CFUNCTYPE(errcode, protocol)
+cb_recv_any_frame_t = ctypes.CFUNCTYPE(errcode, protocol, time)
+cb_fmt_spec_t = ctypes.CFUNCTYPE(ctypes.c_int, frame, ctypes.c_void_p)
+cb_recv_frame_t = ctypes.CFUNCTYPE(
+    errcode, protocol, time, cb_fmt_spec_t, ctypes.c_void_p
+)
+cb_get_id_t = ctypes.CFUNCTYPE(
+    errcode, protocol, ctypes.POINTER(ctypes.c_char_p), frame
+)
+
+protocol_t._fields_ = [
+    ("protocol_id", ctypes.c_int),
+    ("layer_id", layer_id),
+    ("base_protocol", protocol),
+    ("cb_open", cb_generic_t),
+    ("cb_close", cb_generic_t),
+    ("cb_send_frame", cb_generic_t),
+    ("cb_recv_any_frame", cb_recv_any_frame_t),
+    ("cb_recv_frame", cb_recv_frame_t),
+    ("cb_flush", cb_generic_t),
+    ("cb_destroy", cb_generic_t),
+    ("cb_get_id", cb_get_id_t),
+    ("opened", ctypes.c_bool),
+    ("send_frame", frame_t),
+    ("recv_frame", frame_t),
+    ("recv_delay", time),
+    ("mempool", mempool_object_t),
+    ("friendly_name", ctypes.c_char_p),
+]
+
+
+R = TypeVar("R", covariant=True)
+P = ParamSpec("P")
+C = TypeVar("C", bound=type)
+
+
+class CBrpLibFunction(Protocol[P, R]):
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        ...
+
+
+CharP = Annotated[ctypes.Array[ctypes.c_char], ctypes.c_char_p]
+CharPP = Annotated[Any, ctypes.POINTER(ctypes.c_char_p)]
+CInt = Annotated[int, ctypes.c_int]
+CSize = Annotated[int, ctypes.c_size_t]
+CSizeP = Annotated[Any, ctypes.POINTER(ctypes.c_size_t)]
+CUShortP = Annotated[Any, ctypes.POINTER(ctypes.c_ushort)]
+CChar = Annotated[bytes, ctypes.c_char]
+CBool = Annotated[bool, ctypes.c_bool]
+CBuf = Annotated[bytes, buf]
+CLongLong = Annotated[int, ctypes.c_longlong]
+CTime = Annotated[int, ctypes.c_ulong]
+CProtocol = Annotated[Any, protocol]
+CProtocolP = Annotated[Any, ctypes.POINTER(protocol)]
+CFrame = Annotated[Any, frame]
+CFrameReader = Annotated[Any, frame_reader]
+CSocket = Annotated[int, socket]
+CMempool = Annotated[Any, mempool]
+CIoiter = Annotated[Any, ioiter]
+CIoiterP = Annotated[Any, ioiter_p]
+CUShort = Annotated[int, ctypes.c_ushort]
+
+ErrorCode = Annotated[None, errcode]
+
+
+def _to_ctype(t: Any) -> Any:
+    if t is type(None):
+        return None
+
+    args = typing.get_args(t)
+    if args:
+        return args[1]
+
+    return t
+
+
+def _get_log_link(prot: Any) -> Optional[str]:
+    path_ptr = c_brp_lib.brp_get_log_path(prot, None)
+    if not path_ptr:
+        return None
+
+    path = Path(ctypes.string_at(path_ptr).decode('utf-8'))
+    if not path.exists():
+        return None
+    url = f"{path.as_uri()}"
+
+    anchor_ptr = ctypes.c_char_p()
+    c_brp_lib.brp_get_current_log_anchor(prot, ctypes.byref(anchor_ptr), None)
+    if anchor_ptr.value:
+        return f"{url}{anchor_ptr.value.decode('utf-8')}"
+    return url
+
+
+def with_error_handling(fn: Callable[P, int]) -> Callable[P, None]:
+    @functools.wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+        result = fn(*args, **kwargs)
+        if result:
+            log_url = None
+            with suppress():
+                if len(args) > 0 and isinstance(args[0], protocol):
+                    log_url = _get_log_link(args[0])
+            raise BrpError.from_error_code(result, log_url=log_url)
+
+    return wrapper
+
+
+def _not_implemented(name: str, version: str, *args: object, **kwargs: object) -> Never:
+    raise NotImplementedError(f"{name} is not implemented in brp_lib {version}")
+
+
+class CBrpLib:
+    brp_get_version: CBrpLibFunction[[], CharP]
+    brp_create: CBrpLibFunction[[], CProtocol]
+    brp_destroy: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_set_io: CBrpLibFunction[[CProtocol, CProtocol], ErrorCode]
+    brp_open: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_close: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_suppress_monitoring: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_get_io_id: CBrpLibFunction[[CProtocol, CharPP, CFrame], ErrorCode]
+    brp_get_friendly_name: CBrpLibFunction[[CProtocol, CharPP], ErrorCode]
+    brp_ioiter_create: CBrpLibFunction[[], CIoiter]
+    brp_ioiter_create_usb_hid: CBrpLibFunction[[], CIoiter]
+    brp_ioiter_next: CBrpLibFunction[[CIoiter, CProtocolP], ErrorCode]
+    brp_ioiter_destroy: CBrpLibFunction[[CIoiterP], None]
+    brp_create_usb_hid: CBrpLibFunction[[CLongLong], CProtocol]
+    brp_create_rs232: CBrpLibFunction[[CharP, CInt, CChar], CProtocol]
+    brp_create_secure_channel: CBrpLibFunction[[CInt, CBuf, CInt], CProtocol]
+    brp_set_crypto: CBrpLibFunction[[CProtocol, CProtocol], ErrorCode]
+    brp_set_monitor: CBrpLibFunction[[CProtocol, CInt], ErrorCode]
+    brp_send_frame: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_recv_any_frame: CBrpLibFunction[[CProtocol, CInt], ErrorCode]
+    brp_exec_cmd: CBrpLibFunction[[CProtocol, CInt, CBuf, CSize, CBuf, CSize, CSizeP, CTime], ErrorCode]
+    brp_frame_rest: CBrpLibFunction[[CFrameReader], CSize]
+    brp_frame_init: CBrpLibFunction[[CFrame], None]
+    brp_frame_deinit: CBrpLibFunction[[CFrame], None]
+    brp_frame_write_start: CBrpLibFunction[[CFrame], None]
+    brp_frame_write: CBrpLibFunction[[CFrame, CBuf, CSize], None]
+    brp_frame_write_err: CBrpLibFunction[[CFrame], CBool]
+    brp_frame_read_start: CBrpLibFunction[[CFrameReader, CFrame], None]
+    brp_frame_read: CBrpLibFunction[[CFrameReader, CBuf, CSize], None]
+    brp_frame_read_err: CBrpLibFunction[[CFrameReader], CBool]
+    brp_frame_read_eof: CBrpLibFunction[[CFrameReader], CBool]
+    brp_annotation_start: CBrpLibFunction[[CProtocol], None]
+    brp_annotation_end: CBrpLibFunction[[CProtocol, CBool, CharP], None]
+    brp_set_log_path: CBrpLibFunction[[CProtocol, CharP], ErrorCode]
+    brp_get_current_log_anchor: CBrpLibFunction[[CProtocol, CharPP, CMempool], ErrorCode]
+    brp_get_log_path: CBrpLibFunction[[CProtocol, CMempool], CharP]
+
+    def __init__(self) -> None:
+        self.__dll_path: Optional[Path] = None
+
+    @property
+    def dll_path(self) -> Optional[Path]:
+        return self.__dll_path
+
+    @dll_path.setter
+    def dll_path(self, dll_path: Path) -> None:
+        self.__dll_path = dll_path.absolute()
+        dll = ctypes.CDLL(str(self.__dll_path))
+
+        for name, annotation in type(self).__annotations__.items():
+            if typing.get_origin(annotation) == CBrpLibFunction:
+                argtypes, restype = typing.get_args(annotation)
+                fn = getattr(dll, name, None)
+                if fn is None:
+                    fn = functools.partial(
+                        _not_implemented,
+                        name=name,
+                        version=bytes(self.brp_get_version()).decode("ascii")
+                                if name != "brp_get_version"
+                                else "<unknown>"
+                    )
+                else:
+                    fn.restype = _to_ctype(restype)
+                    fn.argtypes = tuple(map(_to_ctype, argtypes))
+                    if restype == ErrorCode:
+                        fn = with_error_handling(fn)
+                setattr(self, name, fn)
+
+    def __getattr__(self, item: str) -> Any:
+        if item in type(self).__annotations__:
+            raise RuntimeError("Please initialize the brp_lib path calling `brp_lib.set_brp_lib_path('.../libbrp_lib.so')`.")
+        return super().__getattribute__(item)
+
+
+c_brp_lib = CBrpLib()

brp_lib/err.py

@@ -0,0 +1,328 @@
+import abc
+from typing import Dict, Type, Optional
+
+__all__ = [
+    "BrpError",
+    "DeviceError",
+    "CommunicationError",
+    "CommUnsupported",
+    "CommAccessDeniedError",
+    "CommTimeoutError",
+    "CommFrameFormatError",
+    "CommUndefined",
+    "LibError",
+    "LibInvalidCallError",
+    "LibNonRecoverableError",
+    "LibOsError",
+    "LibUndefinedError",
+    "InternalError",
+    "CommandTimeoutError",
+    "FrameFormatError",
+    "InvalidApiCallError",
+    "OutOfMemoryError",
+    "BrpNotImplementedError",
+    "BusyError",
+    "ClosedError",
+    "BufferOverflowError",
+    "OpenIOError",
+    "WriteIOError",
+    "WaitIOError",
+    "ReadIOError",
+    "CloseIOError",
+    "PayloadFormatError",
+    "CryptoFormatError",
+    "SecurityLevelNotSupportedError",
+    "UnsupportedCommandError",
+    "CommandDeniedError",
+    "UnexpectedFrameError",
+    "BrpTimeoutError",
+    "CalledInvalidFrameError",
+    "ExistingLayerError",
+    "GenRandomDataError",
+    "InvalidKeyError",
+    "NoDeviceFoundError",
+    "AmbiguousDeviceError",
+    "PayloadTooLongError",
+    "PayloadTooShortError",
+]
+
+class BrpError(Exception, metaclass=abc.ABCMeta):
+    ErrorCodeMap: Dict[int, Type["BrpError"]] = {}
+
+    ErrorCode: Optional[int] = None
+    URL: Optional[str] = None
+
+    def __init_subclass__(cls) -> None:
+        if cls.ErrorCode is not None:
+            already_registered_class = cls.ErrorCodeMap.get(cls.ErrorCode)
+            if already_registered_class is not None:
+                if issubclass(cls, already_registered_class):
+                    return
+                raise TypeError(f"multiple exceptions defined for same status code {hex(cls.ErrorCode)} ({cls} and {already_registered_class})")
+            cls.ErrorCodeMap[cls.ErrorCode] = cls
+
+    @classmethod
+    def from_error_code(cls, ec: int, *, log_url: Optional[str] = None) -> "BrpError":
+        error_class: Type["BrpError"] = cls.ErrorCodeMap.get(ec, cls)
+        return error_class(log_url=log_url)
+
+    def __init__(self, message: str = "", *, log_url: Optional[str] = None) -> None:
+        self.log_url = log_url
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return "\n".join(
+            map(str,
+                filter(
+                    lambda i: i is not None, [
+                        f"0x{self.ErrorCode:08X} {super()!s}\n",
+                        f"DESC: {self.__doc__.strip() if self.__doc__ else None}",
+                        f"DOCS: {self.URL}" if self.URL else None,
+                        f"LOGS: {self.log_url}" if self.log_url else None,
+                    ]
+                )
+            )
+        )
+
+
+class CommunicationError(BrpError, metaclass=abc.ABCMeta):
+    """Any kind of device <-> host communication problem"""
+
+
+class CommUnsupported(CommunicationError, metaclass=abc.ABCMeta):
+    """A command cannot be executed as the device does not support the requested feature"""
+
+
+class CommAccessDeniedError(CommunicationError, metaclass=abc.ABCMeta):
+    """A command cannot be executed as the device does not allow access this features in the current operations mode"""
+
+
+class CommTimeoutError(CommunicationError, metaclass=abc.ABCMeta):
+    """A the device or host exceeded the allowed time for sending a frame"""
+
+
+class CommFrameFormatError(CommunicationError, metaclass=abc.ABCMeta):
+    """The device or host send a frame that does not correspond the expected frame"""
+
+
+class CommUndefined(CommunicationError, metaclass=abc.ABCMeta):
+    """any device <-> host communication problem which is not categoriezed by one of the BRP_ERRGRP_COMM_* macros"""
+
+
+class LibError(BrpError, metaclass=abc.ABCMeta):
+    """Any error which occured in the library"""
+
+
+class LibInvalidCallError(LibError, metaclass=abc.ABCMeta):
+    """The libraries API was used in an invalid manner"""
+
+
+class LibNonRecoverableError(LibError, metaclass=abc.ABCMeta):
+    """A fatal error occured, which the library cannot recover from. The application should be closed"""
+
+
+class LibOsError(LibError, metaclass=abc.ABCMeta):
+    """A error in the operating system layer (i.e. hardware drivers) occured"""
+
+
+class LibUndefinedError(LibError, metaclass=abc.ABCMeta):
+    """any library specific error which is not one of the BRP_ERRGRP_LIB_* macros"""
+
+
+class DeviceError(BrpError, metaclass=abc.ABCMeta):
+    """
+    A command failed to execute due to a error on the device side which is
+    not host communication related (card error, ...)
+
+    The lower 16bits of the error code will contains the command group code and
+    the status code (see also #BRP_ERR_STATUS() on how to construct a specific
+    error code).
+    The exact list of error codes returned by the device can be found
+    in the @ref baltech_sdk.
+    """
+
+
+class InternalError(LibNonRecoverableError):
+    """This error must not be returned if the library operates correctly.
+    It is only returned, if a bug in the implementation was detected."""
+    ErrorCode = 0x20000001
+
+
+class CommandTimeoutError(CommTimeoutError):
+    """A BRP command that was send by brp_send_frame() exceeded the specified
+    timeout (see also brp_send_cmd() / brp_exec_cmd()).
+
+    **Attention:** must not be intermixed with #BRP_ERR_TIMEOUT."""
+    ErrorCode = 0x02000002
+
+
+class FrameFormatError(CommFrameFormatError):
+    """The frame returned from the reader does not match the format expected
+    by the BRP protocol."""
+    ErrorCode = 0x04000003
+
+
+class InvalidApiCallError(LibInvalidCallError):
+    """Returned if the a parameter contains an invalid value.
+    I.e. if a required pointer is set to NULL."""
+    ErrorCode = 0x10000004
+
+
+class OutOfMemoryError(LibNonRecoverableError):
+    """The heap has not enough memory to allocate a buffer that is required
+    for the wanted operation."""
+    ErrorCode = 0x20000005
+
+
+class BrpNotImplementedError(LibInvalidCallError):
+    """The requested feature is not implemented yet"""
+    ErrorCode = 0x10000006
+
+
+class BusyError(LibInvalidCallError):
+    """The Library is not ready to send/receive data. Probably it is still
+    processing another request."""
+    ErrorCode = 0x10000007
+
+
+class ClosedError(LibInvalidCallError):
+    """The protocol/device is not opened"""
+    ErrorCode = 0x10000008
+
+
+class BufferOverflowError(CommFrameFormatError):
+    """A Command's response is bigger than the buffer provided for the response."""
+    ErrorCode = 0x04000009
+
+
+class OpenIOError(LibOsError):
+    """Failed to open the I/O connection"""
+    ErrorCode = 0x4000000A
+
+
+class WriteIOError(LibOsError):
+    """Failed to send data via IO connection"""
+    ErrorCode = 0x4000000B
+
+
+class WaitIOError(LibOsError):
+    """Failed to wait for data via IO connection"""
+    ErrorCode = 0x4000000C
+
+
+class ReadIOError(LibOsError):
+    """Failed to wait for data via IO connection"""
+    ErrorCode = 0x4000000D
+
+
+class CloseIOError(LibOsError):
+    """Failed to open the I/O connection"""
+    ErrorCode = 0x4000000E
+
+
+class PayloadFormatError(CommFrameFormatError):
+    """The payload of a frame has invalid format"""
+    ErrorCode = 0x0400000F
+
+
+class CryptoFormatError(CommFrameFormatError):
+    """The payload of an encrypted command had invalid format/response."""
+    ErrorCode = 0x04000010
+
+
+class SecurityLevelNotSupportedError(CommAccessDeniedError):
+    """The given securitylevel is not supported"""
+    ErrorCode = 0x01000016
+
+
+class UnsupportedCommandError(CommUnsupported):
+    """The specified BRP command is not supported by the connected device
+
+    Internally the driver maps the status code BRP_ERR_STATUS(xxxx, 0x41) to this
+    (cmdcode independant) error code."""
+    ErrorCode = 0x00800020
+
+
+class CommandDeniedError(CommAccessDeniedError):
+    """The BRP command is not allowed to be executed from the current security level
+
+    Internally the driver maps the status code BRP_ERR_STATUS(xxxx, 0x42) to this
+    (cmdcode independant) error code."""
+    ErrorCode = 0x01000021
+
+
+class UnexpectedFrameError(CommFrameFormatError):
+    """The received frame is a valid BRP frame but not expected in this protocol
+    state."""
+    ErrorCode = 0x04000022
+
+
+class BrpTimeoutError(CommTimeoutError):
+    """The response to a brp_recv_frame() / brp_recv_any_frame() is not returned
+    within the specified timeout.
+
+    **Attention:** Must not be intermixed with #BRP_ERR_CMD_TIMEOUT, which is
+    returned if the timeout of a BRP command is exceeded (see brp_send_cmd())."""
+    ErrorCode = 0x02000023
+
+
+class CalledInvalidFrameError(LibInvalidCallError):
+    """Returned if the a frame passed to a function to be transferred to the device
+    has invalid format"""
+    ErrorCode = 0x10000024
+
+
+class ExistingLayerError(LibInvalidCallError):
+    """The layer is tried to be added to a composite protocol
+    (see brp_add_layer() / brp_set_layer()) although already added earlier.
+    Or it is tried to be removed (brp_detach_layer()) also not part of the
+    composite protocol."""
+    ErrorCode = 0x10000025
+
+
+class GenRandomDataError(LibOsError):
+    """The OS failed to generate a random number"""
+    ErrorCode = 0x40000026
+
+
+class InvalidKeyError(CommAccessDeniedError):
+    """The readers KEY does not match the key of the host."""
+    ErrorCode = 0x01000027
+
+
+class NoDeviceFoundError(OpenIOError):
+    """No device was found when trying to open a connection."""
+    ErrorCode = 0x40000028
+
+
+class AmbiguousDeviceError(OpenIOError):
+    """Multiple devices found but connection string does not uniquely identify one."""
+    ErrorCode = 0x40000029
+
+
+##############################################################################
+#                    PYTHON ONLY EXCEPTIONS                                  #
+##############################################################################
+
+class PayloadTooLongError(PayloadFormatError):
+    """Raised when payload contains more data than expected."""
+
+    def __init__(self, additional_data: bytes) -> None:
+        super().__init__()
+        self.additional_data = additional_data
+
+    def __str__(self) -> str:
+        return f'{len(self.additional_data)} bytes of unexpected data'
+
+
+class PayloadTooShortError(PayloadFormatError):
+    """Raised when payload contains less data than expected."""
+
+    def __init__(self, missing_bytes: int) -> None:
+        super().__init__()
+        self.missing_bytes = missing_bytes
+
+    def __str__(self) -> str:
+        if self.missing_bytes == 1:
+            return "1 byte is missing"
+        return f'{self.missing_bytes} bytes are missing'

brp_lib/protocols.py

@@ -0,0 +1,355 @@
+import abc
+import ctypes
+import os
+from pathlib import Path
+from typing import Any, Optional, TypeVar, Literal, Type, Union, Iterator
+from contextlib import contextmanager
+
+from .dll_wrapper import c_brp_lib, buf, frame_reader_t, frame_t, protocol
+
+T = TypeVar("T")
+
+
+class CProtocolWrapper(metaclass=abc.ABCMeta):
+    def __init__(self, c_protocol: Any) -> None:
+        self._c_protocol = c_protocol
+
+    @property
+    def __c_protocol__(self) -> Any:
+        if self._c_protocol is None:
+            raise RuntimeError("Protocol ownership has been transferred to a parent protocol")
+        return self._c_protocol
+
+    def __take_c_protocol__(self) -> Any:
+        if self._c_protocol is None:
+            raise RuntimeError("Protocol ownership has already been transferred")
+        c_protocol = self._c_protocol
+        self._c_protocol = None
+        return c_protocol
+
+    @property
+    def closed(self) -> bool:
+        return not self.__c_protocol__.contents.opened
+
+    def open(self) -> None:
+        c_brp_lib.brp_open(self.__c_protocol__)
+
+    def close(self) -> None:
+        c_brp_lib.brp_close(self.__c_protocol__)
+
+    def __enter__(self) -> Any:
+        if self.closed:
+            self.open()
+        return self
+
+    def __exit__(self, exc_type: Type[Exception], exc_val: Exception, exc_tb: Any) -> None:
+        if not self.closed:
+            self.close()
+
+    def __del__(self) -> None:
+        # Check if _c_protocol exists and is not None (ownership not transferred)
+        if hasattr(self, '_c_protocol') and self._c_protocol is not None:
+            if not self.closed:
+                self.close()
+            c_brp_lib.brp_destroy(self._c_protocol)
+
+    @property
+    def id(self) -> str:
+        """Device ID (e.g., serial number for USB HID devices)."""
+        intf_name_ptr = ctypes.c_char_p()
+        device_id_frame = frame_t()
+        c_brp_lib.brp_frame_init(ctypes.pointer(device_id_frame))
+        try:
+            c_brp_lib.brp_get_io_id(self.__c_protocol__, ctypes.byref(intf_name_ptr), ctypes.pointer(device_id_frame))
+            if device_id_frame.ptr:
+                return ctypes.string_at(device_id_frame.ptr, device_id_frame.act_size).decode('utf-8', errors='replace').rstrip('\x00')
+            return ""
+        finally:
+            c_brp_lib.brp_frame_deinit(ctypes.pointer(device_id_frame))
+
+    @property
+    def friendly_name(self) -> Optional[str]:
+        """Human-readable device name (e.g., product name for USB HID devices)."""
+        friendly_name_ptr = ctypes.c_char_p()
+        c_brp_lib.brp_get_friendly_name(self.__c_protocol__, ctypes.byref(friendly_name_ptr))
+        if friendly_name_ptr.value:
+            return friendly_name_ptr.value.decode('utf-8', errors='replace')
+        return None
+
+    def __str__(self) -> str:
+        """Return a string representation of the protocol."""
+        name = self.friendly_name
+        if name:
+            return f"{name} {self.id} ({self.__class__.__name__})"
+        return f"{self.id} ({self.__class__.__name__})"
+
+
+class IoProtocol(CProtocolWrapper, metaclass=abc.ABCMeta):
+    pass
+
+
+class UsbHid(IoProtocol):
+    def __init__(self, serialnumber: Optional[int] = None) -> None:
+        self.serialnumber = serialnumber
+        super().__init__(c_brp_lib.brp_create_usb_hid(serialnumber or 0))
+
+    @classmethod
+    def enumerate(cls) -> Iterator['UsbHid']:
+        """
+        Enumerate all connected Baltech USB HID devices.
+
+        Yields UsbHid instances for each connected device. The caller is responsible
+        for managing the lifecycle of yielded devices (e.g., using context managers).
+
+        Example:
+            >>> for device in UsbHid.enumerate():
+            ...     with device:
+            ...         print(f"Device: {device.friendly_name or device.id}")
+            ...         # Use device for communication
+        """
+        # Create USB HID-specific iterator
+        iter_handle = c_brp_lib.brp_ioiter_create_usb_hid()
+        if not iter_handle:
+            return
+
+        try:
+            while True:
+                # Get next protocol
+                protocol_ptr = protocol()
+                c_brp_lib.brp_ioiter_next(iter_handle, ctypes.byref(protocol_ptr))
+
+                # Check if we reached the end
+                if not protocol_ptr:
+                    break
+
+                # Wrap the protocol from iterator in a UsbHid instance
+                # The protocol already has friendly_name populated from the iterator
+                device = cls.__new__(cls)
+                device._c_protocol = protocol_ptr
+                yield device
+        finally:
+            # Clean up iterator
+            iter_ref = ctypes.pointer(iter_handle)
+            c_brp_lib.brp_ioiter_destroy(iter_ref)
+
+
+class RS232(IoProtocol):
+    def __init__(self, comport: str, baudrate: int = 115200, parity: Literal[b"O", b"E", b"N"] = b"N") -> None:
+        self.comport = comport
+        comport_cstr = ctypes.create_string_buffer(comport.encode("ascii"))
+        super().__init__(c_brp_lib.brp_create_rs232(comport_cstr, baudrate, parity))
+
+
+class CryptoProtocol(CProtocolWrapper, metaclass=abc.ABCMeta):
+    pass
+
+
+class SecureChannel(CryptoProtocol):
+    def __init__(self, *, security_level: int, key: bytes, security_mode: Literal["std", "plain", "stateless"] = "std") -> None:
+        secmode = dict(std=0, plain=1, stateless=2).get(security_mode, 0)
+        super().__init__(c_brp_lib.brp_create_secure_channel(security_level, key, secmode))
+
+
+MonitorMode = Union[Literal["disabled", "enabled", "plaintext"], bool]
+
+
+class AnnotationLogger:
+
+    def __init__(self) -> None:
+        self._message = ""
+        self._fail = False
+
+    def info(self, message: str) -> None:
+        self._message += message
+
+    def fail(self, message: str = "") -> None:
+        self._fail = True
+        self._message += message
+
+
+class BrpStack(CProtocolWrapper):
+    def __init__(
+            self,
+            io: IoProtocol,
+            *,
+            crypto: Optional[CryptoProtocol] = None,
+            monitor: MonitorMode = "enabled",
+            log_path: Optional[Union[str, Path]] = None,
+            open: bool = False,
+    ) -> None:
+        super().__init__(c_brp_lib.brp_create())
+
+        c_brp_lib.brp_set_io(self.__c_protocol__, io.__take_c_protocol__())
+
+        if crypto:
+            c_brp_lib.brp_set_crypto(self.__c_protocol__, crypto.__take_c_protocol__())
+
+        if monitor not in (True, "enabled"):
+            self.monitor = monitor
+
+        if log_path is not None:
+            self.log_path = Path(log_path)
+
+        if open:
+            self.open()
+
+    def send_frame(self, frame: bytes) -> None:
+        send_frame = ctypes.pointer(self.__c_protocol__.contents.send_frame)
+
+        c_brp_lib.brp_frame_write_start(send_frame)
+        c_brp_lib.brp_frame_write(send_frame, frame, len(frame))
+        c_brp_lib.brp_frame_write_err(send_frame)
+        c_brp_lib.brp_send_frame(self.__c_protocol__)
+
+    def recv_any_frame(self, timeout: int = 0xFFFFFFFF) -> bytes:
+        reader = frame_reader_t()
+        c_brp_lib.brp_recv_any_frame(self.__c_protocol__, timeout)
+        c_brp_lib.brp_frame_read_start(
+            ctypes.pointer(reader), ctypes.pointer(self.__c_protocol__.contents.recv_frame)
+        )
+        rest = c_brp_lib.brp_frame_rest(ctypes.pointer(reader))
+
+        result = ctypes.create_string_buffer(rest)
+        c_brp_lib.brp_frame_read(ctypes.pointer(reader), buf(result), rest)  # type: ignore[call-overload]
+        c_brp_lib.brp_frame_read_err(ctypes.pointer(reader))
+
+        eof = c_brp_lib.brp_frame_read_eof(ctypes.pointer(reader))
+        if not eof:
+            raise RuntimeError("UnexpectedData")
+
+        return result.raw
+
+    def process_frame(self, frame: bytes) -> bytes:
+        self.send_frame(frame)
+        return self.recv_any_frame()
+
+    def exec_cmd(self, cmd_code: int, params: bytes, *, timeout: int, max_resp_len: int = 65536) -> bytes:
+        resp_buf = ctypes.create_string_buffer(max_resp_len)
+        resp_len = ctypes.c_size_t()
+
+        c_brp_lib.brp_exec_cmd(
+            self.__c_protocol__,
+            cmd_code,
+            params,
+            len(params),
+            buf(resp_buf),  # type: ignore[call-overload]
+            max_resp_len,
+            ctypes.pointer(resp_len),
+            timeout
+        )
+
+        return resp_buf.raw[:resp_len.value]
+
+    def set_monitor(self, new_val: MonitorMode) -> None:
+        map = {"disabled": 0, "enabled": 1, "plaintext": 2, False:0, True:1}
+        c_brp_lib.brp_set_monitor(self.__c_protocol__, map[new_val])
+
+    @contextmanager
+    def annotate_log(self, comment:str="") -> Iterator[AnnotationLogger]:
+        """
+        Adds an annotations/comment to all brplogs that are executed within
+        this context.
+
+        Returns a contextmanager that allows to add further log-messages
+        (log.info(...) or log.fail(...)). if at least one failure message is
+        send the whole block is marked as failed.
+
+        If an exception occurs the block will be marked as failed, too.
+        If no log.fail() was called the exception text will be added to
+        the log annotation.
+
+        :param comment: A string that shall be added as annotation to the logs
+        :return: a contextmanager of type AnnotationLogger()
+        """
+        annotation_logger = AnnotationLogger()
+        annotation_logger.info(comment)
+        try:
+            c_brp_lib.brp_annotation_start(self.__c_protocol__)
+            yield annotation_logger
+        except Exception as exc:
+            if not annotation_logger._fail:
+                exc_text = f"{type(exc).__name__}: {str(exc)}"
+                annotation_logger.fail(exc_text.splitlines()[0])
+            raise
+        finally:
+            message_utf8 = annotation_logger._message.encode('utf8')
+            message_cstr = ctypes.create_string_buffer(message_utf8)
+            fail = annotation_logger._fail
+            c_brp_lib.brp_annotation_end(
+                self.__c_protocol__, not fail, message_cstr)
+
+    monitor = property(fset=set_monitor)
+
+    @property
+    def current_log_anchor(self) -> Optional[str]:
+        """
+        Get the anchor ID of the current (last written) log entry.
+
+        The anchor can be used to create direct links to specific log entries,
+        e.g., ``f"file://{log_path}#{brp.current_log_anchor}"``
+
+        :return: The anchor string (e.g., "_a3") in hex format, or None
+            if no log entries have been written yet.
+        """
+        anchor_ptr = ctypes.c_char_p()
+        c_brp_lib.brp_get_current_log_anchor(self.__c_protocol__, ctypes.byref(anchor_ptr), None)
+        if anchor_ptr.value:
+            return anchor_ptr.value.decode("ascii")
+        return None
+
+    @property
+    def log_path(self) -> Optional[Path]:
+        """
+        Get the current log file path.
+
+        :return: The full path to the log file currently being used,
+                 or None if no monitor protocol is present.
+        """
+        path_ptr = c_brp_lib.brp_get_log_path(self.__c_protocol__, None)
+        if path_ptr:
+            # path_ptr is a c_char_p, convert to string
+            path_str = ctypes.string_at(path_ptr).decode("utf-8")
+            return Path(path_str)
+        return None
+
+    @log_path.setter
+    def log_path(self, path: Union[str, Path]) -> None:
+        """
+        Set the log file path.
+
+        :param path: The log file path. Can be a full file path
+            (e.g., "C:/logs/debug.html"), a directory (uses the default
+            filename schema {interface}-{instance}.html),
+            or None to restore the default behavior.
+        """
+        if path is None:
+            path_cstr = None
+        else:
+            path_obj = Path(path)
+            if path_obj.is_dir():
+                path_str = str(path_obj) + os.sep
+            else:
+                path_str = str(path)
+            path_cstr = ctypes.create_string_buffer(path_str.encode("utf-8"))
+        c_brp_lib.brp_set_log_path(self.__c_protocol__, path_cstr)
+
+    @log_path.setter
+    def log_path(self, path: Optional[Union[str, Path]]) -> None:
+        """
+        Set the log file path.
+
+        :param path: The log file path. Can be a full file path
+            (e.g., "C:/logs/debug.html"), a directory (uses the default
+            filename schema {interface}-{instance}.html),
+            or None to restore the default behavior.
+        """
+        if path is None:
+            path_cstr = None
+        else:
+            path_obj = Path(path)
+            if path_obj.is_dir():
+                path_str = str(path_obj) + os.sep
+            else:
+                path_str = str(path)
+            path_cstr = ctypes.create_string_buffer(path_str.encode("utf-8"))
+        c_brp_lib.brp_set_log_path(self.__c_protocol__, path_cstr)  # type: ignore[arg-type]

brp_lib-4.0.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: brp_lib
+Version: 4.0.0
+Summary: Low-level C library wrapper for Baltech RFID readers.
+Author-email: Baltech AG <info@baltech.de>
+Requires-Python: >=3.9
+Requires-Dist: typing-extensions

brp_lib-4.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+brp_lib/__init__.py,sha256=BLBfvZuxaSftpKd9n6h-Sr2oH8tKSUA-CF1v8Rp05AA,1082
+brp_lib/brp_lib.win32.dll,sha256=S2HTbVM5M4lkjkitgOaO_sq_wvEB1U-QcflwiJYRE1c,271888
+brp_lib/brp_lib.win64.dll,sha256=vgnSYcfdjSLvnd3Bnr1lGzdj1eXmASvLOZqFYW8Dj08,321040
+brp_lib/dll_wrapper.py,sha256=W_Ax9-mtThrXPaX2vYXVm2hXrNHe-M0BRlAPUiq78Ck,8836
+brp_lib/err.py,sha256=OI7FONYRr8mZ3yVc-fztqS3WQOLzDiqUwC-Oeahg7do,10780
+brp_lib/protocols.py,sha256=y1fxZnyatZS88xFxoEPq1tDwrEItQXrAWGGuE5868_M,13186
+brp_lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+brp_lib-4.0.0.dist-info/METADATA,sha256=NXmVSaAfhEbBPSxokFAdBmIEyvXc83wG0-s53hu5Rm0,220
+brp_lib-4.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+brp_lib-4.0.0.dist-info/top_level.txt,sha256=Lmc-it2tnEN23dUJJarKCeJKFWkM_S9EBYZ66nKbI1w,8
+brp_lib-4.0.0.dist-info/RECORD,,

brp_lib-4.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

brp_lib-4.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+brp_lib