Common Library (C++ Only)

The Common library (ReaderIntegrationKitCommon) is a C++ library providing shared types, configuration structures, card types, file parsers, and utilities used across the RIK ecosystem. It is not published to NuGet or PyPI — it is consumed directly by C++ applications.

note

This library is C++ only and is not available via NuGet or PyPI.

Installation

find_package(ReaderIntegrationKitCommon REQUIRED)

You can also use FetchContent or add_subdirectory to integrate the library. See the installation guide for details.

Card Types

All card type APIs live in the RikCommon namespace.

CardType

Represents a single card type with its numeric ID and human-readable names.

Method	Return Type	Description
`CardType(const CardTypeInfo&)`	—	Construct from ABI-safe struct
`GetValue()`	`uint16_t`	Numeric card type ID
`GetName()`	`std::string`	Human-readable name (e.g. `"HID iCLASS"`)
`GetEnumName()`	`std::string`	Enum-style name (e.g. `"HID_ICLASS_ID"`)
`GetCategory()`	`CardCategory`	Card category (secure, non-secure, or Bluetooth)
`GetFrequency()`	`CardFrequency`	Card RF frequency (high, low, BLE, or dual)
`ToCardTypeInfo()`	`CardTypeInfo`	Convert back to ABI-safe struct

C# / Python expose the same data as properties / to_dict() keys rather than Get* methods: Category and Frequency on the facade CardTypeInfo (C# typed enums; Python integer ordinals).

CardTypeResolver

Static utility for looking up card types.

Method	Description
`ResolveConfiguredCardType(uint16_t value)`	Look up a configured card type by value
`ResolveSupportedCardType(uint16_t value)`	Look up a supported card type by value
`FromName(const std::string& name)`	Look up by human-readable name. Returns `std::optional<CardType>`.
`FromEnumName(const std::string& enumName)`	Look up by enum identifier (e.g. `"HID_PROX"`). Returns `std::optional<CardType>`.
`GetAll()`	Returns `std::vector<CardType>` of all known types
`GetCount()`	Number of known card types
`GetVersion()`	Returns `CardTypeVersion` (see below)
`GetVersionString()`	Card type version as a string

CardTypeVersion

ABI-safe semver struct returned by CardTypeResolver::GetVersion().

note

CardTypeVersion is a global extern "C" struct. It is not in namespace RikCommon. Do not write RikCommon::CardTypeVersion.

Field	Type	Description
`Major`	`uint8_t`	Major version component
`Minor`	`uint8_t`	Minor version component
`Patch`	`uint8_t`	Patch version component

Example

#include "CardTypes/CardTypeResolver.h"
#include <iostream>

using namespace RikCommon;

int main() {
    auto allTypes = CardTypeResolver::GetAll();
    std::cout << "Known card types: " << CardTypeResolver::GetCount() << "\n";

    auto cardType = CardTypeResolver::FromEnumName("HID_PROX");
    if (cardType) {
        std::cout << "Value: " << cardType->GetValue()
                  << "  Name: " << cardType->GetName() << "\n";
    }

    return 0;
}

Configuration Structures

ReaderConfiguration

Fluent-builder wrapper around the packed C struct ReaderConfigurationStruct. Each setter returns ReaderConfiguration& for chaining. See the struct page for the 62-field ABI layout (C++, C#, and Python).

note

This class is C++ only. It is not available in the C# NuGet package or the Python package. C# and Python use ReaderConfigurationStruct directly.

Header: #include "Structures/Configuration/ReaderConfigurationStruct.h"

Constants:

Constant	Value	Description
`FAC_DIGIT_COUNT_MAX`	`26`	Maximum value for `SetFacDigitCount`
`ID_DIGIT_COUNT_MAX`	`26`	Maximum value for `SetIdDigitCount`
`PARITY_COUNT_MAX`	`0x8E` (142)	Maximum value for `SetTotalStripLeadingParityCount` and `SetTotalStripTrailingParityCount`

Block 1 — FAC/ID Format (16)

Method	Parameter Type	Description / Constraints
`SetFacDigitCount(unsigned int count)`	`unsigned int`	Sets `FacDigitCount`. Range: `[0, 26]`. Throws `RfIdeasException` if out of range.
`SetIdDigitCount(unsigned int count)`	`unsigned int`	Sets `IdDigitCount`. Range: `[0, 26]`. Throws `RfIdeasException` if out of range.
`SetTotalStripLeadingParityCount(unsigned int count)`	`unsigned int`	Range: `[0, 0x8E / 142]`. Throws `RfIdeasException` if out of range.
`SetTotalStripTrailingParityCount(unsigned int count)`	`unsigned int`	Range: `[0, 0x8E / 142]`. Throws `RfIdeasException` if out of range.
`SetIdBitCount(unsigned int count)`	`unsigned int`	Sets `IdBitCount`.
`SetExpectedBitCount(unsigned int count)`	`unsigned int`	Sets `ExpectedBitCount`.
`SetIdAndFacDelimiter(unsigned char delimiter)`	`unsigned char`	Sets `IdAndFacDelimiter`.
`SetTerminationCharacter(unsigned char terminationCharacter)`	`unsigned char`	Sets `TerminationCharacter`.
`UseFixedLengthForFacAndId(bool useFixedLength)`	`bool`	Sets `UseFixedLengthForFacAndId`.
`EnforceExpectedBitCount(bool enforce)`	`bool`	Sets `EnforceExpectedBitCount`.
`StripFacFromId(bool stripFac)`	`bool`	Sets `StripFacFromId`.
`SendFacAfterStrippingIt(bool sendFac)`	`bool`	Sets `SendFacAfterStrippingIt`.
`UseIdAndFacDelimiter(bool useDelimiter)`	`bool`	Sets `UseIdAndFacDelimiter`.
`DisableKeystrokeTerminationCharacter(bool disable)`	`bool`	Sets `DisableKeystrokeTerminationCharacter`.
`EnableContinuousRead(bool enable)`	`bool`	Sets `EnableContinuousRead`.
`DisableKeystroking(bool disable)`	`bool`	Sets `DisableKeystroking`.

Block 2 — Timing and Output Format (16)

Method	Parameter Type	Description / Constraints
`SetLegacyBitStreamTimeOutMs(unsigned int milliseconds)`	`unsigned int`	Must be multiple of 4; range `[0, 1020]`. Throws `RfIdeasException` if not.
`SetDataHoldTimeMs(unsigned int milliseconds)`	`unsigned int`	Must be multiple of 50; range `[0, 12750]`. Throws `RfIdeasException` if not.
`SetLockOutTimeMs(unsigned int milliseconds)`	`unsigned int`	Must be multiple of 50; range `[0, 12750]`. Throws `RfIdeasException` if not.
`SetKeyPressTimeMs(unsigned int milliseconds)`	`unsigned int`	Must be multiple of 4; range `[0, 1020]`. Throws `RfIdeasException` if not.
`SetKeyReleaseTimeMs(unsigned int milliseconds)`	`unsigned int`	Must be multiple of 4; range `[0, 1020]`. Throws `RfIdeasException` if not.
`EnableIdExtendedPrecision(bool enable)`	`bool`	Sets `EnableIdExtendedPrecision`.
`UseLowercaseHex(bool useLowercase)`	`bool`	Sets `UseLowercaseHex`.
`EnableProxProEmulation(bool enable)`	`bool`	Sets `EnableProxProEmulation`.
`EnableHexadecimalId(bool enable)`	`bool`	Sets `EnableHexadecimalId`.
`EnableHexadecimalFac(bool enable)`	`bool`	Sets `EnableHexadecimalFac`.
`UseIndividualIdAndFacNumberFormats(bool useIndividualFormats)`	`bool`	Sets `UseIndividualIdAndFacNumberFormats`.
`UseNumericKeypad(bool useNumericKeypad)`	`bool`	Sets `UseNumericKeypad`.
`ReaderSupportsReverseAllBytes(bool supports)`	`bool`	Sets `ReaderSupportsReverseAllBytes`. Device-reported; `SetReaderConfiguration` preserves this field.
`ReaderSupportsAsciiExtended(bool supports)`	`bool`	Sets `ReaderSupportsAsciiExtended`. Device-reported; `SetReaderConfiguration` preserves this field.
`ReaderSupportsExtendedMode(bool supports)`	`bool`	Sets `ReaderSupportsExtendedMode`. Device-reported; `SetReaderConfiguration` preserves this field.
`EnableRoswellMode(bool enable)`	`bool`	Sets `EnableRoswellMode`. Device-preserved; not user-overridable via `SetReaderConfiguration`.

Block 3 — LED, Beeper, and Character Output (16)

Method	Parameter Type	Description / Constraints
`EnableRedLed(bool enable)`	`bool`	Sets `EnableRedLed`.
`EnableGreenLed(bool enable)`	`bool`	Sets `EnableGreenLed`.
`EnableOemRelay(bool enable)`	`bool`	Sets `EnableOemRelay`.
`EnableOemBeeper(bool enable)`	`bool`	Sets `EnableOemBeeper`.
`SetIsBootDevice(bool enable)`	`bool`	Sets `IsBootDevice`. Device-reported; `SetReaderConfiguration` preserves this field.
`UseLeadingCharacters(bool useLeadingChars)`	`bool`	Sets `UseLeadingCharacters`.
`EnabledSoftwareControlledLed(bool enable)`	`bool`	Sets `EnabledSoftwareControlledLed`.
`UseHexadecimalForBothFacAndId(bool useHex)`	`bool`	Sets `UseHexadecimalForBothFacAndId`.
`InvertWiegandBits(bool invert)`	`bool`	Sets `InvertWiegandBits`.
`EnableBeepOnCardRead(bool enable)`	`bool`	Sets `EnableBeepOnCardRead`.
`EnableReverseWiegandBits(bool reverse)`	`bool`	Sets struct field `ReverseWiegandBits`.
`EnableReverseWiegandBytes(bool reverse)`	`bool`	Sets struct field `ReverseWiegandBytes`.
`UseDataInvert(bool useInvert)`	`bool`	Sets `UseDataInvert`.
`AddCardGoneCharacter(unsigned char character)`	`unsigned char`	Appends to `CardGoneCharacters`. Max 2 entries. Throws `RfIdeasException` if array is full.
`AddLeadingCharacter(unsigned char character)`	`unsigned char`	Appends to `LeadingTrailingCharacters`. Value `0` is silently ignored. Combined leading+trailing max 3. Throws `RfIdeasException` if combined count would exceed 3.
`AddTrailingCharacter(unsigned char character)`	`unsigned char`	Appends to `LeadingTrailingCharacters` (after leading characters). Value `0` is silently ignored. Combined leading+trailing max 3. Throws `RfIdeasException` if combined count would exceed 3.

Block 4 — Extended Format (8)

Method	Parameter Type	Description / Constraints
`UseIndividualIdAndFacFixedLengths(bool useIndividualFixedLengths)`	`bool`	Sets `UseIndividualIdAndFacFixedLengths`.
`UseFixedLengthFac(bool useFixedLengthFac)`	`bool`	Sets `UseFixedLengthFac`.
`UseFixedLengthId(bool useFixedLengthId)`	`bool`	Sets `UseFixedLengthId`.
`SetCfgRb3(unsigned int value)`	`unsigned int`	Sets `CfgRb3`. Opaque firmware byte; no public meaning.
`SetCfgRb4(unsigned int value)`	`unsigned int`	Sets `CfgRb4`. Opaque firmware byte; no public meaning.
`EnableFacExtendedPrecision(bool enable)`	`bool`	Sets `EnableFacExtendedPrecision`.
`EnableAzertyKeyboardShift(bool enable)`	`bool`	Sets struct field `AzertyKeyboardShift`.
`EnableExtendedMode(bool enable)`	`bool`	Sets `EnableExtendedMode`.

Block 5 — Card Type (5)

Method	Parameter Type	Description / Constraints
`DisableCardConfiguration(bool disable)`	`bool`	Sets `DisableCardConfiguration`.
`SetCardType(unsigned int cardType)`	`unsigned int`	Sets `CardType`.
`EnableHighPriorityCardType(bool highPriority)`	`bool`	Sets struct field `SetHighPriorityCardType`.
`SetJetMobileCompatibilityCharacter(unsigned char character)`	`unsigned char`	Sets `JetMobileCompatibilityCharacter`.
`SetJetMobileCharacterCount(unsigned int count)`	`unsigned int`	Sets `JetMobileCharacterCount`.

Additional public members

Member	Return Type	Description
`GetStruct()`	`ReaderConfigurationStruct`	Returns the underlying packed struct.
`GetLeadingCharacter(size_t index)`	`unsigned char`	Returns the leading character at the given index.
`GetTrailingCharacter(size_t index)`	`unsigned char`	Returns the trailing character at the given index.
`operator==` / `operator!=`	`bool`	Compares two `ReaderConfiguration` objects. Device-reported fields (`ReaderSupportsReverseAllBytes`, `ReaderSupportsAsciiExtended`, `ReaderSupportsExtendedMode`, `IsBootDevice`) are excluded from comparison.

Example

#include "Structures/Configuration/ReaderConfigurationStruct.h"

RikCommon::ReaderConfiguration config;
config
    .SetFacDigitCount(3)
    .SetIdDigitCount(5)
    .SetTotalStripLeadingParityCount(1)
    .SetTotalStripTrailingParityCount(1)
    .SetLegacyBitStreamTimeOutMs(100)   // must be multiple of 4
    .SetDataHoldTimeMs(200)             // must be multiple of 50
    .EnableContinuousRead(true)
    .AddLeadingCharacter('%')
    .AddTrailingCharacter('?');

RikCommon::ReaderConfigurationStruct s = config.GetStruct();

ReaderBleConfiguration

Fluent-builder wrapper around the packed struct ReaderBleConfigurationStruct. Used by BleHwgFileParser.

note

This type is C++ only. C# and Python use file-based ReadBleConfigurationFromReader / WriteBleConfigurationToReader instead of marshalling this struct.

Constant: BLE_DATA_MAX_SIZE = 384

Packed struct fields:

Field	Type	Description
`DataType`	`BleDataType`	Type of BLE payload. `UnencryptedKey` is write-only.
`DataLength`	`uint16_t`	Number of valid bytes in `BleData` (not `uint8_t`; max is 384).
`BleData`	`std::array<uint8_t, BLE_DATA_MAX_SIZE>`	BLE configuration payload (`BLE_DATA_MAX_SIZE` = 384).

Wrapper class methods:

Method	Description
`SetDataType(BleDataType dataType)`	Sets `DataType`. Returns `ReaderBleConfiguration&`.
`SetBleData(const std::vector<uint8_t>& data)`	Copies payload into `BleData` and sets `DataLength`. Throws `RfIdeasException` if `data.size() > BLE_DATA_MAX_SIZE`.
`GetBleData()`	Returns a vector of the first `DataLength` bytes.
`GetStruct()`	Returns the underlying `ReaderBleConfigurationStruct`.
`operator==` / `operator!=`	Compares `DataType`, `DataLength`, and the valid `BleData` bytes.

ExtendedConfiguration

Packed struct in namespace RikCommon describing field separator and extended field data. EXTENDED_CONFIGURATION_SIZE (128) is the serialized ToVector / FromVector size, not sizeof the in-memory struct.

See ExtendedConfiguration for the full field reference (C++, C#, and Python).

HashData

Packed struct holding two 16-byte AES keys and firmware security state, passed to SetExtendedConfiguration / SetReaderConfiguration.

See HashData for the full field reference (C++, C#, and Python).

SmartCardConfiguration

C++ wrapper around SmartCardConfigurationStruct.

Method	Description
`GetStruct()`	Returns the underlying packed struct
`SetConfiguration(const BlobHeader& header, const std::vector<uint8_t>& data)`	Sets header and data fields
`operator==` / `operator!=`	Compares two `SmartCardConfiguration` objects

See SmartCardConfigurationStruct for the packed layout (BlobHeader + 1016-byte Data buffer).

HwgFileMetaData

Metadata supplied when writing HWG files. Namespace: RikCommon.

Field	Type	Description
`DeviceFirmwareVersion`	`std::string`	Device firmware version string
`LibraryVersion`	`std::string`	Library version string
`IsSecureHwgFormat`	`bool`	Whether to write the secure HWG format (default: `true`)

This type is an input parameter to write APIs:

HwgFileParser::WriteConfigurationToHwgFile(..., const HwgFileMetaData& metaData)
BleHwgFileParser::WriteBleConfigurationToBleHwgFile(..., const HwgFileMetaData& metaData, bool secureHwgFormat = true)

Read APIs (ReadConfigurationFromHwgFile, ReadBleConfigurationFromBleHwgFile) do not return HwgFileMetaData.

File Parsers

HwgFileParser

Static methods in the RikCommon namespace for reading and writing HWG configuration files.

Method	Description
`ReadConfigurationFromHwgFile(const std::string& path)`	Returns `std::vector<std::tuple<ReaderConfiguration, ExtendedConfiguration>>`
`WriteConfigurationToHwgFile(configs, extConfigs, path, metaData)`	Writes configurations to an HWG file

Example

#include "Utility/Parsers/HwgFileParser.h"
#include <iostream>

using namespace RikCommon;

auto configs = HwgFileParser::ReadConfigurationFromHwgFile("/path/to/config.hwg");
for (auto& [readerConfig, extConfig] : configs) {
    std::cout << "Expected bit count: " << static_cast<int>(readerConfig.GetStruct().ExpectedBitCount) << "\n";
}

BleHwgFileParser

Static methods for BLE-specific HWG files.

Method	Description
`ReadBleConfigurationFromBleHwgFile(const std::string& path)`	Returns `ReaderBleConfiguration`
`WriteBleConfigurationToBleHwgFile(config, path, metaData, secureHwgFormat)`	Writes BLE config; `secureHwgFormat` defaults to `true`

SmartCardConfigurationFileParser

Method	Description
`ReadConfigurationFromSmartCardIniFile(const std::string& path)`	Returns `std::vector<SmartCardConfiguration>`

Utilities

Logger

Singleton logger supporting file and console output.

auto& logger = Logger::GetInstance(/*fileLogging=*/true, /*consoleLogging=*/true);
logger.LogInfo("MyModule", "Reader connected successfully");

Method	Description
`GetInstance(bool fileLogging, bool consoleLogging)`	Get or create the singleton
`LogTrace(module, message)`	Log at Trace level
`LogDebug(module, message)`	Log at Debug level
`LogInfo(module, message)`	Log at Info level
`LogWarning(module, message)`	Log at Warning level
`LogError(module, message)`	Log at Error level
`LogCritical(module, message)`	Log at Critical level

StringUtils

Static string helper functions.

Method	Description
`Trim(str)`	Trim whitespace
`Split(str, delimiter)`	Split into vector
`Join(vec, delimiter)`	Join vector into string
`StartsWith(str, prefix)`	Prefix check
`ParseInt(str)`	Parse to int
`ParseBool(str)`	Parse to bool
`GetHexStr(value, width = 2)`	Format an unsigned integer as a hex string
`GetBoolStr(value)`	Bool to `"1"` / `"0"`

CRC32

Method	Description
`CalculateCRC(const std::vector<uint8_t>& data)`	Returns CRC32 as a string

RfIdeasFirmwareFileStream

Stream reader for firmware files (.hex).

Method	Description
`Open()`	Open the file
`Close()`	Close the file
`IsOpen()`	Check if open
`NextLineFromFile()`	Read next line
`HasEnded()`	Check for EOF
`ResetAndGetLineCount()`	Reset to start; returns total line count
`GetFileType()`	Returns `FirmwareFileType` (`CONTROL`, `RADIO`, or `BLUETOOTH`)

TimeDelay

Virtual delay utility (useful for mocking in tests).

Method	Description
`DelayMilliseconds(int ms)`	Sleep for N milliseconds
`DelaySeconds(int seconds)`	Sleep for N seconds

Exceptions

RfIdeasException

Base exception class for all RIK errors.

Field	Type	Description
`Message`	`std::string`	Error message
`File`	`std::string`	Source file where thrown
`Line`	`int`	Line number
`Function`	`std::string`	Function name
`ExceptionType`	`std::string`	Exception category

Macros:

Macro	Description
`THROW_RFIDEAS_EXCEPTION(msg)`	Throw with auto-populated file/line/function
`RFIDEAS_EXCEPTION(var, msg)`	Create an exception object without throwing

Template helper:

// Throws RfIdeasException if propertyValue is outside [minValue, maxValue]
RfIdeasException::ThrowExceptionForPropertyOutOfRange(
    const std::string& propertyName, T propertyValue, T minValue, T maxValue);

Installation​

Card Types​

CardType​

CardTypeResolver​

CardTypeVersion​

Example​

Configuration Structures​

ReaderConfiguration​

Block 1 — FAC/ID Format (16)​

Block 2 — Timing and Output Format (16)​

Block 3 — LED, Beeper, and Character Output (16)​

Block 4 — Extended Format (8)​

Block 5 — Card Type (5)​

Additional public members​

Example​

ReaderBleConfiguration​

ExtendedConfiguration​

HashData​

SmartCardConfiguration​

HwgFileMetaData​

File Parsers​

HwgFileParser​

Example​

BleHwgFileParser​

SmartCardConfigurationFileParser​

Utilities​

Logger​

StringUtils​

CRC32​

RfIdeasFirmwareFileStream​

TimeDelay​

Exceptions​

RfIdeasException​

Installation

Card Types

CardType

CardTypeResolver

CardTypeVersion

Example

Configuration Structures

ReaderConfiguration

Block 1 — FAC/ID Format (16)

Block 2 — Timing and Output Format (16)

Block 3 — LED, Beeper, and Character Output (16)

Block 4 — Extended Format (8)

Block 5 — Card Type (5)

Additional public members

Example

ReaderBleConfiguration

ExtendedConfiguration

HashData

SmartCardConfiguration

HwgFileMetaData

File Parsers

HwgFileParser

Example

BleHwgFileParser

SmartCardConfigurationFileParser

Utilities

Logger

StringUtils

CRC32

RfIdeasFirmwareFileStream

TimeDelay

Exceptions

RfIdeasException