Basic Usage

Complete working examples for connecting to readers, reading metadata, and performing basic operations.

Connect to a Reader

Connect to an rf IDEAS reader over USB, read metadata, beep, and close.

C++

main.cpp

#include <iostream>
#include "Reader/Reader.h"

int main() {
    using namespace Rik;
    using namespace RikCommon;

    ReaderHandle handle = nullptr;

    try {
        ReaderDefinition readerDef;
        readerDef.DeviceId.VendorId = 0x0C27;
        readerDef.DeviceId.ProductId = 0x3BFA;
        readerDef.ProtocolType = PROTOCOL_TYPE_FEATURE_REPORT;

        handle = AbstractReader::CreateReaderInstance(readerDef, 3);
        auto* reader = dynamic_cast<Reader*>(
            AbstractReader::GetInstance(handle)
        );
        reader->Init();

        auto metadata = reader->GetMetadataStruct();
        std::cout << "Part Number: " << metadata.PartNumber << std::endl;
        std::cout << "Serial: " << metadata.ESN << std::endl;

        reader->Beep(2, RikProtocol::BEEP_DURATION_SHORT);

        reader->Close();
        AbstractReader::DestroyInstance(handle);
        handle = nullptr;
        return 0;

    } catch (const ReaderException& e) {
        std::cerr << "Error: " << e.Message << std::endl;
        if (handle) AbstractReader::DestroyInstance(handle);
        return 1;
    }
}

C#

Program.cs

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

try
{
    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 Number: {metadata.PartNumber}");
    Console.WriteLine($"Serial: {metadata.ESN}");

    app.Beep(2, BeepDuration.Short);
}
catch (ReaderException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Python

main.py

import reader_integration_kit.facade as rik
from reader_integration_kit.structures import (
    ReaderDefinition, DeviceId, SerialPortSettings
)
from reader_integration_kit.enum import (
    ProtocolType, BeepDuration
)
from reader_integration_kit.errors import ReaderException

try:
    reader_def = ReaderDefinition(
        DeviceId=DeviceId(VendorId=0x0C27, ProductId=0x3BFA),
        ProtocolType=ProtocolType.FEATURE_REPORT,
        SerialPortSettings=SerialPortSettings()
    )

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

        metadata = app.get_metadata()
        print(f"Part Number: {metadata.get('PartNumber')}")
        print(f"Serial: {metadata.get('ESN')}")

        app.beep(2, BeepDuration.BEEP_DURATION_SHORT)

except ReaderException as e:
    print(f"Error: {e.message}")

Get Library Version

Retrieve RIK library version info. No reader connection required.

C++

#include <iostream>
#include "Reader/AbstractReader.h"

int main() {
    LibraryInfo info;
    auto result = Rik::AbstractReader::GetLibraryInfo(info);

    if (!result.HasException) {
        std::cout << "Version: " << info.VersionString << std::endl;
        std::cout << "SemVer:  " << info.SemVer << std::endl;
        std::cout << "Build:   " << info.BuildVer << std::endl;
    }

    return 0;
}

C#

using rfIDEAS.ReaderIntegrationKit;

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

Python

import reader_integration_kit.facade as rik

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

Connect by USB Path

When multiple readers share the same VID/PID and serial numbers are unavailable, connect by USB path to target a specific physical port.

C++

#include <cwchar>
#include "Reader/Reader.h"

using namespace Rik;
using namespace RikCommon;

ReaderDefinition readerDef{};
readerDef.ProtocolType = PROTOCOL_TYPE_FEATURE_REPORT;

// USB path -- VID/PID are not required in this mode
// Linux: bus-port path (e.g., "1-7" or "1-7.2")
// Windows: location path (e.g., "PCIROOT(0)#PCI(1400)#USBROOT(0)#USB(7)")
std::wstring usbPath = L"1-7";
std::wcsncpy(readerDef.DeviceId.UsbPath, usbPath.c_str(),
             sizeof(readerDef.DeviceId.UsbPath) / sizeof(wchar_t) - 1);

auto handle = AbstractReader::CreateReaderInstance(readerDef, 3);
auto* app = AbstractReader::GetInstance(handle);
app->Init();

auto metadata = app->GetMetadataStruct();
std::cout << "Part Number: " << metadata.PartNumber << std::endl;

app->Close();
AbstractReader::DestroyInstance(handle);

C#

using System.Runtime.InteropServices;
using rfIDEAS.ReaderIntegrationKit;
using rfIDEAS.ReaderIntegrationKit.Objects;
using rfIDEAS.ReaderIntegrationKit.Enum;

var readerDef = new ReaderDefinition
{
    DeviceId = new DeviceId
    {
        // VID/PID are not required when using USB path
        // Linux: "1-7", Windows: "PCIROOT(0)#PCI(1400)#USBROOT(0)#USB(7)"
        UsbPath = Marshal.StringToHGlobalUni("1-7")
    },
    ProtocolType = ProtocolType.FeatureReport
};

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

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

Python

import ctypes
import reader_integration_kit.facade as rik
from reader_integration_kit.structures import (
    ReaderDefinition, DeviceId, SerialPortSettings
)
from reader_integration_kit.enum import ProtocolType

reader_def = ReaderDefinition(
    DeviceId=DeviceId(
        # VID/PID are not required when using USB path
        # Linux: "1-7", Windows: "PCIROOT(0)#PCI(1400)#USBROOT(0)#USB(7)"
        UsbPath=ctypes.cast(ctypes.c_wchar_p("1-7"), ctypes.c_void_p)
    ),
    ProtocolType=ProtocolType.FEATURE_REPORT,
    SerialPortSettings=SerialPortSettings()
)

with rik.Reader(reader_def) as app:
    app.init()
    metadata = app.get_metadata()
    print(f"Part Number: {metadata.get('PartNumber')}")

tip

See Discovering USB Paths for a complete guide including the C++ UsbDeviceEnumerator API, a Linux shell utility, and Windows PowerShell commands.

Serial Port Connection

Connect to a reader over RS-232 serial.

C++

#include "Reader/AbstractReader.h"

using namespace Rik;
using namespace RikCommon;

ReaderDefinition readerDef;
readerDef.ProtocolType = PROTOCOL_TYPE_SERIAL_BINARY;

std::strcpy(readerDef.SerialPortSettings.PortName, "COM3");
readerDef.SerialPortSettings.BaudRate = SERIAL_PORT_BAUD_9600;
readerDef.SerialPortSettings.Parity = SERIAL_PORT_PARITY_NONE;
readerDef.SerialPortSettings.DataBits = SERIAL_PORT_DATA_BITS_8;
readerDef.SerialPortSettings.StopBits = SERIAL_PORT_STOP_BITS_ONE;

auto handle = AbstractReader::CreateReaderInstance(readerDef, 3);
auto* app = AbstractReader::GetInstance(handle);
app->Init();

auto metadata = app->GetMetadataStruct();
std::cout << "Part Number: " << metadata.PartNumber << std::endl;

app->Close();
AbstractReader::DestroyInstance(handle);

C#

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

var readerDef = new ReaderDefinition
{
    ProtocolType = ProtocolType.SerialBinary,
    SerialPortSettings = new SerialPortSettings
    {
        PortName = "COM3",
        BaudRate = SerialPortBaudRate.Baud9600,
        Parity = SerialPortParity.None,
        DataBits = SerialPortDataBits.Eight,
        StopBits = SerialPortStopBits.One
    }
};

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

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

Python

import reader_integration_kit.facade as rik
from reader_integration_kit.structures import (
    ReaderDefinition, DeviceId, SerialPortSettings
)
from reader_integration_kit.enum import (
    ProtocolType, SerialPortBaudRate, SerialPortParity,
    SerialPortDataBits, SerialPortStopBits
)

serial_settings = SerialPortSettings(
    PortName="COM3",  # Or "/dev/ttyUSB0" on Linux
    BaudRate=SerialPortBaudRate.BAUD_9600,
    Parity=SerialPortParity.NONE,
    DataBits=SerialPortDataBits.DATA_BITS_8,
    StopBits=SerialPortStopBits.ONE
)

reader_def = ReaderDefinition(
    DeviceId=DeviceId(),
    ProtocolType=ProtocolType.SERIAL_BINARY,
    SerialPortSettings=serial_settings
)

with rik.Reader(reader_def) as app:
    app.init()
    metadata = app.get_metadata()
    print(f"Part Number: {metadata.get('PartNumber')}")

Error Handling

C++

#include <iostream>
#include "Reader/AbstractReader.h"
#include "ErrorHandling/ReaderException.h"

using namespace Rik;
using namespace RikCommon;

ReaderHandle handle = nullptr;

try {
    ReaderDefinition readerDef;
    readerDef.DeviceId.VendorId = 0x0C27;
    readerDef.DeviceId.ProductId = 0x3BFA;
    readerDef.ProtocolType = PROTOCOL_TYPE_FEATURE_REPORT;

    handle = AbstractReader::CreateReaderInstance(readerDef, 3);
    auto* app = AbstractReader::GetInstance(handle);
    app->Init();

    // ... operations ...

    app->Close();
    AbstractReader::DestroyInstance(handle);
    handle = nullptr;

} catch (const ReaderException& e) {
    std::cerr << "Message:  " << e.Message << std::endl;
    std::cerr << "File:     " << e.File << std::endl;
    std::cerr << "Line:     " << e.Line << std::endl;
    std::cerr << "Function: " << e.Function << std::endl;

    if (handle) AbstractReader::DestroyInstance(handle);
}

C#

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

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

    using var app = new Reader(readerDef);
    app.Init();
    // ... operations ...
}
catch (ReaderException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
    Console.WriteLine(ex.ToString());
}

Python

import reader_integration_kit.facade as rik
from reader_integration_kit.structures import (
    ReaderDefinition, DeviceId, SerialPortSettings
)
from reader_integration_kit.enum import ProtocolType
from reader_integration_kit.errors import ReaderException

try:
    reader_def = ReaderDefinition(
        DeviceId=DeviceId(VendorId=0x0C27, ProductId=0x3BFA),
        ProtocolType=ProtocolType.FEATURE_REPORT,
        SerialPortSettings=SerialPortSettings()
    )

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

except ReaderException as e:
    print(f"Error: {e.message}")
    if e.has_protocol_exception:
        print(f"Protocol: {e.protocol_message}")

tip

Always wrap RIK operations in try/catch (C++/C#) or try/except (Python). The exception objects carry source file, line number, and function name for diagnostics.