reader-integration-kit 1.4.2__py3-none-win_amd64.whl

reader_integration_kit/facade/__init__.py

@@ -0,0 +1,882 @@
+"""
+Internal infrastructure module for loading the native library and managing function pointers.
+This module is used internally by Reader and should not be used directly.
+Use Reader instead for all reader operations.
+"""
+from __future__ import annotations
+
+import ctypes
+from ctypes import (
+    c_size_t, c_ushort, c_uint, c_byte, c_char_p, c_ulong, c_int, POINTER, Structure, byref,
+    create_string_buffer, c_void_p, c_uint8, c_uint16, c_uint32, c_bool, CFUNCTYPE
+)
+import os
+import platform
+from typing import Callable, Optional
+
+# Type alias for the Python-level credential callback.
+# Signature: callback(card_data: CardData) -> None
+CredentialCallback = Callable[['CardData'], None]
+
+from reader_integration_kit.errors import ReaderException
+from reader_integration_kit.structures import *
+from reader_integration_kit.enum import *
+
+
+class _NativeLibrary:
+    """Internal class for loading the native library and managing function pointers."""
+
+    _instance: Optional['_NativeLibrary'] = None
+    _native_library_handle = None
+    _dll = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._load_library()
+            cls._instance._initialize_functions()
+        return cls._instance
+
+    @staticmethod
+    def _get_library_name() -> str:
+        """Get the library name based on the platform."""
+        if platform.system() == 'Windows':
+            return "ReaderIntegrationKit.dll"
+        elif platform.system() == 'Linux':
+            return "libReaderIntegrationKit.so"
+        elif platform.system() == 'Darwin':
+            return "libReaderIntegrationKit.dylib"
+        else:
+            raise RuntimeError(f"Unsupported OS platform: {platform.system()}")
+
+    @staticmethod
+    def _detect_arm_variant() -> str:
+        """Detect the ARM64 variant at runtime (pi5 or generic).
+
+        Mirrors the C# DetectArmVariant() logic.  The RIK_ARM_VARIANT env var
+        can override auto-detection for CI or testing purposes.
+        """
+        override = os.getenv('RIK_ARM_VARIANT', '').strip().lower()
+        if override:
+            return override
+        try:
+            with open('/proc/device-tree/model', 'r', errors='replace') as f:
+                model = f.read()
+            if 'Raspberry Pi 5' in model:
+                return 'pi5'
+        except OSError:
+            pass
+        return 'generic'
+
+    def _get_library_path(self) -> str:
+        """Get the path to the native library."""
+        library_name = self._get_library_name()
+        lib_dir = os.path.join(os.path.dirname(__file__), '..', 'lib')
+
+        # On aarch64/arm64 Linux, the unified wheel bundles both pi5 and generic
+        # variants in subdirectories.  Pick the right one at runtime.
+        machine = platform.machine().lower()
+        if platform.system() == 'Linux' and machine in ('aarch64', 'arm64'):
+            variant = self._detect_arm_variant()
+            variant_path = os.path.join(lib_dir, variant, library_name)
+            if os.path.exists(variant_path):
+                return variant_path
+
+        lib_path = os.path.join(lib_dir, library_name)
+        if not os.path.exists(lib_path):
+            # Try alternative locations for development / non-wheel installs
+            alt_paths = [
+                os.path.join(os.path.dirname(__file__), '..', '..', 'lib', library_name),
+                os.path.join(os.path.dirname(__file__), '..', '..', '..', 'lib', library_name),
+                library_name,  # Try system library path
+            ]
+
+            for alt_path in alt_paths:
+                if os.path.exists(alt_path):
+                    return alt_path
+
+            raise FileNotFoundError(
+                f"Shared library not found. Tried: {lib_path} and {alt_paths}"
+            )
+
+        return lib_path
+
+    def _load_library(self):
+        """Load the native library."""
+        try:
+            lib_path = self._get_library_path()
+            # On Windows, use WinDLL to properly capture stdout/stderr from the DLL
+            # On Linux/Mac, use CDLL
+            if platform.system() == 'Windows':
+                self._dll = ctypes.WinDLL(lib_path)
+            else:
+                self._dll = ctypes.CDLL(lib_path)
+            self._native_library_handle = self._dll
+        except Exception as e:
+            raise RuntimeError(f"Failed to load native library: {e}") from e
+
+    def _initialize_functions(self):
+        """Initialize all function signatures."""
+        # Factory functions
+        self._dll.RikReader_Open.argtypes = [POINTER(RikResult), POINTER(ReaderDefinition), c_int]
+        self._dll.RikReader_Open.restype = c_void_p
+
+        # Common reader methods
+        self._dll.Rik_Close.argtypes = [POINTER(RikResult), c_void_p]
+        self._dll.Rik_Close.restype = None
+
+        self._dll.Rik_Init.argtypes = [POINTER(RikResult), c_void_p]
+        self._dll.Rik_Init.restype = None
+
+        # Metadata functions - work directly with reader
+        self._dll.Rik_RefreshMetadata.argtypes = [POINTER(RikResult), c_void_p]
+        self._dll.Rik_RefreshMetadata.restype = None
+
+        # Rik_GetMetadataStruct
+        from reader_integration_kit.structures.reader_metadata_struct import ReaderMetadataStruct
+        self._dll.Rik_GetMetadataStruct.argtypes = [POINTER(RikResult), c_void_p, POINTER(ReaderMetadataStruct), c_bool]
+        self._dll.Rik_GetMetadataStruct.restype = None
+
+        # WaveID-specific methods
+        self._dll.RikReader_Beep.argtypes = [POINTER(RikResult), c_void_p, c_uint8, c_uint8]
+        self._dll.RikReader_Beep.restype = None
+
+        self._dll.RikReader_GetCardData.argtypes = [POINTER(RikResult), c_void_p, POINTER(c_uint8), ctypes.c_size_t, POINTER(ctypes.c_uint32)]
+        self._dll.RikReader_GetCardData.restype = None
+
+        self._dll.RikReader_GetBeeperVolume.argtypes = [POINTER(RikResult), c_void_p, POINTER(c_uint8)]
+        self._dll.RikReader_GetBeeperVolume.restype = None
+
+        self._dll.RikReader_SetBeeperVolume.argtypes = [POINTER(RikResult), c_void_p, c_uint8]
+        self._dll.RikReader_SetBeeperVolume.restype = None
+
+        self._dll.RikReader_GetReaderConfiguration.argtypes = [POINTER(RikResult), c_void_p, c_uint8, POINTER(ReaderConfigurationStruct), POINTER(ExtendedConfiguration)]
+        self._dll.RikReader_GetReaderConfiguration.restype = None
+
+        self._dll.RikReader_SetReaderConfiguration.argtypes = [POINTER(RikResult), c_void_p, c_uint8, POINTER(ReaderConfigurationStruct), POINTER(ExtendedConfiguration), POINTER(HashData)]
+        self._dll.RikReader_SetReaderConfiguration.restype = None
+
+        self._dll.RikReader_GetModuleState.argtypes = [POINTER(RikResult), c_void_p, c_uint8, POINTER(c_uint)]
+        self._dll.RikReader_GetModuleState.restype = None
+
+        self._dll.RikReader_SetModuleState.argtypes = [POINTER(RikResult), c_void_p, c_uint8, c_uint]
+        self._dll.RikReader_SetModuleState.restype = None
+
+        # LED configuration functions
+        from reader_integration_kit.structures.led_configuration import LedConfiguration
+        self._dll.RikReader_GetLedConfiguration.argtypes = [POINTER(RikResult), c_void_p, c_uint8, POINTER(LedConfiguration)]
+        self._dll.RikReader_GetLedConfiguration.restype = None
+
+        self._dll.RikReader_SetLedConfiguration.argtypes = [POINTER(RikResult), c_void_p, c_uint8, POINTER(LedConfiguration)]
+        self._dll.RikReader_SetLedConfiguration.restype = None
+
+        # Enable keystroking functions
+        self._dll.RikReader_EnableKeystroking.argtypes = [POINTER(RikResult), c_void_p, c_bool]
+        self._dll.RikReader_EnableKeystroking.restype = None
+
+        # LUID functions
+        self._dll.RikReader_GetLuid.argtypes = [POINTER(RikResult), c_void_p, POINTER(LuidResponseInformation)]
+        self._dll.RikReader_GetLuid.restype = None
+
+        self._dll.RikReader_SetLuid.argtypes = [POINTER(RikResult), c_void_p, c_uint16]
+        self._dll.RikReader_SetLuid.restype = None
+
+        # Get Supported Card Types
+        from reader_integration_kit.structures.card_type_info import SupportedCardTypesResult
+        self._dll.RikReader_GetSupportedCardTypes.argtypes = [POINTER(RikResult), c_void_p, POINTER(SupportedCardTypesResult)]
+        self._dll.RikReader_GetSupportedCardTypes.restype = None
+
+        # Read/Write BLE Configuration functions
+        self._dll.RikReader_ReadBleConfigurationFromReader.argtypes = [POINTER(RikResult), c_void_p, c_uint8, c_char_p]
+        self._dll.RikReader_ReadBleConfigurationFromReader.restype = None
+
+        self._dll.RikReader_WriteBleConfigurationToReader.argtypes = [POINTER(RikResult), c_void_p, c_uint8, c_char_p]
+        self._dll.RikReader_WriteBleConfigurationToReader.restype = None
+
+        # Hwg file functions
+        self._dll.RikReader_WriteHwgFileToReader.argtypes = [POINTER(RikResult), c_void_p, c_char_p]
+        self._dll.RikReader_WriteHwgFileToReader.restype = None
+
+        self._dll.RikReader_ReadHwgFileFromReader.argtypes = [POINTER(RikResult), c_void_p, c_char_p, c_bool]
+        self._dll.RikReader_ReadHwgFileFromReader.restype = None
+
+        # Smart card configuration functions
+        self._dll.RikReader_WriteSmartCardConfigurationToReader.argtypes = [POINTER(RikResult), c_void_p, c_char_p]
+        self._dll.RikReader_WriteSmartCardConfigurationToReader.restype = None
+
+        self._dll.RikReader_ReadSmartCardConfigurationFromReader.argtypes = [POINTER(RikResult), c_void_p, POINTER(SmartCardConfigurationStruct)]
+        self._dll.RikReader_ReadSmartCardConfigurationFromReader.restype = None
+
+        # Write and reset reader configuration functions
+        self._dll.RikReader_WriteUserDefaultsToReader.argtypes = [POINTER(RikResult), c_void_p]
+        self._dll.RikReader_WriteUserDefaultsToReader.restype = None
+
+        self._dll.RikReader_ResetReaderConfiguration.argtypes = [POINTER(RikResult), c_void_p, c_uint8]
+        self._dll.RikReader_ResetReaderConfiguration.restype = None
+
+        # Credential-presented callback functions
+        # NativeCredentialCallback: void (*)(const uint8_t* cardData, uint32_t bitCount)
+        NativeCredentialCallback = CFUNCTYPE(None, POINTER(c_uint8), c_uint32)
+        self._credential_callback_type = NativeCredentialCallback
+        self._dll.RikReader_OnCredentialPresented.argtypes = [POINTER(RikResult), c_void_p, NativeCredentialCallback]
+        self._dll.RikReader_OnCredentialPresented.restype = c_uint32
+
+        self._dll.RikReader_UnsubscribeCredentialCallback.argtypes = [POINTER(RikResult), c_void_p, c_uint32]
+        self._dll.RikReader_UnsubscribeCredentialCallback.restype = None
+
+        # Transparent mode functions
+        self._dll.RikReader_EnableTransparentMode.argtypes = [POINTER(RikResult), c_void_p, c_uint8, c_uint8]
+        self._dll.RikReader_EnableTransparentMode.restype = None
+
+        self._dll.RikReader_GetTransparentModeStatus.argtypes = [POINTER(RikResult), c_void_p, POINTER(c_uint8), POINTER(c_uint8)]
+        self._dll.RikReader_GetTransparentModeStatus.restype = None
+
+        # Library info function (extern "C")
+        from reader_integration_kit.structures.library_info import LibraryInfo
+        self._dll.Rik_BuildLibraryInfo.argtypes = []
+        self._dll.Rik_BuildLibraryInfo.restype = LibraryInfo
+
+        # Reader discovery functions
+        self._dll.Rik_DiscoverUsbReaders.argtypes = [POINTER(RikResult), POINTER(ReaderDefinition), POINTER(c_size_t)]
+        self._dll.Rik_DiscoverUsbReaders.restype = None
+
+
+class ReaderHandle:
+    """Represents an opaque handle to an reader instance."""
+
+    def __init__(self, handle: c_void_p):
+        # Always store as c_void_p to guarantee correct type for is_valid comparison
+        self._handle = ctypes.c_void_p(handle if isinstance(handle, int) else getattr(handle, 'value', handle))
+
+    @property
+    def value(self) -> c_void_p:
+        """Get the raw handle value."""
+        return self._handle
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the handle is valid (not None/null)."""
+        return self._handle is not None and self._handle.value is not None
+
+    def __bool__(self) -> bool:
+        return self.is_valid
+
+
+class AbstractReader:
+    """
+    Base class for Reader instances.
+    Provides common functionality for all reader types.
+    """
+
+    def __init__(self, handle: ReaderHandle, native_lib: _NativeLibrary):
+        """
+        Initialize a new instance of the AbstractReader class.
+
+        Args:
+            handle: The reader handle.
+            native_lib: The native library instance.
+        """
+        self._native_lib = native_lib
+        self._handle: Optional[ReaderHandle] = handle
+        self._disposed = False
+
+        if not self._handle.is_valid:
+            raise RuntimeError("Failed to create reader instance: invalid handle")
+
+    @property
+    def handle(self) -> ReaderHandle:
+        """Get the reader handle for this instance."""
+        return self._handle
+
+    def _throw_if_disposed(self):
+        """Throw an exception if the object has been disposed."""
+        if self._disposed:
+            raise RuntimeError("AbstractReader instance has been disposed")
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - automatically dispose."""
+        self.dispose()
+
+    def dispose(self):
+        """Dispose of the reader instance, destroying the native handle."""
+        if not self._disposed and self._handle is not None and self._handle.is_valid:
+            try:
+                # Unsubscribe all active credential callbacks before closing.
+                if hasattr(self, '_credential_callbacks'):
+                    for sub_id in list(self._credential_callbacks.keys()):
+                        try:
+                            result = RikResult()
+                            self._native_lib._dll.RikReader_UnsubscribeCredentialCallback(
+                                byref(result), self._handle.value, c_uint32(sub_id))
+                        except Exception:
+                            pass
+                    self._credential_callbacks.clear()
+                    
+                result = RikResult()
+                self._native_lib._dll.Rik_Close(byref(result), self._handle.value)
+                ReaderException.raise_if_error(result)
+            except Exception:
+                # Optionally log or handle native errors
+                pass
+            finally:
+                self._handle = None
+                self._disposed = True
+
+    def __del__(self):
+        """Destructor - ensure cleanup."""
+        if hasattr(self, '_disposed') and not self._disposed:
+            self.dispose()
+
+    def init(self):
+        """Initialize the reader (populates metadata, etc.)."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.Rik_Init(byref(result), self._handle.value)
+        ReaderException.raise_if_error(result)
+
+    def refresh_metadata(self):
+        """Refresh metadata from device."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.Rik_RefreshMetadata(byref(result), self._handle.value)
+        ReaderException.raise_if_error(result)
+
+    def get_metadata(self, force_refresh: bool = False) -> dict:
+        """
+        Get metadata as a dictionary.
+        Returns a fully populated dictionary with all available metadata fields.
+        Only fields that are present (Has* flag is True) will be included.
+        
+        Args:
+            force_refresh: If True, forces a refresh from the device even if metadata
+                          has already been populated. If False (default), metadata is
+                          populated lazily on first access.
+        
+        Returns:
+            Dictionary containing all available metadata fields.
+        """
+        self._throw_if_disposed()
+        from reader_integration_kit.structures.reader_metadata_struct import ReaderMetadataStruct
+        
+        # Create the struct to receive the data
+        metadata_struct = ReaderMetadataStruct()
+        
+        # Call the native function to populate the struct
+        result = RikResult()
+        self._native_lib._dll.Rik_GetMetadataStruct(byref(result), self._handle.value, byref(metadata_struct), force_refresh)
+        ReaderException.raise_if_error(result)
+        
+        # Convert the struct to a dictionary
+        return metadata_struct.to_dict()
+
+    @staticmethod
+    def get_library_info() -> dict:
+        """
+        Get library information including version and build metadata.
+        This is a static method that does not require an reader instance.
+        
+        Returns:
+            Dictionary containing library information (name, version, build date, etc.).
+        """
+        from reader_integration_kit.structures.library_info import LibraryInfo
+        
+        # Get the native library instance to access the DLL
+        native_lib = _NativeLibrary()
+        
+        # Call Rik_BuildLibraryInfo (extern "C" function)
+        library_info = native_lib._dll.Rik_BuildLibraryInfo()
+        
+        # Convert to dictionary
+        return library_info.to_dict()
+
+
+class Reader(AbstractReader):
+    """
+    A class that encapsulates a WaveID reader handle and provides instance methods for WaveID operations.
+    The handle is automatically created in the constructor and destroyed when the object is disposed.
+    """
+
+    def __init__(self, reader_definition: ReaderDefinition, retry_count: int = 3):
+        """
+        Initialize a new instance of the Reader class with the specified reader definition.
+
+        Args:
+            reader_definition: The reader definition to use for creating the reader instance.
+            retry_count: The number of retries to attempt when creating the reader instance. Default is 3.
+        """
+        native_lib = _NativeLibrary()
+
+        # Create reader handle
+        result = RikResult()
+        handle_ptr = native_lib._dll.RikReader_Open(
+            byref(result), byref(reader_definition), c_int(retry_count)
+        )
+        ReaderException.raise_if_error(result)
+
+        if handle_ptr is None:
+            raise RuntimeError("Failed to create WaveID reader instance: returned None")
+
+        handle = ReaderHandle(handle_ptr)
+
+        self._credential_callbacks = {}
+        super().__init__(handle, native_lib)
+
+    def beep(self, beep_count: int, duration: BeepDuration) -> None:
+        """Beep the reader."""
+        self._throw_if_disposed()
+        duration_value = duration.value if hasattr(duration, 'value') else duration
+        result = RikResult()
+        self._native_lib._dll.RikReader_Beep(
+            byref(result), self._handle.value, c_uint8(beep_count), c_uint8(duration_value)
+        )
+        ReaderException.raise_if_error(result)
+
+    def get_beeper_volume(self) -> BeepVolume:
+        """Get the beeper volume."""
+        self._throw_if_disposed()
+        volume = c_uint8()
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetBeeperVolume(
+            byref(result), self._handle.value, byref(volume)
+        )
+        ReaderException.raise_if_error(result)
+        return BeepVolume(volume.value)
+
+    def set_beeper_volume(self, volume: BeepVolume) -> None:
+        """Set the beeper volume."""
+        self._throw_if_disposed()
+        volume_value = volume.value if hasattr(volume, 'value') else volume
+        result = RikResult()
+        self._native_lib._dll.RikReader_SetBeeperVolume(
+            byref(result), self._handle.value, c_uint8(volume_value)
+        )
+        ReaderException.raise_if_error(result)
+
+    def get_module_state(self, module_id: ReaderModuleId) -> ReaderModuleState:
+        """
+        Get the module state for the specified module.
+
+        Args:
+            module_id: The module ID to query.
+
+        Returns:
+            The current state of the specified module.
+        """
+        self._throw_if_disposed()
+        module_id_value = module_id.value if hasattr(module_id, 'value') else module_id
+        state = c_uint()
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetModuleState(
+            byref(result), self._handle.value, c_uint8(module_id_value), byref(state)
+        )
+        ReaderException.raise_if_error(result)
+
+        # Try to convert to enum, but handle unexpected values gracefully
+        try:
+            return ReaderModuleState(state.value)
+        except ValueError:
+            # If the value isn't in the enum, raise a more helpful error
+            raise ValueError(
+                f"Received unexpected module state value: {state.value} (0x{state.value:X}). "
+                f"Valid values are: {[f'{s.name}={s.value} (0x{s.value:X})' for s in ReaderModuleState]}"
+            )
+
+    def set_module_state(self, module_id: ReaderModuleId, state: ReaderModuleState) -> None:
+        """
+        Set the module state for the specified module.
+
+        Args:
+            module_id: The module ID to configure.
+            state: The desired state for the module.
+        """
+        self._throw_if_disposed()
+        module_id_value = module_id.value if hasattr(module_id, 'value') else module_id
+        state_value = state.value if hasattr(state, 'value') else state
+        result = RikResult()
+        self._native_lib._dll.RikReader_SetModuleState(
+            byref(result), self._handle.value, c_uint8(module_id_value), c_uint(state_value)
+        )
+        ReaderException.raise_if_error(result)
+
+    def get_card_data(self) -> 'CardData':
+        """
+        Get card data from the reader.
+        Returns:
+            CardData: The card data read from the reader.
+        Raises:
+            ReaderException: If the operation fails or no valid card data is available.
+        """
+        self._throw_if_disposed()
+        from reader_integration_kit.structures.card_data import CardData
+        
+        # Allocate buffer for card data (32 bytes)
+        buffer = (ctypes.c_uint8 * 32)()
+        bit_count = ctypes.c_uint32()
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetCardData(
+            byref(result), self._handle.value, buffer, ctypes.c_size_t(32), byref(bit_count)
+        )
+        ReaderException.raise_if_error(result)
+        # Create CardData and populate it
+        card_data = CardData()
+        for i in range(32):
+            card_data.data[i] = buffer[i]
+        card_data.bit_count = bit_count.value
+        return card_data
+
+    def get_reader_configuration(self, configuration_number: int) -> tuple[ReaderConfigurationStruct, ExtendedConfiguration]:
+        """Get the WaveID reader configuration and Extended configuration for the specified configuration number."""
+        self._throw_if_disposed()
+        config = ReaderConfigurationStruct()
+        extended_config = ExtendedConfiguration()
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetReaderConfiguration(
+            byref(result), self._handle.value, c_uint8(configuration_number), byref(config), byref(extended_config)
+        )
+        ReaderException.raise_if_error(result)
+        return config, extended_config
+
+    def set_reader_configuration(self, configuration_number: int, config: ReaderConfigurationStruct, extended_config: ExtendedConfiguration, hash_data: HashData) -> None:
+        """Set the WaveID reader configuration and Extended configuration for the specified configuration number."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_SetReaderConfiguration(
+            byref(result), self._handle.value, c_uint8(configuration_number), byref(config), byref(extended_config), byref(hash_data)
+        )
+        ReaderException.raise_if_error(result)
+
+    def get_led_configuration(self, configuration_number: int):
+        """Get the LED configuration for the specified configuration number."""
+        self._throw_if_disposed()
+        from reader_integration_kit.structures.led_configuration import LedConfiguration
+        led_config = LedConfiguration()
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetLedConfiguration(
+            byref(result), self._handle.value, c_uint8(configuration_number), byref(led_config)
+        )
+        ReaderException.raise_if_error(result)
+        return led_config
+
+    def set_led_configuration(self, configuration_number: int, led_configuration):
+        """Set the LED configuration for the specified configuration number."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_SetLedConfiguration(
+            byref(result), self._handle.value, c_uint8(configuration_number), byref(led_configuration)
+        )
+        ReaderException.raise_if_error(result)
+    
+    def enable_keystroking(self, enable: bool) -> None:
+        """Enable or disable key stroking."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_EnableKeystroking(
+            byref(result), self._handle.value, c_bool(enable)
+        )
+        ReaderException.raise_if_error(result)
+    
+    def get_luid(self) -> LuidResponseInformation:
+        """
+        Get Luid information from the reader.
+        
+        Returns:
+            LuidResponseInformation: Structure containing Luid, application version, and bootloader version.
+        """
+        self._throw_if_disposed()
+        luid_info = LuidResponseInformation()
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetLuid(
+            byref(result), self._handle.value, byref(luid_info)
+        )
+        ReaderException.raise_if_error(result)
+        return luid_info
+
+    def set_luid(self, luid: int) -> None:
+        """
+        Set Luid on the reader.
+        
+        Args:
+            luid: The Luid value to set.
+        """
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_SetLuid(
+            byref(result), self._handle.value, c_uint16(luid)
+        )
+        ReaderException.raise_if_error(result)
+
+    def write_user_defaults_to_reader(self) -> None:
+        """Write user defaults to reader (copies active flash configuration to stored flash)."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_WriteUserDefaultsToReader(
+            byref(result), self._handle.value
+        )
+        ReaderException.raise_if_error(result)
+
+    def reset_reader_configuration(self, checkpoint_type: CheckpointType) -> None:
+        """
+        Reset reader configuration to a specified checkpoint.
+
+        Args:
+            checkpoint_type: CheckpointType enum value (FACTORY_DEFAULTS=1, USER_SETTINGS=2).
+        """
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_ResetReaderConfiguration(
+            byref(result), self._handle.value, c_uint8(checkpoint_type.value)
+        )
+        ReaderException.raise_if_error(result)
+
+    def get_supported_card_types(self) -> list:
+        """Get the supported card types for this reader.
+
+        Returns:
+            list: A list of CardTypeInfo dicts, each containing 'Value', 'Name', and 'EnumName'.
+        """
+        self._throw_if_disposed()
+        from reader_integration_kit.structures.card_type_info import SupportedCardTypesResult
+
+        result = RikResult()
+        supported = SupportedCardTypesResult()
+
+        self._native_lib._dll.RikReader_GetSupportedCardTypes(
+            byref(result), self._handle.value, byref(supported)
+        )
+        ReaderException.raise_if_error(result)
+
+        # Convert valid entries to dicts
+        return [supported.CardTypes[i].to_dict() for i in range(supported.Count)]
+
+    def read_ble_configuration_from_reader(self, data_type: BleDataType, file_name: str) -> None:
+        """
+        Read BLE configuration from the reader and write it to a file.
+
+        Args:
+            data_type: The BLE data type (BleDataType.DATA or BleDataType.KEY).
+            file_name: The file path to write the BLE configuration to.
+                      The file will be in BLE HWG+ format (.hwg+ extension recommended).
+
+        Raises:
+            ReaderException: If the operation fails.
+        """
+        self._throw_if_disposed()
+        data_type_value = data_type.value if hasattr(data_type, 'value') else data_type
+
+        result = RikResult()
+        file_name_bytes = file_name.encode('utf-8')
+
+        self._native_lib._dll.RikReader_ReadBleConfigurationFromReader(
+            byref(result), self._handle.value, c_uint8(data_type_value), file_name_bytes
+        )
+        ReaderException.raise_if_error(result)
+
+    def write_ble_configuration_to_reader(self, data_type: BleDataType, file_name: str) -> None:
+        """
+        Write BLE configuration from a file to the reader.
+
+        Args:
+            data_type: The BLE data type (BleDataType.DATA, BleDataType.KEY, or BleDataType.UNENCRYPTED_KEY).
+            file_name: The file path to read the BLE configuration from.
+                      The file must be in BLE HWG+ format (.hwg+ extension).
+
+        Raises:
+            ReaderException: If the operation fails.
+        """
+        self._throw_if_disposed()
+        data_type_value = data_type.value if hasattr(data_type, 'value') else data_type
+
+        result = RikResult()
+        file_name_bytes = file_name.encode('utf-8')
+
+        self._native_lib._dll.RikReader_WriteBleConfigurationToReader(
+            byref(result), self._handle.value, c_uint8(data_type_value), file_name_bytes
+        )
+        ReaderException.raise_if_error(result)
+
+
+    def write_hwg_file_to_reader(self, file_name: str) -> None:
+        """Write an HWG file to the WaveID reader."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_WriteHwgFileToReader(
+            byref(result), self._handle.value, c_char_p(file_name.encode('utf-8'))
+        )
+        ReaderException.raise_if_error(result)
+
+    def read_hwg_file_from_reader(self, file_name: str, secure_hwg_format: bool = True) -> None:
+        """Read an HWG file from the WaveID reader."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_ReadHwgFileFromReader(
+            byref(result), self._handle.value, c_char_p(file_name.encode('utf-8')), c_bool(secure_hwg_format)
+        )
+        ReaderException.raise_if_error(result)
+
+    def write_smart_card_configuration_to_reader(self, file_name: str) -> None:
+        """Write smart card configuration to the reader."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_WriteSmartCardConfigurationToReader(
+            byref(result), self._handle.value, file_name.encode('utf-8')
+        )
+        ReaderException.raise_if_error(result)
+
+    def read_smart_card_configuration_from_reader(self, config: SmartCardConfigurationStruct) -> None:
+        """Read smart card configuration from the reader."""
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_ReadSmartCardConfigurationFromReader(
+            byref(result), self._handle.value, byref(config)
+        )
+        ReaderException.raise_if_error(result)
+
+    def on_credential_presented(self, callback: CredentialCallback) -> int:
+        """
+        Subscribe to card-read events. The callback is invoked on the reader's
+        background executor thread whenever a new credential is detected.
+
+        The event fires on the leading edge of a card presence. If a card remains
+        on the reader continuously - including across periods with no active
+        subscribers - the event will not re-fire for that card. The event only
+        fires again after the card is removed and a new (or the same) card is
+        presented.
+
+        Note:
+            If a card is removed and re-placed while no subscribers are active,this may not be detected.
+
+        Args:
+            callback: A Python callable with signature
+                      ``callback(card_data: CardData) -> None``.
+                      The callable is kept alive automatically for the duration
+                      of the subscription.
+
+        Returns:
+            int: A subscription ID. Pass this to unsubscribe_credential_callback()
+                 to cancel the subscription.
+        """
+        self._throw_if_disposed()
+
+        # Build the CFUNCTYPE wrapper and keep it alive on self to prevent GC.
+        NativeCredentialCallback = self._native_lib._credential_callback_type
+
+        def _native_cb(card_data_ptr, bit_count):
+            card_data = CardData()
+            for i in range(len(card_data.data)):
+                card_data.data[i] = card_data_ptr[i]
+            card_data.bit_count = bit_count
+            callback(card_data)
+
+        native_cb = NativeCredentialCallback(_native_cb)
+
+        # Store against subscription ID after we know the ID.
+        result = RikResult()
+        sub_id = self._native_lib._dll.RikReader_OnCredentialPresented(
+            byref(result), self._handle.value, native_cb
+        )
+        ReaderException.raise_if_error(result)
+
+        # Keep the ctypes wrapper alive for the duration of the subscription.
+        self._credential_callbacks[sub_id] = native_cb
+
+        return sub_id
+
+    def unsubscribe_credential_callback(self, subscription_id: int) -> None:
+        """
+        Cancel a previously registered credential-callback subscription.
+        Stops the polling thread if no subscribers remain.
+
+        Args:
+            subscription_id: The ID previously returned by on_credential_presented().
+        """
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_UnsubscribeCredentialCallback(
+            byref(result), self._handle.value, c_uint32(subscription_id)
+        )
+        ReaderException.raise_if_error(result)
+
+        # Release the ctypes wrapper now that the C++ side no longer holds it.
+        self._credential_callbacks.pop(subscription_id, None)
+
+    def enable_transparent_mode(self, enable: bool, write_to_flash: bool) -> None:
+        """Enable or disable transparent mode on the reader.
+
+        Args:
+            enable: True to enable transparent mode, False to disable.
+            write_to_flash: True for permanently enabling/disabling the transparent mode state irrespective of the reader power cycle. False otherwise.
+        """
+        self._throw_if_disposed()
+        result = RikResult()
+        self._native_lib._dll.RikReader_EnableTransparentMode(
+            byref(result), self._handle.value,
+            c_uint8(1 if enable else 0),
+            c_uint8(1 if write_to_flash else 0)
+        )
+        ReaderException.raise_if_error(result)
+
+    def get_transparent_mode_status(self) -> tuple[TransparentModeState, TransparentModeStatus]:
+        """
+        Get the current transparent mode state and status from the reader.
+
+        Returns:
+            tuple: 
+            TransparentModeState indicates whether transparent mode is currently enabled or disabled in the reader. <br>
+            TransparentModeStatus Can be Ready/NotReady. Ready indicates that reader card polling has been terminated. Not ready indicates that the reader is still polling.
+        """
+        self._throw_if_disposed()
+        state_raw = c_uint8(0)
+        status_raw = c_uint8(0)
+        result = RikResult()
+        self._native_lib._dll.RikReader_GetTransparentModeStatus(
+            byref(result), self._handle.value, byref(state_raw), byref(status_raw)
+        )
+        ReaderException.raise_if_error(result)
+        return TransparentModeState(state_raw.value), TransparentModeStatus(status_raw.value)
+
+class ReaderDiscovery:
+    """
+    A helper class for discovering connected rfIDEAS readers.
+    """
+
+    @staticmethod
+    def discover_usb_readers() -> list:
+        """
+        Enumerates the available rfIDEAS USB readers.
+
+        Returns:
+            List: ReaderDefinition objects describing each connected USB reader.
+
+        Raises:
+            ReaderException: If device enumeration fails.
+        """
+        
+        # Get the native library instance to access the DLL
+        native_lib = _NativeLibrary()
+        
+        # First call: get the count of readers
+        result = RikResult()
+        reader_count = ctypes.c_size_t(0)
+        native_lib._dll.Rik_DiscoverUsbReaders(byref(result), None, byref(reader_count))
+        ReaderException.raise_if_error(result)
+        
+        # If no readers found, return empty list
+        if reader_count.value == 0:
+            return []
+        
+        # Second call: get the actual reader information
+        readers_array = (ReaderDefinition * reader_count.value)()
+        result = RikResult()
+        native_lib._dll.Rik_DiscoverUsbReaders(byref(result), readers_array, byref(reader_count))
+        ReaderException.raise_if_error(result)
+        
+        # Convert to list of ReaderDefinition objects
+        return list(readers_array[:reader_count.value])
+
+# Export the main classes
+__all__ = ['AbstractReader', 'Reader', 'ReaderDiscovery', 'ReaderHandle', 'CredentialCallback']
+