Metadata-Version: 2.4
Name: reader-integration-kit
Version: 1.7.0
Summary: A Python wrapper for the rfIDEAS Reader Integration Kit library
Home-page: https://docs.rfideas.com/rik/
Author: rf IDEAS, Inc.
Author-email: appdev@rfideas.com
Project-URL: Documentation, https://docs.rfideas.com/rik/
Project-URL: Homepage, https://www.rfideas.com
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: rfIDEAS_EULA.txt
Requires-Dist: setuptools>=42
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Reader Integration Kit - Python Binding

A Python wrapper for the rf IDEAS Reader Integration Kit native library. This package enables Python
applications to communicate with rf IDEAS readers using a high-level reader interface.

## Supported Platforms

This package ships platform-tagged wheels for all supported architectures.
`pip` automatically selects the correct wheel for your operating system and CPU:

| Platform / Architecture | Wheel tag |
|---|---|
| Linux x86_64 | `manylinux_*_x86_64` |
| Linux ARM64 (generic aarch64 and Raspberry Pi 5) | `manylinux_*_aarch64` |
| Linux 32-bit ARM hard-float (ARMhf / armv7) | `manylinux_*_armv7l` |
| Windows x86_64 | `win_amd64` |
| macOS 12.0+ (Intel + Apple Silicon) | `macosx_12_0_universal2` |

## Installation

Install from PyPI with a single command — no need to pick a platform-specific package name:

```sh
pip install reader-integration-kit
```

### Raspberry Pi 5 runtime detection

The `linux_aarch64` wheel bundles both the Pi 5-optimized and the generic ARM64 native library.
The correct variant is selected automatically at import time by reading `/proc/device-tree/model`.
You can override this for testing with the `RIK_ARM_VARIANT` environment variable:

```sh
RIK_ARM_VARIANT=pi5     python my_script.py   # force Pi 5 variant
RIK_ARM_VARIANT=generic python my_script.py   # force generic variant
```

### Backward-compatible package names

Users upgrading from the old per-platform package names (e.g.
`reader-integration-kit-linux-x86-64`) will be automatically redirected to this unified
package via pip's dependency resolution — no manual action is required.

### Prerequisites

- Windows 10/11 (x64), Linux x64, Linux ARM64 / ARMhf (Ubuntu 24.04+ or equivalent),
  or macOS 12.0 (Monterey) or later (Intel or Apple Silicon)
- A connected rf IDEAS reader (USB or serial), e.g. WaveID
- Python 3.8 or later
- On Linux, appropriate udev rules may be required for USB reader access
- On macOS, no `sudo` / root and no App Sandbox HID/USB entitlements are
  required for CLI or non-sandboxed apps on macOS 12.0 Monterey and later
  (Intel x86_64 and Apple Silicon arm64). Reader discovery does not require
  Input Monitoring. Opening a keyboard-class HID collection (typical for
  current rf IDEAS readers) may require an Input Monitoring
  (`kTCCServiceListenEvent`) grant on the *responsible process* — often the
  host app such as Terminal.app, not the RIK binary itself. Headless or
  LaunchDaemon hosts can discover readers but still fail to open them when
  no console TCC identity is available.

## Keystroking Behavior

RIK opens readers non-exclusively. If a reader is configured in keystroking mode,
it will continue to send keystrokes to the focused application while RIK is
connected. This is intended behavior. Applications that connect to readers
potentially configured for keystroking should account for simultaneous keystroke
delivery when designing their input handling — for example by calling
`enable_keystroking(False)` before connecting, or by ensuring no sensitive input
field is focused during card reads.

## Usage

Import the `reader_integration_kit` module and create an instance of `Reader`. The facade uses
handles to manage reader instances, allowing you to interact with multiple readers concurrently.

### WaveID Reader Example

```python
import reader_integration_kit.facade as reader
from reader_integration_kit.structures import ReaderDefinition, DeviceId, SerialPortSettings
from reader_integration_kit.enum import ProtocolType, BeepDuration, BeepVolume

# Create a reader definition for WaveID
reader_def = ReaderDefinition(
    DeviceId=DeviceId(VendorId=0x0c27, ProductId=0x3bfa),
    ProtocolType=ProtocolType.FEATURE_REPORT,
    SerialPortSettings=SerialPortSettings()
)

# Create a WaveID reader instance
with reader.Reader(reader_def, retry_count=3) as waveid:
    # Initialize the reader
    waveid.init()

    # Get reader metadata (populated lazily on first access)
    metadata_dict = waveid.get_metadata()
    print(f"Part Number: {metadata_dict.get('PartNumber', 'N/A')}")

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

    # Beep the reader
    waveid.beep(2, BeepDuration.BEEP_DURATION_SHORT)

    # Get beeper volume
    volume = waveid.get_beeper_volume()
    print(f"Beeper Volume: {volume}")

    # Set beeper volume
    waveid.set_beeper_volume(BeepVolume.BEEP_VOLUME_HIGH)
```

**Note:** The `Reader` class manages reader handles internally. Each instance corresponds to
a single reader handle. You can create multiple `Reader` instances to interact with multiple readers
simultaneously. Resources are automatically released when exiting the context manager (`with`
statement) or when the object is garbage collected.

## Documentation

For integration guides and complete API reference, see the
[rf IDEAS Documentation](https://docs.rfideas.com/rik/).

## License

This package is proprietary software distributed by rf IDEAS, Inc. Use of this package is subject to
the End-User License Agreement (EULA) included with the package. See the included `rfIDEAS_EULA.txt` for
full terms and conditions.

---
Copyright rf IDEAS, Inc. All rights reserved.
