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 the platform-specific package:

# Linux
pip install reader-integration-kit-linux-x86-64

# Windows
pip install reader-integration-kit-windows-x86-64
note

Each package includes the native shared library for its platform. The Python import name is the same regardless of which platform package you install.

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,
)
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()CardDataRead card data from the reader

Credential Callbacks​

MethodReturnsDescription
on_credential_presented(callback)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.

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

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

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

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_void_pUSB device path (optional; use to target a specific USB port)
SerialNumberc_void_pUSB serial number string (optional; use to target a specific reader)

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

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}")

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​