C# API

The C# facade wraps the RIK native library in idiomatic .NET classes with IDisposable support and managed exceptions.

Installation

dotnet add package rfIDEAS.ReaderIntegrationKit

note

The NuGet package includes pre-built native libraries for Windows x64, Linux x64, Linux ARM64, Linux ARMhf, and macOS (Intel + Apple Silicon, Monterey 12+). No additional native library setup is needed. The package targets .NET 8.0 and .NET 10.0.

Supported platforms

Platform	Runtime identifier	Native library path (inside package)
Windows x64	win-x64	runtimes/win-x64/native/ReaderIntegrationKit.dll
Linux x64	linux-x64	runtimes/linux-x64/native/libReaderIntegrationKit.so
Linux ARM64 (generic)	linux-arm64	runtimes/linux-arm64/native/libReaderIntegrationKit.so
Linux ARM64 (Raspberry Pi 5)	linux-arm64	runtimes/linux-arm64/native/libReaderIntegrationKit.pi5.so
Linux ARM 32-bit (ARMhf)	linux-arm	runtimes/linux-arm/native/libReaderIntegrationKit.so
macOS x64	osx-x64	runtimes/osx-x64/native/libReaderIntegrationKit.dylib
macOS ARM64 (Apple Silicon)	osx-arm64	runtimes/osx-arm64/native/libReaderIntegrationKit.dylib

macOS universal fallback

The package also includes the same dylib at runtimes/osx-universal/native/libReaderIntegrationKit.dylib. The NativeLibraryLocator in the C# facade probes the RID-specific path (osx-x64 or osx-arm64) first and falls back to osx-universal automatically. Consumer projects do not need to reference osx-universal directly.

ARM64: generic vs Raspberry Pi 5

The package ships two ARM64 builds under runtimes/linux-arm64/native/:

• libReaderIntegrationKit.so — portable aarch64 build for any ARMv8-A device
• libReaderIntegrationKit.pi5.so — build optimized for Raspberry Pi 5 (-mcpu=cortex-a76)

At runtime the loader uses the RIK_ARM_VARIANT environment variable when set (pi5 or generic); otherwise it reads /proc/device-tree/model and falls back to generic. Set RIK_ARM_VARIANT=pi5 to force the Pi 5 build, or generic for the portable build.

Namespace

using rfIDEAS.ReaderIntegrationKit;
using rfIDEAS.ReaderIntegrationKit.Objects;
using rfIDEAS.ReaderIntegrationKit.Enum;

---

AbstractReader (abstract)

Base class for all reader applications. Implements IDisposable.

Methods

Method	Returns	Description
Init()	void	Initialize connection to the reader
RefreshMetadata()	void	Force a metadata refresh from the device
GetMetadata(bool forceRefresh = false)	ReaderMetadataStruct	Get reader metadata (cached unless forceRefresh is true)
GetLibraryInfo()	LibraryInfo	Static. Get library version info (no instance required)
Dispose()	void	Release native resources

---

Reader : AbstractReader

Application class for rf IDEAS readers.

Constructor

new Reader(ReaderDefinition readerDefinition, int retryCount = 3)

Parameter	Type	Description
readerDefinition	ReaderDefinition	Reader connection parameters
retryCount	int	Connection retry attempts (default: 3)

Methods

Beeper

Method	Returns	Description
Beep(int beepCount, BeepDuration duration)	void	Sound the beeper
GetBeeperVolume()	BeepVolume	Get current volume
SetBeeperVolume(BeepVolume volume)	void	Set volume

Card Data

Method	Returns	Description
GetCardData(out CardData cardData, GetCardDataSizeParameters sizeParameter = GetCardDataSizeParameters.Read32Bytes)	void	Read card data from the reader

8-byte reads truncate silently

GetCardDataSizeParameters.Read8Bytes 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. BitCount always reports the full credential width, so a bit count greater than 64 means the card carries more data than was returned. Prefer GetCardDataSizeParameters.Read32Bytes. See GetCardDataSizeParameters.

Credential Callbacks

Method	Returns	Description
OnCredentialPresented(CredentialCallback callback, GetCardDataSizeParameters sizeParameter = GetCardDataSizeParameters.Read32Bytes)	uint	Subscribe to credential events. Returns a subscription ID.
UnsubscribeCredentialCallback(uint subscriptionId)	void	Unsubscribe a previously registered callback

The CredentialCallback delegate is defined as:

public delegate void CredentialCallback(CardData cardData);

tip

When a card is presented to the reader, the callback fires on a background thread 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 OnCredentialPresented call with a different sizeParameter changes the payload delivered to all existing subscribers on that reader.

Configuration

Method	Returns	Description
GetReaderConfiguration(byte configurationNumber)	(ReaderConfigurationStruct, ExtendedConfiguration)	Read configuration slot
SetReaderConfiguration(byte configurationNumber, ReaderConfigurationStruct config, ExtendedConfiguration extendedConfig, HashData hashData)	void	Write configuration slot
WriteUserDefaultsToReader()	void	Copy the active flash configuration to stored (user-default) flash
ResetReaderConfiguration(CheckpointType checkpointType)	void	Reset configuration to a checkpoint (CheckpointType.FactoryDefaults or CheckpointType.UserSettings)

note

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

LED

Method	Returns	Description
GetLedConfiguration(int configurationNumber)	LedConfiguration	Read LED configuration
SetLedConfiguration(int configurationNumber, LedConfiguration ledConfig)	void	Write LED configuration

LUID

Method	Returns	Description
GetLuid()	LuidResponseInformation	Get Logical Unit ID
SetLuid(int luid)	void	Set Logical Unit ID

Module Control

Method	Returns	Description
GetModuleState(ReaderModuleId moduleId)	ReaderModuleState	Get module power state
SetModuleState(ReaderModuleId moduleId, ReaderModuleState state)	void	Set module power state

Modes

Method	Returns	Description
EnableKeystroking(bool enable)	void	Enable or disable keystroking
EnableTransparentMode(bool enable, bool writeToFlash)	void	Enable or disable transparent mode
GetTransparentModeStatus(out TransparentModeState state, out TransparentModeStatus status)	void	Get transparent mode state and readiness

Card Types

Method	Returns	Description
GetSupportedCardTypes()	IEnumerable<CardTypeInfo>	List supported card types

BLE Configuration

Method	Returns	Description
ReadBleConfigurationFromReader(BleDataType dataType, string fileName)	void	Read BLE config to file
WriteBleConfigurationToReader(BleDataType dataType, string fileName)	void	Write BLE config from file

HWG Configuration

Method	Returns	Description
WriteHwgFileToReader(string fileName)	void	Write an HWG configuration file to the reader
ReadHwgFileFromReader(string fileName, bool secureHwgFormat = true)	void	Read configuration from the reader and save to an HWG file

Smart Card Configuration

Method	Returns	Description
WriteSmartCardConfigurationToReader(string filePath)	void	Write smart card configuration from an INI file to the reader
ReadSmartCardConfigurationFromReader(ref SmartCardConfigurationStruct configStruct)	void	Read smart card configuration from the reader

---

ReaderDiscovery (static)

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

Methods

Method	Returns	Description
DiscoverUsbReaders()	List<ReaderDefinition>	Static. Discovers all connected rf IDEAS USB readers

Throws: ReaderException if USB enumeration fails.

using rfIDEAS.ReaderIntegrationKit;

var readers = ReaderDiscovery.DiscoverUsbReaders();

foreach (var readerDef in readers)
{
    Console.WriteLine($"VID:PID: 0x{readerDef.DeviceId.VendorId:X4}:0x{readerDef.DeviceId.ProductId:X4}");
    Console.WriteLine($"Path:    {readerDef.DeviceId.UsbPathString}");
    Console.WriteLine($"Serial:  {readerDef.DeviceId.SerialNumberString}");
}

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

---

Key Types

Defined in rfIDEAS.ReaderIntegrationKit.Objects.

ReaderDefinition

Property	Type	Description
DeviceId	DeviceId	Vendor and product identifiers
ProtocolType	ProtocolType	Communication protocol
SerialPortSettings	SerialPortSettings	Serial port configuration (serial connections only)

DeviceId

Property	Type	Description
VendorId	ushort	USB vendor ID
ProductId	ushort	USB product ID
UsbPath	byte[512]	USB device path as UTF-8 byte array (optional). Read back via UsbPathString helper property.
SerialNumber	byte[256]	USB serial number as UTF-8 byte array (optional). Read back via SerialNumberString helper property.

SerialPortSettings

Property	Type
BaudRate	SerialPortBaudRate
Parity	SerialPortParity
FlowControl	SerialPortFlowControl
PortName	string
ByteSize	int
DataBits	SerialPortDataBits
StopBits	SerialPortStopBits

ReaderMetadataStruct

Contains string fields (part number, serial number, model name, etc.), firmware version structs, hardware capability flags, Has* boolean flags indicating which fields were populated, and an AdvancedAttributes struct with read-only hardware capabilities. See Structures for full details.

CardData

Property	Type	Description
Data	byte[]	Raw card data bytes
BitCount	int	Number of valid bits
IsEmpty()	bool	Returns true if bit count is zero and all data bytes are zero
AsHexString()	string	Hex representation of the data

LibraryInfo

Contains 27+ string fields with library version and build metadata (version string, build date, compiler, platform, etc.).

LedConfiguration

Property	Type	Description
Color	LedColor	LED color
SoftwareControlEnabled	bool	Whether software LED control is active

ReaderException

Thrown on any native library error.

Property	Type	Description
Message	string	Error description
FileName	string	Source file
LineNumber	int	Source line
FunctionName	string	Source function
HasProtocolException	bool	Whether protocol-level details are available
ProtocolMessage	string	Protocol error description

---

Enums

Defined in rfIDEAS.ReaderIntegrationKit.Enum.

ProtocolType

Value	Description
Invalid	Not set
FeatureReport	USB HID feature report
SerialBinary	Serial binary protocol
Unknown	Unrecognized

BeepDuration

Value	Description
BeepDurationShort	Short beep
BeepDurationLong	Long beep

BeepVolume

Value	Description
Off	Muted
Low	Low volume
Medium	Medium volume
High	High volume
Unknown	Unknown / unset

LedColor

Value	Description
Invalid	Not set
Off	LED off
Red	Red
Green	Green
Amber	Amber
Unknown	Unknown / unset

ReaderModuleId

Value	Description
Invalid	Not set
LowFrequencyRadio	125 kHz radio
HighFrequencyRadio	13.56 MHz radio
BleRadio	Bluetooth Low Energy radio

ReaderModuleState

Value	Hex	Description
Invalid	0x00	Not set
PowerOff	0x80	Module powered off
PowerOnNormal	0x81	Module powered on, normal operation

BleDataType

Value	Int	Description
Data	1	BLE data payload
Key	2	Encrypted key
UnencryptedKey	3	Unencrypted key

CheckpointType

Value	Int	Description
Undefined	0	Not set
FactoryDefaults	1	Reset configuration to factory defaults
UserSettings	2	Reset configuration to the stored user defaults

GetCardDataSizeParameters

Value	Hex	Description
Undefined	0x00	Invalid / unset — do not pass
Read8Bytes	0x01	8-byte read
Read32Bytes	0x02	32-byte read (default)

CardCategory

Value	Int	Description
Off	0	Category not applicable / disabled
Secure	1	Secure credential
NonSecure	2	Non-secure credential
Bluetooth	3	Bluetooth / mobile credential

CardFrequency

Value	Int	Description
Na	0	Frequency not applicable
Ble	1	Bluetooth Low Energy RF
High	2	High frequency
Low	3	Low frequency
Dual	4	Dual frequency

---

Examples

Basic Connection

using rfIDEAS.ReaderIntegrationKit;
using rfIDEAS.ReaderIntegrationKit.Objects;
using rfIDEAS.ReaderIntegrationKit.Enum;

var readerDef = new ReaderDefinition
{
    DeviceId = new DeviceId { VendorId = 0x0C27, ProductId = 0x3BFA },
    ProtocolType = ProtocolType.FeatureReport
};

using var app = new Reader(readerDef);
app.Init();

var metadata = app.GetMetadata();
Console.WriteLine($"Part: {metadata.PartNumber}");
Console.WriteLine($"Serial: {metadata.ESN}");

Beep

using var app = new Reader(readerDef);
app.Init();

app.Beep(2, BeepDuration.BeepDurationShort);
app.SetBeeperVolume(BeepVolume.High);

Read Card Data

using var app = new Reader(readerDef);
app.Init();

// Default: 32-byte path
app.GetCardData(out var card);
if (!card.IsEmpty())
{
    Console.WriteLine($"Bits: {card.BitCount}");
    Console.WriteLine($"Hex: {card.AsHexString()}");
}

using var app = new Reader(readerDef);
app.Init();

// 8-byte read
app.GetCardData(out var card, GetCardDataSizeParameters.Read8Bytes);
if (!card.IsEmpty())
{
    if (card.BitCount > 64)
        Console.WriteLine("Warning: card data was truncated (BitCount > 64)");
    Console.WriteLine($"Hex: {card.AsHexString()}");
}

Library Info (No Reader Required)

var info = AbstractReader.GetLibraryInfo();
Console.WriteLine($"Version: {info.VersionString}");

Thread Safety

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

See Also

• C++ API
• Python API
• Structures
• Enumerations
• Exceptions