Skip to main content

Python API

The Python facade wraps the RIK native library using ctypes. Classes support the context manager protocol (with statement) for automatic resource cleanup.

Installation​

Install from PyPI with a single command. pip selects the correct platform-tagged wheel automatically:

pip install reader-integration-kit
note

The wheel bundles the native shared library for your platform and CPU architecture (manylinux_*_x86_64, manylinux_*_aarch64, manylinux_*_armv7l, win_amd64, or macosx_12_0_universal2). The import name is reader_integration_kit on every platform. On macOS, a single universal2 wheel covers both Intel (x86_64) and Apple Silicon (arm64) -- no architecture-specific wheel selection is required. On Raspberry Pi 5 the ARM64 wheel bundles both the Pi 5-optimized and generic ARM64 libraries and selects the right one at import time (override with RIK_ARM_VARIANT=pi5 or RIK_ARM_VARIANT=generic). Older per-platform names such as reader-integration-kit-linux-x86-64 still resolve as redirect packages.

Requirements: Python 3.8+

Package​

import reader_integration_kit as rik
from reader_integration_kit.structures import ReaderDefinition, DeviceId, SerialPortSettings
from reader_integration_kit.enum import (
    ProtocolType, BeepDuration, BeepVolume, LedColor,
    ReaderModuleId, ReaderModuleState, BleDataType,
    GetCardDataSizeParameters,
)
from reader_integration_kit.errors import ReaderException

AbstractReader (base class)​

Base class for all reader applications. Supports the context manager protocol.

Methods​

MethodReturnsDescription
init()NoneInitialize connection to the reader
refresh_metadata()NoneForce a metadata refresh from the device
get_metadata(force_refresh=False)dictGet reader metadata
get_library_info()dictStatic. Get library version info (no instance required)
dispose()NoneRelease native resources

init() is not called automatically -- you must call it explicitly after entering the with block. Exiting the with block calls dispose().

tip

Always call init() after creating an instance or entering a with block. The constructor opens the connection but does not initialize communication with the reader.

Reader(AbstractReader)​

Application class for rf IDEAS readers.

Constructor​

Reader(reader_definition: ReaderDefinition, retry_count: int = 3)
ParameterTypeDescription
reader_definitionReaderDefinitionReader connection parameters
retry_countintConnection retry attempts (default: 3)

Methods​

Beeper​

MethodReturnsDescription
beep(beep_count, duration)NoneSound the beeper
get_beeper_volume()BeepVolumeGet current volume
set_beeper_volume(volume)NoneSet volume

Card Data​

MethodReturnsDescription
get_card_data(size_parameter=GetCardDataSizeParameters.READ_32_BYTES)CardDataRead card data from the reader
8-byte reads truncate silently

GetCardDataSizeParameters.READ_8_BYTES returns at most the first 8 bytes of the credential. The CardData buffer is still 32 bytes: bytes 0–7 hold the returned data and bytes 8–31 are zero. bit_count always reports the full credential width, so a bit count greater than 64 means the card carries more data than was returned. Prefer GetCardDataSizeParameters.READ_32_BYTES. See GetCardDataSizeParameters.

Credential Callbacks​

MethodReturnsDescription
on_credential_presented(callback, size_parameter=GetCardDataSizeParameters.READ_32_BYTES)intSubscribe to credential events. Returns a subscription ID.
unsubscribe_credential_callback(subscription_id)NoneUnsubscribe a previously registered callback

The callback signature is:

def my_callback(card_data: CardData) -> None:
    ...
tip

When a card is presented to the reader, the callback fires with the card data. Multiple callbacks can be registered simultaneously.

Read size is shared across subscribers

There is one read size per reader instance. A later on_credential_presented call with a different size_parameter changes the payload delivered to all existing subscribers on that reader.

Configuration​

MethodReturnsDescription
get_reader_configuration(configuration_number)tuple[ReaderConfigurationStruct, ExtendedConfiguration]Read configuration slot
set_reader_configuration(configuration_number, config, extended_config, hash_data)NoneWrite configuration slot
write_user_defaults_to_reader()NoneCopy the active flash configuration to stored (user-default) flash
reset_reader_configuration(checkpoint_type)NoneReset configuration to a checkpoint (CheckpointType.FACTORY_DEFAULTS or CheckpointType.USER_SETTINGS)
note

If the extended configuration header is invalid, set_reader_configuration logs a warning and skips writing the extended configuration. The standard ReaderConfigurationStruct is still written. This path does not raise.

LED​

MethodReturnsDescription
get_led_configuration(configuration_number)LedConfigurationRead LED configuration
set_led_configuration(configuration_number, led_configuration)NoneWrite LED configuration

LUID​

MethodReturnsDescription
get_luid()LuidResponseInformationGet Logical Unit ID
set_luid(luid)NoneSet Logical Unit ID

Module Control​

MethodReturnsDescription
get_module_state(module_id)ReaderModuleStateGet module power state
set_module_state(module_id, state)NoneSet module power state

Modes​

MethodReturnsDescription
enable_keystroking(enable)NoneEnable or disable keystroking
enable_transparent_mode(enable, write_to_flash)NoneEnable or disable transparent mode
get_transparent_mode_status()tuple[TransparentModeState, TransparentModeStatus]Get transparent mode state and readiness

Card Types​

MethodReturnsDescription
get_supported_card_types()list[dict]List supported card types

BLE Configuration​

MethodReturnsDescription
read_ble_configuration_from_reader(data_type, file_name)NoneRead BLE config to file
write_ble_configuration_to_reader(data_type, file_name)NoneWrite BLE config from file

HWG Configuration​

MethodReturnsDescription
write_hwg_file_to_reader(file_name)NoneWrite an HWG configuration file to the reader
read_hwg_file_from_reader(file_name, secure_hwg_format=True)NoneRead configuration from the reader and save to an HWG file

Smart Card Configuration​

MethodReturnsDescription
write_smart_card_configuration_to_reader(file_name)NoneWrite smart card configuration from an INI file to the reader
read_smart_card_configuration_from_reader(config)NoneRead smart card configuration from the reader

ReaderDiscovery​

Discovers connected rf IDEAS USB readers. Returns ready-to-use ReaderDefinition objects that can be passed directly to the Reader constructor.

Methods​

MethodReturnsDescription
discover_usb_readers()list[ReaderDefinition]Static. Discovers all connected rf IDEAS USB readers

Raises: ReaderException if USB enumeration fails.

from reader_integration_kit.facade import ReaderDiscovery

readers = ReaderDiscovery.discover_usb_readers()

for reader_def in readers:
    print(f"VID:PID: 0x{reader_def.DeviceId.VendorId:04X}:0x{reader_def.DeviceId.ProductId:04X}")
    print(f"Path:    {reader_def.DeviceId.UsbPath.decode()}")
    print(f"Serial:  {reader_def.DeviceId.SerialNumber.decode()}")

See Discovering USB Readers for full examples including discover-then-connect patterns.

Structures​

Defined in reader_integration_kit.structures. These are ctypes Structure subclasses.

ReaderDefinition​

FieldTypeDescription
DeviceIdDeviceIdVendor and product identifiers
ProtocolTypeProtocolTypeCommunication protocol
SerialPortSettingsSerialPortSettingsSerial port configuration (serial connections only)

DeviceId​

FieldTypeDescription
VendorIdintUSB vendor ID
ProductIdintUSB product ID
UsbPathc_char * 512USB device path as UTF-8 byte string (optional). Set via b"..." literal.
SerialNumberc_char * 256USB serial number as UTF-8 byte string (optional). Set via b"..." literal.

SerialPortSettings​

FieldType
BaudRateSerialPortBaudRate
ParitySerialPortParity
FlowControlSerialPortFlowControl
PortNamestr
ByteSizeint
DataBitsSerialPortDataBits
StopBitsSerialPortStopBits

CardData​

Field / MethodTypeDescription
datalist[int]Raw card data bytes (32-element list)
bit_countintNumber of valid bits
is_empty()boolTrue if bit count is zero and all data bytes are zero
as_bytes()bytesCard data as a bytes object
as_list()list[int]Card data as a list of integers
as_hex_string()strSpace-separated hex representation (e.g. "12 34 AB")

Enums​

Defined in reader_integration_kit.enum.

ProtocolType​

MemberValueDescription
INVALID0x00Invalid / unset
FEATURE_REPORT0x01USB HID feature report
SERIAL_BINARY0x03Serial binary protocol
UNKNOWN0xFFUnknown protocol

BeepDuration​

MemberValue
BEEP_DURATION_SHORT0
BEEP_DURATION_LONG1

BeepVolume​

MemberValue
BEEP_VOLUME_OFF0
BEEP_VOLUME_LOW1
BEEP_VOLUME_MEDIUM2
BEEP_VOLUME_HIGH3

LedColor​

MemberValue
INVALID0
OFF1
RED2
GREEN3
AMBER4
UNKNOWN0xFF

ReaderModuleId​

MemberValue
INVALID0
LOW_FREQUENCY_RADIO1
HIGH_FREQUENCY_RADIO2
BLE_RADIO3

ReaderModuleState​

MemberValueDescription
INVALID0x00Not set
POWER_OFF0x80Module powered off
POWER_ON_NORMAL0x81Module powered on, normal operation

BleDataType​

MemberValueDescription
DATA1BLE data payload
KEY2Encrypted key
UNENCRYPTED_KEY3Unencrypted key

GetCardDataSizeParameters​

MemberValueDescription
UNDEFINED0x00Invalid / unset — do not pass
READ_8_BYTES0x018-byte read
READ_32_BYTES0x0232-byte read (default)

CardCategory​

MemberValueDescription
OFF0Category not applicable / disabled
SECURE1Secure credential
NON_SECURE2Non-secure credential
BLUETOOTH3Bluetooth / mobile credential

CardFrequency​

MemberValueDescription
NA0Frequency not applicable
BLE1Bluetooth Low Energy RF
HIGH2High frequency
LOW3Low frequency
DUAL4Dual frequency

Errors​

ReaderException​

Raised on any native library error.

AttributeTypeDescription
messagestrError description
file_namestrSource file
line_numberintSource line
function_namestrSource function
has_protocol_exceptionboolWhether protocol-level details are available
protocol_messagestrProtocol error description

Examples​

Basic Connection​

import reader_integration_kit as rik
from reader_integration_kit.structures import ReaderDefinition, DeviceId
from reader_integration_kit.enum import ProtocolType

reader_def = ReaderDefinition()
reader_def.DeviceId.VendorId = 0x0C27
reader_def.DeviceId.ProductId = 0x3BFA
reader_def.ProtocolType = ProtocolType.FEATURE_REPORT

with rik.Reader(reader_def) as app:
    app.init()
    metadata = app.get_metadata()
    print(f"Part: {metadata['PartNumber']}")
    print(f"Serial: {metadata['ESN']}")

Beep​

with rik.Reader(reader_def) as app:
    app.init()
    app.beep(2, BeepDuration.BEEP_DURATION_SHORT)
    app.set_beeper_volume(BeepVolume.BEEP_VOLUME_HIGH)

Read Card Data​

with rik.Reader(reader_def) as app:
    app.init()
    card = app.get_card_data()
    if card.bit_count > 0:
        print(f"Bits: {card.bit_count}")
        print(f"Data: {card.data}")
from reader_integration_kit.enum import GetCardDataSizeParameters

with rik.Reader(reader_def) as app:
    app.init()
    # 8-byte read
    card = app.get_card_data(size_parameter=GetCardDataSizeParameters.READ_8_BYTES)
    if card.bit_count > 64:
        # data was truncated; bytes 8-31 are zero
        pass

Metadata​

with rik.Reader(reader_def) as app:
    app.init()

    # Cached metadata
    metadata = app.get_metadata()

    # Force refresh from device
    metadata = app.get_metadata(force_refresh=True)

Library Info (No Reader Required)​

info = rik.AbstractReader.get_library_info()
print(f"Version: {info['VersionString']}")

Error Handling​

from reader_integration_kit.errors import ReaderException

try:
    with rik.Reader(reader_def) as app:
        app.init()
        card = app.get_card_data()
except ReaderException as e:
    print(f"Error: {e.message}")
    if e.has_protocol_exception:
        print(f"Protocol: {e.protocol_message}")

Thread Safety​

All methods are thread-safe. Internal locking ensures safe concurrent access.

See Also​